@namzu/sdk 27.1.0 → 28.0.0

package/src/types/run/state.ts

@@ -1,8 +1,8 @@
-import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
+import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PendingDecision } from '../hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
-import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
 import type { StopReason } from './stop-reason.js'
 
 /**
@@ -25,15 +25,20 @@ import type { StopReason } from './stop-reason.js'
  */
 export interface RunState {
 	/**
-	 * Schema version. Bumped when the shape changes incompatibly, so a
-	 * host that stored a snapshot with an older SDK gets a clear failure
-	 * from {@link parseRunState} instead of a partial restore.
+	 * Schema version. A v1 snapshot (the pre-NZ-TOPIC-03 shape — `threadId`
+	 * instead of `topicId`) and a v2 snapshot (the shape between NZ-TOPIC-03
+	 * and NZ-TOPIC-04 — `topicId` already the field name, but its value can
+	 * still carry the pre-narrowing `thd_` prefix) are both coerced forward
+	 * by {@link parseRunState}; any other unrecognized version is refused
+	 * with a clear failure rather than a partial restore, because silently
+	 * dropping fields this build does not know about is the outcome worth
+	 * failing loudly to avoid.
 	 */
-	readonly version: 1
+	readonly version: 3
 
 	readonly runId: RunId
 	readonly sessionId: SessionId
-	readonly threadId: ThreadId
+	readonly topicId: TopicId
 	readonly projectId: ProjectId
 	readonly tenantId: TenantId
 	/** Present for sub-runs, so a hierarchical store can key the snapshot. */
@@ -42,7 +47,7 @@ export interface RunState {
 	readonly agentId?: string
 	readonly agentName?: string
 
-	readonly status: AgentStatus
+	readonly status: RunExecutionStatus
 	readonly stopReason?: StopReason
 	readonly lastError?: string
 
@@ -87,7 +92,30 @@ export class RunStateVersionError extends Error {
 	}
 }
 
-export const RUN_STATE_VERSION = 1 as const
+export const RUN_STATE_VERSION = 3 as const
+
+/** 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: Record<string, unknown>): Record<string, unknown> {
+	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
@@ -96,14 +124,53 @@ export const RUN_STATE_VERSION = 1 as const
  * 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: string | unknown): RunState {
 	const raw: unknown = typeof json === 'string' ? JSON.parse(json) : json
 	if (typeof raw !== 'object' || raw === null) {
 		throw new RunStateVersionError(raw, RUN_STATE_VERSION)
 	}
-	const version = (raw as { version?: unknown }).version
+	const record = raw as Record<string, unknown>
+	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,
+		} as RunState
+	}
+
+	if (version === RUN_STATE_PRE_PREFIX_VERSION) {
+		return {
+			...rewriteLegacyTopicIdPrefix(record),
+			version: RUN_STATE_VERSION,
+		} as RunState
+	}
+
 	if (version !== RUN_STATE_VERSION) {
 		throw new RunStateVersionError(version, RUN_STATE_VERSION)
 	}

package/src/types/run/stop-reason.ts

@@ -38,6 +38,15 @@ export type StopReason =
 	| '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/src/types/run/store.ts

@@ -27,6 +27,7 @@
  * 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'
 
@@ -140,6 +141,45 @@ export interface RunStore {
 	 */
 	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/src/types/sandbox/index.ts

@@ -4,6 +4,7 @@ import {
 	SANDBOX_DEFAULT_MEMORY_LIMIT_MB,
 	SANDBOX_DEFAULT_TIMEOUT_MS,
 } from '../../constants/sandbox/index.js'
+import type { OpenTerminalOptions, TerminalSession } from '../../sandbox/terminal.js'
 import type { SandboxId } from '../ids/index.js'
 
 // ---------------------------------------------------------------------------
@@ -204,6 +205,21 @@ 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>
 	/**
@@ -454,6 +470,27 @@ 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'),
 })
 
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>

package/src/types/session/actor.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}.
@@ -10,7 +10,15 @@ import type { AgentId, TenantId, UserId } from '../ids/index.js'
  */
 export type ActorRef =
 	| { kind: 'user'; userId: UserId; tenantId: TenantId }
-	| { kind: 'agent'; agentId: AgentId; tenantId: TenantId; parentActor?: ActorRef }
+	// `agentId` is a plain `string`, and that is a correction rather than a
+	// loosening. It was annotated `AgentId` (`` `agt_${string}` ``) and every
+	// value that ever reached it was an agent's REGISTRY KEY — `'worker'`,
+	// `'supervisor'` — put there through an `as AgentId` cast. Nothing in this
+	// kernel has ever minted an `agt_` id; there is no `generateAgentId`. Now
+	// that the id types are nominal (NZ-SURF-11) the annotation could only be
+	// satisfied by an assertion, so it would have documented a guarantee that
+	// is impossible to hold rather than one nobody kept.
+	| { kind: 'agent'; agentId: string; tenantId: TenantId; parentActor?: ActorRef }
 	| { kind: 'system'; role: SystemRoleId; tenantId: TenantId }
 
 /** Branded id for the {@link ActorRef} `system` variant. */

package/src/types/session/entity.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
@@ -21,14 +21,16 @@ export type SessionStatus =
  * 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.
@@ -46,7 +48,7 @@ export type SessionStatus =
  */
 export interface Session {
 	id: SessionId
-	threadId: ThreadId
+	topicId: TopicId
 	projectId: ProjectId
 	tenantId: TenantId
 	status: SessionStatus

package/src/types/session/ids.ts

@@ -8,7 +8,9 @@
 
 export type {
 	ProjectId,
+	/** @deprecated Use `TopicId`. */
 	ThreadId,
+	TopicId,
 	SubSessionId,
 	HandoffId,
 	WorkspaceId,

package/src/types/session/index.ts

@@ -4,6 +4,7 @@
 
 export type {
 	ProjectId,
+	/** @deprecated Use `TopicId`. */
 	ThreadId,
 	SubSessionId,
 	HandoffId,
@@ -38,5 +39,6 @@ export type {
 	FailureMode,
 	SubSession,
 	SubSessionKind,
+	SubSessionDelegationStatus,
 	SubSessionStatus,
 } from './sub-session.js'

package/src/types/session/store.ts

@@ -19,22 +19,22 @@ import type {
 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
@@ -101,6 +101,19 @@ 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
 }
 
 /**
@@ -132,6 +145,19 @@ export interface SessionStore {
 
 	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.
 	 *
@@ -218,32 +244,37 @@ 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/src/types/session/sub-session.ts

@@ -5,23 +5,56 @@ 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 SubSessionDelegationStatus = 'pending' | 'active' | 'idle' | 'failed' | 'archived'
+
+/**
+ * @deprecated Use {@link SubSessionDelegationStatus}. Removal is a later
+ * major, and the six extra members go with it.
+ *
+ * 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 finds 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 stays this wide for one release so a host that persisted one of
+ * these values still typechecks while it migrates.
  */
 export type SubSessionStatus =
-	| 'pending'
-	| 'active'
-	| 'idle'
-	| 'failed'
+	| SubSessionDelegationStatus
+	/** @deprecated no producer since ratification */
 	| 'awaiting_merge'
+	/** @deprecated no producer since ratification */
 	| 'pending_merge'
+	/** @deprecated no producer since ratification */
 	| 'merging'
+	/** @deprecated no producer since ratification */
 	| 'merged'
+	/** @deprecated no producer since ratification */
 	| 'merge_conflict'
+	/** @deprecated no producer since ratification */
 	| 'merge_rejected'
-	| 'archived'
 
 /**
  * Discriminator for how a sub-session was created. Pattern doc §4.4
@@ -65,6 +98,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

package/src/types/skills/index.ts

@@ -1,3 +1,19 @@
+/**
+ * Who may reach for a skill.
+ *
+ * Every skill was offered to the model and to nobody else, and the two
+ * halves of that are both wrong. A skill that only an operator can
+ * meaningfully run — "collect a support bundle", "rotate the deploy key" —
+ * sat in the model's manifest as something to attempt, and the model would
+ * attempt it. A skill that is purely model guidance had no way to be
+ * offered to an operator at all.
+ *
+ * `both` is the default because it is what every existing skill silently
+ * was, and narrowing one is a decision its author makes rather than one a
+ * version bump makes for them.
+ */
+export type SkillInvocation = 'model' | 'operator' | 'both'
+
 export interface SkillMetadata {
 	name: string
 
@@ -9,9 +25,43 @@ export interface SkillMetadata {
 
 	allowedTools?: string
 
+	/**
+	 * Who may invoke this skill. Absent means {@link SKILL_INVOCATION_DEFAULT}.
+	 *
+	 * Optional rather than required, so that a `SkillMetadata` written
+	 * before this existed still type-checks — and resolved through
+	 * {@link skillInvocation} rather than with `?? 'both'` at each reader,
+	 * because the default is one decision and four copies of it is three
+	 * chances to disagree.
+	 */
+	invocation?: SkillInvocation
+
 	metadata?: Record<string, string>
 }
 
+/** What a skill that says nothing means. */
+export const SKILL_INVOCATION_DEFAULT: SkillInvocation = 'both'
+
+/** The skill's stated policy, or the default. */
+export function skillInvocation(skill: { metadata: SkillMetadata }): SkillInvocation {
+	return skill.metadata.invocation ?? SKILL_INVOCATION_DEFAULT
+}
+
+/**
+ * May this audience reach for this skill?
+ *
+ * `both` satisfies either side, which is the only reason the third value
+ * exists — a two-value policy would force every author to pick a side for a
+ * skill that genuinely serves both.
+ */
+export function isInvocableBy(
+	skill: { metadata: SkillMetadata },
+	audience: 'model' | 'operator',
+): boolean {
+	const policy = skillInvocation(skill)
+	return policy === 'both' || policy === audience
+}
+
 export interface Skill {
 	metadata: SkillMetadata