@namzu/sdk 27.1.0 → 29.0.0

package/dist/types/run/state.js

@@ -9,7 +9,28 @@ export class RunStateVersionError extends Error {
         this.name = 'RunStateVersionError';
     }
 }
-export const RUN_STATE_VERSION = 1;
+export const RUN_STATE_VERSION = 3;
+/** The shape `RunState` had before NZ-TOPIC-03: `threadId`, not `topicId`. */
+const RUN_STATE_LEGACY_VERSION = 1;
+/**
+ * The shape `RunState` had between NZ-TOPIC-03 and NZ-TOPIC-04: `topicId`
+ * is already the field name, but its value can still carry the
+ * pre-narrowing `thd_` prefix.
+ */
+const RUN_STATE_PRE_PREFIX_VERSION = 2;
+/**
+ * Shared by both legacy branches below: rewrite a `thd_`-prefixed topicId
+ * value to `top_`, leaving everything else — including an absent topicId —
+ * untouched. Mirrors `store/session/disk.ts`'s
+ * `migrateSessionStoreTopicIdPrefix`: same no-op-when-already-correct
+ * shape, same reason (idempotence under a repeated migration pass).
+ */
+function rewriteLegacyTopicIdPrefix(record) {
+    const topicId = record.topicId;
+    if (typeof topicId !== 'string' || !topicId.startsWith('thd_'))
+        return record;
+    return { ...record, topicId: `top_${topicId.slice('thd_'.length)}` };
+}
 /**
  * Parse a serialized snapshot, refusing anything this SDK cannot fully
  * restore.
@@ -17,14 +38,50 @@ export const RUN_STATE_VERSION = 1;
  * The version guard is the point. A snapshot is written by one deployment
  * and read by another, possibly weeks later and possibly after an SDK
  * upgrade; a silent partial restore there produces a run that looks healthy
- * and has lost its budgets. Failing loudly is the only honest option.
+ * and has lost its budgets. Failing loudly is the only honest option — for
+ * every version this build does not otherwise recognize. Versions 1 and 2
+ * are the exceptions: both are coerced forward rather than refused, the
+ * same shape-tolerant rename `store/schema.ts`'s migrations use for the
+ * on-disk session record, because a host that parks a run across either
+ * release boundary would otherwise have every in-flight snapshot refused
+ * on the way back in. `threadId` is renamed only when present (v1), and
+ * a `thd_`-prefixed `topicId` is rewritten only when present (v1 and v2),
+ * so a snapshot a host wrote with the field already absent, or already
+ * `top_`-prefixed, does not gain a stamped or double-rewritten value.
+ * Nothing here re-persists the coerced snapshot — a host that calls
+ * `parseRunState` and then serializes the result back out upgrades the
+ * record on THAT write, same as `store/schema.ts`'s "migrate on read,
+ * re-stamp on next write" contract.
+ *
+ * A snapshot from a NEWER build read by an OLDER SDK is refused, not
+ * partially restored: that SDK's `RUN_STATE_VERSION` is behind, so a
+ * record's `version` matches neither the current version nor a legacy
+ * version it knows how to coerce, and falls through to the throw below.
  */
 export function parseRunState(json) {
     const raw = typeof json === 'string' ? JSON.parse(json) : json;
     if (typeof raw !== 'object' || raw === null) {
         throw new RunStateVersionError(raw, RUN_STATE_VERSION);
     }
-    const version = raw.version;
+    const record = raw;
+    const version = record.version;
+    if (version === RUN_STATE_LEGACY_VERSION) {
+        const { threadId, ...rest } = record;
+        const withTopicId = {
+            ...rest,
+            ...(threadId !== undefined ? { topicId: threadId } : {}),
+        };
+        return {
+            ...rewriteLegacyTopicIdPrefix(withTopicId),
+            version: RUN_STATE_VERSION,
+        };
+    }
+    if (version === RUN_STATE_PRE_PREFIX_VERSION) {
+        return {
+            ...rewriteLegacyTopicIdPrefix(record),
+            version: RUN_STATE_VERSION,
+        };
+    }
     if (version !== RUN_STATE_VERSION) {
         throw new RunStateVersionError(version, RUN_STATE_VERSION);
     }

package/dist/types/run/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/types/run/state.ts"],"names":[],"mappings":"AA4EA,yEAAyE;AACzE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAEpC;IACA;IAFV,YACU,KAAc,EACd,QAAgB;QAEzB,KAAK,CACJ,gDAAgD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,oBAAoB,QAAQ,wFAAwF,CACzL,CAAA;QALQ,UAAK,GAAL,KAAK,CAAS;QACd,aAAQ,GAAR,QAAQ,CAAQ;QAKzB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACnC,CAAC;CACD;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAU,CAAA;AAE3C;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAAsB;IACnD,MAAM,GAAG,GAAY,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACvE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC7C,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAA;IACvD,CAAC;IACD,MAAM,OAAO,GAAI,GAA6B,CAAC,OAAO,CAAA;IACtD,IAAI,OAAO,KAAK,iBAAiB,EAAE,CAAC;QACnC,MAAM,IAAI,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;IAC3D,CAAC;IACD,OAAO,GAAe,CAAA;AACvB,CAAC"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/types/run/state.ts"],"names":[],"mappings":"AAiFA,yEAAyE;AACzE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAEpC;IACA;IAFV,YACU,KAAc,EACd,QAAgB;QAEzB,KAAK,CACJ,gDAAgD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,oBAAoB,QAAQ,wFAAwF,CACzL,CAAA;QALQ,UAAK,GAAL,KAAK,CAAS;QACd,aAAQ,GAAR,QAAQ,CAAQ;QAKzB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACnC,CAAC;CACD;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAU,CAAA;AAE3C,8EAA8E;AAC9E,MAAM,wBAAwB,GAAG,CAAC,CAAA;AAElC;;;;GAIG;AACH,MAAM,4BAA4B,GAAG,CAAC,CAAA;AAEtC;;;;;;GAMG;AACH,SAAS,0BAA0B,CAAC,MAA+B;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;IAC9B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAA;IAC7E,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,CAAA;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,aAAa,CAAC,IAAsB;IACnD,MAAM,GAAG,GAAY,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACvE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC7C,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAA;IACvD,CAAC;IACD,MAAM,MAAM,GAAG,GAA8B,CAAA;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;IAE9B,IAAI,OAAO,KAAK,wBAAwB,EAAE,CAAC;QAC1C,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAA;QACpC,MAAM,WAAW,GAAG;YACnB,GAAG,IAAI;YACP,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD,CAAA;QACD,OAAO;YACN,GAAG,0BAA0B,CAAC,WAAW,CAAC;YAC1C,OAAO,EAAE,iBAAiB;SACd,CAAA;IACd,CAAC;IAED,IAAI,OAAO,KAAK,4BAA4B,EAAE,CAAC;QAC9C,OAAO;YACN,GAAG,0BAA0B,CAAC,MAAM,CAAC;YACrC,OAAO,EAAE,iBAAiB;SACd,CAAA;IACd,CAAC;IAED,IAAI,OAAO,KAAK,iBAAiB,EAAE,CAAC;QACnC,MAAM,IAAI,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;IAC3D,CAAC;IACD,OAAO,GAAe,CAAA;AACvB,CAAC"}

package/dist/types/run/stop-reason.d.ts

@@ -31,6 +31,15 @@ export type StopReason = 'end_turn' | 'token_budget' | 'cost_limit'
  | 'cost_unmeasurable' | 'timeout' | 'max_iterations' | 'cancelled' | 'plan_rejected'
 /** A caller-supplied `stopWhen` predicate returned true. */
  | 'stop_condition'
+/**
+ * A host's `beforeStep` refused the next model call.
+ *
+ * Distinct from `stop_condition`, which reads `steps` and therefore
+ * only fires AFTER the step it disliked ran and was paid for. This one
+ * fires before the provider is called at all — the case a host with a
+ * live rate limit, a revoked tenant or a spend ceiling actually has.
+ */
+ | 'step_refused'
 /** The model never produced a valid structured output within its retries. */
  | 'structured_output_failed'
 /**

package/dist/types/run/stop-reason.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stop-reason.d.ts","sourceRoot":"","sources":["../../../src/types/run/stop-reason.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GACnB,UAAU,GACV,cAAc,GACd,YAAY;AACd;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;GACD,mBAAmB,GACnB,SAAS,GACT,gBAAgB,GAChB,WAAW,GACX,eAAe;AACjB,4DAA4D;GAC1D,gBAAgB;AAClB,6EAA6E;GAC3E,0BAA0B;AAC5B;;;;;;;;GAQG;GACD,iBAAiB;AACnB,4DAA4D;GAC1D,iBAAiB;AACnB,uDAAuD;GACrD,kBAAkB,GAClB,QAAQ,GACR,OAAO,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAC1B,UAAU,GACV,UAAU,GACV,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,SAAS,GACT,iBAAiB;AACnB;;;;;;;;GAQG;GACD,WAAW,CAAA"}
+{"version":3,"file":"stop-reason.d.ts","sourceRoot":"","sources":["../../../src/types/run/stop-reason.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GACnB,UAAU,GACV,cAAc,GACd,YAAY;AACd;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;GACD,mBAAmB,GACnB,SAAS,GACT,gBAAgB,GAChB,WAAW,GACX,eAAe;AACjB,4DAA4D;GAC1D,gBAAgB;AAClB;;;;;;;GAOG;GACD,cAAc;AAChB,6EAA6E;GAC3E,0BAA0B;AAC5B;;;;;;;;GAQG;GACD,iBAAiB;AACnB,4DAA4D;GAC1D,iBAAiB;AACnB,uDAAuD;GACrD,kBAAkB,GAClB,QAAQ,GACR,OAAO,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAC1B,UAAU,GACV,UAAU,GACV,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,SAAS,GACT,iBAAiB;AACnB;;;;;;;;GAQG;GACD,WAAW,CAAA"}

package/dist/types/run/store.d.ts

@@ -26,6 +26,7 @@
  * attribution it was constructed with plus the bound run id. If this is later
  * re-keyed per call, it happens once, deliberately, as its own change.
  */
+import type { AuditEvent } from './audit.js';
 import type { Run } from './entity.js';
 import type { PersistedRunEvent, RunEvent } from './events.js';
 /** What a caller asks the log for. See {@link RunStore.readEvents}. */
@@ -128,6 +129,43 @@ export interface RunStore {
      * filesystem. Valid only after {@link RunStore.initRun}.
      */
     getRunDir(): string | null;
+    /**
+     * Append one entry to this run's AUDIT trail. OPTIONAL on the contract,
+     * the same way {@link RunStore.addToIndex} is — an existing custom
+     * `RunStore` keeps compiling without it. Unlike `addToIndex`, though, its
+     * absence is not a shrug:
+     * {@link import('../../manager/run/persistence.js').RunPersistence.recordAudit}
+     * REFUSES rather than silently running a bound store that lacks it, per
+     * `refuse-do-not-degrade` — an audit trail nobody can point at is not a
+     * degraded feature, it is the kernel's central claim quietly not being
+     * true. NOTE: because `recordAudit` is called from every run's terminal
+     * path, a `RunStore` implementer that adopts this contract without also
+     * implementing this method will see every run throw. See the major-bump
+     * changeset.
+     *
+     * A SEPARATE trail from {@link RunStore.appendEvent}: an operational log
+     * is level-filtered, sampled, rotatable and legitimately absent when no
+     * host installed a sink. None of that is acceptable for evidence of what
+     * an agent did, under whose identity, at what cost, and whether it was
+     * allowed — see `types/run/audit.ts` for the full reasoning (ses_020's
+     * logging design §5).
+     *
+     * A write that rejects here must fail the caller's operation. This is the
+     * one place on this whole contract where that is true — every other write
+     * here may be retried or reported by a caller that chooses to; this one
+     * is durability's last line, and a caller that catches and continues past
+     * a rejection here has silently degraded the audit trail into decoration.
+     */
+    appendAuditEvent?(event: AuditEvent): Promise<void>;
+    /**
+     * Read the run's audit trail back, oldest first. OPTIONAL for the same
+     * reason {@link RunStore.appendAuditEvent} is. What a resumed run seeds
+     * its next audit `seq` from, and the input to
+     * {@link import('./audit.js').replayRun}. See {@link RunStore.readEvents}
+     * for the ordering and gap obligations — the same three apply here,
+     * against this trail's own sequence space.
+     */
+    readAuditEvents?(): Promise<readonly AuditEvent[]>;
     /**
      * Record the run in a browsable catalogue of runs. OPTIONAL.
      *

package/dist/types/run/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/run/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE9D,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;OASG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEpE,gEAAgE;IAChE,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErC,8CAA8C;IAC9C,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtC;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAA;IAEjF;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEpD;;;;;;;;;;;;OAYG;IACH,kBAAkB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAA;IAE/D;;;OAGG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI,CAAA;IAE1B;;;;;;;;;OASG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/run/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE9D,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;OASG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEpE,gEAAgE;IAChE,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErC,8CAA8C;IAC9C,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtC;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAA;IAEjF;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEpD;;;;;;;;;;;;OAYG;IACH,kBAAkB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAA;IAE/D;;;OAGG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI,CAAA;IAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,gBAAgB,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnD;;;;;;;OAOG;IACH,eAAe,CAAC,IAAI,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAA;IAElD;;;;;;;;;OASG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC"}

package/dist/types/sandbox/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { OpenTerminalOptions, TerminalSession } from '../../sandbox/terminal.js';
 import type { SandboxId } from '../ids/index.js';
 export type SandboxStatus = 'creating' | 'ready' | 'busy' | 'destroyed';
 export declare function assertSandboxStatus(status: SandboxStatus): void;
@@ -134,6 +135,20 @@ export interface Sandbox {
      * same rule the tiered sandbox provider follows, for the same reason.
      */
     setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
+    /**
+     * Open a real pseudo-terminal inside this sandbox.
+     *
+     * Optional, and a backend that cannot provide one must **throw** rather
+     * than hand back a pipe — the same rule {@link Sandbox.setNetworkPolicy}
+     * states one line up, and for a sharper reason. A pipe would appear to
+     * work: bytes would flow, and every program that calls `isatty` would
+     * take its non-interactive branch. The prompt never appears, the REPL
+     * exits immediately, the progress bar prints ten thousand lines, and
+     * nothing says why.
+     *
+     * See `sandbox/terminal.ts` for why the backing binding is optional.
+     */
+    openTerminal?(options: OpenTerminalOptions): Promise<TerminalSession>;
     writeFile(path: string, content: string | Buffer): Promise<void>;
     readFile(path: string): Promise<Buffer>;
     /**
@@ -349,6 +364,27 @@ export declare const SandboxConfigSchema: z.ZodObject<{
      * quiet downgrade.
      */
     requireIsolation: z.ZodDefault<z.ZodArray<z.ZodEnum<["filesystem", "network", "process"]>, "many">>;
+    /**
+     * What the sandbox is rooted at.
+     *
+     * `'ephemeral'` (the default, and the previous and only behaviour) gives
+     * the run a fresh temp directory. Nothing the agent writes touches the
+     * caller's files, and nothing the caller has is visible to it.
+     *
+     * `'working-directory'` roots it at the run's own `workingDirectory`, so
+     * a sandboxed `bash` acts on the project the agent was asked about
+     * instead of on an empty directory. That is the case the sandbox was
+     * wanted for and the one it could not do: the field existed on
+     * `SandboxCreateConfig` and the kernel never set it, so configuring a
+     * sandbox through `runConfig.sandbox` always got a temp directory
+     * whatever the run's own cwd was.
+     *
+     * The trade is the point of naming it rather than inferring it. Rooted
+     * at the working directory, confinement still bounds the agent to that
+     * subtree — but the subtree is now the caller's real files, and a
+     * destructive command inside it is destructive for real.
+     */
+    workspace: z.ZodDefault<z.ZodEnum<["ephemeral", "working-directory"]>>;
 }, "strip", z.ZodTypeAny, {
     enabled: boolean;
     provider: "local";
@@ -356,6 +392,7 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     memoryLimitMb: number;
     maxProcesses: number;
     requireIsolation: ("filesystem" | "network" | "process")[];
+    workspace: "ephemeral" | "working-directory";
 }, {
     enabled?: boolean | undefined;
     provider?: "local" | undefined;
@@ -363,6 +400,7 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     memoryLimitMb?: number | undefined;
     maxProcesses?: number | undefined;
     requireIsolation?: ("filesystem" | "network" | "process")[] | undefined;
+    workspace?: "ephemeral" | "working-directory" | undefined;
 }>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"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"}

package/dist/types/sandbox/index.js

@@ -47,5 +47,26 @@ export const SandboxConfigSchema = z.object({
      * quiet downgrade.
      */
     requireIsolation: z.array(z.enum(['filesystem', 'network', 'process'])).default([]),
+    /**
+     * What the sandbox is rooted at.
+     *
+     * `'ephemeral'` (the default, and the previous and only behaviour) gives
+     * the run a fresh temp directory. Nothing the agent writes touches the
+     * caller's files, and nothing the caller has is visible to it.
+     *
+     * `'working-directory'` roots it at the run's own `workingDirectory`, so
+     * a sandboxed `bash` acts on the project the agent was asked about
+     * instead of on an empty directory. That is the case the sandbox was
+     * wanted for and the one it could not do: the field existed on
+     * `SandboxCreateConfig` and the kernel never set it, so configuring a
+     * sandbox through `runConfig.sandbox` always got a temp directory
+     * whatever the run's own cwd was.
+     *
+     * The trade is the point of naming it rather than inferring it. Rooted
+     * at the working directory, confinement still bounds the agent to that
+     * subtree — but the subtree is now the caller's real files, and a
+     * destructive command inside it is destructive for real.
+     */
+    workspace: z.enum(['ephemeral', 'working-directory']).default('ephemeral'),
 });
 //# sourceMappingURL=index.js.map

package/dist/types/sandbox/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACN,6BAA6B,EAC7B,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAA;AASzC,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACxD,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,WAAW;YACf,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,MAAM,CAAA;YACjC,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAA;QACzD,CAAC;IACF,CAAC;AACF,CAAC;AAyBD,MAAM,CAAC,MAAM,0BAA0B,GAAuC;IAC7E,YAAY;IACZ,SAAS;IACT,SAAS;CACT,CAAA;AAKD,MAAM,UAAU,wBAAwB,CAAC,GAAuB;IAC/D,QAAQ,GAAG,EAAE,CAAC;QACb,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,OAAO;YACX,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,GAAG,CAAA;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,EAAE,CAAC,CAAA;QAC9D,CAAC;IACF,CAAC;AACF,CAAC;AA+WD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC;IACpE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC;IAC7E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,6BAA6B,CAAC;IAC1E;;;;;;OAMG;IACH,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACnF,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACN,6BAA6B,EAC7B,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAA;AAUzC,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACxD,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,WAAW;YACf,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,MAAM,CAAA;YACjC,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAA;QACzD,CAAC;IACF,CAAC;AACF,CAAC;AAyBD,MAAM,CAAC,MAAM,0BAA0B,GAAuC;IAC7E,YAAY;IACZ,SAAS;IACT,SAAS;CACT,CAAA;AAKD,MAAM,UAAU,wBAAwB,CAAC,GAAuB;IAC/D,QAAQ,GAAG,EAAE,CAAC;QACb,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,OAAO;YACX,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,GAAG,CAAA;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,EAAE,CAAC,CAAA;QAC9D,CAAC;IACF,CAAC;AACF,CAAC;AA8XD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC;IACpE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC;IAC7E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,6BAA6B,CAAC;IAC1E;;;;;;OAMG;IACH,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACnF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;CAC1E,CAAC,CAAA"}

package/dist/types/session/actor.d.ts

@@ -1,4 +1,4 @@
-import type { AgentId, TenantId, UserId } from '../ids/index.js';
+import type { TenantId, UserId } from '../ids/index.js';
 /**
  * Discriminated union of actors that can own a {@link Session}.
  *
@@ -13,7 +13,7 @@ export type ActorRef = {
     tenantId: TenantId;
 } | {
     kind: 'agent';
-    agentId: AgentId;
+    agentId: string;
     tenantId: TenantId;
     parentActor?: ActorRef;
 } | {

package/dist/types/session/actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../../src/types/session/actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEhE;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE7D,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,EAAE,CAAA"}
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../../src/types/session/actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GASpD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE7D,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,EAAE,CAAA"}

package/dist/types/session/entity.d.ts

@@ -1,6 +1,6 @@
 import type { SessionId, TenantId } from '../ids/index.js';
 import type { ActorRef } from './actor.js';
-import type { ProjectId, ThreadId, WorkspaceId } from './ids.js';
+import type { ProjectId, TopicId, WorkspaceId } from './ids.js';
 /**
  * Session lifecycle states. See session-hierarchy.md §4.3 and the state
  * machine in §5.1. `awaiting_merge` is a sub-state of idle used on the
@@ -12,14 +12,16 @@ export type SessionStatus = 'active' | 'idle' | 'locked' | 'awaiting_hitl' | 'aw
  * Multi-turn work unit owned by exactly one {@link ActorRef} at a time.
  *
  * Scope identifiers:
- *   - `threadId` — the topic-level {@link import('../thread/entity.js').Thread}
- *     this Session lives under. Set at creation, immutable; Sessions never
- *     move threads.
+ *   - `topicId` — the {@link import('../topic/entity.js').Topic} this
+ *     Session lives under. Set at creation, immutable; Sessions never move
+ *     topics. Spelled `threadId` before NZ-TOPIC-03 — see
+ *     `session/migration/id-prefix.ts` for the UNRELATED `thd_` meaning
+ *     that rename did not touch (D2, ses_020).
  *   - `projectId` — the {@link import('../project/entity.js').Project} the
- *     owning Thread belongs to. **Denormalized** from `thread.projectId` at
+ *     owning Topic belongs to. **Denormalized** from `topic.projectId` at
  *     creation time; immutable. Kept on the Session record for ergonomic
  *     access (Project-scoped consumers — handoff validators, archival,
- *     retention — would otherwise need a second round-trip to ThreadStore
+ *     retention — would otherwise need a second round-trip to TopicStore
  *     on every read). This is NOT a deprecated mirror of a fading field;
  *     it is a deliberate denormalization of structurally-immutable derived
  *     data.
@@ -37,7 +39,7 @@ export type SessionStatus = 'active' | 'idle' | 'locked' | 'awaiting_hitl' | 'aw
  */
 export interface Session {
     id: SessionId;
-    threadId: ThreadId;
+    topicId: TopicId;
     projectId: ProjectId;
     tenantId: TenantId;
     status: SessionStatus;

package/dist/types/session/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/types/session/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACtB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,UAAU,CAAA;AAEb;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,SAAS,CAAA;IACb,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,MAAM,EAAE,aAAa,CAAA;IACrB,YAAY,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC7B,cAAc,EAAE,SAAS,QAAQ,EAAE,CAAA;IACnC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/types/session/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACtB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,UAAU,CAAA;AAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,SAAS,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,MAAM,EAAE,aAAa,CAAA;IACrB,YAAY,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC7B,cAAc,EAAE,SAAS,QAAQ,EAAE,CAAA;IACnC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}

package/dist/types/session/ids.d.ts

@@ -5,5 +5,5 @@
  * for ergonomic co-location with session-scoped callers (they already import
  * from `types/session/`).
  */
-export type { ProjectId, ThreadId, SubSessionId, HandoffId, WorkspaceId, SummaryId, DeliverableId, SessionId, TenantId, RunId, AgentId, UserId, TaskId, } from '../ids/index.js';
+export type { ProjectId, TopicId, SubSessionId, HandoffId, WorkspaceId, SummaryId, DeliverableId, SessionId, TenantId, RunId, AgentId, UserId, TaskId, } from '../ids/index.js';
 //# sourceMappingURL=ids.d.ts.map

package/dist/types/session/ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/types/session/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EACX,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,QAAQ,EACR,KAAK,EACL,OAAO,EACP,MAAM,EACN,MAAM,GACN,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/types/session/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EACX,SAAS,EACT,OAAO,EACP,YAAY,EACZ,SAAS,EACT,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,QAAQ,EACR,KAAK,EACL,OAAO,EACP,MAAM,EACN,MAAM,GACN,MAAM,iBAAiB,CAAA"}

package/dist/types/session/index.d.ts

@@ -1,7 +1,7 @@
-export type { ProjectId, ThreadId, SubSessionId, HandoffId, WorkspaceId, SummaryId, DeliverableId, SessionId, TenantId, RunId, AgentId, UserId, TaskId, } from './ids.js';
+export type { ProjectId, SubSessionId, HandoffId, WorkspaceId, SummaryId, DeliverableId, SessionId, TenantId, RunId, AgentId, UserId, TaskId, } from './ids.js';
 export type { SessionStore, SessionView, CreateProjectParams, CreateSessionParams, CreateSubSessionParams, } from './store.js';
 export type { SessionMessage } from './messages.js';
 export type { ActorRef, SystemRoleId } from './actor.js';
 export type { Session, SessionStatus } from './entity.js';
-export type { CompletionMode, DeliverableRef, FailureMode, SubSession, SubSessionKind, SubSessionStatus, } from './sub-session.js';
+export type { CompletionMode, DeliverableRef, FailureMode, SubSession, SubSessionKind, SubSessionDelegationStatus, SubSessionStatus, } from './sub-session.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/session/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/session/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACX,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,QAAQ,EACR,KAAK,EACL,OAAO,EACP,MAAM,EACN,MAAM,GACN,MAAM,UAAU,CAAA;AAEjB,YAAY,EACX,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,YAAY,CAAA;AAEnB,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAExD,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEzD,YAAY,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,UAAU,EACV,cAAc,EACd,gBAAgB,GAChB,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/session/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACX,SAAS,EACT,YAAY,EACZ,SAAS,EACT,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,QAAQ,EACR,KAAK,EACL,OAAO,EACP,MAAM,EACN,MAAM,GACN,MAAM,UAAU,CAAA;AAEjB,YAAY,EACX,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,YAAY,CAAA;AAEnB,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAExD,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEzD,YAAY,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,UAAU,EACV,cAAc,EACd,0BAA0B,EAC1B,gBAAgB,GAChB,MAAM,kBAAkB,CAAA"}

package/dist/types/session/store.d.ts

@@ -13,21 +13,21 @@ import type { CompletionMode, FailureMode, SubSession, SubSessionKind } from '..
 import type { SessionSummaryRef } from '../../types/summary/ref.js';
 import type { MessageId, SessionId, TenantId } from '../ids/index.js';
 import type { Message } from '../message/index.js';
-import type { ProjectId, SubSessionId, SummaryId, ThreadId } from '../session/ids.js';
+import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../session/ids.js';
 /**
  * Params for {@link SessionStore.createSession}. The store owns id generation,
  * `ownerVersion` initialization, and timestamps.
  *
- * Both `threadId` and `projectId` are required. `projectId` must equal the
- * `projectId` of the thread identified by `threadId`; the store does NOT
- * perform that cross-store consistency check (it has no ThreadStore handle
- * by design — see the store-boundary rationale in {@link ThreadStore}). The
+ * Both `topicId` and `projectId` are required. `projectId` must equal the
+ * `projectId` of the topic identified by `topicId`; the store does NOT
+ * perform that cross-store consistency check (it has no TopicStore handle
+ * by design — see the store-boundary rationale in {@link import('../topic/store.js').TopicStore}). The
  * caller is the authority; typically spawn and handoff paths copy both from
- * a freshly-loaded `Thread` record or from their own context which already
+ * a freshly-loaded `Topic` record or from their own context which already
  * tracks both.
  */
 export interface CreateSessionParams {
-    threadId: ThreadId;
+    topicId: TopicId;
     projectId: ProjectId;
     /**
      * Initial owner of the session. May be `null` for bootstrap scenarios where
@@ -90,6 +90,18 @@ export interface CreateProjectParams {
      * workspaces is for.
      */
     config?: ProjectConfigInput;
+    /**
+     * The directory this project's work happens in. Canonicalized through
+     * `realpath` before storage, so a symlink or a trailing slash cannot
+     * produce a second record for one directory.
+     *
+     * A second project for the same canonical directory is REFUSED, not
+     * deduplicated into the first — a caller who wanted the existing one
+     * should say so with {@link SessionStore.findProjectByRootPath}, and
+     * silently returning it would hide that their `name` and `config` were
+     * discarded.
+     */
+    rootPath?: string;
 }
 /**
  * Return shape for {@link SessionStore.drill}. See session-hierarchy.md §14.3.
@@ -115,6 +127,18 @@ export interface SessionView {
 export interface SessionStore {
     createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project>;
     getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null>;
+    /**
+     * The project bound to a directory, or `null`. OPTIONAL.
+     *
+     * Optional for the reason `updateProjectConfig` below gives: this
+     * interface is implemented by hosts, and a required method stops them
+     * compiling for a capability they never asked for.
+     *
+     * The argument is canonicalized here too, so a caller may pass whatever
+     * they have — a relative path, a symlink, a trailing slash — and get the
+     * same answer the writer got.
+     */
+    findProjectByRootPath?(rootPath: string, tenantId: TenantId): Promise<Project | null>;
     /**
      * Change a Project's limits after it exists. OPTIONAL.
      *
@@ -184,31 +208,36 @@ export interface SessionStore {
      */
     updateSession(session: Session, tenantId: TenantId, expectedOwnerVersion?: number): Promise<void>;
     /**
-     * List every Session that belongs to the given Thread for the caller's
+     * List every Session that belongs to the given Topic for the caller's
      * tenant, ordered by `createdAt` ascending. Returns an empty array when
      * none exist.
      *
-     * Thread-scoped queries rely on `session.threadId` (set at creation, never
-     * rewritten). Cross-tenant sessions that happen to share the supplied
-     * `threadId` are silently skipped — the listing is tenant-scoped, not an
-     * isolation violation (the caller did not request a specific record).
+     * Renamed from `listSessions` alongside the `threadId` → `topicId` field
+     * rename (NZ-TOPIC-03) — a query method named after the retired word
+     * would have kept pointing at the concept this whole chain exists to
+     * rename. Topic-scoped queries rely on `session.topicId` (set at
+     * creation, never rewritten). Cross-tenant sessions that happen to share
+     * the supplied `topicId` are silently skipped — the listing is
+     * tenant-scoped, not an isolation violation (the caller did not request
+     * a specific record).
      *
-     * Exists to back ThreadManager's archival + delete preconditions
-     * ({@link import('../../manager/thread/lifecycle.js').ThreadManager.archive}
+     * Exists to back TopicManager's archival + delete preconditions
+     * ({@link import('../../manager/topic/lifecycle.js').TopicManager.archive}
      * rejects when any session is in a non-terminal state; `delete` rejects
-     * while any session still references the thread). Keeping this primitive
+     * while any session still references the topic). Keeping this primitive
      * on {@link SessionStore} preserves the store-ownership boundary —
-     * ThreadStore stays unaware of session layout (Convention #0).
+     * TopicStore stays unaware of session layout (Convention #0).
      */
-    listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]>;
+    listSessionsByTopic(topicId: TopicId, tenantId: TenantId): Promise<readonly Session[]>;
     /**
      * Every Session attached to a workspace, oldest first. OPTIONAL.
      *
-     * The project-scoped sibling of {@link SessionStore.listSessions}, and the
-     * one the archive precondition reads: closing a workspace has to know what
-     * is still running in it, and "what is running in this thread" was never
-     * the question — a project can hold sessions across many threads, and after
-     * the Thread level is removed it is the only grouping left.
+     * The project-scoped sibling of {@link SessionStore.listSessionsByTopic},
+     * and the one the archive precondition reads: closing a workspace has to
+     * know what is still running in it, and "what is running in this topic"
+     * was never the question — a project can hold sessions across many
+     * topics, and after the Topic level is removed it is the only grouping
+     * left.
      */
     listSessionsByProject?(projectId: ProjectId, tenantId: TenantId): Promise<readonly Session[]>;
     /**

package/dist/types/session/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/session/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/session/store.ts"],"names":[],"mappings":"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"}

package/dist/types/session/sub-session.d.ts

@@ -4,12 +4,43 @@ import type { SessionId } from '../ids/index.js';
 import type { ActorRef } from './actor.js';
 import type { SubSessionId, SummaryId, WorkspaceId } from './ids.js';
 /**
- * Full 11-variant status union. See session-hierarchy.md §4.4 and the merge
- * state machine in §4.4.1. Absence of a `closed` state is load-bearing —
- * completed sub-sessions land on `idle` and stay there for drill-down
- * (Decision #5).
+ * The lifecycle of the DELEGATION — the edge from parent to child, not the
+ * child.
+ *
+ * This is the distinction the eleven-variant union lost. A `SubSession`
+ * record describes one parent's handoff to one child; the child is an
+ * ordinary `Session` in `SessionStore` with its own `SessionStatus`. Both
+ * unions carry `active`, `idle` and `archived`, and `SessionStatus`
+ * additionally carries `awaiting_merge` — so "is this thing active" had two
+ * answers and nothing said which record to ask.
+ *
+ * Ask this one about the delegation: has the parent handed off yet, is the
+ * child working, did the handoff fail, has the edge been retired. Ask
+ * `SessionStatus` about the child's own work.
+ *
+ * These five are every value the kernel produces. Absence of a `closed`
+ * state is load-bearing: a completed sub-session lands on `idle` and stays
+ * there so it can still be drilled into.
  */
-export type SubSessionStatus = 'pending' | 'active' | 'idle' | 'failed' | 'awaiting_merge' | 'pending_merge' | 'merging' | 'merged' | 'merge_conflict' | 'merge_rejected' | 'archived';
+export type SubSessionDelegationStatus = 'pending' | 'active' | 'idle' | 'failed' | 'archived';
+/**
+ * @deprecated Use {@link SubSessionDelegationStatus}. This is now an alias of
+ * it and carries no members of its own; the name goes in a later major.
+ *
+ * The merge half of this union was declared and never driven. Grepping
+ * `packages/sdk` and `packages/cli` for each of `awaiting_merge`,
+ * `pending_merge`, `merging`, `merged`, `merge_conflict` and
+ * `merge_rejected` AS A SUB-SESSION STATUS found no writer at all — the many
+ * hits on `awaiting_merge` are `SessionStatus`, which is the shadowing this
+ * type's replacement exists to end. Two of them (`merged`, `merge_rejected`)
+ * had a READER: they sat in `ARCHIVABLE_STATUSES`, a set that could never
+ * match on them.
+ *
+ * The union stayed wide for one release so a host that had persisted one of
+ * those values still typechecked while it migrated. 28.0.0 carried that
+ * window to the registry and NZ-RUNREC-14 closed it.
+ */
+export type SubSessionStatus = SubSessionDelegationStatus;
 /**
  * Discriminator for how a sub-session was created. Pattern doc §4.4
  * enumerates four variants; the three kept here collapse `user_handoff`
@@ -48,6 +79,14 @@ export interface SubSession {
     parentSessionId: SessionId;
     childSessionId: SessionId;
     kind: SubSessionKind;
+    /**
+     * The DELEGATION's lifecycle, not the child's. The child session has its
+     * own {@link import('./entity.js').SessionStatus}; when the two disagree
+     * this one is authoritative about whether the parent still has a live
+     * handoff, and that one is authoritative about whether the child is
+     * working. Typed as the wide alias for one more release; every value the
+     * kernel writes is a {@link SubSessionDelegationStatus}.
+     */
     status: SubSessionStatus;
     spawnedBy: ActorRef;
     spawnedAt: Date;