Jeden/Docs

CLI command

jeden import

Preserve sessions of another harness — their conversation history and interrupted requests — in native Jeden ledgers without executing work.

Exact invocation#

Shell
jeden import <path>... [--refresh] [--json]

Inputs and options#

  • Required: one or more paths. A path is a transcript file another harness wrote, or a directory that is scanned recursively for such files. Which harness wrote a file is read from its content, never from the command: today the supported format is omp, a JSONL transcript whose {"type":"session"} header carries the session id and workspace. The workspace and title come from the transcript itself.
  • The destination is the normal Jeden session root, or JEDEN_SESSION_ROOT when explicitly set. --refresh replaces only a never-adopted native import; it never rewrites an already-used native conversation.
  • Jeden Desktop exposes File → Import Sessions. Enter absolute paths on the Stado-selected host, one per line. The window reports each imported path and each refusal; it does not start agents or transfer execution ownership.

Output and state effect#

Returns JSON with imported, existing, sessions and failures. Each successful row names format, sourceSession, sourcePath, sessionPath, cwd, title and interrupted. The native session is keyed by the format and the source id (omp-&lt;sha256&gt;), so importing the same source again reports it as existing and refreshing it replaces the same directory. The full source file is retained at artifacts/&lt;format&gt;-source.jsonl. The active source branch becomes a native context snapshot; unanswered requests enter the native retained-work store. Import does not stop the other harness, start a model, or transfer execution ownership. A copied history is not a completed migration. Inspect failures even when the command exits successfully: per-source failures do not discard other successful imports.

Refusals and boundaries#

  • No path is refused as Usage: jeden import &lt;path&gt;... [--refresh] [--json]. A file named outright that is no supported transcript is a failure row: &lt;path&gt;: not a transcript of a supported harness (supported: omp); inside a scanned directory such files are skipped without a word. Paths that yield nothing at all are refused as no sessions to import under &lt;paths&gt;.
  • Unknown options, including single-dash spellings, are usage refusals before any transcript is opened or the destination store is created. Prefix a literal filename beginning with a dash with ./.
  • Unreadable sources, malformed JSON records, missing ancestors, cyclic ancestry and an unavailable source workspace are returned per source. A source changed during import is refused, leaving its original history intact. A changed source from an earlier import is refused as source changed since import; use --refresh only for a never-adopted import. Adopted imports, child sessions and changed native retained work refuse refresh.
  • Refresh reads retained completion work through the same typed, read-only reader as jeden todo list --session &lt;directory&gt; --json and the native work surface. Unsupported schema versions, malformed fields and unsafe completion paths retain the canonical reader's cause and the actual completion path, before any replacement is published. Legacy retained work is checked by that reader too; a missing completion file does not authorize ignoring legacy tasks or requests. A refused inspection does not migrate or rewrite the ledger.
  • A concurrent import refuses its import lock. Interrupted replacement publication is recovered before the next import attempts that source.
  • The maintained node tests/sessions/import_workspace/journey.mjs qualification needs JEDEN_BIN, OKO_BIN, JEDEN_TEST_SOURCE_REVISION, OKO_TEST_SOURCE_ROOT, OKO_TEST_SOURCE_REVISION, JEDEN_TEST_IMPORT_SOURCE and JEDEN_TEST_RETAINED_SESSION. It requires clean source checkouts and binds the actual Jeden source-bearing development version to its full commit; a dirty, unknown or release-only version without that source identity refuses qualification. Oko's existing integrity-inventory probe checks its compiled source revision and an actual issued row in an isolated copy of its register. Release version labels and executable digests alone do not qualify a source revision. The journey retains actual versions, commands, statuses, hashes and source-bound probe results under .build/import-workspace; it neither writes the operator's register nor treats unavailable provenance as a pass.
  • That real journey also requires a genuine pending imported request. Its isolated valid-JSON corruptions remove the required tasks field or replace the recorded planned Boolean with a string. It first observes the actual canonical todo-list schema refusal, then requires refresh to retain that observed cause and completion path while preserving directory identity and the metadata, transcript, completion and retained source bytes. A separate macOS ACL case denies reading the importer's actual regular completion file, measures its read refusal and requires that operating-system cause and path in the refused refresh, with the ledger identity and bytes unchanged after permissions are restored. It does not substitute a symlink that the canonical reader must reject before reading, or guess that a typed parser must print a malformed field name. Permission restoration attempts run after qualification failure too; report-retention failures remain visible alongside the initiating and cleanup failures. These are forensic copies, not fabricated harness executions. An unexecuted definition, missing fixture or refused dependency is not a passing qualification.
  • The publication journeys use actual macOS filesystem restrictions on isolated imports. One ACL case proves that a replacement is already published when removing its protected previous backup fails. A separate /usr/bin/sandbox-exec -f policy denies creation only at the actual imported destination: refresh must retain both the failed staging-to-destination publication and the failed backup-to-destination recovery. Qualification checks the retained backup's original filesystem identity and metadata, transcript, completion and source bytes, observes the same recovery refusal through a second real import, then requires an unrestricted normal import to restore that exact ledger without a manual rename. The report retains policy bytes, commands, statuses and observed paths. A missing sandbox facility, an unsupported policy or failure to reach both rename boundaries is a failed or blocked qualification, never a pass.
  • A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits 2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: &lt;operation&gt;.&lt;cause&gt;, and jeden errors show &lt;operation&gt; lists every cause of that functionality.