Leave. Return. Keep going.

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.

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 with task <id> criterion <n> names <path>, and no accepted observation happened there. 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.

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.

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 export, show, artifacts, artifact, search-sessions, resume, and recall_conversation inspect or reuse recorded work. 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 sessions
jeden show <session>
jeden export <session> <output>
jeden artifacts <session>
jeden artifact <session> <name> <output>
jeden resume <session> "continue"
jeden search-sessions "query"
jeden recall_conversation --list

Adopt existing work#

jeden workspace discover [path] validates an existing directory without writing. jeden workspace adopt <path> 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 <workspace>/.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 <path> 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.

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.

jeden workspace discover /path/to/repository
jeden workspace adopt /path/to/repository
jeden workspace status

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.

Durable memory#

Durable memory uses SQLite/FTS at ~/.jeden/memory.sqlite3 by default. JEDEN_MEMORY_DB selects another database; legacy JEDEN_MEMORY_FILE remains an input-path override.

/memory enqueue, /memory queue, /memory queue run, /memory queue drain, and /memory rebuild expose durable worker and index maintenance; /memory rebuild reconstructs the memory index.

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.

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

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. Work Jeden can perform stays in execution, not in a next-steps list. 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 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.

Behavioral tests live in the product’s tests/<area> 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.

npm run test:contracts compiles the real contract suite once, selects the exact executables from Cargo's artifact report, signs the native product, and runs the returned test executable directly. It never invokes Cargo again after signing. target/contract-runs retains source revision and changes, signed binary digests, command output and final state. Model access uses the configured Brama identity and remains a real dependency.

The report explains functionality, diagnostics, cli, gui, documentation, tests and delivery. 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.

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 answer that never arrives usable is corrected the same way, under the same event: a cut-off or unreadable answer is quoted back to the model once inside the turn as a contract_violation with rule model-answer, then the turn ends if the second answer is unusable too. The refusal says what happened to the answer — model answer stopped mid-JSON after 191 bytes: a JSON string is never closed; the answer was cut off by the output budget of 48 tokens — instead of a JSON parser's column, and the retained request stays open for the next turn. Jeden Desktop shows the same event as an answer correction rather than a report correction.

The RPC config/contracts/get and config/contracts/set results include taskContract: a localized, versioned built-in description containing instructions and requirements (id, 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.

{
  "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": []}
  }
}

jeden run "Implement the requested reusable behavior"
/prompt
printf '%s
' '{"id":1,"method":"config/contracts/get","params":{}}' | 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.

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