@namzu/sdk 27.1.0 → 29.0.0

package/src/types/tool/index.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod'
 import type { Logger } from '../../utils/logger.js'
+import type { CodeNavigationProvider } from '../code-navigation/index.js'
 // Type-only, and circular by design: a tool-result guardrail is described in
 // terms of the tool that produced the result, and the registry that holds
 // the guardrails is described here. Erased at compile time, so neither
@@ -9,6 +10,7 @@ import type { RunId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { Sandbox } from '../sandbox/index.js'
+import type { ToolPresentation } from './presentation.js'
 
 export interface ToolRegistryRef {
 	searchDeferred(query: string): ToolDefinition[]
@@ -16,6 +18,72 @@ export interface ToolRegistryRef {
 	getAvailability(name: string): ToolAvailability
 }
 
+/**
+ * The slice of the background job registry a tool is given.
+ *
+ * A structural reference rather than the class, for the reason
+ * `ToolRegistryRef` exists: this type file is imported by everything, and
+ * naming the implementation here would drag a `node:child_process` module
+ * into every consumer's type graph. `owner` is not on this surface at all —
+ * the executor binds it to the run, so a tool cannot start a job that
+ * outlives, or is billed to, somebody else's run.
+ */
+/**
+ * The slice of the skills registry a tool is given.
+ *
+ * Structural for the reason `ToolRegistryRef` is: this file is imported by
+ * everything, and naming `SkillRegistry` here would drag the skill loader's
+ * filesystem imports into every consumer's type graph.
+ */
+export interface SkillRegistryRef {
+	/**
+	 * Load a skill's full body, or `undefined` for a name nobody registered.
+	 *
+	 * Full disclosure by design: a tool call asking for a skill is asking
+	 * for its instructions, and returning metadata the model already has in
+	 * its manifest would answer a question it did not ask.
+	 */
+	load(name: string): Promise<
+		| {
+				skill: {
+					metadata: {
+						name: string
+						description: string
+						allowedTools?: string
+						/**
+						 * The literal union, not `string`. Widening it here would
+						 * let a ref satisfy this interface while carrying a value
+						 * `isInvocableBy` cannot read, and the failure would be a
+						 * silent `both` — the fail-open answer.
+						 */
+						invocation?: 'model' | 'operator' | 'both'
+					}
+					body?: string
+				}
+		  }
+		| undefined
+	>
+	/** Every registered name, for a "did you mean" that names real options. */
+	names(): readonly string[]
+}
+
+export interface BackgroundJobRegistryRef {
+	start(params: { command: string; workingDirectory: string }): { id: string; status: string }
+	get(id: string): { id: string; status: string; exitCode?: number }
+	read(
+		id: string,
+		opts?: { fromOffset?: number },
+	): {
+		chunk: string
+		nextOffset: number
+		droppedBytes: number
+		status: string
+		exitCode?: number
+	}
+	kill(id: string): Promise<{ id: string; status: string }>
+	list(): readonly { id: string; command: string; status: string }[]
+}
+
 /**
  * Tracks which files the agent has read in the current run.
  * Write tool consults this to enforce the "read before overwrite" invariant
@@ -120,8 +188,93 @@ export interface ToolContext {
 	 */
 	allowedTools?: readonly string[]
 	sandbox?: Sandbox
+	/**
+	 * Symbol resolution for this run, when a host wired one up.
+	 *
+	 * Absent means the `lsp` tool is not registered at all — see
+	 * `tools/builtins/lsp.ts` for why a tool that is always present and
+	 * always says "unavailable" is worse than one that is not there.
+	 */
+	codeNavigation?: CodeNavigationProvider
 	fileReadTracker?: FileReadTracker
 
+	/**
+	 * Where work that outlives this call is held.
+	 *
+	 * Absent means the host has provided nowhere to put a background job, and
+	 * a tool asked for one must REFUSE rather than fall back to `cmd &`. The
+	 * fallback is not a lesser version of this — under the local sandbox's
+	 * `linux-namespace` tier the wrapping `sh` is PID 1 of a fresh PID
+	 * namespace, so a backgrounded grandchild dies the moment that shell
+	 * exits, on the successful path. It returns in milliseconds looking like
+	 * it worked, with the work already dead.
+	 */
+	backgroundJobs?: BackgroundJobRegistryRef
+
+	/**
+	 * Where the `skill` tool reads from.
+	 *
+	 * Absent means the run has no skills, and the tool says so rather than
+	 * reporting an empty list — "no skills here" and "no registry" are
+	 * different answers.
+	 */
+	skills?: SkillRegistryRef
+
+	/**
+	 * How this run reaches the web.
+	 *
+	 * Two independent halves, and either may be absent. This kernel ships a
+	 * guarded fetch provider and NO search backend, so `search` missing is
+	 * the ordinary case rather than a failure — the tools say which piece is
+	 * missing so an operator can tell a wiring decision from a fault.
+	 */
+	web?: {
+		readonly fetch?: {
+			fetch(request: { url: string; signal?: AbortSignal }): Promise<{
+				url: string
+				status: number
+				contentType?: string
+				body: string
+				truncated: boolean
+				redirects: readonly string[]
+			}>
+		}
+		readonly search?: {
+			search(request: { query: string; limit?: number; signal?: AbortSignal }): Promise<{
+				query: string
+				hits: readonly { title: string; url: string; snippet?: string }[]
+			}>
+		}
+	}
+
+	/**
+	 * Adopt the tool scope a skill declared.
+	 *
+	 * Called by the `skill` tool when a loaded skill names `allowed-tools`.
+	 * The scope INTERSECTS what the turn already allows and takes effect from
+	 * the next batch — a skill loaded alongside other calls must not
+	 * retroactively refuse them.
+	 */
+	adoptSkillScope?: (scope: { skill: string; allowedTools: readonly string[] }) => void
+
+	/**
+	 * Run another tool through the same dispatch this call came through.
+	 *
+	 * For `run_code`, whose whole purpose is calling tools in a loop. NOT
+	 * added to {@link ToolRegistryRef}: that ref is about discovering and
+	 * activating tools, and putting `execute` on it would make "can dispatch"
+	 * a property of holding a registry reference rather than a capability a
+	 * host wired deliberately.
+	 *
+	 * Available to every tool, which is worth being explicit about rather
+	 * than quietly true. Tools are host-installed code — the model cannot add
+	 * one — so the trust boundary this protects is the MODEL's reach, and
+	 * that is bounded where it has always been: `allowedTools` is enforced at
+	 * dispatch, so a tool calling through here reaches exactly what a
+	 * `tool_use` block would have.
+	 */
+	dispatchTool?: (name: string, input: unknown) => Promise<ToolResult>
+
 	/**
 	 * The `tool_use_id` of the assistant block that triggered this
 	 * execution. Tools that spawn background work (e.g. coordinator
@@ -222,7 +375,7 @@ export interface ToolResult {
 	retryable?: boolean
 }
 
-export interface ToolDefinition<TInput = unknown> {
+export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {
 	name: string
 	description: string
 	inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>
@@ -450,3 +603,5 @@ export interface ToolRegistryContract {
 }
 
 export * from './repair.js'
+
+export type { ToolCallView, ToolPresentation, ToolResultView } from './presentation.js'

package/src/types/tool/presentation.ts

@@ -0,0 +1,48 @@
+import type { ToolResult } from './index.js'
+
+/**
+ * How a tool call should be shown, decided by the tool.
+ *
+ * Presentation lived in one host as four free functions switching on a
+ * lowercased tool NAME: `name === 'write'` and `name === 'edit'` got a
+ * diff, everything else got a truncated string. So a tool the host had
+ * never heard of — an MCP server's, a plugin's, a second host's — could
+ * not get a diff no matter what it did, and every new host started from
+ * the raw arguments and rebuilt the same switch.
+ *
+ * The tool knows what it is doing; the host knows how its surface renders.
+ * These are the three shapes one host had already found it needed, closed
+ * deliberately: an open union would let a tool ask for a rendering no host
+ * has, which is a request that fails silently at the far end.
+ */
+export type ToolCallView =
+	/** A line of text. What everything that is not a diff or a command gets. */
+	| { readonly kind: 'generic'; readonly label: string }
+	/**
+	 * A change to a document. `path` is optional because not every diff is
+	 * a file — a tool patching a remote record has a before and an after
+	 * and no path a host could open.
+	 */
+	| {
+			readonly kind: 'diff'
+			readonly path?: string
+			readonly before: string
+			readonly after: string
+	  }
+	/** A command and what it printed. */
+	| { readonly kind: 'terminal'; readonly command?: string; readonly output: string }
+
+/** The same three shapes, for what a call produced. */
+export type ToolResultView = ToolCallView
+
+/**
+ * Optional presentation hooks on a tool definition.
+ *
+ * Both may return `undefined`, which means "no opinion" and is different
+ * from returning a generic view: the first defers to the host's fallback,
+ * the second asserts that a plain label is the right rendering.
+ */
+export interface ToolPresentation<TInput = unknown> {
+	presentCall?(input: TInput): ToolCallView | undefined
+	presentResult?(input: TInput, result: ToolResult): ToolResultView | undefined
+}

package/src/types/{thread → topic}/entity.ts

@@ -1,51 +1,57 @@
 import type { TenantId } from '../ids/index.js'
-import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
 
 /**
- * Lifecycle state of a Thread.
+ * Lifecycle state of a Topic.
  *
  * - `open` — accepts new Sessions and new Runs under existing Sessions.
  * - `archived` — read-only tombstone. No new Sessions may be created; existing
  *   Sessions remain navigable. Transitioning `open → archived` requires that
- *   no Session under the Thread is in a non-terminal state (guarded at the
+ *   no Session under the Topic is in a non-terminal state (guarded at the
  *   store level by listing + status fan-in).
  *
- * There is no `active` variant — Thread does NOT derive status from its child
- * Sessions the way a Session does from its Runs. Thread is a pure container
- * (Phase 0 decision B.1: Thread is container-only, no message stream, no
+ * There is no `active` variant — Topic does NOT derive status from its child
+ * Sessions the way a Session does from its Runs. Topic is a pure container
+ * (Phase 0 decision B.1: Topic is container-only, no message stream, no
  * fan-in). Its status is an explicit owner action.
  */
-export type ThreadStatus = 'open' | 'archived'
+export type TopicStatus = 'open' | 'archived'
 
 /**
  * Topic-level container sitting between {@link ProjectId Project} and
  * {@link import('../session/ids.js').SessionId Session} in the five-layer hierarchy
- * (Project → Thread → Session → SubSession → Run).
+ * (Project → Topic → Session → SubSession → Run).
  *
- * A Thread groups together many Sessions that address the same coherent
+ * NZ-TOPIC-01 renamed this entity from `Thread` to `Topic` — its own docstring
+ * already called it a "Topic-level container" before the identifier caught up.
+ * NZ-TOPIC-04 narrows the exported {@link import('../ids/index.js').TopicId}
+ * from the pre-0.2.0 `thd_` shape to `top_`; on-disk records written under
+ * the old prefix are migrated on read (`store/session/disk.ts`).
+ *
+ * A Topic groups together many Sessions that address the same coherent
  * topic or line-of-work within a Project (e.g. "auth refactor", "billing
- * incident"). Sessions under the same Thread share Project-level shared
+ * incident"). Sessions under the same Topic share Project-level shared
  * resources (memory, vaults, knowledge bases) but have independent actor
  * state, handoff history, and Run streams.
  *
- * ## Why Thread is a first-class layer (A2A-connection surface)
+ * ## Why Topic is a first-class layer (A2A-connection surface)
  *
  * The layer exists because of how enterprise sharing works in Namzu:
  *
  * - **Project is the folder-bound sharing unit.** An enterprise team shares
  *   a Project (`.namzu/` in a repo, a long-lived goal scope). Everyone with
  *   Project access sees its shape but not necessarily its active work.
- * - **Thread is the path-independent, A2A-attachable topic surface.** A
- *   Project can have multiple Threads — one per objective or line-of-work —
- *   and the Threads can be partitioned by device, user, or agent identity.
- *   A2A (agent-to-agent) connections attach at the Thread level: connecting
- *   to a Thread exposes every Session under it and the ability to join the
+ * - **Topic is the path-independent, A2A-attachable topic surface.** A
+ *   Project can have multiple Topics — one per objective or line-of-work —
+ *   and the Topics can be partitioned by device, user, or agent identity.
+ *   A2A (agent-to-agent) connections attach at the Topic level: connecting
+ *   to a Topic exposes every Session under it and the ability to join the
  *   ongoing work.
  * - **Sessions are the immediate work unit.** A user or agent enters a
- *   Thread and opens/resumes Sessions for the concrete interval of work.
+ *   Topic and opens/resumes Sessions for the concrete interval of work.
  *
  * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). The
- * Thread layer has no counterpart elsewhere — it is Namzu's answer to
+ * Topic layer has no counterpart elsewhere — it is Namzu's answer to
  * the question "how do you expose a multi-session topic to A2A without
  * coupling it to the Project's filesystem identity?".
  *
@@ -55,23 +61,25 @@ export type ThreadStatus = 'open' | 'archived'
  *   - Container only. No own message stream, no own Run stream. Messages
  *     live in Sessions (Phase 0 decision B.1).
  *   - `title` is a user-facing label. **Titles are NOT unique within a
- *     Project.** Callers disambiguate by {@link ThreadId}; the title is
+ *     Project.** Callers disambiguate by {@link TopicId}; the title is
  *     freeform display text. If a product surface needs uniqueness (e.g.
  *     a human-typed slug), that constraint lives at the API layer, not in
  *     the kernel.
- *   - `ownerVersion` is the CAS counter for mutations — `updateThread` and
+ *   - `ownerVersion` is the CAS counter for mutations — `updateTopic` and
  *     archival transitions require a matching version and reject
- *     {@link StaleThreadError} on mismatch. Mirrors the
- *     {@link import('./entity.js').Session} handoff CAS pattern (§6.1).
+ *     {@link import('../../session/errors.js').StaleThreadError} on mismatch
+ *     (error class name is unchanged this release — see NZ-TOPIC-01 risks).
+ *     Mirrors the {@link import('./entity.js').Session} handoff CAS pattern
+ *     (§6.1).
  *   - No fan-in `deriveStatus()` helper — status is owner-managed, not
- *     Run-derived. This is the Thread-vs-Session contract boundary.
+ *     Run-derived. This is the Topic-vs-Session contract boundary.
  */
-export interface Thread {
-	id: ThreadId
+export interface Topic {
+	id: TopicId
 	projectId: ProjectId
 	tenantId: TenantId
 	title: string
-	status: ThreadStatus
+	status: TopicStatus
 	ownerVersion: number
 	createdAt: Date
 	updatedAt: Date

package/src/types/topic/index.ts

@@ -0,0 +1,23 @@
+// Sub-barrel for the Topic type surface (Convention #4).
+// Concrete types live in sibling files; re-export them here so consumers
+// import via `../types/topic/index.js`.
+//
+// NZ-TOPIC-01: this barrel used to be `types/thread/index.ts`, exporting
+// `ThreadStore`/`CreateThreadParams`/`Thread`/`ThreadStatus`. None of those
+// four names was ever part of the SDK's public surface (verified against
+// public-runtime.ts / public-types.ts, including their wildcard re-export
+// chains), so they were free to rename outright with no deprecated alias.
+
+export type { TopicStore, CreateTopicParams } from './store.js'
+export type { Topic, TopicStatus } from './entity.js'
+
+export { StaleObjectiveError } from './objective.js'
+export type {
+	ObjectiveAdvance,
+	ObjectiveAdvanceResult,
+	ObjectiveBlock,
+	ObjectivePhase,
+	ObjectiveRefusal,
+	ObjectiveRoundVerdict,
+	TopicObjective,
+} from './objective.js'

package/src/types/topic/objective.ts

@@ -0,0 +1,93 @@
+import type { RunId, TenantId, TopicId } from '../ids/index.js'
+
+/**
+ * Work that outlives one run.
+ *
+ * Nothing in this kernel survived a single `query()` call. `stopWhen` and
+ * `prepareStep` shape one loop, the completion inbox holds one run open for
+ * a worker, and the topic manager owned a container with no work state in
+ * it at all — so a host wanting "keep going until X is done, stop safely if
+ * it stalls or runs long, let a human pause and inspect" had to hand-roll
+ * the store, the round cap and the compare-and-set outside the SDK.
+ *
+ * The Topic's own docstring already called it "one per objective or
+ * line-of-work". This is that objective, written down.
+ */
+
+export type ObjectivePhase = 'active' | 'paused' | 'blocked' | 'complete'
+
+/** Why an objective stopped, in a form a caller can branch on. */
+export interface ObjectiveBlock {
+	/**
+	 * A code, not just prose. `round_cap` and "the model gave up" are
+	 * different situations with different next moves, and a message alone
+	 * makes a host parse English to tell them apart.
+	 */
+	readonly code: 'round_cap' | 'runner_failed' | 'external'
+	readonly message: string
+}
+
+export interface TopicObjective {
+	readonly id: string
+	readonly topicId: TopicId
+	readonly tenantId: TenantId
+	/** Compare-and-set counter, `0` before the first write. */
+	readonly revision: number
+	readonly objective: string
+	readonly phase: ObjectivePhase
+	readonly blockedReason?: ObjectiveBlock
+	/**
+	 * The hard stop.
+	 *
+	 * Not a suggestion and not a timeout: an objective that cannot tell it
+	 * is stuck will keep spending money on rounds that make no progress, and
+	 * a wall-clock bound stops a slow objective rather than a stalled one.
+	 */
+	readonly maxRounds: number
+	/**
+	 * Rounds BEGUN, not rounds finished.
+	 *
+	 * Debited before the work runs, so a round that crashes still counts. A
+	 * counter that only advanced on success lets an objective failing every
+	 * round spin forever, which is precisely the runaway the cap exists to
+	 * stop.
+	 */
+	readonly roundsStarted: number
+	readonly lastRunId?: RunId
+	readonly updatedAt: number
+}
+
+/** A write whose `revision` no longer matches what is stored. */
+export class StaleObjectiveError extends Error {
+	readonly details: { id: string; expectedRevision: number; actualRevision: number }
+
+	constructor(details: { id: string; expectedRevision: number; actualRevision: number }) {
+		super(
+			`Stale objective ${details.id}: expected revision=${details.expectedRevision}, actual=${details.actualRevision}`,
+		)
+		this.name = 'StaleObjectiveError'
+		this.details = details
+	}
+}
+
+/** Why an `advanceObjective` did nothing. */
+export interface ObjectiveRefusal {
+	readonly kind: 'refused'
+	readonly reason: string
+	readonly phase: ObjectivePhase
+}
+
+export interface ObjectiveAdvance {
+	readonly kind: 'advanced'
+	readonly objective: TopicObjective
+}
+
+export type ObjectiveAdvanceResult = ObjectiveAdvance | ObjectiveRefusal
+
+/** What one round decided. */
+export interface ObjectiveRoundVerdict {
+	/** `undefined` leaves the phase alone: the round ran and said nothing. */
+	readonly phase?: Extract<ObjectivePhase, 'complete' | 'blocked'>
+	readonly blockedReason?: ObjectiveBlock
+	readonly runId?: RunId
+}

package/src/types/topic/state.ts

@@ -0,0 +1,60 @@
+import type { TenantId, TopicId } from '../ids/index.js'
+import type { PermissionMode } from '../permission/index.js'
+
+/**
+ * State that outlives a run but belongs to the conversation, not to a run.
+ *
+ * `PermissionMode` was resolved once per run and copied into the executor,
+ * so leaving plan mode meant ending the run and starting a fresh one with
+ * `permissionMode: 'auto'` — discarding the in-flight step and the
+ * tool-schema context with it. The look-around, propose, get-approval,
+ * continue-in-the-SAME-conversation flow could not be built on that, and
+ * `approve_plan` already existed with its approval changing nothing about
+ * the mode.
+ *
+ * Its own record beside the Topic rather than a field on it, with its own
+ * schema version. The Topic record is identity and ownership; this is
+ * mutable session state that changes several times within one conversation
+ * and whose writers are not the Topic's writers. Merging them would make
+ * every mode toggle a CAS conflict against a title rename.
+ */
+export interface TopicState {
+	readonly topicId: TopicId
+	readonly tenantId: TenantId
+	/**
+	 * Compare-and-set counter, starting at 0 for a record's first write.
+	 *
+	 * Separate from the Topic's `ownerVersion` on purpose — see above. A
+	 * host toggling the mode and a manager renaming the topic must not
+	 * invalidate each other.
+	 */
+	readonly revision: number
+	readonly permissionMode: PermissionMode
+	/**
+	 * Messages left for the run that has not started yet.
+	 *
+	 * On the same record as the mode and under the same revision, so a host
+	 * queueing a message and one toggling the mode cannot silently overwrite
+	 * each other — they collide loudly instead, which is what a shared
+	 * conversation needs.
+	 */
+	readonly queuedMessages?: readonly import('../message/index.js').Message[]
+	readonly updatedAt: number
+}
+
+/** A write whose `revision` no longer matches what is stored. */
+export class StaleTopicStateError extends Error {
+	readonly details: {
+		topicId: TopicId
+		expectedRevision: number
+		actualRevision: number
+	}
+
+	constructor(details: { topicId: TopicId; expectedRevision: number; actualRevision: number }) {
+		super(
+			`Stale topic state for ${details.topicId}: expected revision=${details.expectedRevision}, actual=${details.actualRevision}`,
+		)
+		this.name = 'StaleTopicStateError'
+		this.details = details
+	}
+}

package/src/types/topic/store.ts

@@ -0,0 +1,101 @@
+/**
+ * TopicStore — canonical persistence contract for the Topic layer
+ * (Project → **Topic** → Session → SubSession → Run).
+ *
+ * Topics are pure containers (Phase 0 decision B.1). They have no own
+ * message stream and no fan-in `deriveStatus()` — status is owner-managed
+ * (`'open' | 'archived'`). Every accessor takes explicit {@link TenantId};
+ * cross-tenant access rejects with `TenantIsolationError` (Convention #17).
+ *
+ * Read accessors return `null` when the resource does not exist for the
+ * supplied tenant (deny-by-default surface). Callers branch on missing
+ * explicitly — no fallback substitution.
+ *
+ * `deleteTopic` is intentionally a dumb record-delete at this layer:
+ * it does NOT walk session ownership. The "reject when sessions attached"
+ * precondition lives in {@link import('../../manager/topic/lifecycle.js').TopicManager}
+ * where both stores are in scope. Keeping TopicStore free of cross-store
+ * awareness preserves the single-boundary ownership boundary that Phase 2
+ * has just introduced for this layer (Convention #0).
+ *
+ * NZ-TOPIC-01 renamed this from `ThreadStore`/`createThread` etc, leaving
+ * the `threadId` parameter below alone — it is the FK field a Session
+ * carries to its owning Topic, and that rename had its own data-migration
+ * story (persisted `session.json` records already on disk, see
+ * `store/session/disk.ts`). NZ-TOPIC-03 lands it: the parameter below is
+ * `topicId` now, matching the `Session.topicId` it identifies.
+ */
+
+import type { Topic } from '../../types/topic/entity.js'
+import type { TenantId } from '../ids/index.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
+
+/**
+ * Params for {@link TopicStore.createTopic}. The store owns id generation,
+ * `ownerVersion` initialization (0 at create), and timestamps.
+ */
+export interface CreateTopicParams {
+	projectId: ProjectId
+	/**
+	 * User-facing display label. Not unique within the project — see
+	 * {@link Topic} JSDoc. Empty strings are permitted; callers that require
+	 * a label should validate at the API layer.
+	 */
+	title: string
+}
+
+/**
+ * Canonical persistence contract for the Topic layer. Every accessor takes
+ * explicit `tenantId`; cross-tenant reads/writes reject with
+ * `TenantIsolationError` (`session/errors.ts`, Convention #17).
+ */
+export interface TopicStore {
+	/**
+	 * Persist a new Topic under the given project. Returns the minted
+	 * {@link Topic} with `ownerVersion: 0` and freshly-generated
+	 * {@link import('../ids/index.js').TopicId}. Callers must ensure the parent
+	 * project exists and belongs to the same tenant — the store does not
+	 * validate project ownership (that is a cross-store precondition owned by
+	 * the manager).
+	 */
+	createTopic(params: CreateTopicParams, tenantId: TenantId): Promise<Topic>
+
+	/**
+	 * Read a Topic by id. Returns `null` when absent. Cross-tenant reads
+	 * reject with `TenantIsolationError`.
+	 */
+	getTopic(topicId: TopicId, tenantId: TenantId): Promise<Topic | null>
+
+	/**
+	 * Persist a mutation to a Topic record. CAS on `ownerVersion`: if the
+	 * supplied `topic.ownerVersion` does not match the persisted version,
+	 * rejects with {@link import('../../session/errors.js').StaleThreadError}
+	 * (class name unchanged this release). On success the write commits with
+	 * `ownerVersion + 1` and a refreshed `updatedAt`.
+	 *
+	 * Archival transition (`status: 'open' → 'archived'`) shares this path;
+	 * the caller is responsible for verifying that no non-terminal Sessions
+	 * are attached before flipping (see TopicManager.archive).
+	 */
+	updateTopic(topic: Topic, tenantId: TenantId): Promise<void>
+
+	/**
+	 * Hard-delete a Topic record. Idempotent — absent topics succeed as a
+	 * no-op. Rejects with `TenantIsolationError` on cross-tenant access.
+	 *
+	 * **Does NOT cascade to child Sessions** — the caller (typically
+	 * TopicManager) enforces the precondition that no Sessions reference
+	 * this topic. Convention #5: deny-by-default, no implicit cascade.
+	 */
+	deleteTopic(topicId: TopicId, tenantId: TenantId): Promise<void>
+
+	/**
+	 * List all Topics under a project for the given tenant, ordered by
+	 * `createdAt` ascending. Returns an empty array when none exist.
+	 * Cross-tenant reads reject with `TenantIsolationError`.
+	 *
+	 * The return shape is a concrete snapshot — callers that mutate the
+	 * result array do not affect store state.
+	 */
+	listTopics(projectId: ProjectId, tenantId: TenantId): Promise<readonly Topic[]>
+}

package/src/types/workspace/ref.ts

@@ -42,6 +42,13 @@ export type WorkspaceBackendMeta = GitWorktreeBackendMeta
  * Persisted ref to a provisioned workspace. Every {@link Session} with a
  * running Run persists a {@link WorkspaceRef} so recovery after process
  * restart is possible (session-hierarchy.md §7.1).
+ *
+ * NOT `Project.rootPath`. This is per-RUN provisioning — a git worktree cut
+ * for one run and discarded after it, which may be a different directory
+ * entirely. `Project.rootPath` is the durable binding a host uses to answer
+ * "which project is this directory" across sessions and process restarts.
+ * The two words are close enough that the distinction has been rediscovered
+ * more than once; it is written here so it does not have to be again.
  */
 export interface WorkspaceRef {
 	id: WorkspaceId

package/src/utils/abort.ts

@@ -27,7 +27,22 @@ import { toErrorMessage } from './error.js'
  */
 export function abortReasonText(reason: unknown): string | undefined {
 	if (!(reason instanceof Error)) return undefined
-	if (reason.name === 'AbortError' || reason.name === 'TimeoutError') return undefined
+	// `RunCancelled` carries a machine-readable CAUSE ('user' | 'parent' |
+	// 'budget' | 'hook'), and rendering it here would print "was cancelled:
+	// run cancelled by parent" — the same noise the two names above are
+	// suppressed for. A reader wanting the cause asks `cancelCauseOf`.
+	//
+	// By name, not by class, for the reason this whole function is: a reason
+	// crosses a package boundary where `instanceof` stops holding across
+	// duplicate copies. Importing the class here would also close a cycle
+	// between `utils/` and `types/run/`.
+	if (
+		reason.name === 'AbortError' ||
+		reason.name === 'TimeoutError' ||
+		reason.name === 'RunCancelled'
+	) {
+		return undefined
+	}
 	const text = toErrorMessage(reason).trim()
 	return text.length > 0 ? text : undefined
 }