@namzu/sdk 43.0.0 → 44.0.0

package/CHANGELOG.md

@@ -1,5 +1,511 @@
 # Changelog
 
+## 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