Jeden/Docs

Durable state

Leave. Return. Keep going.

Jeden records the work behind the answer — tool results, artifacts, decisions, and state — so a serious task can outlive a single interaction. Sessions are durable, append-only, and owned by the operator.

Where sessions live#

Sessions live under ~/.jeden/sessions/ (JEDEN_SESSION_ROOT overrides). Each session directory holds state.json and transcript.jsonl, an append-only ledger of sequenced, parent-linked, checksum-sealed events that is validated on read and fsynced on every append.

Per-project state lives in <cwd>/.jeden/. All of it is on the operator’s disk; Jeden uploads none of it, and session transcripts are never expired or deleted by Jeden. Backing up ~/.jeden/ and <cwd>/.jeden/ is the operator’s responsibility — Jeden ships no backup or restore command.

Configured and automatically discovered secret values are replaced with [REDACTED] in the model-bound copy of the context, while the local transcript keeps the original text.

Jeden emits no telemetry to Wisent from a default local run; the per-session event ledger is Jeden’s audit record. Every completion appends tokens, the Brama-catalog-priced cost breakdown, and the served billing target and decision ID to <cwd>/.jeden/usage.json; jeden stats and /usage show read the ledger.

Retained work and verified completion#

The session's completion.json owns original requests, their workspace, acceptance requirements, task states and verification references. Atomic replacement and a process lock preserve them across interruptions. A model's todo done is only a verification request. It cannot remove user-owned tasks, change their acceptance criteria or approve its own result.

Every proposed final answer is checked against all unresolved original requests and every recorded criterion. Work criteria require successful observations from a fresh read-only verifier. Questions and reading requests do not acquire implementation requirements. An unmet but actionable requirement returns control to the execution loop instead of ending the conversation; assistantMessage carries progress or an interim answer without claiming completion.

A final answer that promises the work for later ("I will do it and let you know") while the work is undone is such an answer: no mechanism of the run carries that promise out, so the acceptance review keeps the request open, the refusal is recorded as completion_rejected, the promise is never published as the final event or printed, and the same run continues the missing work. The real journey JEDEN_BIN=/path/to/candidate JEDEN_TEST_SOURCE_REVISION=&lt;candidate-commit&gt; JEDEN_TEST_STADO=&lt;stado&gt; node tests/completion/gates/promise.mjs plays the model through Stado's attestation alternative under the run's own HOME: it ends its first turn on such a promise, then, once Jeden refuses it, writes the file with write_file and finishes. The journey reads the exported session: the promise as the model's action, a completion_rejected after it, no published promise, a later accepted final and the file with the requested content. It writes its report under .build/completion-journeys/.

Each inspection stage gets exactly one correction. When an intake or acceptance-review answer cannot be read as the required JSON object, or the native controller refuses the plan it carries, the exact refusal is recorded as completion_rejected and quoted back to a fresh read-only inspection, together with the piece of the answer the parser stopped at. A second refusal records the durable blocker; one unusable answer no longer strands a retained request. A missing field is read the strict way rather than refused: an intake task without kind is work, and a review without criteria has reviewed no criterion, so the controller still refuses the acceptance and the loop keeps the work open. A field the answer adds is ignored, and taskId, task_id, task and id are read as the same identifier, because an echoed or differently spelled name is not a different verdict. An answer the output budget cut mid-JSON is the one refusal more words cannot repair, so its correction is asked for with twice the inspection budget and with every explanation held to one sentence.

Model or verification failure records the actual operation and error and keeps complete: false. An explicit step limit reports paused; interruption reports interrupted. Operator pauses and cancellations remain authoritative. A resumed session inspects prior results before proposing repeated effects. The model still interprets whether observations satisfy natural-language criteria; the native controller checks coverage, evidence identity and state transitions rather than claiming infallible judgement.

The place a criterion names is decided by the controller, not by that interpretation. When a work criterion names a path, an accepted verdict requires an accepted observation at one of the places that criterion names, and a verdict anchored at none of them is refused as jeden.completion.review.place-unobserved, naming the task, the criterion, the place and where the observations happened. One sentence may name several places while only one of them is the requirement, as in "the workspace root must hold alpha.txt; a copy already sits in scratch/", so demanding every named place would refuse finished work over a place that was only mentioned. A bare file name is read as the workspace root the request recorded, so a write one directory below it does not satisfy the criterion. A path of several parts is matched exactly against that same workspace; only an observation that happened outside the workspace may match it by ending with those parts, because one file is spelled from different roots inside a receipt. Inside the workspace a nested copy of the same name is a different place: workspace/alpha.txt is not met by a write to workspace/workspace/alpha.txt. A criterion whose last part is not a file name is read as a place, so work done inside it counts. A slash alone is not a place: input/output and CLI/GUI are prose, and only an anchored path, a trailing slash or a segment that names a file is read as one. Version numbers, host names and gateway addresses are not paths, and a criterion that names no path is left entirely to the reviewer's prose.

Every request gets a time to completion. The independent intake that records its acceptance requirements also records estimate: the whole minutes it expects the request to take until every task is independently verified, with the moment it was recorded, before any execution. Nothing revises that first estimate. When an independent review accepts the request, the controller records completedAt. A defect that reopens the request removes completedAt again, so the measured time runs on from the same estimate until a fresh review accepts the repair; a request closed by cancellation never gets one. An intake answer without estimateMinutes above zero is refused as jeden.completion.intake.estimate-missing, naming what it gave, and gets its one correction like any other refused intake.

The completion snapshot, from jeden todo list --json, RPC session/completion/get and every completion event, carries timing: one entry per request that has an estimate, with estimateMinutes, estimatedAt and dueAt, and, once the request is verified complete, completedAt, elapsedSeconds, differenceSeconds (the actual time minus the estimate, negative when the work finished early) and ratio. state is open, on_time, late, cancelled or unmeasurable; every *At is Unix seconds. unmeasurable means the request was verified complete at a moment before its estimate was recorded, which only a clock set back between the two produces: the entry keeps both stamps, carries no elapsed time, and its reason names both, so the time is never reported as zero. A completion file whose estimate.recordedAt or completedAt is not whole Unix seconds, or whose estimate is more seconds than can be counted, is refused when it is read or written as jeden.completion.state.stamp-not-seconds, estimate-uncountable or due-uncountable, naming the request and the field; an estimateMinutes of zero is refused while the file is decoded. jeden todo list prints the same comparison under each request, for example Time to completion: estimated 5 min · done in 1 min 45 s, 3 min 15 s under the estimate, and the Tasks panels of Jeden Desktop and Jeden iOS print the same words; a panel that receives an entry lacking a field its state needs prints Time to completion: cannot be shown: the &lt;state&gt; entry carries no &lt;field&gt; instead of guessing it, and an open request whose estimate lies ahead of the device clock prints both readings. The terminal shows the estimate as soon as the intake records it, and the answer of the turn in which a request is accepted ends with its measured time in the conversation language. Completion files written before schema version 3 open unchanged and are carried forward; a file written by a newer Jeden is refused as jeden.completion.state.schema-other, naming both schemas.

The independent review is recorded only as a whole, jeden.completion.review, and its refusal is read back by the reviewer to correct its verdict, leaving the session as it was: an answer that is no JSON object of the review's shape is answer-unreadable (line, column and the line it stopped on, an entry of tasks named by its place); a verdict naming no task while several are open is verdict-unnamed; a review that does not cover every open task or unresolved request exactly once is tasks-uncovered or requests-uncovered, naming the missing, the extra and the repeated ids; a verdict without its explanation, or a criterion past the task's last, explained twice or not at all, is explanation-missing or criterion-invalid; a done verdict whose criterion is unsatisfied or has no successful observation by a read tool of the review is observation-missing; a block without a failed operation of the execution or an ask is block-unproven, a block after the operator's answer with nothing failed since is block-after-answer, and an ask the register does not hold or one it already holds an answer to is ask-unregistered or ask-answered. The receipts a verdict cites are found as jeden.completion.evidence finds them: only in the execution under review or its review (session-foreign), receipt-unknown, and a receipt or answer time that is no stamp.

Use the Conversation screen's Tasks panel in Desktop or mobile to read requests, acceptance criteria, blocker details and evidence references, or to pause, resume and cancel a task with a reason. Continue retained work uses the same session operation as the CLI and does not add an artificial user obligation. Reopening a graphical session reloads its current completion state; a terminal response event alone does not mean all work is complete.

Inspect and continue the retained session
jeden todo list --session <session> --json
jeden todo pause <request-id> --session <session> --revision <revision> --reason "Pause this request"
jeden todo list --session <session> --json
jeden todo resume <request-id> --session <session> --revision <new-revision> --reason "Resume this request"
jeden todo continue --session <session> --allow-write

Inspect, export, resume#

jeden sessions search, show, export, artifacts, artifact and resume inspect or reuse recorded work; inside a session the agent's recall_conversation tool reads the same text-only transcript show prints. Resume inherits both selected history and retained tasks into a child session. Without a new prompt it continues unfinished work, preserving the recorded workspace and requiring explicit execution grants.

jeden export &lt;session&gt; &lt;output&gt; [--html|--markdown] writes JSON by default, or the one selected readable format. It refuses an absent output, an unknown option (including a single-dash spelling), a second output or repeated/conflicting format options before reading the session or writing a file. A missing or unreadable session and a failed output write name their cause; HTML and Markdown also refuse a recorded session without a string id, string path or events array instead of inventing content.

Session commands
jeden sessions
jeden sessions search "query"
jeden show <session>
jeden export <session> <output>
jeden export <session> <output.html> --html
jeden export <session> <output.md> --markdown
jeden artifacts <session>
jeden artifact <session> <name> <output>
jeden resume <session> "continue"

Adopt existing work#

jeden workspace discover [path] validates an existing directory without writing. jeden workspace adopt &lt;path&gt; then stores only its canonical absolute path as workspace.defaultPath in ~/.jeden/config.yml, after validation succeeds. Relative input is resolved from the invocation directory; a path containing .., a missing or unreadable directory, or malformed existing &lt;workspace&gt;/.jeden/config.json is refused before user state changes.

Adoption does not import or copy a repository, configuration, credential, or transcript. The working tree remains byte-for-byte where the user owns it. Session ledgers remain under the canonical session root and are associated by the cwd already recorded in each state.json. Re-adopting the same canonical path reports unchanged; unreadable session state is counted as rejected instead of silently omitted.

The terminal first-use screen and /setup workspace &lt;path&gt; call the same operation as Jeden Desktop’s first-use folder chooser and Settings → Default workspace over workspace/adopt RPC. Both show the accepted canonical path and accepted/rejected session counts. Replay is /onboarding reset in the terminal and Settings → First-run walkthrough → Show it again on macOS.

First-use progress is kept per device subject, the user name and home Jeden runs under, and reported through the Stado integration API when both STADO_INTEGRATION_API_URL and JEDEN_STADO_INTEGRATION_TOKEN are declared; with neither it stays offline on this machine. /onboarding refuses one variable without the other, an address the integration transport rejects, and a process with no readable USER, naming the variable, instead of silently reporting nowhere or sharing one placeholder subject between nameless accounts.

Jeden iOS cannot read or adopt a path from the phone. Its supported adapter is the canonical headless session protocol: after a host identity is configured, choose a row under On this host. Completion is recorded only after session/open resumes that exact ledger and session/history returns its retained turns. The next mobile prompt therefore uses the session’s recorded host workspace. The Settings gear shows every accepted host session and Choose an existing workspace session replays the same first-use selector. The host repository and ledger never leave the host.

Inspect and adopt without copying data
jeden workspace discover /path/to/repository
jeden workspace adopt /path/to/repository
jeden workspace status

Import retained sessions from another harness#

jeden import &lt;transcript&gt; --json reads the actual source format and preserves its history and interrupted requests in a native ledger. It does not execute the requests, stop their former harness, start a model, or prove a completed migration. Inspect both sessions and failures: a per-source refusal remains a failure even when the batch command exits successfully.

The canonical source workspace is retained in state.json and in a new import’s context_snapshot. The copied context is metadata, not a new operator request. Consumers can inspect an older import’s declared native state without rewriting its adopted history; a missing or unreadable workspace must retain its cause, not become a guessed directory.

An unchanged import preserves the same ledger. If its source changed, ordinary import refuses; --refresh is allowed only for an import that no native run adopted. A refresh refusal is not permission to replace a used conversation or invent a new session identity.

Snapshot and staging failures name the actual operation and its source, file or directory. Creating, writing and synchronizing state.json or import.json likewise retains the failed JSON target and its actual cause. If removing failed staging also fails, the returned source error preserves the initiating import failure and appends the cleanup target and operating-system cause. Failure inspecting staging for cleanup is likewise additional evidence, not a replacement for the initiating error. A surviving staging directory is not an imported session.

A publication refusal identifies both staging and destination. If restoring an interrupted publication also fails, the initiating rename error survives together with the recovery source, destination and cause. If parent synchronization or old-backup removal fails after the new directory was published, the error explicitly identifies that published session and the failed remaining operation. A failed batch row is therefore not proof that nothing was published: inspect its named destination and backup before continuing; a refusal never authorizes replacing adopted native history.

Refresh admission distinguishes an absent adoption marker, completion record or sibling state file from an inspection failure. An unreadable marker, retained-work record or lineage state is a refusal naming the attempted inspection, read or decode and its actual path and cause; it is never evidence that the import is unused. A non-file lineage state is likewise refused with the observed file type. Admission failure leaves the existing imported directory and history in place.

Jeden Desktop → File → Import Sessions uses session/import with the same per-source failures and complete diagnostic text. An import result is not evidence that a conversation, model request or continuation started.

The real node tests/sessions/import_workspace/journey.mjs journey requires JEDEN_BIN, OKO_BIN, JEDEN_TEST_IMPORT_SOURCE, JEDEN_TEST_RETAINED_SESSION, JEDEN_TEST_SOURCE_REVISION, OKO_TEST_SOURCE_ROOT and OKO_TEST_SOURCE_REVISION. Inputs are genuine stable captures and clean exact product revisions. It exercises the actual import and inventory CLIs, new and retained workspace inspection, meaningful refusals, corrupted artifacts, and real macOS ACL cases that refuse snapshot creation or direct state-JSON creation, followed by staging cleanup. The state case measures refusal of opening that actual file for creation and requires its operating-system code in the initiating diagnostic. A separate real refresh refuses old-backup removal after publication, verifies the new destination and the old backup by their actual filesystem identities, and preserves the old protected transcript and the new source snapshot. Only isolated copied state and its permissions change; source captures remain unchanged.

The same journey separately denies directory search on isolated adoption-marker and sibling-lineage targets and measures their actual stat refusals before requesting refresh. Its completion-record case instead keeps the importer’s real regular completion.json, denies read access with a macOS ACL and measures the actual read refusal. Each case requires its measured operating-system cause and target in the CLI refusal, unchanged destination identity, native state and transcript bytes, and unchanged protected artifact bytes after permission restoration. These are real filesystem admission failures against copied genuine imports, not a claim to have run native adoption or child-session workflows.

Completion-admission cases start with a genuine imported pending request, then change only its isolated retained-work document: one removes the required tasks field and another changes planned from a boolean to a string. Each first requires the canonical jeden todo list --session &lt;destination&gt; --json reader to refuse and records its actual completion path and read or decode cause, without assuming which field name the decoder prints. Refresh must preserve that same observed canonical cause rather than replace the malformed state; the destination’s device and inode, native state, transcript, completion and copied source bytes must remain unchanged. These are qualification requirements, not evidence that an unexecuted candidate already enforces typed refresh admission.

Executable identity is checked before those cases. The actual Jeden --version must carry a clean development-source revision resolving to JEDEN_TEST_SOURCE_REVISION; a release label, digest alone or dirty identity does not satisfy that check. For Oko, the journey copies its actual issued defect register into the isolated run and invokes defects integrity-inventory --id &lt;issued-id&gt; --revision oko@&lt;full-commit&gt; --json. That existing probe compares the executable’s compiled source revision and the CLI’s observed row with the copied persisted row. Missing provenance, a revision mismatch or a differing row refuses qualification. The journey retains actual versions, executable digests and probe output without editing the operator’s register or claiming that unrelated concurrent writes are its own mutation.

Reports retain actual commands, exit statuses, executable and capture digests, persisted observations and both qualification and permission-restoration failures. Protected-parent ACL restoration is attempted before recursive root restoration, and every cleanup attempt runs even after another fails. If retaining the fixture evidence also fails, that cause is aggregated with the initiating qualification and ACL-restoration failures rather than replacing them. A failed restoration cannot produce a passing report. This local journey requires macOS ACL support and neither invokes a model nor qualifies leased continuation or a native screen.

Checkpoints and rewind#

/checkpoint [label] records the exact model-visible context, /checkpoint list prints durable checkpoint event IDs, and /rewind <checkpoint-event-id> appends a new active lineage without deleting abandoned history.

A session transcript with a truncated tail is read up to the last valid event, refuses further appends, and must be continued in a child session. In the interactive attachment tray, /attach <relative-path>, /attachments, and /detach <id|all> manage bounded, workspace-jailed text and PNG, JPEG, GIF, or WebP inputs consumed by the next submitted turn.

/move &lt;directory&gt; in an interactive terminal or an RPC-backed conversation prepares the new system prompt and persists the session's working directory before publishing either in memory. Relative destinations resolve from the active directory, including after an earlier move. Subsequent SDK turns and reset use that active directory rather than the original session options. The operation writes and syncs a separate state file, preserves the original file permissions, then replaces state.json by rename. A refusal before replacement leaves the prior state file, active prompt and working directory intact; the error identifies the inspection, read, encoding, staging, permission, write, sync or publication operation and its path and cause. A failed staging cleanup is reported alongside the original error. This is an atomic replacement, not a directory-fsync durability guarantee.

Workspace adoption also uses this active-context transition, but adoption saves the configured workspace before rebasing the conversation. A rebase refusal does not undo that saved default: the current conversation remains at its prior working directory while the configured default may already name the new workspace.

The lifecycle journey includes tests/sessions/moves/move.mjs: real RPC moves, a subsequent relative move and reset, a directory obstructing its isolated state-file path, malformed JSON and non-object session state, an unreadable state file, a genuinely unwritable session directory refusing staging-file creation, and missing, non-directory and absent destination refusals. It compares the persisted working directory and exported checkpoint context after refusal, then performs a relative /move . to prove that the live directory still matches the retained state. It requires state decoding failures to identify the state path and cause without replacing the invalid input, checks measured filesystem error codes in RPC state-read and staging refusals, and restores the obstructed file and measured file and directory permissions. Every restoration step is attempted; a failed cleanup retains both the initiating error and all cleanup causes in the lifecycle report instead of replacing the original failure. A case passes only after its restoration succeeds.

The move journey also creates a real self-importing context file in its isolated destination. It requires the context-cycle refusal to name that file, preserves the prior state bytes and model window, and proves that a subsequent relative move still starts at the original directory. Removing the invalid destination context allows the ordinary move and reset flow to continue; no context loader is mocked.

The same lifecycle journey invokes tests/sessions/listing/read.mjs against a separate real session. It removes transcript read permission, measures the actual OS refusal, requires both CLI export and RPC checkpoint to expose that path and cause, and compares the transcript and active-leaf state with their prior bytes. After permissions are restored, the same session must retain its earlier checkpoint, omit the refused checkpoint and persist a new one. A permission-restoration failure is retained alongside the original qualification failure instead of replacing it. No fake reader or model response replaces the product.

tests/sessions/moves/mirror.mjs exercises the distinct partial-persistence boundary through RPC: the transcript remains appendable while its session directory refuses new state files. The checkpoint must report the exact committed event and the OS cause of the failed active-leaf mirror, preserve prior events and state bytes, and remain in the exported ledger. After restoring the directory permissions, a new checkpoint must publish its own active leaf without deleting the earlier committed event. If restoration fails, both the initiating qualification error and cleanup cause remain in the report; the case cannot pass. This is not a model-triggered secondary-recording test.

The move and mirror journeys measure refusal of the file-creation operation itself; the checkpoint and automatic-compaction journeys separately measure opening their real transcripts for append. Closing or removing a successfully opened probe cannot stand in for the required refusal. Unexpected descriptors and probe files are cleaned, original permissions are restored, and cleanup failures remain visible alongside the initiating qualification failure.

The lifecycle handoff-refusal cases retain the initiating RPC or assertion failure together with failures removing the isolated obstruction or restoring the original artifact. Both cleanup operations are attempted, and a case becomes passed only after restoration succeeds; a failed cleanup cannot leave a passed case in the retained report.

Restore instructions after compaction#

Lifecycle instructions belong in the model context, not a startup banner. Before an ordinary session's first model request, Jeden runs SessionStart hooks and records their context as system messages. After /compact, automatic compaction or handoff, it runs them again against the new window. Resume, reset, rewind, fork and branch restore them before the next model request. Model-only sessions do not run these hooks.

The hook receives source, session_id, transcript_path and cwd. Native additionalContext and event-specific hookSpecificOutput.additionalContext both contribute their complete text. This includes Tama's inject-operator-rules hook when the installed Tama registry declares it; Oko owns the standing rules and their original message references. Without Tama, ordinary user and project hooks use the same lifecycle.

A hook's nonzero exit or explicit refusal stops context restoration with its observed output. Invalid context fields identify their field and received value instead of becoming an empty instruction. The error begins SessionStart (&lt;source&gt;) for &lt;session&gt;:; the transition remains pending, so a later request cannot silently skip it. RPC clients receive the same failure, and session_start context snapshots in the exported ledger retain what was restored. No terminal banner is treated as proof that a model received a rule.

Automatic compaction failures stop the requesting turn with auto-compaction (&lt;reason&gt;) failed: &lt;cause&gt;, including when compaction runs after preparing an answer. They are not treated as a successful decision to skip compaction. The ledger records auto_compaction_error; if writing that event also fails, the returned error preserves both the original compaction cause and the recording failure. CLI and RPC-backed graphical conversations receive the same refusal.

Handoff prepares the child session, its checked system prompt and inherited retained work before replacing the active conversation. A child-creation failure says handoff could not prepare child session &lt;path&gt;: &lt;cause&gt;; an inheritance failure names both source and destination. Either leaves the original session active with its instructions and work. Once the prepared child becomes active, instruction restoration remains pending until its hook context is persisted successfully. CLI and RPC-backed graphical conversations share this transition.

Artifact failures happen before the active session changes. A directory-creation refusal says handoff could not create artifact directory &lt;path&gt;: &lt;cause&gt;; a brief-write refusal says handoff could not write brief &lt;path&gt;: &lt;cause&gt;. Both preserve the operating-system cause and reach terminal and RPC-backed conversation failure displays. The real lifecycle journey obstructs each artifact path only inside its isolated session, observes the actual filesystem error, checks the RPC refusal and original request ownership, and restores the saved artifact in finally.

The real tests/hooks/session-context.mjs journey also removes write permission from its own isolated session-root directory, observes the operating-system refusal, requests a handoff through RPC and verifies that the same original requests remain owned after refusal. It restores the measured directory mode in finally, retains the actual cause and before/after completion state, and uses the configured real model and hooks rather than a simulated handoff.

Reset, resume, fork and branch use the same child preparation. They persist the new seed context before publishing a different active recorder or discarding the old model window. Their child-creation and retained-work inheritance refusals name the transition and affected paths, so a failed reset cannot silently clear the conversation and a failed fork cannot move subsequent work to an unprepared child. The isolated lifecycle journey exercises both handoff and resume refusals against the real filesystem.

SDK and RPC prompts beginning with /compact, /handoff, /checkpoint, /rewind, /new, /fork or /branch invoke the active conversation’s native operation. They are not instructions for a model to imitate, and they do not open whichever session ran last in another client. Model-only requests remain literal model input. The lifecycle journey exercises actual reset, fork and branch preparation refusals as well as handoff and resume.

Durable context failures distinguish transcript append, transcript migration, active-leaf state publication and directory synchronization. Each refusal names the attempted operation and affected file or directory, preserving the operating-system cause; encoding failures name the event or state being encoded. The real lifecycle journey makes its own transcript unwritable, requests a checkpoint through RPC and checks both the exact observed append cause and the unchanged transcript digest before restoring the measured file mode.

CLI, interactive sessions and the RPC-backed Desktop and mobile conversations share this model window. In a configured session, use /compact from the terminal or the conversation input, then export the session and inspect the context snapshots. A readable registry or a successful hook command alone does not prove post-compaction delivery.

Keep project instructions while shortening a long investigation
jeden
# In the conversation, after working on the investigation:
/compact Preserve the investigation, evidence and unfinished work.
# Inspect the retained context from another terminal:
jeden export <session> <output>

Durable memory#

Durable memory uses the database named by JEDEN_DATABASE_URL (tables memories and memory_*), or Jeden's own ~/.jeden/state.sqlite3 when none is named. Hosts share memories when they use the same server database; a local SQLite file is local to its host. A server URL also requires JEDEN_DATABASE_CA_FILE for certificate verification. Jeden does not resolve or read this credential through Skarbiec. A database that cannot be opened is named by /memory stats and jeden doctor with the refusal below; an unreadable URL is identified without echoing credential bytes. PostgreSQL recall uses full-text ranking.

/memory enqueue, /memory queue, /memory queue run LIMIT LEASE_MS, /memory queue drain LIMIT LEASE_MS, and /memory rebuild expose durable worker and index maintenance; /memory rebuild reconstructs the memory index. run and drain process at most LIMIT jobs and claim each for LEASE_MS milliseconds, the time this worker holds a job before another worker may reclaim it; both are required positive integers with no default, and a missing or invalid one is refused by name. A failed job returns to the queue at once with its error and is claimable on the next pass; there is no attempt count or backoff. /memory queue lists every job.

Opening the durable state#

Memory, pursuit requests and relay rooms are kept in one database, opened once per process: the functionality jeden.state.open. JEDEN_DATABASE_URL names it as sqlite:&lt;file&gt;, postgres://, postgresql:// or mysql://; a server is verified against the certificate authority in JEDEN_DATABASE_CA_FILE. With the variable unset or empty, Jeden creates its own ~/.jeden/state.sqlite3 on first use, readable and writable by its owner only, and says so on standard error. A file JEDEN_DATABASE_URL names is opened only where it exists and is never created, and a database that cannot be opened is refused, never replaced by another store. Jeden then creates or upgrades its tables there.

Every check that reads only the environment runs before a file or the network is touched. Each refusal prints what failed, why, what was observed, then fix: … and cause: jeden.state.open.&lt;cause&gt;; jeden errors show jeden.state.open prints the causes below with their tests, which tests/state/open.mjs provokes through jeden pursue --status. A server that does not answer exits 69, since running the same command again can succeed; every other refusal exits 1.

  • url-not-unicode: JEDEN_DATABASE_URL is set, but its value is not Unicode text; the bytes are not shown. Fix: set the URL as text, or unset it.
  • url-scheme-unsupported: its scheme names no engine Jeden opens, observed: the scheme, or none when the value does not begin with &lt;scheme&gt;://, so a value that is no URL is not echoed. Fix: a SQLite, PostgreSQL or MySQL URL.
  • ca-file-missing: a server URL with JEDEN_DATABASE_CA_FILE unset or empty. Fix: name the server's PEM certificate authority file.
  • ca-file-unreadable: reading the certificate file &lt;path&gt; that JEDEN_DATABASE_CA_FILE names: the file cannot be read as text by this user, observed: what the system answered.
  • url-invalid: the database driver of its engine cannot read the URL, observed: the driver's answer. Fix: the form its engine takes.
  • stand-in-directory-uncreatable: creating ~/.jeden, the directory of Jeden's own state file …: … the directory cannot be created, observed: what the system answered. Fix: make it a directory this user can write, or name a database.
  • stand-in-not-a-file: something other than a file, such as a directory, is at ~/.jeden/state.sqlite3. Fix: move it aside, or name a database.
  • stand-in-file-uncreatable: ~/.jeden/state.sqlite3 does not exist and cannot be created, observed: what the system answered. Fix: make ~/.jeden writable by this user.
  • sqlite-file-unopenable: opening &lt;file&gt;: SQLite cannot open the file for reading and writing, observed: the driver's answer. Fix: give this user read and write access, point the URL at the file that exists on this host, or unset it.
  • server-unreachable: connecting to the &lt;scheme&gt; server JEDEN_DATABASE_URL names: the server did not accept a verified connection, observed: the driver's answer, without the URL's password; exit 69. Fix: start the server, or correct its address, credentials or certificate authority.
  • tables-uncreatable: creating Jeden's tables in &lt;database&gt;: the database refused the statements that create or upgrade Jeden's tables, observed: the database's answer, such as file is not a database. Fix: move a file that is not Jeden's database aside, or grant the account the right to create tables.
  • Opening the state uses jeden.home: the stand-in file and the database client's descriptor are under the home (JEDEN_STADO_HOME names another for the descriptor), and with no home found the refusal is its home-unknown, described on the CLI reference.

Reading and appending the ledger#

Every command and RPC method that reads or continues a recorded session reads its transcript.jsonl through jeden.session.ledger.read, and every event a session records is appended through jeden.session.ledger.append; jeden errors show with either id prints its causes with their tests (tests/sessions/moves/ledger.mjs). Each line is read in order: a line of the first ledger format is carried into the current one, a current line must decode as a sealed event, carry the schema version this build reads and seal to the checksum it records, and then follow the events before it. The last line of a ledger whose write was cut short is recovered as a truncated tail; any other damage refuses the read naming &lt;path&gt;:&lt;line&gt;, exit 1, and the fix is to restore the file, since Jeden never rewrites a recorded event.

The session's id is the one its state.json names, else its directory's name. Appending reads the whole ledger first, writes the event and makes it durable, then mirrors it as the active leaf into state.json; an event written before the mirror fails stays written and the refusal says so on a context: line.

  • transcript-unreadable and state-unreadable: cannot read &lt;path&gt;, observed: what the system answered. state-not-json and state-not-object: the state is no JSON object.
  • line-not-json (&lt;path&gt;:&lt;line&gt; is malformed JSON), line-not-event (is not a valid V2 event), schema-unsupported, checksum-mismatch (event &lt;id&gt; checksum mismatch, observed: the recorded and the actual seal) and legacy-line-invalid (a line of the first format without its ts, type or data, or of a type or version Jeden never wrote).
  • sequence-broken (breaks ledger sequence), event-duplicated, lineage-broken (breaks ledger lineage, observed: parent and active leaf), rewind-invalid (a rewind that leaves another event than the active leaf, has another parent than its checkpoint, or names an event that is no checkpoint of the active lineage), session-mismatch (belongs to session X, expected Y) and links-invalid (causation, correlation or outbox seeds).
  • Appending: tail-truncated (cannot append &lt;dir&gt;: transcript has a recovered truncated tail; resume into a child session), transcript-unwritable (the ledger cannot be opened, written or synced), state-unwritable (cannot create active-leaf state file …, with the context event &lt;id&gt; committed, but active leaf mirror update failed), directory-unsyncable and event-unencodable.

Configuration and context#

Process environment wins over every file. User config loads from ~/.jeden/config.json and ~/.jeden/config.yml; project config loads from <cwd>/.jeden/config.json and overrides user config.

A configuration layer that exists and cannot be read, is not JSON or YAML, has no object at its root, or holds a value its setting cannot take is never read as empty: every jeden command refuses to start with Error: configuration &lt;path&gt; cannot be read: &lt;cause&gt;, … is not valid: &lt;cause&gt; or … does not hold valid settings: &lt;cause&gt;. A layer that breaks during a run stops that run with the same sentence; a file that does not exist is no layer.

Environment files load from the selected workspace (.env, .env.local, .env.production, .env.vercel, in that order) and then ~/.jeden/.env before a command runs; a variable the environment already names is never replaced. Each line is a KEY=value declaration with no whitespace in the key, a # comment or blank. Any other line, including export KEY=value, whitespace before the key or =, and a line without =, stops every command with &lt;file&gt;: line index &lt;n&gt; (zero-based) holds `&lt;line&gt;`, not KEY=value instead of being skipped. /setup reads and writes ~/.jeden/.env through the same reader, so it refuses the same line rather than offering to set a key the file already tries to hold.

A trailing # outside quotes begins a comment; the same text inside a quoted value remains part of the value. /setup quotes values that would parse differently, including a hash, whitespace, embedded quotes or backslashes; the next run reads those bytes intact.

Double-quoted values use JSON string escaping, including embedded quotes and backslashes. An unclosed quote or invalid escape refuses the file and zero-based line index with the parser's cause rather than loading a partial value.

When /setup updates an existing key, it leaves unrelated lines and their original line endings unchanged. An unreadable file is refused before any rewrite, with its path and read cause.

Before each run, Jeden loads user context from ~/.jeden/instructions.md and ~/.jeden/context.md. Project context walks from the project ancestor to --cwd and reads:

  • JEDEN.md
  • AGENTS.md
  • CLAUDE.md
  • RULES.md
  • .jeden/instructions.md
  • .jeden/context.md
Inspect and save the user environment
jeden run "/setup status" --json
jeden run "/setup agent-id operator-id" --json

Communication and functionality contracts#

The contracts.communication setting tells Jeden how to write to you. The contracts.functionality setting tells it how to carry out work and what must be complete before it answers.

The built-in communication contract asks for plain sentences under three headings: what was done, actual blockers, and decisions or actions that genuinely belong outside the agent. An answer holds only what you asked: no recommendation, opinion, choice of Jeden's own or extra section you did not ask for. Work Jeden can perform stays in execution, not in a next-steps list. Each heading holds only what concerns your latest message: hooks, guards, task ledgers and verification runs appear only where they stopped that work. A guard or hook that interrupts a turn is settled with tool calls, and an answer already given is not sent again; a message reports work done and never replaces work Jeden can still do. Your own text replaces the default; none disables that wording, not the native completion checks.

Jeden adds the contracts to every new or rebuilt system prompt after its built-in engineering and task contracts. They supplement the built-in rules and cannot relax tool grants, path jails, safety checks, or evidence requirements. jeden run /prompt shows the contract in force, and config/contracts/get reports which one it is in communicationSource (default, operator, or disabled) with the default text in communicationDefault.

The CLI and Jeden Desktop Settings screen edit the same user defaults in ~/.jeden/config.yml; the Settings screen also shows the default text while it is in force. A project may override either key in <cwd>/.jeden/config.json.

Jeden Desktop reads and writes these settings over RPC as the functionality jeden.config.settings: config/contracts/get|set, config/communication/get|set and config/language/get|set; jeden errors show jeden.config.settings prints every cause with its test (tests/config/settings.mjs). Every read and write first reads each configuration layer that applies where jeden rpc runs, so one that exists and cannot be read, is not JSON or YAML, has no object at its root or holds a value its setting does not take — even one broken while the server runs — is never read as the defaults and never written over: a get answers {refusal, path} with the declared refusal of jeden.config.read, a set refuses with config_write_failed and the same text, and the server answers the next request. jeden config set, reset and unset refuse the same way. config/task-limits/get answers the cause in refusal and config/task-limits/set refuses with invalid_params. The Jeden Desktop Settings screens show that refusal.

An OMP session follows the same rule through Jeden's answer-scope extension, packages/omp-answer-scope, which OMP loads from its extensions setting (omp config set extensions with the path to index.ts). Which actions you forbade — compiling, building, installing, running tests — and which sentences of an answer tell you one of them was not done, is waiting or is blocked are judged by the model Stado's inference family names for Jeden (stado capabilities call inference --consumer jeden), in any wording or language (nie kompiluj, Kod jak zwykle nieskompilowany), not by a list of words. Your rulings count as your words: an action the operator-rulings extension stopped in this session (the refused tool call's result carries its stop) is forbidden there too, and a judgment that leaves one out is refused. Each prompt carries a reminder of them, and each such sentence stops the session before it ends: the extension names it and the session writes its answer again without it. When your latest message asks about the action, the answer may speak of it. A judgment the model cannot give is the extension's error, named, and the other rules below still decide. The same stop is refused when the answer ends the turn on work it says it is doing or will do (wypycham ponownie, teraz biorę następne zadanie, I'll fix it next) or announces work left open (Czego nie zrobiłem, Co zostaje otwarte, Następne kroki, next steps): OMP stops a session only once its background jobs are idle, so nothing of that work runs, and the extension names each such sentence and asks for the work instead; an answer to your question about the plan (co dalej?) may say what comes next. It is refused as well when it states a cause or a fact as a guess (prawdopodobnie, chyba, niepotwierdzona, likely, probably): the session reads what shows it — the logs, the code, a command's output — and says what that shows, or says plainly that it is not known. It is refused when it hands you an action to take (uruchom, wklej, zaloguj, zainstaluj, please run, you need to): you run nothing for the session, so the extension names each such sentence and the session does the action itself — sign-ins through Weles, builds and installs through Stado — and answers with what was done. An answer with no words — a lone period, or nothing after the last tool call — never ends a turn. When your latest message says not to code (do not code., nie koduj, stop coding, no coding, przestań kodować), every tool call is refused, reads included, and the prompt says so: the answer is words from what is already in hand. Your next message lifts it. When your latest message asks for yes or no (tak czy nie, tak lub nie, tak albo nie, a closing czy nie, yes or no), the answer is Tak or Nie alone on its first line, followed only by the numbered lines your communication contract appends; any other answer is refused before the session ends. Messages the harness writes into the conversation (a background job's result) are not read as yours, so they neither lift a rule nor count as your question. None of these rules touches a session a program reads — OMP's print and json modes (omp -p: a harsh reviewer, a judge) and a subagent, whose answer its parent reads — since its answer is that program's input and its messages are not yours. Words are matched whole in every script, so a Polish word ending in ę or ć is read as a word. The real journey is node tests/contracts/answer_scope_omp.mjs: it registers the extension's handlers and hands them session branches carrying your words and answers this session gave, starting no OMP child, since your settings deny running another agent from a session, asks the same model the extension asks, and keeps every answer in .build/answer-scope/&lt;run&gt;/report.json.

Jeden's operator-rulings extension, packages/omp-operator-rulings, warns an OMP session before it acts against a ruling of yours, without being asked. Before a shell command that builds, compiles, formats, tests, installs or releases runs (cargo build|check|test, swift build|test, xcodebuild, make, npm|bun install|build|test, stado product install|update|sync, …), it asks the register of your rulings whether that action may run now: the register Stado's alternatives name for Jeden (stado capabilities resolve work-registers --consumer jeden --json, Oko today) and its one admission decision, admit ACTION --product P --session S --json, where the product is the repository the command runs in and the session is the OMP session's id. Only what the shell runs is read: quoted strings and heredoc bodies are text a program reads, so a commit message saying make cargo build faster asks nothing. A refusal stops the command with the ruling's own words and tells the session not to reach it another way; the verdict holds until your next message. When Stado names no register (a Stado release that does not declare the work-registers family answers family-unknown), or the register answers no verdict, the command is stopped too, naming which read failed and that it answers once Stado names a register program and that register answers admit: a ruling that cannot be read is no permission. A command run in no repository is asked with no product (admit ACTION --session S --json), since your rulings on the session and on every session decide it all the same: a session started in your home directory runs every command outside a repository, and asking nothing there let each of them run. Its stop says the register was asked with no product and that the command, run from a product's repository, is asked about that product. A program a standing ruling of yours forbids every session (no-run:&lt;program&gt;, such as no-run:cargo) is stopped whatever it is asked to do and wherever it runs, with the ruling's words: cargo metadata builds nothing and is still cargo. That list is read when your message arrives and a command is held against the last list read, never made to wait for one, and a ruling counts only while its own words name the program, as Oko's conduct guard reads it. Your message starts the verdicts for every action of the session's own repository at once, or with no product when the session started in none, so a command meets an answer already asked; a register slower than OMP's extensionHandlers.toolCallTimeoutMs for a command elsewhere stops that first command by OMP's timeout, and the verdict it was asking for is kept, so the next attempt is answered at once. The real journey is node tests/contracts/operator_rulings_omp.mjs, which registers the extension's handler and hands it real bash calls against real git, Stado and the register, and keeps every answer in .build/operator-rulings/&lt;run&gt;/report.json.

Jeden's model-switch extension, packages/omp-model-switch, keeps an OMP session from changing its model unseen. OMP's auto-retry may move a request to another model or provider (retry.modelFallback, retry.usageAwareFallback, retry.fallbackChains in its settings); each such switch is written into the conversation as a shown message naming the model it left, the model it took, the role and OMP's reason (or that OMP gave none), and the request that then succeeds on the new model is written too, so the transcript keeps every switch for Oko. The real journey is node tests/contracts/model_switch_omp.mjs, which hands the extension's handlers the events OMP emits and keeps what was shown in .build/model-switch/&lt;run&gt;/report.json.

  • parameter-invalid (invalid_params): reading the parameter &lt;name&gt; of RPC &lt;method&gt;: &lt;method&gt; takes &lt;name&gt; as text, and the request holds &lt;what it holds&gt;, observed: the parameters the request names. Every parameter is required: communication and functionality; mode, toolCalls, toolResults, reasoning and code; language.
  • parameter-unexpected (invalid_params): &lt;method&gt; takes &lt;its parameters&gt;, and `&lt;name&gt;` is none of them; a get takes no parameters. Both are refused before any file is read.
  • A value its setting does not take is jeden.config.value-invalid (config_write_failed), such as reading the value of ui.language: ui.language takes one of: auto, …, and `xx` is not that; nothing is written.
  • setting-undeclared: a setting the method names is missing from the schema compiled into the build. working-directory-unreadable: config/communication/get|set cannot learn the directory jeden rpc runs in, whose project layer the policy in force folds in; start it again from a directory that exists.
Set, inspect, replace, or turn off the contracts
jeden config get contracts.communication
jeden config set contracts.communication "Answer in Polish using three plain sentences."
jeden config set contracts.communication none
jeden config reset contracts.communication
jeden config set contracts.functionality "Finish the requested behavior before answering."
jeden config reset contracts.functionality

Task contract and delivery report#

Every ordinary user turn, including a delegated task, carries Jeden’s built-in task contract. Completion means durable, reusable product functionality rather than a one-off action. Only an assigned implementation task authorizes product changes: a question, request to read or explain, or planning request does not. Defects related to the assigned task are repaired at their source; diagnostics must make failures actionable; and applicable CLI, GUI, and public documentation surfaces must agree. A recorded open defect of a product the session works on is assigned work that is repaired, not explained away, and a turn does not end while the session holds an open task or open defect. An operator contract, the communication contract included, changes only on the operator's explicit instruction; a defect report is not one.

Behavioral tests live in the product’s tests/&lt;area&gt; tree and execute a complete lifecycle through the real product, its real interface, and real dependencies, observing the final state rather than accepting mocks, canned responses, dry runs, or syntax checks. Tests may be created and run directly with the product’s own tools; Probierz is optional. Every run retains its exact source revision, commands, exit statuses, supported reports, traces, screenshots and recordings, and actual result.

No one script runs every journey and no npm script compiles a contract suite. Each real journey is a file under tests/&lt;area&gt; run with node; it states the variables it needs at its top, most of them the binary JEDEN_BIN names and the source revision JEDEN_TEST_SOURCE_REVISION names, and it records that revision, the binary's digest, the commands, exit statuses and final state. The test step a release runs is the one .wisent-release.json declares, node tests/release/stage.mjs, which builds the real binaries on the release worker. Model access uses the configured Brama identity and remains a real dependency.

The report explains functionality, diagnostics, cli, gui, documentation, tests, delivery and followOn. It is an execution agent's claim, not evidence of completion. The independent acceptance pass still checks the real result and every retained original request.

Version 3 adds followOn: before reporting, the agent reviews the finished change for every way it can be done better (a faster path, fewer reads of a slow dependency, a clearer refusal, an actionable error code, a diagnostic that shows the cause at once, the feature the user reaches for next) and every task that follows from it (the same defect elsewhere, the functionality that keeps it from returning, each surface, refusal, runbook entry, document and test the change touches, the work it unblocks). Each is one evidence item starting with done: (done in this work, with where), recorded: (where it is recorded and the cause it cannot be done now) or open: (still to do). An item with none of the three is refused for correction with report.followOn.evidence item "…" starts with none of done:, recorded: or open:: say whether it is done in this work, recorded with its cause, or still to do. Every open: item is sent back to the agent as work, recorded as a follow_on_tasks ledger event with outcome continued, and the next report reviews the result again, so tasks keep being added and done until none is open. When the invocation has no step left, the turn fails with Task contract not satisfied: the report leaves follow-on tasks open and the invocation has no step left: … and the event's outcome is rejected; the open tasks are never handed to the user as a next-steps list.

Version 2 of the contract adds the time to completion: before implementation the task gets an estimate and the user is told when it will be done, that first estimate is never changed to fit the result, and the actual time is reported beside it. Jeden records the estimate at intake and measures the time to verified completion itself, so the time is not a report entry and the model cannot flatter it.

A malformed report is returned for correction while the invocation has steps available. Exhaustion remains a failed invocation with retained work. CLI, TUI, SDK, RPC and headless share these checks; model-only turns and Pursuit's separately reviewed stages retain their own output contracts.

An unusable answer records a contract_violation with rule model-answer. The exact refusal returns to the model while the observed failures change and any caller-supplied --max-steps permits continuation; there is no fixed correction count. Repeating the same malformed answer or the same provider cut-off cause stops the invocation with the original cause, repeatedFailure: true and a durable run_error. The diagnostic distinguishes malformed JSON from a provider output cut-off and names the actual output budget when supplied. The retained request remains open. Jeden Desktop shows the same violation as an answer correction rather than a report correction.

If recording the violation or terminal refusal fails, CLI and RPC-backed conversations retain the initiating provider or parsing cause alongside the answer-recovery failure and its filesystem cause. A missing durable event is not evidence that the model request succeeded or that retained work is complete. An appended event whose active-leaf mirror cannot be updated is reported as committed with a failed mirror update, not as a successful recovery or an unwritten event.

The RPC config/contracts/get and config/contracts/set results include taskContract: a localized, versioned built-in description containing instructions, the eight requirements (id, title, and description) and timeToCompletion (title and description). It is read-only, not a third editable operator contract, and Jeden Desktop shows it read-only beside the editable communication and functionality settings. /prompt shows the contract active for the current session.

Required final action shape
{
  "action": "final",
  "text": "Concise answer.",
  "report": {
    "functionality": {"status": "done", "explanation": "Reusable behavior implemented.", "evidence": ["src/feature.rs"]},
    "diagnostics": {"status": "done", "explanation": "Failures identify the cause and recovery.", "evidence": ["src/diagnostics.rs"]},
    "cli": {"status": "done", "explanation": "The existing CLI flow exposes the behavior.", "evidence": ["src/cli.rs"]},
    "gui": {"status": "not_applicable", "explanation": "This change has no GUI surface.", "evidence": []},
    "documentation": {"status": "done", "explanation": "Public usage is documented.", "evidence": ["web/docs/pages.mjs"]},
    "tests": {"status": "done", "explanation": "The real lifecycle and final state ran through Probierz.", "evidence": ["Probierz run jeden/feature"]},
    "delivery": {"status": "blocked", "explanation": "Release signing credential is unavailable.", "evidence": []},
    "followOn": {"status": "done", "explanation": "Reviewed the change for improvements and follow-on tasks.", "evidence": ["done: the refusal now names the missing field, src/feature.rs", "recorded: the same parser in the importer waits on its owner's release, recorded in the task register"]}
  }
}
Inspect the active and RPC-projected contract
jeden run "Implement the requested reusable behavior"
/prompt
printf '%s
' '{"id":"read-contracts","method":"config/contracts/get","params":{}}' | jeden rpc

Parking an RPC process that has nothing to do#

Stado places every Jeden Desktop tab as stado workload attach jeden-session, and the attach holds the kind’s declared reservation — two cores and 4 GiB — for exactly as long as jeden rpc lives. A handful of idle tabs, each stopped at its first model call with a completion blocker, can hold more cores than the laptop has at 0.0% CPU, and the laptop then refuses every fleet build with reservations_exhausted.

When the process is started with JEDEN_PARK_AFTER_SECONDS, which Stado fills from the kind’s park_after_seconds, it looks at itself once every declared park time. It parks when no prompt is in flight, no open session has an active request, and no frame has arrived from its client for the declared time; it parks after one quiet check when every open session carries a completion blocker, because a blocker is not work. A process therefore parks between one and two park times after it went quiet. Parking sends one frame, {"type":"parked","reason":"idle"|"blocked","quietSeconds":…,"parkAfterSeconds":…,"sessions":[{"sessionId":…,"blocker":…}]}, writes jeden rpc parked (idle): nothing ran for N s to standard error, disposes every session to its ledger through the ordinary shutdown path, and exits 0. Stado’s attach then sees its runtime end and releases the reservation, and --resume brings the session back whole.

Parking never ends work. A turn, a tool call, a question waiting for the operator and a completion continuation all count as a prompt in flight for as long as they run, however long that is. Without the setting nothing parks, which is what every client other than a Stado attach gets. A value that is not a whole number of seconds above zero refuses the process before ready with JEDEN_PARK_AFTER_SECONDS must be a whole number of seconds above zero, got "…", so an unreadable declaration never turns into “never park”.

On the existing RPC connection that owns a session, session/status with its returned sessionId answers {"activeRequestIds":[...]}. These are requests still executing or queued in that owning runtime, not a count inferred from transcript age. A request remains active through tool execution, answer review, automatic compaction, state persistence and final result publication. A final transcript event can precede those operations; run_error with recovering: true records recovery in progress rather than an idle session.

Use status to inspect an editor or automation session you already own; starting another RPC process does not give it ownership of a session in the first process. An unknown session or an unreadable active-request lock is a refusal, not an empty active list. An empty list says no request is active at that observation, not that retained tasks are complete, and it is not an atomic grant to start another writer or terminate the process. Consumers must preserve ownership and operation admission rather than turn this read into a check-then-act race.

To close an idle SDK-backed session without cancelling work, send {"id":"retire-owned-session","method":"session/retire","params":{"sessionId":"the ID returned by session/new or session/open"}} on its owning jeden rpc connection. Retirement checks the active-request set and seals new admission under that same lock. Active requests cause a refusal naming their IDs and leave admission, cancellation flags and registration unchanged; successful cleanup returns {"disposed":true} and removes registration. Unlike session/dispose, this operation never chooses to cancel admitted work. It is an SDK/RPC ownership primitive, not authority over an unrelated terminal session or proof that retained tasks are complete.

In Jeden Desktop, open the selected session's Conversation screen and choose Retire session when it is ready. The action uses the same atomic request; a server refusal leaves the owning session in place and shows its actual message in the conversation. Sending another prompt is disabled while retirement is pending. After confirmation, Desktop closes its RPC input, removes its recovery registration and keeps the durable transcript; failures in either cleanup operation are shown separately rather than reported as successful cleanup. Reconnect opens the retained session again through normal host selection. Retirement never marks unfinished tasks complete.

Retirement acknowledgement does not prove that the Stado connection exited successfully. If that process subsequently fails, Desktop shows its actual exit status, captured Stado refusal and last connection status instead of silently keeping an idle success state. When neither detail was captured, it says so explicitly. This failure does not automatically reconnect a deliberately retired session.

A failed live connection uses the same complete diagnostic: exit status, captured Stado refusal and last connection status are distinct observations, and none replaces another with an empty message. Ordinary connection loss retains its existing recovery policy; a previously recorded initiating failure is not overwritten by a later process exit.

Disposal and prompt admission share the active-request synchronization boundary. A prompt that reaches admission after disposal has sealed the session refuses with session disposed before entering the active request set; a prompt admitted earlier remains visible to disposal's cancellation. This protects SDK and RPC-backed clients without treating transcript silence as lifecycle authority.

Subscription and interaction-handler registration check the disposal seal while holding their own mutation lock, so cleanup cannot be followed by late registration from an earlier check. A disposal attempt seals admission but does not treat that seal as proof that cleanup succeeded: repeated calls still perform cleanup and return its actual failed operation and lock cause. RPC retains the session registration if cleanup fails and removes it only after successful cleanup; failures identify the owning session. No global session-registry lock is held while waiting for conversation cleanup.

A failure to remove a finished request from the active set is returned with its request identity and lock cause, not reported as successful completion. If publishing a request's failure event also fails, the RPC or SDK error retains the initiating error and adds the failed publication operation and cause. RPC cleanup likewise preserves an initiating prompt failure when ending its event subscription, forwarding events or joining the forwarder fails; the error identifies the RPC request and the failed operation. A forwarder panic retains its string payload, or explicitly identifies a non-string payload instead of inventing its contents. A consumer must not turn either refusal into an idle observation.

If retaining the session path after an SDK request fails, the error names that request and the actual lock failure. A failed prompt keeps its initiating cause alongside this secondary retention error rather than being replaced by a generic poisoned-lock message. CLI RPC and Desktop receive the same SDK error.

If returning a failed prompt's RPC response also fails, the runtime retains the original prompt or cleanup cause together with the actual response-delivery failure. During RPC shutdown, a failed cancellation identifies the active request and its actual cause rather than silently claiming cancellation succeeded. These are failure diagnostics, not evidence that the session became idle or that its retained work is complete.

A one-shot jeden run worker owns its own conversation, not an RPC session in another process. Its result includes task-outcome and final session-path persistence: these writes cannot fail silently behind a successful exit. If saving the last-session reference fails after a failed turn, the diagnostic retains both the turn's cause and the persistence operation and workspace. Supervisors must observe that worker's actual completion and result; an earlier transcript answer or an unrelated RPC status does not establish it.

The real tests/hooks/session-context.mjs journey reads status after completed compaction, disposes its own isolated session, requires a subsequent prompt to refuse with that unknown session's identity, and compares the persisted transcript digest before reopening through the normal resume flow. It also retires its isolated session after genuine missing-hook executable refusals, verifies registration was removed and preserves the exact failed transcript bytes. These cases exercise actual RPC ownership and ledger preservation; they do not by themselves qualify active-retirement refusal or every concurrent admission/disposal ordering.

With JEDEN_TEST_COMPACTION_THRESHOLD stated, the same journey runs tests/hooks/compaction/journey.mjs: each case starts its own RPC process with that threshold, so the first answer crosses it, and configures a real SessionStart hook process that refuses only the compact restoration. The answer must report auto-compaction (threshold) failed with the hook's cause, the ledger must hold auto_compaction_error, and the still-pending restoration must refuse the next request without another model action. In the second case the hook first makes the session's own transcript unwritable and proves the append is refused, so the answer must also carry recording the failure also failed with the transcript path and measured OS error, and the transcript must hold exactly the bytes it held when the hook ran; the journey restores the transcript mode afterwards.

Watch a process park
printf '%s\n' '{"id":"open","method":"session/new","params":{}}' \
  | (cat; sleep 20) | JEDEN_PARK_AFTER_SECONDS=5 jeden rpc

Communication modes#

The communication.mode setting chooses what Jeden shows of its own work while it answers. normal shows tool names while Jeden works and then the answer with its code. debug also shows every tool call with its input, every tool result, and the model's reasoning when the route streams it. quiet shows only the answer.

Four keys override one item each and default to auto, which follows the mode: communication.toolCalls, communication.toolResults, communication.reasoning, and communication.code. Setting a key to show or hide wins over the mode, so debug with communication.toolResults hide shows calls and reasoning but no results.

Hiding code replaces every fenced code block in an answer with [code hidden: N lines] and tells the model to answer in prose; tools still write and run code. The setting is read at the start of every turn, so /settings set communication.mode quiet changes the next turn of a running session, and Jeden Desktop edits the same values on its Settings screen. The session transcript records every tool call, result, and answer regardless of the mode.

Choose a mode and override one item
jeden config set communication.mode debug
jeden config set communication.toolResults hide
jeden config set communication.code hide
jeden config get communication.mode
jeden config reset communication.code

Screen language#

The ui.language setting chooses the language of Jeden's screens and the one it answers in. auto follows your messages; a language code pins it. The languages offered are the fleet's list every Wisent product offers (wisent-texts languages.json), with each language's own name; every screen text reads in each of them, and a test fails the build when one lacks a text.

Jeden Desktop edits the same value on Settings → Language through RPC config/language/get, which answers language, auto and languages (code, english, native), and config/language/set with {"language": CODE}. A code outside the list is refused as config_write_failed with jeden.config.value-invalid (reading the value of ui.language: ui.language takes one of: auto, …, and `xx` is not that), a missing language as invalid_params with jeden.config.settings.parameter-invalid. A user configuration that cannot be read stops jeden rpc before it answers, as every command does (configuration &lt;path&gt; is not valid: &lt;cause&gt;); one broken while it runs is answered with that refusal, as the contracts section above says, and neither is ever overwritten. The real journeys are node tests/config/language.mjs and node tests/config/settings.mjs with JEDEN_BIN and JEDEN_TEST_SOURCE_REVISION.

Pin the language, then follow your messages again
jeden config set ui.language de
jeden config get ui.language
jeden config reset ui.language