@namzu/sdk 43.0.0 → 44.1.0

package/CHANGELOG.md

@@ -1,5 +1,525 @@
 # Changelog
 
+## 44.1.0
+
+### Minor Changes
+
+- 51af1b3: Plan mode now refuses a change that a permission rule allows. Before, a batch whose every call a rule allowed (for example `permissions: { bash: 'allow' }`) ran without reaching the review handler, so a turn in plan mode, whether it started there or the operator entered it with Shift+Tab mid-turn, still ran `touch` or any other allowed command, while the model had been told that every change is refused. The CLI now asks the kernel to send such batches to review while it is in plan mode; nothing changes in any other mode.
+
+  For SDK hosts: `QueryParams.reviewAllowedCalls?: () => boolean` is new and optional. Read once per batch; `true` sends a batch a rule allows, or a grant from earlier in the turn covers, to `resumeHandler` instead of running it, each call carrying the gate's decision in `authorization`. A rule's `deny` still refuses. Absent, behaviour is unchanged.
+
+- 406e7a2: A task removed with `task_update` status `deleted` is now distinguishable on the stream: its `task_updated` event carries `deleted: true` (the SSE `task.updated` event too), with the subject and status the task had when it went. Before, a removal arrived as an update that changed nothing, so the interactive terminal kept drawing the removed task as an open step in the checklist. It now drops the task and writes `Removed task · <subject>`. The field is optional and absent on every other update; a consumer that ignores it sees the same events as before.
+
+### Patch Changes
+
+- 0d23de8: The planning tools `task_create`, `task_update` and `task_list` now present themselves in words to a host: `Add task · <subject>`, `Start task`, `Complete task`, `Check tasks`, a hidden result view when a call succeeds, and `Tasks · N/M done` for a listing. No presented view carries a task id, an owner or the JSON arguments any more; a host that renders the generic presenter used to show `Task update({"id":"01a0…","status":"completed"})` above `Task 01a0… updated — status: completed`. The model-facing output still names the id it needs. `task_create` and `task_update` add `subject` to their result `data`, and `task_list` says `1 task:` rather than `1 tasks:`. Nothing to change on upgrade unless a host matched the old presented strings.
+
+## 44.0.0
+
+### Major Changes
+
+- 9355755: Checkpoint retention is part of every checkpoint store, and a failed prune no
+  longer ends a turn.
+
+  - `SessionCheckpointStore.prune(scope, keepLast)` is **required**. It deletes
+    a turn's oldest committed checkpoints until `keepLast` newer ones remain and
+    returns the deleted ids, which the kernel records as `checkpoint_pruned`. It
+    never deletes a checkpoint an open decision references, and it counts and
+    deletes only checkpoints a `checkpoint_written` record commits. A custom
+    store implements it; the optional `pruneCheckpoints` it replaces is gone.
+    `selectSessionCheckpointsToPrune` is the selection the built-in stores use.
+  - A prune that throws after an iteration's checkpoint is logged
+    (`Checkpoint retention failed; older checkpoints are kept for now`) and the
+    turn continues. Before, the error failed the live turn.
+  - Listing parked work no longer reads checkpoints at all:
+    `SessionIndex.listPendingDecisions` and `listTurns` answer from the index.
+
+- 755a81a: Consolidation no longer writes the same learning twice. `consolidationEntry` now adds a `knowledge:<digest>` tag, `metadata.knowledgeDigest` and `type: 'project'`, the digest covering the turn's decisions, discoveries and failures. Before writing, the runtime calls the new `isConsolidated(store, entry)` and skips the write — and its `memory_consolidated` event — when a consolidation with that digest already exists, archived included. This is the deduplication `createMemoryPromoter` already did.
+
+  Why major: the duplicate records were a defect — search filled with copies of one learning — but a documented event and a store write that used to happen on every settled turn with `consolidateInto` now do not happen for a turn whose learnings match an earlier one. A host that counted `memory_consolidated` events or records per turn observes that as a changed default, whatever the reason for it.
+
+  What changes for a host passing `consolidateInto`: a turn whose learnings are identical to an earlier consolidation's writes no record and emits no `memory_consolidated` event. A host that expected one record per turn should look for the earlier record by its `knowledge:<digest>` tag. A host comparing `consolidationEntry(...).tags` exactly sees one more tag. There is no switch to restore a write per turn; a host that needs one writes the entry itself with `store.create(consolidationEntry(...))`.
+
+- cb1f00c: A session held in memory stays in memory: its checkpoints, its token ledger
+  and the child sessions it delegates to. Before, such a session kept only its
+  evidence in memory and wrote its ledger and checkpoints to disk, one tree per
+  call with nothing that removed it.
+
+  **What changes for you.**
+
+  - A `query()` (or agent) whose `sessionLog` is an `InMemorySessionLog` and
+    which names no `paths` and no `checkpointStore` keeps its checkpoints and
+    ledger in memory, with the log. A later call with the same log can resume
+    the same turn. A host that wants those files on disk passes `paths` (a
+    `SessionPaths`) or its own `checkpointStore` and `tokenBudgetStore`.
+  - With no `tokenBudgetStore`, the ledger lives where the checkpoints live. A
+    host that passes an `InMemorySessionCheckpointStore` and later copies its
+    checkpoints into a new one to resume must pass the same
+    `InMemorySessionTokenBudgetStore` to both calls; otherwise the resume fails
+    because the ledger its checkpoint names is missing.
+  - `BaseAgentConfig` takes `sessionLog` and `checkpointStore`, which
+    `ReactiveAgent` and `SupervisorAgent` forward to `query()`. A
+    `SupervisorAgent` held in memory sets `AgentTaskContext.childStorage`
+    (`ChildSessionStorage`), and `AgentManager` then gives each delegated child
+    its own `InMemorySessionLog` (and the supervisor's `checkpointStore`, if it
+    named one) unless the child's config names a `sessionLog` or `paths`. Such a
+    child writes nothing under `NAMZU_HOME`. A host that pairs `query()` with its
+    own `LocalTaskScheduler` sets `childStorage` on the context it builds.
+
+  `InMemorySessionTokenBudgetStore` is a process-local
+  `SessionTokenBudgetStore` that refuses the same regressions
+  `DiskSessionTokenBudgetStore` refuses.
+
+- 933ba6d: `read_memory`'s output is no longer the memory body alone for text and Markdown records.
+
+  For a store that implements `getRecord` — `DiskMemoryStore`, `InMemoryMemoryStore` and `MarkdownMemoryStore` all do — `read_memory` now appends, after the body, a `---` line, then when the memory was last updated and how old it is, a notice to verify named files and functions when it is older than today, and each `[[name]]` link resolved. This is what lets the model see that a memory is a point-in-time claim.
+
+  What breaks: a host that displayed or parsed `read_memory`'s `output` as the stored body sees the footer after it. A record saved with `format: 'json'` is unaffected — its output is still exactly the stored text and still parses — so only prose records change.
+
+  What to do: take the body from the store (`store.get(id)`) rather than from the tool's output, or strip everything from the last `\n\n---\n`. `data` carries `updatedAt`, `name`, `type` and the resolved `links` for every format.
+
+- 3e7a97b: The run is gone. The kernel's model is now **session → turn → message**: a
+  session is one conversation with one agent, a turn is one unit of work inside
+  it (a prompt, a goal round, a resident step, a verification step), and a
+  subagent is a child session. Each session is recorded in one append-only,
+  hash-chained JSONL log under `NAMZU_HOME`, and that log is the source of
+  truth; SQLite is only an index rebuilt from the logs. See
+  `docs/sdk/session-log.md` for the record schema.
+
+  **Before you upgrade: resolve or abandon parked runs on 43.x.** Run
+  `drainRuns` (or `resumeRun`) on the old version until nothing is parked. This
+  version cannot read a run tree, a `RunState`, an old checkpoint or an old token
+  ledger, so a run still parked when you upgrade cannot be resumed. There is no
+  migration.
+
+  ## What breaks
+
+  **Identity and ids.**
+
+  - `RunId`, `generateRunId`, `asRunId`, `parseRunId` and `isEntityId(v, 'run')`
+    are removed. Use `TurnId`, `generateTurnId`, `asTurnId`, `parseTurnId` and
+    `'turn'`. A new `RecordId` names a log record.
+  - Every `generate*Id` mints a UUID version 7 instead of v4, so ids sort by
+    creation time as strings. Every id check still accepts versions 1 to 8.
+  - Anywhere a `runId` field named the owner of something, it is now
+    `sessionId`, plus `turnId` where the thing belongs to one turn:
+    `ToolContext` (third-party tools read `context.sessionId` and
+    `context.turnId`), the context a guardrail receives, `StepResult`,
+    `PrepareStepContext`, `AnswerReviewContext`, probes and provider
+    instrumentation, deliverables, plans and approval requests, bus owners,
+    background-job owners, tasks, working memory and `HandoffLockRejected.details`
+    (`turnId: TurnId`).
+    `parentRunId` becomes `parentSessionId` plus `parentTurnId`.
+
+  **Core types (rename, same meaning unless noted).**
+
+  | Removed                                                                                                                                                                                                   | Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+  | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `Run`, `AgentRun`, `AgentSession`                                                                                                                                                                         | `Turn`, `AgentTurn` (`Turn` gains `sessionId`; `replayOf` becomes `forkedFrom`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+  | `RunExecutionStatus`, `RunStatus`, `deriveRunStatus`                                                                                                                                                      | `TurnExecutionStatus`, `TurnStatus`, `deriveTurnStatus` (same members)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+  | `RunCancelled`                                                                                                                                                                                            | `TurnCancelled`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+  | `AgentRunConfig`, `RunConfigSnapshot`, `RunMetadata`, `RunStateMetadata`                                                                                                                                  | `TurnConfig`, `TurnConfigSnapshot`, `TurnMetadata`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+  | `RunPersistence`, `RunPersistenceConfig` (`.runConfig`)                                                                                                                                                   | `TurnRecorder`, `TurnRecorderConfig` (`.turnConfig`; `pruneKeepLast` stays on it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+  | `RunEvent`, `RunEventListener`, `PersistedRunEvent`, `RUN_EVENT_SCHEMA_VERSION`, `RunEventSchemaVersion`                                                                                                  | `SessionEvent`, `SessionEventListener`, `SessionRecord`, `SESSION_RECORD_SCHEMA_VERSION`, `SessionRecordSchemaVersion` (the event field `schemaVersion` becomes the record field `v`)                                                                                                                                                                                                                                                                                                                                                                                       |
+  | `RunEventCursor`, `RunEventReplay`, `RunEventReplayRefusal`, `RunEventLogHead`, `resolveRunEventReplay`                                                                                                   | `SessionLogCursor`, `SessionLogReplay`, `SessionLogReplayRefusal`, `SessionLogHead`, `resolveSessionLogReplay`                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+  | `RunState`, `RUN_STATE_VERSION`, `parseRunState`, `RunStateVersionError`, `captureRunState`, `loadRunState`, `RunStateScope`                                                                              | `TurnState`, `TURN_STATE_VERSION` (1), `parseTurnState`, `TurnStateVersionError`, `captureTurnState`, `loadTurnState`, `loadSelectedTurnState`, `TurnStateScope`. `parseTurnState` refuses a `RunState` by name.                                                                                                                                                                                                                                                                                                                                                            |
+  | `resumeRun`, `ResumeRunParams`                                                                                                                                                                            | `resumeSession`, `ResumeSessionParams` (same outcomes: `no-checkpoint`, `awaiting-decision`, `resumed`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+  | `claimRun`, `releaseRun`, `RunLease`, `ClaimRunOptions`                                                                                                                                                   | `claimSession`, `releaseSession`, `SessionLease`, `ClaimSessionOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+  | `drainRuns`, `DrainRun`, `DrainRunsParams`, `DrainRunsResult`                                                                                                                                             | `drainParkedTurns`, `DrainTurn`, `DrainTurnsParams`, `DrainTurnsResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+  | `listDurableRuns`, `paginateDurableRuns`, `toDurableRunEntry`, `DurableRunEntry`, `DurableRunOrder`, `DurableRunPage`, `ListDurableRunsOptions`, `CheckpointListingScope`, `assertContiguousListingScope` | `SessionIndex.listTurns` and `listPendingDecisions`; `DurableTurnEntry`, `DurableTurnOrder`, `DurableTurnPage`, `ListDurableTurnsOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+  | `DelegatedChildRun`, `ChildRunStorage`, `RunHierarchyNode`                                                                                                                                                | `ChildSessionSummary` (`SessionIndex.listChildren`), `ChildSessionStorage`, `SessionTreeNode`                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+  | `replayRun`, `RunSummary`                                                                                                                                                                                 | `replayAudit`, `AuditSummary`. Audit entries are `audit` records in the session log; `AuditEvent.runId` becomes `turnId?`.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+  | `RunQuery`, `RunQueryOptions`, `RunTranscriptUnavailableError`, `RunTranscriptUnavailableReason`                                                                                                          | `SessionQuery`, `SessionQueryOptions`, `SessionTranscriptUnavailableError`, `SessionTranscriptUnavailableReason`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+  | `RunReporter`, `createRunReporter`, `recordRunDuration`                                                                                                                                                   | `TurnReporter`, `createTurnReporter`, `recordTurnDuration`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+  | `RunApprovalPolicy`                                                                                                                                                                                       | `SessionApprovalPolicy` (`ApprovalPolicy` is unchanged and still the `{ name, handler }` value)                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+  | `RunEvidence*`, `RunTextEvidence*`, `DiskRunEvidenceOptions`, `createDiskRunEvidenceSource`, `createDiskRunTextEvidenceSource`                                                                            | `SessionEvidence*`, `SessionTextEvidence*`, `SessionEvidenceSourceOptions` (`{ scope, logPath, … }`), `createSessionEvidenceSource`, `createSessionTextEvidenceSource`; `ToolContext.captureRunEvidence` becomes `captureSessionEvidence`. Its source's scope is the session, not the turn: it reads every earlier turn in the session log and the running turn up to its latest record (the old capture read the running run's own transcript and nothing else). A reader for one turn only is `createSessionTextEvidenceSource` with `scope.turnId` over the session log. |
+  | `RUN_STATUS_READ_MODEL_ID`, `RunStatusReadModelOptions`, `RunStatusState`, `createRunStatusReadModel`                                                                                                     | `SESSION_STATUS_READ_MODEL_ID`, `SessionStatusReadModelOptions`, `SessionStatusState`, `createSessionStatusReadModel`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+  | `SharedRunWorkspace*`, `RegisterSharedRunPlanInput`                                                                                                                                                       | `SharedSessionWorkspace*`, `RegisterSharedSessionPlanInput`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+  | `BidiRun`, `BidiRunParams`, `BidiRunEvent`, `startBidiRun`                                                                                                                                                | `BidiTurn`, `BidiTurnParams`, `BidiTurnEvent`, `startBidiTurn`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+  | `deriveRunOptions`, `DeriveRunOptionsInput`                                                                                                                                                               | `deriveTurnOptions`, `DeriveTurnOptionsInput`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+  | `EvalRun`, `evalRunFromQuery`, `evalRunFromRun`                                                                                                                                                           | `EvalTurn`, `evalTurnFromQuery`, `evalTurnFromTurn`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+  | `RunMemoryCandidate`, `RUN_MEMORY_TAG`                                                                                                                                                                    | `SessionMemoryCandidate`, `SESSION_MEMORY_TAG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+  | `SubsessionSpawnedEvent`, `SubsessionMessagedEvent`, `SubsessionIdledEvent`, `SubsessionLifecycleEvent`                                                                                                   | `ChildSessionSpawnedEvent`, `ChildSessionMessagedEvent`, `ChildSessionIdledEvent`, `ChildSessionLifecycleEvent`                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+  | `ReadRunEventsOptions`                                                                                                                                                                                    | `ReadSessionLogOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+  | `CheckpointRunScope`                                                                                                                                                                                      | `CheckpointScope` (`{ tenantId, projectId, sessionId, turnId }`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+  | `ReplayAttribution` (`Run.replayOf`)                                                                                                                                                                      | `TurnForkOrigin` (`Turn.forkedFrom`, `{ sessionId, turnId, checkpointId }`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+  | `validateTokenBudgetSnapshot`, `OpenTokenBudgetOptions`, `DiskTokenBudgetStoreConfig`                                                                                                                     | `validateSessionTokenBudgetSnapshot`, `OpenSessionTokenBudgetOptions`, `DiskSessionTokenBudgetStoreOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+  | `TurnStatusResolver.blockingRun`, the handoff deps field `runStatus`                                                                                                                                      | `blockingTurn`, `turnStatus` (on `SingleHandoffDeps` and the broadcast deps)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+  | `Agent.forRun()`, `AbstractAgent.forRun()`                                                                                                                                                                | `forTurn()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+  | `AgentHandle.queueForNextRun()`                                                                                                                                                                           | `queueForNextTurn()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+  | `CaseResult.run`                                                                                                                                                                                          | `CaseResult.turn`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+  | `AdvisoryBudget.maxCallsPerRun`, `maxCostPerRun`                                                                                                                                                          | `maxCallsPerTurn`, `maxCostPerTurn` (the advisory stack is built per turn, so the bound always was)                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+  **`query()`, `drainQuery()` and `runAgent()`.** `query()` is now
+  `AsyncGenerator<SessionEvent, Turn>` and `drainQuery()` resolves to a `Turn`.
+  `QueryParams.runConfig` is `turnConfig`. `runStore`, `pathBuilder`,
+  `claimFence`, `emergencySave` and `supersedesEmergencySave` are gone
+  (`ReactiveAgentConfig.emergencySave` goes with them); pass
+  `paths` (a `SessionPaths`), `sessionLog`, `checkpointStore`, `lease`, `budget`
+  and `tokenBudgetStore` instead, and `turnId` with `resumeFromCheckpoint` to
+  continue a turn. `RunAgentResult.run` is renamed `turn`; `runAgent`,
+  `RunAgentOptions` and `RunAgentResult` keep their names.
+
+  **One active turn per session.** Starting a turn while the session has one
+  running, paused or interrupted throws `TurnInProgressError` (`sessionId`,
+  `activeTurnId`, `state`); `isTurnInProgressError` recognises one across package
+  copies. A paused turn is continued with `resumeSession` (same `turnId`) or
+  closed with the new `abandonTurn(sessionId, turnId, reason)`. Parallel work
+  goes to child sessions or separate sessions. Manual compaction between turns is
+  `compactSession`.
+
+  **A rate limit on a turn's first request pauses it.** A retryable provider
+  fault (a 429, an outage, a stalled stream) that survives the retries used to
+  fail the turn when it hit before the turn's first checkpoint, which in
+  practice meant its first request; the same fault after a checkpoint paused
+  it. It now pauses there too, on a checkpoint of the turn where its loop began
+  (`iteration: 0` for a fresh turn, the restored count for a resumed one), and
+  `resumeSession` restarts the turn from where that loop began. Everything the
+  turn did since then is discarded: every iteration it ran before the fault,
+  completed ones included (a partial `max_tokens` answer and the continuation
+  prompt after it, a structured-output re-prompt), is not in the resumed
+  request, and none of those iterations' guards is counted. So after such a
+  fault the session holds a paused turn, and the next `query()` or `runAgent`
+  in it throws `TurnInProgressError` until the turn is resumed or closed with
+  `abandonTurn`: a caller that retried by starting a fresh turn resumes instead.
+  The returned `Turn` has `stopReason: 'paused'` rather than `status:
+'failed'`, the event is `turn_paused` rather than `turn_failed`, and a paused
+  turn's `lastProviderError` now carries the classification (retry delay
+  included) that only a failed turn carried before. A permanent fault still
+  fails the turn.
+
+  **Event literals.** `run_started`, `run_completed`, `run_failed`, `run_paused`
+  and `run_resuming` are `turn_started`, `turn_completed`, `turn_failed`,
+  `turn_paused` and `turn_resuming`. `subsession_spawned`, `subsession_messaged`
+  and `subsession_idled` are `child_session_spawned`, `child_session_messaged`
+  and `child_session_idled`. Every event drops `runId`, carries `sessionId`, and
+  carries `turnId` inside a turn. The other 54 literals are unchanged.
+  `isEphemeralEvent` is now exported at runtime.
+
+  **Other string literals.** `HandoffLockRejectedReason` (and
+  `HandoffLockRejected.details.reason`) `'active_run'` is `'active_turn'`.
+  `ResidentConsumptionAttempt.receiptStatus` `'duplicate-run'` is
+  `'duplicate-turn'`. A caller that compares either value must match the new
+  one.
+
+  **Delegation records.** The parent turn appends `child_session_spawned` and
+  `child_session_ended` to its own log, reading them from the task scheduler's
+  new optional `onChildSessionEvent(callback)`. `LocalTaskScheduler` and
+  `DelegatingTaskScheduler` implement it. A host `TaskScheduler` that does not
+  still delegates, but its parent log names no children, so `SessionIndex`
+  cannot list them: implement it to keep them listable.
+
+  **Storage.**
+
+  - `RunStore`, `RunDiskStore`, `InMemoryRunStore` and `RunStoreConfig` are
+    removed, with `writeRunMeta`, `writeMessages`, `readMessages`, `writeReport`,
+    `addToIndex`, `listRuns` and `listChildren`. Use `SessionLog`
+    (`DiskSessionLog`, `InMemorySessionLog`): metadata comes from records,
+    messages from `foldSessionMessages`, and listing from `SessionIndex`
+    (`openSessionIndex`, `SqliteSessionIndex`, or `ScanSessionIndex` where
+    `node:sqlite` is unavailable). `readRunEventsIn` and `readRunMessagesIn` are
+    `readSessionLog` and `foldSessionMessages`. `RunMessageSnapshot` is removed.
+  - `CheckpointStore`, `DiskCheckpointStore` and `InMemoryCheckpointStore` are
+    `SessionCheckpointStore`, `DiskSessionCheckpointStore` and
+    `InMemorySessionCheckpointStore`, keyed by `CheckpointScope { tenantId,
+projectId, sessionId, turnId }`. `prune(scope, keepLast)` is **required**; it
+    was the optional `pruneCheckpoints`. A checkpoint document holds no messages
+    and is refused on restore when it no longer matches its log. A child
+    session's checkpoints are in its own directory,
+    `<parent-session-dir>/subagents/<child-id>/checkpoints/`; a
+    `DiskSessionCheckpointStore` you build for a child takes that place as its
+    `session` option (`DiskSessionLog.locator`, which a log opened from its
+    file path reads from that path, and which names the right place only for
+    a file in that project's layout).
+    `IterationCheckpoint` and the kind `run-checkpoint` are replaced by the
+    `Checkpoint` document (`kind: 'checkpoint'`); an old one is refused by name.
+  - `TokenBudget`, `TokenBudgetStore`, `DiskTokenBudgetStore`,
+    `InMemoryTokenBudgetStore`, `openTokenBudget` and their snapshot types are
+    `SessionTokenBudget`, `SessionTokenBudgetStore`,
+    `DiskSessionTokenBudgetStore`, `InMemorySessionTokenBudgetStore`,
+    `openSessionTokenBudget` and `SessionTokenBudget*Snapshot`. The ledger is
+    keyed by `(rootSessionId, rootTurnId)`, so each root turn has its own limit
+    and a limit changed between turns no longer throws `Token budget root limit
+mismatch`. `TokenBudgetBinding` is `TurnBudgetBinding`. A version 1 snapshot
+    is refused.
+  - `SessionStore.appendMessage`, `replaceMessages`, `loadMessages` and
+    `loadSessionMessages` are removed: messages are written only by the turn
+    recorder and read with `foldSessionMessages`. A custom `SessionStore` drops
+    those methods. `SqliteSessionStore` and `SqliteSessionStoreConfig` are
+    removed; `SessionIndex` replaces them.
+  - Tasks live under `<session-id>/tasks/<task-id>.json`, one store per
+    session: `DiskTaskStoreConfig` is `{ paths, session, tenantId?, logger? }`,
+    and a store opened on another session's tasks throws
+    `TaskSessionMismatchError`. Each task records the turn that created it;
+    `selectTaskContext(tasks, { turnId, turnStartedAt })` gives the tasks a turn
+    sees (every open task, plus those it closed). The task tools take a
+    `TaskToolScope` of `{ sessionId, turnId, turnStartedAt }`.
+  - `MessageFeedbackStore` is keyed by `(sessionId, messageId)` under
+    `<session-id>/feedback/`, and feedback on a message the session log does not
+    hold throws `UnknownMessageError`.
+  - Custom log backends are checked with `defineSessionLogConformance` from
+    `@namzu/sdk/testing`. `defineCheckpointStoreConformance` and its types are
+    removed, and so are `CHECKPOINT_STORE_CONTRACT_VERSION`,
+    `CheckpointStoreCapabilities` and `DiskCheckpointStoreAttribution`: a
+    checkpoint store is keyed by `CheckpointScope`, and `prune` is part of the
+    interface rather than a capability to probe.
+  - `validateTokenBudgetBinding` is removed with no replacement of its own. It
+    checked the budget binding a checkpoint carried; a checkpoint's binding is
+    now checked with the rest of the document by `parseCheckpoint` (the
+    `budget.binding` of `CheckpointSchema`).
+
+  **The emergency surface is removed.** `EmergencySaveManager`,
+  `EmergencySaveData`, `EmergencySaveConfig`, `EmergencySaveConfigSchema`,
+  `EmergencySaveId`, `generateEmergencySaveId`, `asEmergencySaveId`,
+  `EMERGENCY_DIR_NAME`, `EMERGENCY_EVENTS`, `EMERGENCY_SIGNALS` and
+  `projectEmergencyToCheckpoint` are gone. The log and the per-iteration
+  checkpoints hold everything a dump held. `prepareReplayState`,
+  `PrepareReplayInput` and `PreparedReplayState` are `prepareForkState`,
+  `PrepareForkInput` and `PreparedForkState`, and `fromCheckpoint: 'emergency'`
+  is no longer accepted: the selector (`CheckpointSelector`) is a checkpoint id
+  or `'latest'`. A replay forks a **new session** whose `session_started.forkedFrom`
+  names the source `{ sessionId, turnId, checkpointId }`.
+
+  **Layout.** Everything lives under `NAMZU_HOME` (default `~/.namzu`,
+  `resolveNamzuHome`): `projects/<slug>/<session-id>.jsonl` plus
+  `projects/<slug>/<session-id>/` for child logs, spills, checkpoints, budgets,
+  tasks, feedback, goals and the lease, and `projects/<slug>/{memory,residents,
+worktrees}/`. `SessionPaths`, `ensureProject`, `slugForCwd` and `tempRoot`
+  compute it. `DefaultPathBuilder` and `PathBuilder` are removed. Nothing is
+  generated under the working directory: the default git worktree directory
+  moves from `<repoRoot>/.namzu/worktrees` to `projects/<slug>/worktrees/`. A project
+  id is minted once per working directory into `projects/<slug>/project.json`.
+  Old run trees, `sessions.sqlite`, checkpoints, ledgers and resident learning
+  databases are not read.
+
+  `defaultStateRoot`, `NAMZU_STATE_DIR` and `projectIdForDirectory` were on
+  unreleased `main` and never shipped; they are not in this release. Neither is
+  the per-run message history of that branch (`RunHistory*`: `openRunHistory`,
+  `loadRunHistory`, `resolveRunHistory`, `compactRunHistory` and the rest, with
+  their `history/messages.<g>.jsonl` files). Its idea, that each message is
+  stored once, is the session log's `message` record: a message is appended
+  once, when it ends, and a resume or a compaction refers to it by its
+  `messageId` instead of copying it.
+
+  **Hooks.** Hook events `run_start`, `run_end` and `run_interrupt` are
+  `turn_start`, `turn_end` and `turn_interrupt`; a config naming an old event is
+  refused with a message naming the new one (`RENAMED_PLUGIN_HOOK_EVENTS`).
+  Shell-hook stdin `run_id` becomes `turn_id` and `parent_run_id` becomes
+  `parent_session_id` plus `parent_turn_id`; env `NAMZU_RUN_ID` becomes
+  `NAMZU_TURN_ID`. `session_id` and `NAMZU_SESSION_ID` are always present;
+  `turn_id` and `NAMZU_TURN_ID` are absent on `session_start` and `session_end`.
+  `PluginHookContext.runId` is `turnId?`.
+
+  **Memory.** Consolidation tags are `session:<id>` and `turn:<id>` (not
+  `run:<id>`), with `metadata.sessionId` and `metadata.turnId`. The source value
+  the session promoter stamps is `'session-memory'` (was `'run-memory'`), and
+  `MarkdownMemoryStore` leaves records with that source out of its index.
+
+  **Protocols and wire contracts.**
+
+  - `WireRun`, `WireRunStatus`, `toWireRunStatus`, `RunConfig`,
+    `RunConfigSchema`, `RunIdSchema`, `CreateRunRequest`, `CreateRunSchema`,
+    `CreateStatelessRunRequest`, `CreateStatelessRunSchema`, `RunUsage`,
+    `RunStopReason`, `StreamEvent` and `StreamEventType` are `WireTurn`,
+    `WireTurnStatus`, `toWireTurnStatus`, `WireTurnConfig`, `TurnConfigSchema`,
+    `TurnIdSchema`, `CreateTurnRequest`, `CreateTurnSchema`,
+    `CreateEphemeralSessionRequest`, `CreateEphemeralSessionSchema`,
+    `WireUsage`, `WireStopReason`, `SessionStreamEvent` and
+    `SessionStreamEventType`.
+  - `WireTurnStatus` gains `awaiting_input`: `awaiting_hitl` and
+    `awaiting_hitl_resolution` map to it (they mapped to `running`), and A2A
+    maps it to `input-required`.
+  - SSE event names `run.*` are `turn.*`, with `session_id` and `turn_id`.
+    `mapRunToStreamEvent` is `mapSessionEventToStreamEvent`.
+  - A2A: `contextId` now names a **session**; it used to carry the project id.
+    Any string is accepted and mapped to one session. A client that sent its
+    project UUID as `contextId` gets one session for it, and its tasks queue
+    there one at a time. `Task.id` is the turn id. `runToA2ATask`,
+    `mapRunToA2AEvent`, `runStatusToA2AState`, `RUN_STATUS_TO_A2A`,
+    `CreateRunFromA2A` and `a2aMessageToCreateRun` are `mapTurnToA2ATask`,
+    `mapTurnToA2AEvent`, `turnStatusToA2AState`, `TURN_STATUS_TO_A2A`,
+    `CreateTurnFromA2A` and `a2aMessageToCreateTurn`. `TURN_STATUS_TO_A2A` is
+    keyed by `WireTurnStatus`, so it has the new `awaiting_input` key.
+  - ACP: the default session id is a UUIDv7 instead of `acp_<n>`, and a prompt
+    while a turn is active is refused with `INVALID_REQUEST`.
+  - Telemetry: `NAMZU.RUN_ID`, `NAMZU.RUN_STATUS` and `NAMZU.RUN_PARENT_ID` are
+    removed; spans carry `NAMZU.TURN_ID` (`namzu.turn.id`), `NAMZU.TURN_STATUS`
+    and `NAMZU.SESSION_PARENT_ID`, plus `gen_ai.conversation.id` set to the
+    session id. The span `namzu.agent.run <name>` is `namzu.agent.turn <name>`
+    and the histogram `namzu.run.duration` is `namzu.turn.duration`.
+
+  ## New
+
+  - The session-log schema: `SessionRecord`, `SessionRecordSchema`,
+    `parseSessionRecord`, one `*RecordSchema` per record type,
+    `TurnBoundSessionEventType`, `Checkpoint` with `parseCheckpoint`, and
+    `recordSha256`, `parseSessionLogLine` and `formatSessionLogLine` for one log
+    line.
+  - `resolveA2AContext` (with `A2AContextResolution`) and
+    `resolveExternalSession` (with `ExternalSessionLookup`,
+    `ExternalSessionResolution` and `ResolveExternalSessionOptions`): how a host
+    server resolves an A2A `contextId`, or any protocol's own session id, to a
+    session through the index.
+  - `PrepareStepContext.turnStartedAt`: when the turn began. A resumed turn
+    keeps the time of its `turn_started` record, whichever process wrote it.
+  - `ChildSessionStorage` gains a `disk` kind (`{ kind: 'disk', paths }`). A
+    parent on disk hands its layout to the children it delegates to, so their
+    logs nest under it whether or not a layout was named. Code that switched on
+    `kind` must handle the new member.
+  - `resolveNamzuHome` and `NamzuHomeError` (moved from the CLI, same
+    behaviour), `SessionPaths`, `ensureProject`, `slugForCwd`,
+    `hashedSlugForCwd` and `tempRoot`.
+  - `fixtureId.turn` and `fixtureId.record` in `@namzu/sdk/testing`.
+  - `releaseHeldSessionLeases({ timeoutMs? })` (with
+    `ReleaseHeldSessionLeasesOptions` and `ReleaseHeldSessionLeasesResult`), for
+    a process about to exit: it releases every session lease the process holds,
+    leaving a running turn `interrupted` so the next writer can abandon or
+    resume it at once instead of waiting out the lease. After the first call
+    every claim in the process is refused with `SessionLeasesReleasedError`. A
+    host that stops on SIGTERM calls it from its signal handler; the CLI does.
+    `SessionLog.release` now waits for the log's append in flight, so a release
+    never lands under a half-written record.
+
+  ## What to do
+
+  1. On 43.x, drain or abandon every parked run.
+  2. Rename imports per the table above; the compiler finds every one.
+  3. Replace `runStore`/`pathBuilder` with `sessionLog` (or `paths`), and read
+     results from `Turn` and the session log instead of `run.json` or
+     `messages.json`.
+  4. Re-implement a custom store against the session-log conformance suite, and
+     a custom checkpoint store with the required `prune`.
+  5. Update hook configs, dashboards and any A2A client that put a project id
+     in `contextId`.
+
+- a84dc1c: `runAgent` no longer mints a new `projectId` for every call. When you pass no
+  `projectId`, it is the project of `workingDirectory` (default
+  `process.cwd()`): `ensureProject` mints one UUIDv7 the first time a directory
+  is used, writes it to `<NAMZU_HOME>/projects/<slug>/project.json`, and every
+  later call in that directory adopts it. Two processes that start in a new
+  directory at the same moment get the same id. Every session started in one
+  directory is filed under one Project, in one `projects/<slug>/` tree.
+
+  **What changes for you.** Two `runAgent` calls in the same directory now
+  return the same `identity.projectId`. `sessionId`, `topicId` and `tenantId`
+  are still generated per call, so the calls stay separate conversations. To get
+  the old behaviour, pass `projectId: generateProjectId()` on each call. An
+  explicit `projectId` always wins.
+
+- b064cea: A turn can make a file tool's path outside its roots, or a command outside its
+  sandbox, a reviewed question instead of a refusal. Both are opt-in and default
+  to the old refusal: `QueryParams.outsideRootAccess: 'review'` and
+  `QueryParams.sandboxEscape: 'review'` (also on `ReactiveAgentConfig`).
+
+  **What can break.** `AuditOutcome` (and the session log's `audit.outcome`)
+  gains `'approved'`, written for each approved crossing. A consumer that
+  switches exhaustively over the outcome must handle it; `replayAudit` skips it.
+  A session log written by this version with such a record does not parse in an
+  older SDK.
+
+  **New, all optional.** `ToolCallSummary.escalation` names what a call reaches
+  (`outsidePaths`, `sandboxEscape`); an escalated call is always reviewed, and a
+  gate `allow`, a remembered grant, a read-only declaration and `accept-edits`
+  decline to approve it alone. A sandbox escape runs only when the decision lists
+  its id in the new `confirmedEscalations` (on `approve_tools` and
+  `modify_tools`); `createReviewHandler` asks for it in every mode, and refuses it
+  without a `prompt` (`SANDBOX_ESCAPE_UNATTENDED_REFUSAL`) unless
+  `unattendedSandboxEscape: 'allow'`. A path outside the roots is likewise asked
+  about in every mode (`auto` and a remembered `approve-all` included) and
+  refused without a `prompt` (`OUTSIDE_ROOTS_UNATTENDED_REFUSAL`); `strict`
+  refuses it, and `plan` asks about it when every call in the batch only reads.
+  A refused crossing is an audit record with outcome `refused`, a `deny` rule's
+  refusal included. Tools declare `pathArgument` and
+  `sandboxEscapeArgument`; the executor hands an approved call
+  `ToolContext.approvedPaths` or `sandboxEscapeApproved`. The shipped file tools
+  declare `pathArgument: 'path'`; `bash` gains an optional
+  `dangerously_disable_sandbox` input, refused with `SANDBOX_ESCAPE_NOT_APPROVED`
+  unless approved. `pathOutsideRoots`, `toolRoots` and `OUTSIDE_ROOTS_GUIDANCE`
+  are exported. `resolveWithinReal` now canonicalizes a root that does not
+  exist yet (an approved path a `write` is about to create) instead of refusing
+  every path under it. A file tool's refusal of a path outside its roots now says how
+  the boundary is widened instead of ending at "Tools may only reach".
+
+- 3641102: Working memory leaves the system messages of every model request, a new
+  `PromptPlacement` value `'context'`, and closing requests end with their
+  closing directive.
+
+  **What breaks.**
+
+  - **The working-memory slot is no longer a system message in a request.** The
+    slot (pins, and a `workingMemoryProvider`'s block) keeps its place in the
+    session's history, checkpoints and compaction: the last leading system message.
+    Every request now takes it out of the system messages and sends it after the
+    history as a user-role message with source
+    `{ type: 'runtime-context', kind: 'step-context' }`. It is therefore missing
+    from the system messages every provider receives, from the
+    `request_envelope` event's `systemPrompt`, and from the system messages a
+    `pre_llm_call` hook sees. There is no option to keep the old placement. The
+    message's first line is the label every step-context message carries,
+    `Current step context (runtime-generated; not a new user request):`, and the
+    slot follows verbatim, so the content no longer _starts_ with
+    `WORKING_MEMORY_HEADER` and `isWorkingMemoryMessage(content)` answers `false`
+    for it.
+  - **`PromptPlacement` gains `'context'`.** The union is also an output type:
+    `PromptContribution.placement` and `PromptContributionRegistry.list()` can
+    now hand back `'context'`, so a `switch` over it with an exhaustiveness
+    check stops compiling.
+  - **The closing directive is last.** On the forced-final step at a resource
+    limit and on the request after an empty completion, the
+    `[SYSTEM] ...` message of kind `limit-finalization` now comes after every
+    request-only context message (working memory, `context` contributions,
+    step context, derived work context) instead of before some of them.
+
+  **What to do.**
+
+  - A host that finds the slot in a captured request by looking for a system
+    message starting with `WORKING_MEMORY_HEADER` looks instead for a
+    `step-context` message, drops its first line, and tests the rest with
+    `isWorkingMemoryMessage`. A host that rewrites or strips the slot in a
+    `pre_llm_call` hook does the same. Code reading the session's history or a
+    checkpoint needs no change.
+  - Code that switches over `PromptPlacement` adds a `'context'` case.
+  - A test asserting the closing directive's position expects it last.
+
+  **Why, and what is new.** A driver may hoist every system message ahead of the
+  conversation (Anthropic renders tools, then system, then messages), so a slot
+  that changes whenever a pin does invalidated the cached conversation prefix and
+  re-read the whole history at full price. After the history, a caching driver
+  ends its breakpoint before it and a pin costs only its own tokens. A
+  `PromptContribution` registered with `placement: 'context'` is rendered before
+  every model request, with `iteration`, exactly as `turn` is, and delivered the
+  same way: one labelled `step-context` message after the history, never pushed
+  onto it. `turn` is unchanged and keeps system authority; use `context` for
+  observations, `turn` for text that must act as an instruction.
+
+### Minor Changes
+
+- 8805360: `BaseAgentConfig.pruneKeepLast` sets checkpoint retention for a turn started
+  through `ReactiveAgent` or `SupervisorAgent`, the same way
+  `turnConfig.pruneKeepLast` does for a raw `query()` turn. Both agents build
+  their turn config from a hand-listed literal, so a host that bounded its own
+  turns could not bound a delegated child session's, and the child kept every
+  checkpoint. Absent keeps every checkpoint, as before.
+- a14b013: Memories can be typed and kept as one Markdown file each.
+
+  - `MarkdownMemoryStore({ directory })` implements `MemoryStore` with one `<name>.md` per memory (YAML frontmatter `name`, `description`, `type`, `status`, `createdAt`, `updatedAt`, `tags`, then the body) and a generated `MEMORY.md` index, one line per active memory of at most 150 characters. The index lists only what someone chose to keep: a record with `metadata.source: 'session-memory'` (the session memory promoter) or `metadata.kind: 'consolidation'` stays in the store and in search but is never listed, so a host carrying the index in its system prompt keeps the same prompt, and its prompt cache, when a turn writes one. Lines are ordered `feedback` and `user` memories not saved by the model first, then the model's (`save_memory` stamps `metadata.source: 'agent-memory'`), then the rest, by name within each, so the 200-line cap drops `project` and `reference` lines before an operator's `feedback` or `user` one. It keeps `DiskMemoryStore`'s guarantees: the shared operation lock, atomic private (0600) writes, and refusal — naming the file — of anything it cannot read. It never writes what it would refuse: a NUL character in the body, title, summary, description or a tag, or a file over 256 KiB, is refused before the write with the new `MemoryContentRejectedError` (`reason: 'too_large' | 'nul_byte'`), which `save_memory` and `update_memory` return as a failed result. Two files left with one id by an interrupted rename — both stating their own, different `updatedAt`, or an older hand-written file with no `id` and no `updatedAt` beside the renamed file that carries its name-derived id — are resolved by the later one (the hand-written file dated by its modification time; when it is the newer file it is a new memory under a renamed one's old name, and the pair is refused), the older set aside as `<name>.md.superseded` at the next write; any other pair claiming one id, a hand copy that states its `id` but no `updatedAt` included, is refused naming both files. `readIndex({ maxLines })` renders the index for a prompt, capped at 200 lines by default with a note pointing to `search_memory`, and `readIndex({ derived: true })` lists only the derived records, newest first, for an operator's inspection; `importRecord` moves records in from another store idempotently by id. While a `DiskMemoryStore` `index.json` sits in the same directory, every other operation is refused until its records are imported and the index moved aside.
+  - `MemoryIndexEntry`, `CreateMemoryParams` and `UpdateMemoryParams` gain optional `name`, `description` and `type` (`user | feedback | project | reference`). All three shipped stores persist them, and refuse a `name` another record holds with the new `MemoryNameConflictError`, which names that record. Omitting the fields behaves exactly as before; an existing store, index or custom `MemoryStore` needs no change.
+  - `save_memory` and `update_memory` take `name`, `type` and `description`; a taken name returns a failed tool result pointing at `update_memory`. `read_memory` and `update_memory` accept a memory's name as well as its ID. `search_memory` lines show name, type and age. (`read_memory`'s age footer changes its output and is described in its own changeset.)
+  - `createMemoryRecallStep` adds `name`, `type` and, for a record older than `ageNoticeAfterMs` (default one day), an `age` field, and then ends its block with `MEMORY_VERIFY_NOTICE`. A block of records updated within the day is unchanged apart from the new fields.
+  - New helpers: `renderMemoryIndex(records, { maxLines })` (over `MemoryRecord`s, since who wrote a record is in its metadata), `memoryIndexLine`, `memoryLinkNames`, `describeMemoryAge`, `slugifyMemoryName` (names derived from a title are at most 32 characters, so an index line keeps room for its description), `isMemoryName`, `isMemoryType`, `assertMemoryType`, `MEMORY_TYPES`, `MEMORY_INDEX_MAX_LINES`, `MEMORY_INDEX_LINE_MAX_CHARS`, `MemoryContentRejectedError` and its `MemoryContentRejection` type.
+  - `DiskMemoryStore.get` and `getRecord` no longer return the file's `schemaVersion` stamp as a field of `MemoryContent`, which the type never declared.
+
+  Nothing is removed or renamed. A host that wrote a second record under the same title through `save_memory` still can: names are only enforced when a caller supplies one.
+
+### Patch Changes
+
+- 9238347: A child session's log opened through a symlinked path is now recognised as
+  the log in its place in the layout. Before, when `NAMZU_HOME` (or the
+  `SessionPaths` home) was reached through a symlink and the log was opened by
+  its real path, or the other way round, the two spellings compared unequal and
+  the child's checkpoints were written a second time under its parent. Nothing
+  to change on your side.
+
 ## 43.0.0
 
 ### Major Changes