@namzu/sdk 43.0.0 → 44.1.0

package/src/types/topic/entity.ts

@@ -4,14 +4,14 @@ import type { ProjectId, TopicId } from '../session/ids.js'
 /**
  * Lifecycle state of a Topic.
  *
- * - `open` — accepts new Sessions and new Runs under existing Sessions.
+ * - `open` — accepts new Sessions and new turns 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 Topic is in a non-terminal state (guarded at the
  *   store level by listing + status fan-in).
  *
  * 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
+ * Sessions the way a Session does from its turns. 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.
  */
@@ -20,7 +20,7 @@ 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 → Topic → Session → SubSession → Run).
+ * (Project → Topic → Session → SubSession → Turn).
  *
  * 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.
@@ -32,7 +32,7 @@ export type TopicStatus = 'open' | 'archived'
  * topic or line-of-work within a Project (e.g. "auth refactor", "billing
  * 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.
+ * state, handoff history, and Turn streams.
  *
  * ## Why Topic is a first-class layer (A2A-connection surface)
  *
@@ -58,7 +58,7 @@ export type TopicStatus = 'open' | 'archived'
  * ## Design reference
  *
  * Session design §4 (ratified in ses_001-hierarchy-redesign):
- *   - Container only. No own message stream, no own Run stream. Messages
+ *   - Container only. No own message stream, no own Turn 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 TopicId}; the title is
@@ -71,7 +71,7 @@ export type TopicStatus = 'open' | 'archived'
  *     with `details.topicId`. 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 Topic-vs-Session contract boundary.
+ *     Turn-derived. This is the Topic-vs-Session contract boundary.
  */
 export interface Topic {
 	id: TopicId

package/src/types/topic/objective.ts

@@ -1,10 +1,10 @@
-import type { RunId, TenantId, TopicId } from '../ids/index.js'
+import type { SessionId, TenantId, TopicId, TurnId } from '../ids/index.js'
 
 /**
- * Work that outlives one run.
+ * Work that outlives one turn.
  *
  * Nothing in this kernel survived a single `query()` call. `stopWhen` and
- * `prepareStep` shape one loop, the completion inbox holds one run open for
+ * `prepareStep` shape one loop, the completion inbox holds one turn 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
@@ -53,7 +53,8 @@ export interface TopicObjective {
 	 * stop.
 	 */
 	readonly roundsStarted: number
-	readonly lastRunId?: RunId
+	/** The turn that ran the most recent round. */
+	readonly lastTurn?: { readonly sessionId: SessionId; readonly turnId: TurnId }
 	readonly updatedAt: number
 }
 
@@ -89,5 +90,6 @@ 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
+	readonly sessionId?: SessionId
+	readonly turnId?: TurnId
 }

package/src/types/topic/state.ts

@@ -2,10 +2,10 @@ 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.
+ * State that outlives a turn but belongs to the conversation, not to a turn.
  *
- * `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` was resolved once per turn and copied into the executor,
+ * so leaving plan mode meant ending the turn 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
@@ -31,7 +31,7 @@ export interface TopicState {
 	readonly revision: number
 	readonly permissionMode: PermissionMode
 	/**
-	 * Messages left for the run that has not started yet.
+	 * Messages left for the turn 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

package/src/types/topic/store.ts

@@ -1,6 +1,6 @@
 /**
  * TopicStore — canonical persistence contract for the Topic layer
- * (Project → **Topic** → Session → SubSession → Run).
+ * (Project → **Topic** → Session → SubSession → Turn).
  *
  * Topics are pure containers (Phase 0 decision B.1). They have no own
  * message stream and no fan-in `deriveStatus()` — status is owner-managed

package/src/types/workspace/index.ts

@@ -1,7 +1,7 @@
 // Sub-barrel for the workspace shape surface (Convention #4).
 // Concrete types live in sibling files; re-export them here.
 //
-// Runtime workspace machinery (drivers, registry, path-builder, git-worktree)
+// Runtime workspace machinery (drivers, registry, git-worktree)
 // stays under `session/workspace/` — this barrel is shape-only.
 
 export type {
@@ -12,10 +12,10 @@ export type {
 } from './ref.js'
 
 export type {
-	SharedRunWorkspaceAgentRecord,
-	SharedRunWorkspaceManifest,
-	SharedRunWorkspacePaths,
-	SharedRunWorkspacePlan,
-	SharedRunWorkspaceRefs,
-	SharedRunWorkspaceSource,
-} from './shared-run.js'
+	SharedSessionWorkspaceAgentRecord,
+	SharedSessionWorkspaceManifest,
+	SharedSessionWorkspacePaths,
+	SharedSessionWorkspacePlan,
+	SharedSessionWorkspaceRefs,
+	SharedSessionWorkspaceSource,
+} from './shared-session.js'

package/src/types/workspace/ref.ts

@@ -40,11 +40,11 @@ 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
+ * running turn 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
+ * NOT `Project.rootPath`. This is per-TURN provisioning — a git worktree cut
+ * for one turn 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

package/src/types/workspace/shared-session.ts

@@ -0,0 +1,65 @@
+export interface SharedSessionWorkspacePaths {
+	root: string
+	manifest: string
+	sharedContext: string
+	sources: string
+	plans: string
+	agents: string
+}
+
+export interface SharedSessionWorkspaceSource {
+	id: string
+	label: string
+	path: string
+	kind?: string
+	sizeBytes?: number
+}
+
+export interface SharedSessionWorkspacePlan {
+	id: string
+	briefPath: string
+	status: 'seeded' | 'ready' | 'running' | 'completed' | 'failed'
+	updatedAt: string
+}
+
+export interface SharedSessionWorkspaceAgentRecord {
+	agentId: string
+	taskId?: string
+	workPath: string
+	status: 'assigned' | 'running' | 'completed' | 'failed' | 'canceled'
+	updatedAt: string
+}
+
+export interface SharedSessionWorkspaceManifest {
+	schemaVersion: 1
+	kind: 'shared-session-workspace'
+	createdAt: string
+	updatedAt: string
+	label?: string
+	paths: SharedSessionWorkspacePaths
+	sources: SharedSessionWorkspaceSource[]
+	plans: SharedSessionWorkspacePlan[]
+	agents: SharedSessionWorkspaceAgentRecord[]
+}
+
+export interface SharedSessionWorkspaceRefs {
+	rootPath: string
+	manifestPath: string
+	/**
+	 * Path to the shared coordination packet for this session. Workers read this
+	 * before the larger task context or source inventory so common runtime
+	 * instructions, source summaries, and workspace paths are not rediscovered
+	 * independently by every specialist.
+	 */
+	sharedContextPath: string
+	sourceInventoryPath: string
+	supervisorBriefPath: string
+	/**
+	 * Path to the canonical, full-fidelity user task description for this session.
+	 * Workers read this instead of receiving the user's request text inline in
+	 * every child prompt — keeps child prompts compact and lets the request
+	 * grow without bloating per-worker handoffs.
+	 */
+	taskContextPath: string
+	agentsPath: string
+}

package/src/utils/abort.ts

@@ -28,19 +28,19 @@ import { toErrorMessage } from './error.js'
  */
 export function abortReasonText(reason: unknown): string | undefined {
 	if (!(reason instanceof Error)) return undefined
-	// `RunCancelled` carries a machine-readable CAUSE ('user' | 'parent' |
+	// `TurnCancelled` 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
+	// turn 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/`.
+	// between `utils/` and `types/session/`.
 	if (
 		reason.name === 'AbortError' ||
 		reason.name === 'TimeoutError' ||
-		reason.name === 'RunCancelled'
+		reason.name === 'TurnCancelled'
 	) {
 		return undefined
 	}

package/src/utils/atomic-write.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from 'node:crypto'
-import { rename, unlink, writeFile } from 'node:fs/promises'
+import { type FileHandle, open, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
 
 /**
  * Write-then-rename, with a sidecar name no other writer can pick.
@@ -16,7 +17,7 @@ import { rename, unlink, writeFile } from 'node:fs/promises'
  * the mechanism meant to prevent it.
  *
  * This is not hypothetical for this SDK. The cross-process park and unpark
- * handoff — one process suspending a run and another resuming it — is a
+ * handoff — one process suspending a turn and another resuming it — is a
  * design where two processes legitimately touch the same records, and it is
  * the feature these stores exist to serve. One store already got this
  * right; the rest inherited the fixed name.
@@ -41,10 +42,20 @@ export function temporaryPathFor(filePath: string): string {
  * the store with files that look like records to anything scanning the
  * directory, and the next attempt would not reuse it anyway.
  */
-export async function atomicWriteFile(filePath: string, content: string): Promise<void> {
+export async function atomicWriteFile(
+	filePath: string,
+	content: string,
+	options: { readonly mode?: number } = {},
+): Promise<void> {
 	const tempPath = temporaryPathFor(filePath)
 	try {
-		await writeFile(tempPath, content, 'utf-8')
+		// The mode is applied when the sidecar is created, so the published
+		// file never exists with wider permissions, not even for a moment.
+		await writeFile(
+			tempPath,
+			content,
+			options.mode === undefined ? 'utf-8' : { encoding: 'utf-8', mode: options.mode },
+		)
 		await renameWithRetry(tempPath, filePath)
 	} catch (err) {
 		await unlink(tempPath).catch(() => undefined)
@@ -52,6 +63,58 @@ export async function atomicWriteFile(filePath: string, content: string): Promis
 	}
 }
 
+/**
+ * Publish `content` atomically AND durably: when this resolves, the new body
+ * and the rename that published it are on stable storage.
+ *
+ * {@link atomicWriteFile} survives a process crash — a reader sees the old
+ * file or the new one — but not a power loss: without an fsync the kernel may
+ * not have written the new body, or the directory entry that names it, when
+ * the machine stops. For a record that is about to become the ONLY thing
+ * pointing at some data (the older copy of which the caller deletes next),
+ * that is the difference between losing an update and losing the record.
+ *
+ * Costs two fsyncs, so it is for rare writes. On Windows, where a directory
+ * cannot be opened for fsync, the directory entry is left to the filesystem;
+ * see {@link syncDirectory}.
+ */
+export async function durableWriteFile(filePath: string, content: string): Promise<void> {
+	const tempPath = temporaryPathFor(filePath)
+	let handle: FileHandle | undefined
+	try {
+		handle = await open(tempPath, 'wx')
+		await handle.writeFile(content, 'utf-8')
+		await handle.sync()
+		await handle.close()
+		handle = undefined
+		await renameWithRetry(tempPath, filePath)
+	} catch (err) {
+		await handle?.close().catch(() => undefined)
+		await unlink(tempPath).catch(() => undefined)
+		throw err
+	}
+	await syncDirectory(dirname(filePath))
+}
+
+/**
+ * Make the entries of `directory` — a rename into it, a file created in it —
+ * survive a power loss.
+ *
+ * A failure is thrown on POSIX: a caller that asked for durability and did not
+ * get it must not go on to delete what the durable copy was meant to replace.
+ * On Windows opening a directory for fsync raises `EPERM` and there is no
+ * other way to ask, so there it does nothing; NTFS journals its metadata.
+ */
+export async function syncDirectory(directory: string): Promise<void> {
+	if (process.platform === 'win32') return
+	const handle = await open(directory, 'r')
+	try {
+		await handle.sync()
+	} finally {
+		await handle.close()
+	}
+}
+
 /** Transient on Windows while another handle still holds the target. */
 const CONTENDED = new Set(['EPERM', 'EACCES', 'EBUSY'])
 const RENAME_ATTEMPTS = 5

package/src/utils/cost.ts

@@ -106,17 +106,16 @@ export function calculateCost(usage: TokenUsage, pricing: ModelPricing): CostInf
 /**
  * Whether `current` is a total nothing has been added to yet.
  *
- * All three conditions, not one. A run whose only turn so far was unpriced has
+ * All three conditions, not one. A turn whose only turn so far was unpriced has
  * a zero total and no rate fields too, and adopting the next turn's rate card
  * as though it described the whole total would be exactly the wrong claim.
  *
  * This predicate is only sound while every writer of a `CostInfo` goes through
- * this module or states the truth in its vocabulary. One did not:
- * `projectEmergencyToCheckpoint` wrote `ZERO_COST` beside a real, non-zero
- * `tokenUsage`, which is byte-identical to a fresh total — so a run resumed
- * from an emergency dump would have adopted its next turn's rate card as
- * covering spend that happened before the crash. That projection now records
- * the pre-crash tokens as unpriced, which is both true and, usefully, not
+ * this module or states the truth in its vocabulary. A writer that put
+ * `ZERO_COST` beside a real, non-zero `tokenUsage` would be byte-identical to a
+ * fresh total, and a resumed turn would adopt its next rate card as covering
+ * spend that happened before the resume. Spend whose price is unknown is
+ * recorded as unpriced instead, which is both true and, usefully, not
  * fresh-shaped.
  */
 function isFresh(current: CostInfo): boolean {
@@ -133,13 +132,13 @@ function isFresh(current: CostInfo): boolean {
  *
  * Kept when one card still covers the whole total; dropped when it does not.
  * Dropping rather than overwriting is the change: the previous version wrote
- * the incoming card over whatever was there, so a run that swapped models
+ * the incoming card over whatever was there, so a turn that swapped models
  * reported the last card applied as though it had priced every token.
  *
  * Equal-but-distinct cards are treated as one, deliberately. Two models at the
  * same published rate produce a total that a single rate card DOES describe,
  * which is the only claim these two fields make — they name a rate, not a
- * model, and `Run.steps[].servedBy` carries which model served each turn.
+ * model, and `Turn.steps[].servedBy` carries which model served each turn.
  */
 function ratesFor(
 	current: CostInfo,
@@ -178,11 +177,11 @@ export function accumulateCost(
  * Record tokens that were consumed at a rate nobody has.
  *
  * The alternative was to add nothing and leave the total alone, which is how
- * every run came to report `$0.00` for work that cost real money. Counting the
+ * every turn came to report `$0.00` for work that cost real money. Counting the
  * tokens instead makes the gap a fact the caller can read and the budget guard
  * can refuse on, rather than an absence that looks like an answer.
  *
- * The rate fields go, if they were there: a total that omits part of a run is
+ * The rate fields go, if they were there: a total that omits part of a turn is
  * not described by any single card.
  */
 export function accumulateUnpricedCost(current: CostInfo, additionalUsage: TokenUsage): CostInfo {
@@ -204,7 +203,7 @@ export function formatCost(usd: number): string {
  *
  * Exists so that no surface has to re-derive the free/unknown distinction from
  * two fields and get it subtly wrong. `@namzu/cli` printed
- * `'$0.0000 (this provider reported no price)'` for every run, because every
+ * `'$0.0000 (this provider reported no price)'` for every turn, because every
  * run was unpriced; now the two cases really are different and the string has
  * to follow.
  */

package/src/utils/env.ts

@@ -4,7 +4,7 @@
  *
  * Every bound that can be tuned wants the same three answers, and the third
  * is the one worth sharing: a variable set to `soon`, to `-1` or to nothing
- * at all falls back rather than parsing, because a run must not wait, hold or
+ * at all falls back rather than parsing, because a turn must not wait, hold or
  * time out for `NaN`.
  *
  * `process.env` is read on every call, so where it is called decides when the

package/src/utils/id.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from 'node:crypto'
 import { unsafeId } from '../types/ids/brand.js'
 import type {
 	ActivityId,
@@ -13,7 +12,6 @@ import type {
 	CredentialId,
 	DeliverableId,
 	DocumentId,
-	EmergencySaveId,
 	EnvironmentId,
 	ExecutionContextId,
 	GoalId,
@@ -30,7 +28,7 @@ import type {
 	PlanId,
 	PluginId,
 	ProjectId,
-	RunId,
+	RecordId,
 	SandboxId,
 	SessionId,
 	SubSessionId,
@@ -39,15 +37,23 @@ import type {
 	TenantId,
 	ToolCallId,
 	TopicId,
+	TurnId,
 	UserId,
 	VaultRef,
 	WorkspaceId,
 } from '../types/ids/index.js'
 import { entityIdPattern } from './id-format.js'
+import { uuidv7 } from './uuidv7.js'
 
-/** Factories supply the nominal type; the wire identity carries no kind. */
+/**
+ * Factories supply the nominal type; the wire identity carries no kind.
+ *
+ * Every factory mints a UUIDv7 (`./uuidv7.ts`), so ids sort by creation time
+ * and ids minted by one process sort in the order it minted them. The checks
+ * below accept any RFC 9562 version, so ids minted before this still read.
+ */
 function generateId<T extends string>(): T {
-	return unsafeId<T>(randomUUID())
+	return unsafeId<T>(uuidv7())
 }
 
 export function generateProjectId(): ProjectId {
@@ -58,7 +64,12 @@ export function generateTopicId(): TopicId {
 	return generateId()
 }
 
-export function generateRunId(): RunId {
+export function generateTurnId(): TurnId {
+	return generateId()
+}
+
+/** The id of one session-log record (its `id` field). */
+export function generateRecordId(): RecordId {
 	return generateId()
 }
 
@@ -154,10 +165,6 @@ export function generateAuditEventId(): AuditEventId {
 	return generateId()
 }
 
-export function generateEmergencySaveId(): EmergencySaveId {
-	return generateId()
-}
-
 export function generateMemoryId(): MemoryId {
 	return generateId()
 }
@@ -192,7 +199,8 @@ export function generateDeliverableId(): DeliverableId {
 
 /** Entity kinds are supplied by a typed field or storage collection. */
 export interface EntityIdByKind {
-	run: RunId
+	turn: TurnId
+	record: RecordId
 	message: MessageId
 	session: SessionId
 	goal: GoalId
@@ -216,7 +224,6 @@ export interface EntityIdByKind {
 	lock: LockId
 	advisory: AdvisoryId
 	advisoryCall: AdvisoryCallId
-	emergencySave: EmergencySaveId
 	memory: MemoryId
 	plugin: PluginId
 	sandbox: SandboxId
@@ -238,7 +245,8 @@ export interface EntityIdByKind {
 export type EntityIdKind = keyof EntityIdByKind
 
 const ENTITY_KINDS = new Set<EntityIdKind>([
-	'run',
+	'turn',
+	'record',
 	'message',
 	'session',
 	'goal',
@@ -262,7 +270,6 @@ const ENTITY_KINDS = new Set<EntityIdKind>([
 	'lock',
 	'advisory',
 	'advisoryCall',
-	'emergencySave',
 	'memory',
 	'plugin',
 	'sandbox',
@@ -312,8 +319,8 @@ export function parseProjectId(raw: string): ProjectId {
 	return parseId(raw, 'project', 'ProjectId')
 }
 /** @deprecated Use the `as*Id` constructor of the same type; this family throws a plain Error and is removed in the next major. */
-export function parseRunId(raw: string): RunId {
-	return parseId(raw, 'run', 'RunId')
+export function parseTurnId(raw: string): TurnId {
+	return parseId(raw, 'turn', 'TurnId')
 }
 /** @deprecated Use the `as*Id` constructor of the same type; this family throws a plain Error and is removed in the next major. */
 export function parseConnectorInstanceId(raw: string): ConnectorInstanceId {
@@ -354,7 +361,8 @@ function makeIdParser<K extends EntityIdKind>(kind: K): IdParser<EntityIdByKind[
 	}
 }
 
-export const asRunId: IdParser<RunId> = makeIdParser('run')
+export const asTurnId: IdParser<TurnId> = makeIdParser('turn')
+export const asRecordId: IdParser<RecordId> = makeIdParser('record')
 export const asMessageId: IdParser<MessageId> = makeIdParser('message')
 export const asSessionId: IdParser<SessionId> = makeIdParser('session')
 export const asGoalId: IdParser<GoalId> = makeIdParser('goal')
@@ -379,7 +387,6 @@ export const asCheckpointId: IdParser<CheckpointId> = makeIdParser('checkpoint')
 export const asLockId: IdParser<LockId> = makeIdParser('lock')
 export const asAdvisoryId: IdParser<AdvisoryId> = makeIdParser('advisory')
 export const asAdvisoryCallId: IdParser<AdvisoryCallId> = makeIdParser('advisoryCall')
-export const asEmergencySaveId: IdParser<EmergencySaveId> = makeIdParser('emergencySave')
 export const asMemoryId: IdParser<MemoryId> = makeIdParser('memory')
 export const asPluginId: IdParser<PluginId> = makeIdParser('plugin')
 export const asSandboxId: IdParser<SandboxId> = makeIdParser('sandbox')

package/src/utils/log/attributes.ts

@@ -1,8 +1,8 @@
 // The allowlist for a hand-built attribute bag. `LogContext` on
 // `../logger.ts` stays exactly what it is — `Record<string, unknown>` —
 // because `Logger.child(context: LogContext)` is in INPUT position on the
-// public surface (`logger?: Logger` on `RunConfig` and tool config:
-// `types/run/config.ts:156`, `types/tool/index.ts:396`): narrowing it would
+// public surface (`logger?: Logger` on `TurnConfig` and tool config:
+// `types/session/config.ts:162`, `types/tool/index.ts:861`): narrowing it would
 // break every host that already implemented `Logger` correctly, for a type
 // change with no payoff to them. `LogAttributes` is instead a type a caller
 // builds TOWARD — construct the variable half of a log call with this type

package/src/utils/log/create-logger.ts

@@ -153,7 +153,7 @@ function build(
 		} catch {
 			// A host sink is arbitrary code the kernel does not control. The old
 			// direct `process.stderr.write` implementation could never throw into
-			// an in-flight run; a naive seam here would introduce that failure
+			// an in-flight turn; a naive seam here would introduce that failure
 			// mode for the first time — a broken sink aborting, say, a
 			// tool-completion path. Never rethrown, never logged through the same
 			// sink that just failed — counted instead, so a doctor check can

package/src/utils/log/redact.ts

@@ -2,7 +2,7 @@
 //
 // Runs once, in the pipeline, ahead of sink dispatch — not inside
 // jsonLinesSink, and not inside any other individual sink. A scan that only
-// jsonLinesSink ran would leave prettySink (the one `namzu run` actually
+// jsonLinesSink ran would leave prettySink (the one `namzu exec` actually
 // uses) and every host-supplied sink with no second layer at all, which is
 // the gap a scoped-to-one-sink design would reintroduce: the machine-read
 // path would be the only protected one.

package/src/utils/log/sinks.ts

@@ -19,7 +19,7 @@ export const NOOP_SINK: LogSink = {
 
 /**
  * One JSON object per line — the canonical wire format for the machine-read
- * path (`namzu run-stream`'s stderr). JSON string-escaping neutralises
+ * path (`namzu exec --json`'s stderr). JSON string-escaping neutralises
  * `\n`/`\r` by construction, closing the log-forging surface without a
  * single character-stripping call site, which is bypassable anyway.
  *
@@ -67,7 +67,7 @@ const SEVERITY_LABEL: Record<LogRecord['severityText'], string> = {
 // guarantee yet that either is a constant (that lands with the CI gate in
 // later work) — a remote MCP server that names itself an escape sequence
 // erasing the previous line and printing a fake refusal is a real forging
-// attempt against the terminal `namzu run` writes to today, not a
+// attempt against the terminal `namzu exec` writes to today, not a
 // hypothetical one.
 // biome-ignore lint/suspicious/noControlCharactersInRegex: this pattern IS the control-character filter — the escapes below are ASCII text (`\x00`-`\x1F`, `\x7F`), not raw bytes pasted into the source.
 const CONTROL_BYTE = /[\x00-\x1F\x7F]/g

package/src/utils/log/types.ts

@@ -1,7 +1,7 @@
 // The LogSink seam's record and pipeline types.
 //
 // `../logger.ts` keeps `Logger` and `LogContext` unchanged — `Logger` is in
-// INPUT position on the public surface (`logger?: Logger` on `RunConfig` and
+// INPUT position on the public surface (`logger?: Logger` on `TurnConfig` and
 // tool config), so every host's existing implementation must keep satisfying
 // it forever. This seam was additive when it landed and stayed that way
 // through LOG-20, which removed the two process-global accessors that used to

package/src/utils/shell-compress.ts

@@ -2,13 +2,13 @@ const STACK_FRAME_RE =
 	/^\s+at\s+|^\s+File\s+"[^"]+",\s+line\s+\d+|^\s+at\s+[\w.$]+\(|^\s+\d+:\s+\w|^\s+from\s+\//
 
 // This line is tested against every line of shell output, which is
-// attacker-reachable (e.g. bash stdout can carry bytes the run itself never
+// attacker-reachable (e.g. bash stdout can carry bytes the turn itself never
 // typed — a fetched file, a piped response). The first alternative used to
 // open with an unbounded `[\s...]+` hunting for a PASS/ok marker that may
 // not exist: on a long run of bullet/whitespace characters with nothing to
 // match, the engine restarts that scan at every offset, and the per-offset
 // scan itself walks the remaining string — quadratic in line length (a
-// single crafted line was enough to hang the process). Capping the run
+// single crafted line was enough to hang the process). Capping the turn
 // bounds the per-offset work to a constant, so the unavoidable per-offset
 // restart stays linear overall. 40 is generous for the checkmark/indent
 // prefixes real tool output produces; nothing legitimate needs more.