@namzu/sdk 27.0.0 → 28.0.0

package/src/session/handoff/broadcast.ts

@@ -22,7 +22,7 @@
  */
 
 import { requireOpenProject } from '../../manager/project/lifecycle.js'
-import type { ThreadManager } from '../../manager/thread/lifecycle.js'
+import type { TopicManager } from '../../manager/topic/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
 import type { SubSessionId } from '../../types/session/ids.js'
@@ -48,7 +48,7 @@ export interface BroadcastHandoffDeps {
 	 * Added in Phase 2.6; checked once per broadcast (all recipients share
 	 * a threadId by the fan-out invariant validated above).
 	 */
-	threadManager: ThreadManager
+	threadManager: TopicManager
 }
 
 /**
@@ -116,8 +116,8 @@ export async function executeBroadcastHandoff(
 		if (a.expectedOwnerVersion !== first.expectedOwnerVersion) {
 			throw new Error('executeBroadcastHandoff: all assignments must share expectedOwnerVersion')
 		}
-		if (a.threadId !== first.threadId) {
-			throw new Error('executeBroadcastHandoff: all assignments must share threadId')
+		if (a.topicId !== first.topicId) {
+			throw new Error('executeBroadcastHandoff: all assignments must share topicId')
 		}
 		if (a.projectId !== first.projectId) {
 			throw new Error('executeBroadcastHandoff: all assignments must share projectId')
@@ -143,9 +143,9 @@ export async function executeBroadcastHandoff(
 
 	// Thread archive gate (Phase 2.6) — runs BEFORE source load/capacity so an
 	// archived thread fails fastest with `ThreadClosedError`. All assignments
-	// share `threadId` by the shape validation above. Runs BEFORE the CAS
+	// share `topicId` by the shape validation above. Runs BEFORE the CAS
 	// lock so a denied fan-out leaves the source session untouched.
-	await deps.threadManager.requireOpen(first.threadId, tenantId)
+	await deps.threadManager.requireOpen(first.topicId, tenantId)
 
 	// 3. Load source + tenant check.
 	const source = await deps.store.getSession(first.sourceSessionId, tenantId)
@@ -158,9 +158,9 @@ export async function executeBroadcastHandoff(
 			resource: `session(${source.id})`,
 		})
 	}
-	if (source.threadId !== first.threadId) {
+	if (source.topicId !== first.topicId) {
 		throw new Error(
-			`Assignment threadId ${first.threadId} does not match source threadId ${source.threadId}`,
+			`Assignment topicId ${first.topicId} does not match source topicId ${source.topicId}`,
 		)
 	}
 	if (source.projectId !== first.projectId) {
@@ -245,7 +245,7 @@ export async function executeBroadcastHandoff(
 
 			const childSession = await deps.store.createSession(
 				{
-					threadId: source.threadId,
+					topicId: source.topicId,
 					projectId: source.projectId,
 					currentActor: assignment.recipientActor,
 				},

package/src/session/handoff/single.ts

@@ -21,7 +21,7 @@
  */
 
 import { requireOpenProject } from '../../manager/project/lifecycle.js'
-import type { ThreadManager } from '../../manager/thread/lifecycle.js'
+import type { TopicManager } from '../../manager/topic/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
 import type { SessionStore } from '../../types/session/store.js'
@@ -67,11 +67,11 @@ export interface SingleHandoffDeps {
 	events: HandoffEventSink
 	runStatus?: RunStatusResolver
 	/**
-	 * Gate the recipient-session creation on the Thread being `'open'`.
+	 * Gate the recipient-session creation on the Topic being `'open'`.
 	 * Added in Phase 2.6 to mirror spawn — a handoff into an archived
-	 * Thread would otherwise undermine `ThreadManager.archive`.
+	 * Topic would otherwise undermine `TopicManager.archive`.
 	 */
-	threadManager: ThreadManager
+	threadManager: TopicManager
 }
 
 /**
@@ -97,7 +97,7 @@ export async function executeSingleHandoff(
 	// fails fastest with `ThreadClosedError` rather than a lock rejection or
 	// capacity error. Checked BEFORE the CAS lock so a denied handoff leaves
 	// the source session untouched.
-	await deps.threadManager.requireOpen(assignment.threadId, tenantId)
+	await deps.threadManager.requireOpen(assignment.topicId, tenantId)
 
 	// 1. Load source session + tenant check.
 	const source = await deps.store.getSession(assignment.sourceSessionId, tenantId)
@@ -110,9 +110,9 @@ export async function executeSingleHandoff(
 			resource: `session(${source.id})`,
 		})
 	}
-	if (source.threadId !== assignment.threadId) {
+	if (source.topicId !== assignment.topicId) {
 		throw new Error(
-			`Assignment threadId ${assignment.threadId} does not match source session threadId ${source.threadId}`,
+			`Assignment topicId ${assignment.topicId} does not match source session topicId ${source.topicId}`,
 		)
 	}
 	if (source.projectId !== assignment.projectId) {
@@ -190,7 +190,7 @@ export async function executeSingleHandoff(
 
 		const recipientSession = await deps.store.createSession(
 			{
-				threadId: source.threadId,
+				topicId: source.topicId,
 				projectId: source.projectId,
 				currentActor: assignment.recipientActor,
 			},

package/src/session/migration/filesystem.ts

@@ -2,6 +2,12 @@
  * Boot-time filesystem re-layout — `.namzu/threads/{thd_X}/` →
  * `.namzu/projects/{prj_legacy_<X>}/sessions/ses_legacy_default/runs/...`.
  *
+ * The `thd_X` this module reads off the filesystem is D2 meaning (a), the
+ * pre-0.2.0 top-level container — unrelated to and untouched by
+ * NZ-TOPIC-04's narrowing of the live Topic layer's id to `top_*`. As of
+ * that task `thd_*` means only what this module has always used it to
+ * mean; see `session/migration/id-prefix.ts` for the disambiguation.
+ *
  * Trigger: first {@link RunContextFactory.build} call per process. The
  * factory invokes {@link DefaultFilesystemMigrator.migrate} before resolving
  * any path so legacy runs are never orphaned by the new layout.
@@ -41,10 +47,14 @@
 
 import { mkdir, readdir, rename, stat } from 'node:fs/promises'
 import { join } from 'node:path'
+import { BOOT_EVENT_NAMES } from '../../constants/telemetry/index.js'
 import type { TenantId } from '../../types/ids/index.js'
 import { UNKNOWN_TENANT_ID } from '../../types/ids/index.js'
 import type { ProjectId, SessionId } from '../../types/session/ids.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
+import { asProjectId, asSessionId } from '../../utils/id.js'
+import { EVENT_NAME_ATTRIBUTE } from '../../utils/log/types.js'
+import type { Logger } from '../../utils/logger.js'
 import { FilesystemMigrationError } from './errors.js'
 import { acquireMigrationLock, readMarker, releaseMigrationLock, writeMarker } from './marker.js'
 
@@ -53,7 +63,7 @@ import { acquireMigrationLock, readMarker, releaseMigrationLock, writeMarker } f
  * Session entity. Every migrated thread collapses into this single session
  * so consumers can still address the runs through the new layout.
  */
-export const LEGACY_DEFAULT_SESSION_ID = 'ses_legacy_default' as SessionId
+export const LEGACY_DEFAULT_SESSION_ID = asSessionId('ses_legacy_default')
 
 /** Prefix for projects synthesised from legacy `thd_*` folders. */
 export const LEGACY_DEFAULT_PROJECT_PREFIX = 'prj_legacy_'
@@ -97,6 +107,40 @@ export const NOOP_FILESYSTEM_MIGRATION_SINK: FilesystemMigrationSink = {
 	emit() {},
 }
 
+/**
+ * Wires the migration facts `DefaultFilesystemMigrator` already computes —
+ * `kind`, `migratedThreads`, `markerPath`, `at` — to a `Logger`, instead of
+ * the sink they are thrown at on every real boot today
+ * (`NOOP_FILESYSTEM_MIGRATION_SINK`, still `ensureMigrated`'s default — see
+ * `runtime/query/context.ts`). A caller opts into this by constructing its
+ * own `DefaultFilesystemMigrator(loggingMigrationSink(log))` and passing it
+ * to `ensureMigrated`, the way `runtime/query/index.ts` does; nothing here
+ * changes what the default migrator does.
+ *
+ * `FilesystemMigrationSink.emit` is only ever called with
+ * `type: 'filesystem.migrated'` (Step 6 in the module doc above) —
+ * `already_migrated` and `noop_no_legacy` never reach a sink at all, by the
+ * shape of `FilesystemMigrationEvent`. A caller that wants those two logged
+ * as well reads them straight off `ensureMigrated`'s resolved
+ * `FilesystemMigrationResult`, the way `runtime/query/index.ts` does,
+ * rather than this function growing a case the type it wraps cannot
+ * produce — widening `FilesystemMigrationEvent` to carry them would be a
+ * breaking change to every exhaustive switch already written over it.
+ */
+export function loggingMigrationSink(log: Logger): FilesystemMigrationSink {
+	return {
+		emit(event) {
+			const { result } = event
+			log.info('filesystem migration completed', {
+				[EVENT_NAME_ATTRIBUTE]: BOOT_EVENT_NAMES.MIGRATION_COMPLETED,
+				'namzu.migration.kind': result.kind,
+				'namzu.migration.marker_path': result.markerPath,
+				'namzu.migration.migrated_thread_count': result.migratedThreads.length,
+			})
+		},
+	}
+}
+
 /** Interface so consumers can inject a stub migrator in tests. */
 export interface FilesystemMigrator {
 	migrate(rootDir: string): Promise<FilesystemMigrationResult>
@@ -276,7 +320,7 @@ export class DefaultFilesystemMigrator implements FilesystemMigrator {
 					})
 				}
 
-				const newProjectId = `${LEGACY_DEFAULT_PROJECT_PREFIX}${suffix}` as ProjectId
+				const newProjectId = asProjectId(`${LEGACY_DEFAULT_PROJECT_PREFIX}${suffix}`)
 
 				const legacyRunsDir = join(threadsDir, legacyThreadId, 'runs')
 				const newProjectDir = join(projectsDir, newProjectId)

package/src/session/migration/id-prefix.ts

@@ -1,21 +1,34 @@
 /**
- * ID-prefix migration window — read-side compat for legacy `thd_*` IDs.
+ * ID-prefix migration window — read-side compat for the pre-0.2.0 top-level
+ * `thd_*` container id (D2 meaning (a), ses_020). NZ-TOPIC-04 narrowed the
+ * Topic layer's own id (D2 meaning (b)) to `top_*`, so as of this release
+ * `thd_*` means ONLY the legacy container everywhere in this codebase — see
+ * `types/ids/index.ts` for where the two meanings used to collide.
  *
- * Consumers that touch raw legacy IDs (filesystem migrator, wire decoders,
- * CLI imports) route through {@link acceptLegacyThreadId} so the warning
- * signal is structured rather than ad-hoc console output (Convention #18).
+ * Consumers that touch raw legacy container IDs (the filesystem migrator,
+ * wire decoders, CLI imports) route through {@link acceptLegacyContainerId}
+ * so the warning signal is structured rather than ad-hoc console output
+ * (Convention #18).
  *
  * | Window state | Reader accepts      | Writer emits | Legacy read behaviour         |
  * |--------------|---------------------|--------------|-------------------------------|
  * | OPEN (now)   | `thd_*` AND `prj_*` | `prj_*` only | emits `MigrationWarning` once |
  * | CLOSED       | `prj_*` only        | `prj_*` only | rejects `StalePrefixError`    |
  *
- * The {@link WINDOW_OPEN} constant is the single switch that flips this
- * module from soft-accept to hard-reject. Convention #0: no silent
- * long-lived compat — the window is explicit and fails closed when closed.
+ * The {@link WINDOW_OPEN} constant is the module-level default for
+ * {@link acceptLegacyContainerId}'s `windowOpen` parameter — the single
+ * knob that flips this module from soft-accept to hard-reject in
+ * production. The writer guard {@link rejectLegacyContainerPrefix} has no
+ * such fork: a writer must never emit `thd_*` in EITHER window state (see
+ * the table's Writer column, unchanged across both rows), so it takes no
+ * `windowOpen` parameter at all — one would be unused, which is its own
+ * failure mode (a-check-that-cannot-fail, applied to an argument no less
+ * than to a branch). Convention #0: no silent long-lived compat — the
+ * window is explicit and fails closed when closed.
  */
 
 import type { ProjectId } from '../../types/session/ids.js'
+import { asProjectId } from '../../utils/id.js'
 
 /**
  * Structured event emitted when the reader accepts a legacy `thd_*` ID.
@@ -58,7 +71,7 @@ export class StalePrefixError extends Error {
 	constructor(details: { rawId: string; kind: 'thd_rejected' | 'unknown_prefix' }) {
 		const reason =
 			details.kind === 'thd_rejected'
-				? `Stale ThreadId prefix '${details.rawId.slice(0, 4)}…' — run 'namzu sdk migrate-ids' before 0.3.0`
+				? `Stale legacy container id prefix '${details.rawId.slice(0, 4)}…' — run 'namzu sdk migrate-ids' before 0.3.0`
 				: `Unknown ID prefix '${details.rawId.slice(0, 4)}…' — expected 'prj_' or 'thd_'`
 		super(reason)
 		this.name = 'StalePrefixError'
@@ -80,28 +93,37 @@ export const WINDOW_OPEN = true
 const seenLegacy = new Set<string>()
 
 /**
- * Accept-on-read for legacy `thd_*` IDs during the 0.2.x window.
+ * Accept-on-read for legacy container `thd_*` IDs during the 0.2.x window.
  *
  * Contract:
  *  - `prj_*` inputs return as-is; no warning emitted.
  *  - `thd_*` inputs normalize to `prj_<suffix>` and emit a single
  *    {@link MigrationWarning} per distinct input string per process.
- *  - Everything else throws {@link StalePrefixError}.
- *  - When {@link WINDOW_OPEN} flips to `false`, the `thd_*` branch throws
- *    too — single knob, single commit.
+ *  - Everything else (including a live `top_*` Topic id — NZ-TOPIC-04)
+ *    throws {@link StalePrefixError} with `kind: 'unknown_prefix'}`.
+ *  - `windowOpen` (default {@link WINDOW_OPEN}) is an explicit parameter
+ *    rather than a read of the module constant so the CLOSED branch below
+ *    is reachable from a test without mutating shared module state
+ *    (a-check-that-cannot-fail). When `false`, the `thd_*` branch throws
+ *    too — single knob, single commit, now also a single argument a test
+ *    can flip per-call.
  *
  * Testing hook: {@link __resetSeenLegacyForTests} clears the dedup Set so
  * each test starts with a clean emission history.
  */
-export function acceptLegacyThreadId(raw: string, sink: MigrationWarningSink): ProjectId {
+export function acceptLegacyContainerId(
+	raw: string,
+	sink: MigrationWarningSink,
+	windowOpen: boolean = WINDOW_OPEN,
+): ProjectId {
 	if (raw.startsWith('prj_')) {
 		return raw as ProjectId
 	}
 	if (raw.startsWith('thd_')) {
-		if (!WINDOW_OPEN) {
+		if (!windowOpen) {
 			throw new StalePrefixError({ rawId: raw, kind: 'thd_rejected' })
 		}
-		const normalized = `prj_${raw.slice('thd_'.length)}` as ProjectId
+		const normalized = asProjectId(`prj_${raw.slice('thd_'.length)}`)
 		if (!seenLegacy.has(raw)) {
 			seenLegacy.add(raw)
 			sink.emit({
@@ -118,13 +140,16 @@ export function acceptLegacyThreadId(raw: string, sink: MigrationWarningSink): P
 }
 
 /**
- * Writer guard: reject emission of `thd_*` at encode time. Phase 1's
- * {@link generateProjectId} already emits `prj_*` only; this helper exists
- * so write paths that handle raw strings (e.g. synthesis during filesystem
- * migration) can fail fast on accidental legacy re-emission. Convention #0:
- * no silent back-sliding to the old prefix.
+ * Writer guard: reject emission of a legacy container `thd_*` id at encode
+ * time. Phase 1's {@link generateProjectId} already emits `prj_*` only;
+ * this helper exists so write paths that handle raw strings (e.g.
+ * synthesis during filesystem migration) can fail fast on accidental
+ * legacy re-emission. No `windowOpen` parameter — unlike the reader above,
+ * this guard's outcome does not fork on migration-window state; a writer
+ * must never emit `thd_*` in either window (see the module header's
+ * Writer column). Convention #0: no silent back-sliding to the old prefix.
  */
-export function rejectLegacyPrefix(id: string): void {
+export function rejectLegacyContainerPrefix(id: string): void {
 	if (id.startsWith('thd_')) {
 		throw new StalePrefixError({ rawId: id, kind: 'thd_rejected' })
 	}
@@ -132,10 +157,23 @@ export function rejectLegacyPrefix(id: string): void {
 
 /**
  * Test-only: clear the process-level dedup Set so subsequent
- * {@link acceptLegacyThreadId} calls emit warnings again. Production code
+ * {@link acceptLegacyContainerId} calls emit warnings again. Production code
  * must never call this — the whole point is one warning per distinct
  * legacy id per process.
  */
+/**
+ * @deprecated Use {@link acceptLegacyContainerId}. Removal is NZ-TOPIC-05.
+ *
+ * The rename is the whole point of NZ-TOPIC-04 — `thd_` meant both the
+ * pre-0.2.0 top-level container this coerces and the live Topic layer, and
+ * only this function's NAME said which. The alias exists so the rename
+ * reaches a consumer as a warning first.
+ */
+export const acceptLegacyThreadId = acceptLegacyContainerId
+
+/** @deprecated Use {@link rejectLegacyContainerPrefix}. Removal is NZ-TOPIC-05. */
+export const rejectLegacyPrefix = rejectLegacyContainerPrefix
+
 export function __resetSeenLegacyForTests(): void {
 	seenLegacy.clear()
 }

package/src/session/migration/index.ts

@@ -3,7 +3,11 @@
 // See session-hierarchy.md §13.3.1 (ID prefix) + §13.4.1 (filesystem).
 
 export {
+	acceptLegacyContainerId,
+	/** @deprecated Use `acceptLegacyContainerId`. */
 	acceptLegacyThreadId,
+	rejectLegacyContainerPrefix,
+	/** @deprecated Use `rejectLegacyContainerPrefix`. */
 	rejectLegacyPrefix,
 	NOOP_MIGRATION_WARNING_SINK,
 	StalePrefixError,
@@ -13,6 +17,7 @@ export type { MigrationWarning, MigrationWarningSink } from './id-prefix.js'
 
 export {
 	DefaultFilesystemMigrator,
+	loggingMigrationSink,
 	NOOP_FILESYSTEM_MIGRATION_SINK,
 	LEGACY_DEFAULT_SESSION_ID,
 	LEGACY_DEFAULT_PROJECT_PREFIX,

package/src/session/migration/marker.ts

@@ -70,13 +70,28 @@ export async function readMarker(path: string): Promise<MigrationMarker | null>
 		return null
 	}
 
+	// The shape check above validates the ENVELOPE — version, at, and that
+	// migratedThreads is an array — and never looked inside the array. So
+	// `{"migratedThreads":[null]}` passed it and produced an entry whose
+	// `newProjectId` was `undefined` wearing a `ProjectId` annotation, which
+	// then reached a path join. Each element is checked here, and a bad one
+	// is corruption in exactly the sense this function's own contract names:
+	// return null, and let the caller re-run the migration.
+	const migratedThreads: { legacyThreadId: string; newProjectId: ProjectId }[] = []
+	for (const m of parsed.migratedThreads) {
+		if (typeof m !== 'object' || m === null) return null
+		if (typeof m.legacyThreadId !== 'string') return null
+		if (typeof m.newProjectId !== 'string' || !m.newProjectId.startsWith('prj_')) return null
+		migratedThreads.push({
+			legacyThreadId: m.legacyThreadId,
+			newProjectId: m.newProjectId as ProjectId,
+		})
+	}
+
 	return {
 		version: parsed.version,
 		at: new Date(parsed.at),
-		migratedThreads: parsed.migratedThreads.map((m) => ({
-			legacyThreadId: m.legacyThreadId,
-			newProjectId: m.newProjectId as ProjectId,
-		})),
+		migratedThreads,
 	}
 }
 

package/src/session/retention/archive.ts

@@ -28,7 +28,11 @@
 import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
 import type { WorkspaceId } from '../../types/session/ids.js'
 import type { SessionStore } from '../../types/session/store.js'
-import type { SubSession, SubSessionStatus } from '../../types/session/sub-session.js'
+import type {
+	SubSession,
+	SubSessionDelegationStatus,
+	SubSessionStatus,
+} from '../../types/session/sub-session.js'
 import type { WorkspaceRef } from '../../types/workspace/ref.js'
 import type { WorkspaceBackendRegistry } from '../workspace/registry.js'
 import type { ArchiveBackend, SubSessionTombstone } from './backend.js'
@@ -103,17 +107,33 @@ export type WorkspaceResolver = (
 ) => Promise<WorkspaceRef | null>
 
 /**
- * Sub-session statuses eligible for archival. Pattern doc §12.3 speaks of
- * "idle" broadly; we honor the enumerated terminal-like states. Anything
- * else (active / pending / in-flight merge) rejects with
- * `'not_idle'`.
+ * Delegation states eligible for archival. Anything else — `pending`,
+ * `active` — rejects with `'not_idle'`.
+ *
+ * Typed as {@link SubSessionDelegationStatus}, which is what makes it say
+ * something true: these are values the kernel actually writes.
+ */
+const ARCHIVABLE: ReadonlySet<SubSessionDelegationStatus> = new Set(['idle', 'failed'])
+
+/**
+ * Values no code path in this package can write, kept archivable anyway.
+ *
+ * `merged` and `merge_rejected` sat in the one set above, and nothing has
+ * ever produced either — so that membership described a match that could
+ * not happen. The temptation is to delete them, and that would be wrong:
+ * `SubSessionStore.updateSubSession` takes a whole `SubSession`, so a HOST
+ * could have persisted one of these while the wide union permitted it, and
+ * dropping them here would strand exactly those records as permanently
+ * un-archivable. The union stays wide for one release precisely so such a
+ * host can migrate; this set is the other half of that promise.
+ *
+ * It goes when the six deprecated members go.
  */
-const ARCHIVABLE_STATUSES: ReadonlySet<SubSessionStatus> = new Set([
-	'idle',
-	'merged',
-	'merge_rejected',
-	'failed',
-])
+const ARCHIVABLE_LEGACY: ReadonlySet<SubSessionStatus> = new Set(['merged', 'merge_rejected'])
+
+function isArchivable(status: SubSessionStatus): boolean {
+	return ARCHIVABLE.has(status as SubSessionDelegationStatus) || ARCHIVABLE_LEGACY.has(status)
+}
 
 export interface ArchivalManagerDeps {
 	readonly sessionStore: SessionStore
@@ -165,7 +185,7 @@ export class ArchivalManager {
 		if (sub.status === 'archived') {
 			throw new SubSessionNotArchivableError({ subSessionId, reason: 'already_archived' })
 		}
-		if (!ARCHIVABLE_STATUSES.has(sub.status)) {
+		if (!isArchivable(sub.status)) {
 			throw new SubSessionNotArchivableError({ subSessionId, reason: 'not_idle' })
 		}
 

package/src/session/workspace/git-worktree.ts

@@ -13,8 +13,10 @@
 import { execFile } from 'node:child_process'
 import { join } from 'node:path'
 import { promisify } from 'node:util'
+import { NAMZU } from '../../constants/telemetry/index.js'
 import type { GitWorktreeBackendMeta, WorkspaceRef } from '../../types/workspace/ref.js'
 import { generateWorkspaceId } from '../../utils/id.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import type { Logger } from '../../utils/logger.js'
 import { WorkspaceBackendError } from '../errors.js'
 import type {
@@ -71,7 +73,7 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 	constructor(config: GitWorktreeDriverConfig) {
 		this.repoRoot = config.repoRoot
 		this.worktreesDir = config.worktreesDir ?? join(config.repoRoot, '.namzu', 'worktrees')
-		this.log = config.logger.child({ component: 'GitWorktreeDriver' })
+		this.log = config.logger.child({ [SCOPE_ATTRIBUTE]: 'session/workspace/git-worktree' })
 		this.exec = config.execFile ?? defaultExecFile
 	}
 
@@ -105,9 +107,9 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 				throw new WorkspaceBackendError({ op: 'create', kind: this.kind, cause })
 			}
 			this.log.warn('git-worktree add reported failure but the worktree is present', {
-				branch,
-				worktreePath,
-				cause: cause instanceof Error ? cause.message : String(cause),
+				'namzu.session.branch': branch,
+				'namzu.session.worktree_path': worktreePath,
+				'namzu.session.cause': cause instanceof Error ? cause.message : String(cause),
 			})
 		}
 
@@ -118,7 +120,11 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 			worktreePath,
 		}
 
-		this.log.info('git-worktree created', { id, branch, worktreePath })
+		this.log.info('git-worktree created', {
+			[NAMZU.SESSION_ID]: id,
+			'namzu.session.branch': branch,
+			'namzu.session.worktree_path': worktreePath,
+		})
 		return {
 			id,
 			meta,
@@ -145,15 +151,18 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 				ref.meta.worktreePath,
 				'--force',
 			])
-			this.log.info('git-worktree disposed', { id: ref.id, path: ref.meta.worktreePath })
+			this.log.info('git-worktree disposed', {
+				[NAMZU.SESSION_ID]: ref.id,
+				'namzu.session.path': ref.meta.worktreePath,
+			})
 		} catch (cause) {
 			const message = cause instanceof Error ? cause.message : String(cause)
 			// git exits non-zero with "is not a working tree" when the path is
 			// absent; treat as idempotent success and log at debug.
 			if (/not a working tree|does not exist|No such file/i.test(message)) {
 				this.log.debug('git-worktree already gone; dispose idempotent', {
-					id: ref.id,
-					path: ref.meta.worktreePath,
+					[NAMZU.SESSION_ID]: ref.id,
+					'namzu.session.path': ref.meta.worktreePath,
 				})
 				return
 			}

package/src/skills/loader.ts

@@ -7,11 +7,10 @@ import type {
 	SkillMetadata,
 } from '../types/skills/index.js'
 import { type ParsedFrontmatter, parseFrontmatter } from '../utils/frontmatter.js'
-import { getRootLogger } from '../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 
-const logger = getRootLogger().child({ component: 'SkillLoader' })
-
-const SKILL_FILENAME = 'SKILL.md'
+export const SKILL_FILENAME = 'SKILL.md'
 
 /**
  * How this file's errors name themselves. Passed to the shared reader so a
@@ -90,6 +89,20 @@ function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetad
 		skillMetadata.allowedTools = allowedTools
 	}
 
+	const invocation = scalarAt(values, 'invocation')
+	if (invocation) {
+		// Refused rather than defaulted. A typo'd `invocaton: operator` that
+		// quietly resolved to `both` would put an operator-only skill back in
+		// front of the model, which is precisely what the field was added to
+		// stop — and the author would have no way to tell.
+		if (invocation !== 'model' && invocation !== 'operator' && invocation !== 'both') {
+			throw new Error(
+				`${source}: invocation must be one of model, operator, both — got "${invocation}"`,
+			)
+		}
+		skillMetadata.invocation = invocation
+	}
+
 	const extra = mappingAt(values, 'metadata')
 	if (extra && Object.keys(extra).length > 0) {
 		skillMetadata.metadata = { ...extra }
@@ -135,6 +148,7 @@ function estimateTokens(text: string): number {
 export async function loadSkill(
 	dirPath: string,
 	level: SkillDisclosureLevel = 'metadata',
+	log?: Logger,
 ): Promise<SkillLoadResult> {
 	const skillMdPath = join(dirPath, SKILL_FILENAME)
 	const raw = await readFile(skillMdPath, 'utf-8')
@@ -153,10 +167,23 @@ export async function loadSkill(
 	const metadataTokens = estimateTokens(`${metadata.name}: ${metadata.description}`)
 	const bodyTokens = skill.body ? estimateTokens(skill.body) : 0
 
+	// Resolved here, not at module scope. A module-scope
+	// `getRootLogger().child(...)` ran once, at import time — before any
+	// host's `configureLogger()` call had a chance to run — and `child()`
+	// bakes `minLevel` into the closure `log()` reads from forever after
+	// (`utils/logger.ts`), so whatever level was live at that one moment
+	// was permanent. `configureLogger` replaces the `_rootLogger` binding
+	// rather than mutating the object it points at, so caching the CHILD
+	// (as this loader did) survives no later call at all — including the
+	// CLI's own `configureLogger({ level: 'silent' })`.
+	//
+	// `log`, when the caller has one (`SkillRegistry` now does), wins over
+	// the process default.
+	const logger = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'skills/loader' })
 	logger.debug('Loaded skill', {
-		name: metadata.name,
-		level,
-		tokens: metadataTokens + bodyTokens,
+		'namzu.skills.name': metadata.name,
+		'namzu.skills.level': level,
+		'namzu.skills.tokens': metadataTokens + bodyTokens,
 	})
 
 	return {
@@ -166,7 +193,10 @@ export async function loadSkill(
 	}
 }
 
-export async function discoverSkills(parentDir: string): Promise<string[]> {
+export async function discoverSkills(parentDir: string, log?: Logger): Promise<string[]> {
+	// Resolved here too — see loadSkill above for why module scope froze
+	// this logger's level, and its very reference, at import time.
+	const logger = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'skills/loader' })
 	const dirs: string[] = []
 
 	try {
@@ -184,7 +214,7 @@ export async function discoverSkills(parentDir: string): Promise<string[]> {
 			} catch {}
 		}
 	} catch {
-		logger.debug('Skills directory not found', { parentDir })
+		logger.debug('Skills directory not found', { 'namzu.skills.parent_dir': parentDir })
 	}
 
 	return dirs.sort()