@namzu/sdk 43.0.0 → 44.0.0

package/src/session/paths.ts

@@ -0,0 +1,449 @@
+import { createHash } from 'node:crypto'
+import { lstatSync, mkdirSync } from 'node:fs'
+import { link, mkdir, open, readFile, realpath, unlink } from 'node:fs/promises'
+import { tmpdir, userInfo } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import type {
+	CheckpointId,
+	GoalId,
+	MessageId,
+	ProjectId,
+	SessionId,
+	TaskId,
+	TurnId,
+} from '../types/ids/index.js'
+import { type ProjectDocument, ProjectDocumentSchema } from '../types/session/records.js'
+import { type EntityIdKind, asSessionId, generateProjectId, isEntityId } from '../utils/id.js'
+import { uuidv7 } from '../utils/uuidv7.js'
+
+/**
+ * The on-disk layout of `NAMZU_HOME`, shared by the SDK and the CLI:
+ *
+ * ```text
+ * $NAMZU_HOME/
+ *   index.sqlite                     rebuildable index over every log
+ *   projects/<slug>/
+ *     project.json                   the project id, minted once
+ *     memory/  residents/  worktrees/<label>/
+ *     <session-id>.jsonl             the session log (source of truth)
+ *     <session-id>/
+ *       subagents/<child-id>.jsonl, <child-id>.meta.json, <child-id>/subagents/…
+ *       tool-results/  checkpoints/  budgets/  tasks/  feedback/  goals/
+ *       file-history/  lease.json
+ * $TMPDIR/namzu-<user>/<slug>/<session-id>/scratchpad/
+ * ```
+ *
+ * Every id that becomes a path segment is checked here, because a brand does
+ * not validate a value read from JSON.
+ */
+
+/** Names a session in the tree: its id, and its ancestors from the root down (empty for a root session). */
+export interface SessionLocator {
+	readonly sessionId: SessionId
+	readonly ancestors?: readonly SessionId[]
+}
+
+/**
+ * The locator a session log's own path spells out: `<session-id>.jsonl` at the
+ * top of a project is a root session, and each `<ancestor-id>/subagents/`
+ * above it names an ancestor, nearest last. `undefined` when the file is not
+ * named `<sessionId>.jsonl`.
+ *
+ * The path alone does not say which project the file is in: a
+ * `<sessionId>.jsonl` kept outside any layout still reads as a root session
+ * here. `resolveSessionStorage` trusts this locator only when the layout it
+ * was given puts that locator's log at this very file.
+ *
+ * A log opened from the index's `logPath` knows only its file; this is how it
+ * finds the same `checkpoints/` (and the rest of its session directory) that
+ * {@link SessionPaths} placed for it.
+ */
+export function sessionLocatorFromLogFile(
+	file: string,
+	sessionId: SessionId,
+): SessionLocator | undefined {
+	if (basename(file) !== `${sessionId}.jsonl`) return undefined
+	const ancestors: SessionId[] = []
+	let directory = dirname(file)
+	while (basename(directory) === 'subagents') {
+		const owner = basename(dirname(directory))
+		if (!isEntityId(owner, 'session')) break
+		ancestors.unshift(asSessionId(owner))
+		directory = dirname(dirname(directory))
+	}
+	return ancestors.length === 0 ? { sessionId } : { sessionId, ancestors }
+}
+
+export interface SessionPathsOptions {
+	/** The resolved `NAMZU_HOME` (see `resolveNamzuHome`). */
+	readonly home: string
+	/** The project's slug, as `ensureProject` returned it. */
+	readonly slug: string
+	/**
+	 * The per-user temporary root (`$TMPDIR/namzu-<user>`). Defaults to
+	 * {@link tempRoot}, resolved (and created) the first time `tempDir` is called.
+	 */
+	readonly tempRoot?: string
+}
+
+/** A path segment that is not an id of the expected kind, or not a safe name. */
+export class SessionPathError extends Error {
+	override readonly name = 'SessionPathError'
+}
+
+const SLUG = /^[A-Za-z0-9-]+$/
+/** Worktree labels and resident agent keys: one plain segment, never `.` or `..`. */
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+/** Longest slug before a hash suffix replaces the tail; well under the 255-byte segment limit. */
+const MAX_SLUG = 200
+
+function sha256Hex(value: string): string {
+	return createHash('sha256').update(value).digest('hex')
+}
+
+function checkId(value: string, kind: EntityIdKind): string {
+	if (!isEntityId(value, kind)) {
+		throw new SessionPathError(`Invalid ${kind} id for a path: ${JSON.stringify(value)}`)
+	}
+	return value
+}
+
+function checkName(value: string, what: string): string {
+	if (!NAME.test(value) || value.includes('..')) {
+		throw new SessionPathError(`Invalid ${what} for a path: ${JSON.stringify(value)}`)
+	}
+	return value
+}
+
+/**
+ * The slug a working directory is filed under: every character outside
+ * `[A-Za-z0-9]` becomes `-`.
+ *
+ * Pass the canonical path (`realpath`); `ensureProject` does. A POSIX
+ * absolute path starts with `/`, so its slug starts with `-`; a Windows path
+ * `C:\…` gives `C-…`; a UNC path gives `--…`. None of these can look like a
+ * UUID, which is how a layout reader tells a slug from a legacy
+ * `projects/<uuid>/` directory. A slug longer than 200 characters keeps its
+ * first 191 and ends in `-` plus 8 hex digits of the path's SHA-256.
+ */
+export function slugForCwd(cwd: string): string {
+	const slug = cwd.replace(/[^A-Za-z0-9]/g, '-')
+	if (slug.length <= MAX_SLUG) return slug
+	return `${slug.slice(0, MAX_SLUG - 9)}-${sha256Hex(cwd).slice(0, 8)}`
+}
+
+/** The slug used when `project.json` under the plain slug belongs to a different directory. */
+export function hashedSlugForCwd(cwd: string): string {
+	return `${slugForCwd(cwd)}-${sha256Hex(cwd).slice(0, 8)}`
+}
+
+export interface EnsureProjectOptions {
+	readonly home: string
+	readonly cwd: string
+	/** Clock for `createdAt`; tests pin it. */
+	readonly now?: () => Date
+}
+
+export interface EnsuredProject {
+	readonly slug: string
+	readonly projectId: ProjectId
+	/** The canonical working directory the project stands for. */
+	readonly cwd: string
+	readonly projectDir: string
+	/** True when this call minted `project.json`; false when it adopted an existing one. */
+	readonly created: boolean
+}
+
+/** `project.json` exists and cannot be read as a project document. */
+export class ProjectDocumentError extends Error {
+	override readonly name = 'ProjectDocumentError'
+}
+
+async function readProjectDocument(file: string): Promise<ProjectDocument | null> {
+	let raw: string
+	try {
+		raw = await readFile(file, 'utf8')
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+		throw error
+	}
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch (error) {
+		throw new ProjectDocumentError(
+			`${file} is not JSON: ${error instanceof Error ? error.message : String(error)}`,
+		)
+	}
+	const result = ProjectDocumentSchema.safeParse(parsed)
+	if (!result.success) {
+		throw new ProjectDocumentError(`${file} is not a project document: ${result.error.message}`)
+	}
+	return result.data
+}
+
+/**
+ * Find or create the project a working directory stands for.
+ *
+ * The directory is canonicalised, slugged, and `projects/<slug>/project.json`
+ * is created exclusively: the document is written complete to a private
+ * temporary file and then hard-linked into place, which fails with `EEXIST`
+ * if another process got there first. So a reader never sees a half-written
+ * document, and of two processes racing, exactly one mints the project id and
+ * the other adopts it. If the existing document names a different directory
+ * (two paths that slug alike), the project moves to the hashed slug.
+ */
+export async function ensureProject(options: EnsureProjectOptions): Promise<EnsuredProject> {
+	const cwd = await realpath(options.cwd)
+	const now = options.now ?? (() => new Date())
+	const candidates = [slugForCwd(cwd), hashedSlugForCwd(cwd)]
+	for (const slug of candidates) {
+		const projectDir = join(options.home, 'projects', slug)
+		await mkdir(projectDir, { recursive: true })
+		const file = join(projectDir, 'project.json')
+		let existing = await readProjectDocument(file)
+		if (existing === null) {
+			const document: ProjectDocument = {
+				v: 1,
+				kind: 'project',
+				projectId: generateProjectId(),
+				cwd,
+				slug,
+				createdAt: now().toISOString(),
+			}
+			const temporary = join(projectDir, `.project.json.${process.pid}.${uuidv7()}.tmp`)
+			const handle = await open(temporary, 'wx', 0o600)
+			try {
+				await handle.writeFile(`${JSON.stringify(document)}\n`, 'utf8')
+				await handle.sync()
+			} finally {
+				await handle.close()
+			}
+			let won = false
+			try {
+				await link(temporary, file)
+				won = true
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+			} finally {
+				await unlink(temporary).catch(() => undefined)
+			}
+			if (won) return { slug, projectId: document.projectId, cwd, projectDir, created: true }
+			existing = await readProjectDocument(file)
+			if (existing === null) {
+				throw new ProjectDocumentError(`${file} vanished while it was being created.`)
+			}
+		}
+		if (existing.cwd === cwd) {
+			return { slug, projectId: existing.projectId, cwd, projectDir, created: false }
+		}
+	}
+	throw new ProjectDocumentError(
+		`No project slug is free for ${JSON.stringify(cwd)}: both ${candidates.join(' and ')} belong to other directories.`,
+	)
+}
+
+export interface TempRootOptions {
+	/** Base directory. Default `os.tmpdir()`. */
+	readonly tmpdir?: string
+	/** Default `process.platform`. */
+	readonly platform?: NodeJS.Platform
+	/**
+	 * Default `process.getuid`. Pass `undefined` explicitly to model a
+	 * platform without it (win32).
+	 */
+	readonly getuid?: (() => number) | undefined
+	/** Default `os.userInfo().username`. */
+	readonly username?: () => string
+}
+
+/**
+ * The per-user temporary root, `$TMPDIR/namzu-<user>`, created if missing.
+ *
+ * `<user>` is the numeric uid where the platform has one; otherwise the first
+ * 12 hex digits of the SHA-256 of the user name; otherwise `user`. On POSIX
+ * the directory is created with mode 0700 and refused if it is a symlink, not
+ * a directory, owned by another uid, or open to group or others. On win32
+ * `%TEMP%` is already per user: a symlink or junction is refused and the
+ * owner check is skipped.
+ */
+export function tempRoot(options: TempRootOptions = {}): string {
+	const platform = options.platform ?? process.platform
+	const getuid = 'getuid' in options ? options.getuid : process.getuid?.bind(process)
+	let user = 'user'
+	if (typeof getuid === 'function') {
+		user = String(getuid())
+	} else {
+		try {
+			const name = (options.username ?? (() => userInfo().username))()
+			if (name.length > 0) user = sha256Hex(name).slice(0, 12)
+		} catch {
+			// No user database entry: fall back to the fixed segment.
+		}
+	}
+	const root = join(options.tmpdir ?? tmpdir(), `namzu-${user}`)
+	try {
+		mkdirSync(root, { mode: 0o700 })
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+	}
+	const entry = lstatSync(root)
+	if (entry.isSymbolicLink()) {
+		throw new SessionPathError(`Refusing temporary root ${root}: it is a symbolic link.`)
+	}
+	if (!entry.isDirectory()) {
+		throw new SessionPathError(`Refusing temporary root ${root}: it is not a directory.`)
+	}
+	if (platform !== 'win32' && typeof getuid === 'function') {
+		if (entry.uid !== getuid()) {
+			throw new SessionPathError(`Refusing temporary root ${root}: it belongs to uid ${entry.uid}.`)
+		}
+		if ((entry.mode & 0o077) !== 0) {
+			throw new SessionPathError(
+				`Refusing temporary root ${root}: mode ${(entry.mode & 0o777).toString(8)} lets other users in; it must be 700.`,
+			)
+		}
+	}
+	return root
+}
+
+/** Every path of one project's layout. Pure: nothing is created or read. */
+export class SessionPaths {
+	readonly home: string
+	readonly slug: string
+	#tempRoot: string | undefined
+
+	constructor(options: SessionPathsOptions) {
+		if (!SLUG.test(options.slug)) {
+			throw new SessionPathError(`Invalid project slug: ${JSON.stringify(options.slug)}`)
+		}
+		this.home = options.home
+		this.slug = options.slug
+		this.#tempRoot = options.tempRoot
+	}
+
+	/** `$NAMZU_HOME/index.sqlite`. */
+	indexFile(): string {
+		return join(this.home, 'index.sqlite')
+	}
+
+	projectDir(): string {
+		return join(this.home, 'projects', this.slug)
+	}
+
+	projectFile(): string {
+		return join(this.projectDir(), 'project.json')
+	}
+
+	memoryDir(): string {
+		return join(this.projectDir(), 'memory')
+	}
+
+	residentDir(agentKey: string): string {
+		return join(this.projectDir(), 'residents', checkName(agentKey, 'resident agent key'))
+	}
+
+	/** The `GitWorktreeManager` default root, or one labelled worktree inside it. */
+	worktrees(label?: string): string {
+		const root = join(this.projectDir(), 'worktrees')
+		return label === undefined ? root : join(root, checkName(label, 'worktree label'))
+	}
+
+	/** The directory that holds `<session-id>.jsonl`: the project for a root session, `subagents/` of its parent otherwise. */
+	#logParent(locator: SessionLocator): string {
+		let parent = this.projectDir()
+		for (const ancestor of locator.ancestors ?? []) {
+			parent = join(parent, checkId(ancestor, 'session'), 'subagents')
+		}
+		return parent
+	}
+
+	/** `<session-id>.jsonl`, or `…/subagents/<child-id>.jsonl` for a child session. */
+	sessionLog(locator: SessionLocator): string {
+		return join(this.#logParent(locator), `${checkId(locator.sessionId, 'session')}.jsonl`)
+	}
+
+	/** The session's own directory, beside its log. */
+	sessionDir(locator: SessionLocator): string {
+		return join(this.#logParent(locator), checkId(locator.sessionId, 'session'))
+	}
+
+	#child(parent: SessionLocator, childId: SessionId): SessionLocator {
+		return { sessionId: childId, ancestors: [...(parent.ancestors ?? []), parent.sessionId] }
+	}
+
+	subagentLog(parent: SessionLocator, childId: SessionId): string {
+		return this.sessionLog(this.#child(parent, childId))
+	}
+
+	/** `<parent-dir>/subagents/<child-id>.meta.json`. */
+	subagentMeta(parent: SessionLocator, childId: SessionId): string {
+		return join(this.sessionDir(parent), 'subagents', `${checkId(childId, 'session')}.meta.json`)
+	}
+
+	toolResults(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'tool-results')
+	}
+
+	/** A spilled tool result, named by the SHA-256 of its provider tool-use id; the manifest is `<file>.manifest.json`. */
+	toolResultFile(locator: SessionLocator, toolUseId: string): string {
+		if (toolUseId.length === 0) throw new SessionPathError('A tool-use id is required.')
+		return join(this.toolResults(locator), `${sha256Hex(toolUseId)}.txt`)
+	}
+
+	checkpoints(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'checkpoints')
+	}
+
+	checkpointFile(locator: SessionLocator, checkpointId: CheckpointId): string {
+		return join(this.checkpoints(locator), `${checkId(checkpointId, 'checkpoint')}.json`)
+	}
+
+	/** Token ledgers; written for root sessions only. */
+	budgets(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'budgets')
+	}
+
+	budgetFile(locator: SessionLocator, rootTurnId: TurnId): string {
+		return join(this.budgets(locator), `${checkId(rootTurnId, 'turn')}.json`)
+	}
+
+	tasks(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'tasks')
+	}
+
+	taskFile(locator: SessionLocator, taskId: TaskId): string {
+		return join(this.tasks(locator), `${checkId(taskId, 'task')}.json`)
+	}
+
+	feedback(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'feedback')
+	}
+
+	feedbackFile(locator: SessionLocator, messageId: MessageId): string {
+		return join(this.feedback(locator), `${checkId(messageId, 'message')}.json`)
+	}
+
+	goals(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'goals')
+	}
+
+	goalFile(locator: SessionLocator, goalId: GoalId): string {
+		return join(this.goals(locator), `${checkId(goalId, 'goal')}.json`)
+	}
+
+	/** File snapshots a CLI `/restore` rolls back to. */
+	fileHistory(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'file-history')
+	}
+
+	lease(locator: SessionLocator): string {
+		return join(this.sessionDir(locator), 'lease.json')
+	}
+
+	/** `$TMPDIR/namzu-<user>/<slug>/<session-id>/scratchpad`. Not created; the per-user root is. */
+	tempDir(sessionId: SessionId): string {
+		this.#tempRoot ??= tempRoot()
+		return join(this.#tempRoot, this.slug, checkId(sessionId, 'session'), 'scratchpad')
+	}
+}

package/src/session/retention/archive.ts

@@ -27,6 +27,7 @@
 
 import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
 import type { WorkspaceId } from '../../types/session/ids.js'
+import type { SessionMessage } from '../../types/session/messages.js'
 import type { SessionStore } from '../../types/session/store.js'
 import type {
 	SubSession,
@@ -124,6 +125,15 @@ function isArchivable(status: SubSessionStatus): boolean {
 
 export interface ArchivalManagerDeps {
 	readonly sessionStore: SessionStore
+	/**
+	 * The child session's conversation, read from its session log (the fold
+	 * of its records). The session log is the only store of messages; a
+	 * `SessionStore` holds none.
+	 */
+	readonly readSessionMessages: (
+		sessionId: SessionId,
+		tenantId: TenantId,
+	) => Promise<readonly SessionMessage[]>
 	readonly workspaceRegistry: WorkspaceBackendRegistry
 	/**
 	 * Archive backend. Absent = archival disabled for this manager
@@ -177,12 +187,10 @@ export class ArchivalManager {
 		}
 
 		// 2. Load owning child session bundle (messages + optional summary).
-		// Phase 9 Known Delta #7: uses `loadSessionMessages` for full-fidelity
-		// round-trip (original MessageId + timestamp preserved). Previously
-		// the Phase 8 archivalmanager synthesized `msg_restored_N` IDs from the
-		// payload-only `loadMessages` return — that lossy reshape is gone.
+		// The messages come from the child session's log, with the record ids
+		// and times the log gave them.
 		const childSessionId: SessionId = sub.childSessionId
-		const messages = await this.deps.sessionStore.loadSessionMessages(childSessionId, tenantId)
+		const messages = await this.deps.readSessionMessages(childSessionId, tenantId)
 
 		const summaryRefOrNull = await this.deps.sessionStore.getSummary(childSessionId, tenantId)
 		const summaryRef = summaryRefOrNull ?? undefined

package/src/session/status/derive.ts

@@ -1,5 +1,5 @@
 /**
- * Pure Run→Session fan-in helper per session-hierarchy.md §5.1.
+ * Pure Turn→Session fan-in helper per session-hierarchy.md §5.1.
  *
  * Extracted from `session/hierarchy/session.ts` on 2026-04-21 (ses_010 commit
  * 4) so the shape definition can live under `types/session/` while the
@@ -7,57 +7,57 @@
  * (`types/` = pure shapes, feature folders = runtime).
  *
  * The precedence (highest first) matches the pattern-doc table:
- *   1. Session-level states that do not fan in from Run status:
+ *   1. Session-level states that do not fan in from Turn status:
  *      - `locked` (handoff CAS window) — preserved verbatim
  *      - `awaiting_merge` (broadcast source post-fan-out, §5.4) — preserved
  *      - `archived` (retention tombstone, §12.3) — preserved
- *   2. Any Run `running` or `awaiting_subsession` → Session `active`.
+ *   2. Any turn `running` or `awaiting_subsession` → Session `active`.
  *      Delegation-in-flight is an active state of the parent — the parent
- *      Run is suspended waiting on the child's SessionSummaryMaterializer,
+ *      turn is suspended waiting on the child's SessionSummaryMaterializer,
  *      and the session is NOT idle while that is pending.
- *   3. Any Run `awaiting_hitl` or `awaiting_hitl_resolution` → Session
+ *   3. Any turn `awaiting_hitl` or `awaiting_hitl_resolution` → Session
  *      `awaiting_hitl`.
- *   4. All Runs `failed` and at least one Run present → Session `failed`.
- *   5. Otherwise (all runs terminal — succeeded/cancelled/failed mix, or no
- *      runs at all) → Session `idle`.
+ *   4. All turns `failed` and at least one turn present → Session `failed`.
+ *   5. Otherwise (all turns terminal — succeeded/cancelled/failed mix, or no
+ *      turns at all) → Session `idle`.
  *
  * `cancelled` does NOT surface a `failed` Session (§5.1 — "Cancellation is
- * not a terminal Session state"). Only `failed` runs drive the Session to
- * `failed` when every Run ended that way.
+ * not a terminal Session state"). Only `failed` turns drive the Session to
+ * `failed` when every Turn ended that way.
  */
 
-import type { RunStatus } from '../../types/run/status.js'
 import type { Session, SessionStatus } from '../../types/session/entity.js'
+import type { TurnStatus } from '../../types/session/turn.js'
 
 export function deriveStatus(
 	session: Session,
-	runs: readonly { status: RunStatus }[],
+	turns: readonly { status: TurnStatus }[],
 ): SessionStatus {
-	// Session-level overrides — these states do not fan in from Run status.
+	// Session-level overrides — these states do not fan in from Turn status.
 	if (session.status === 'locked') return 'locked'
 	if (session.status === 'awaiting_merge') return 'awaiting_merge'
 	if (session.status === 'archived') return 'archived'
 
-	// Any active Run (in-flight iteration or awaiting a child sub-session) →
-	// `active`. Delegation is an active state: the parent Run is suspended
+	// Any active turn (in-flight iteration or awaiting a child sub-session) →
+	// `active`. Delegation is an active state: the parent turn is suspended
 	// waiting on the child's Materializer, not idle.
-	const hasActive = runs.some((r) => r.status === 'running' || r.status === 'awaiting_subsession')
+	const hasActive = turns.some((r) => r.status === 'running' || r.status === 'awaiting_subsession')
 	if (hasActive) return 'active'
 
 	// Any HITL block (synchronous or persisted) → `awaiting_hitl`.
-	const hasHitl = runs.some(
+	const hasHitl = turns.some(
 		(r) => r.status === 'awaiting_hitl' || r.status === 'awaiting_hitl_resolution',
 	)
 	if (hasHitl) return 'awaiting_hitl'
 
-	// All failed (with at least one Run) → `failed`. Note that a `cancelled`
-	// Run does NOT drive the Session to `failed`; §5.1 is explicit that
+	// All failed (with at least one turn) → `failed`. Note that a `cancelled`
+	// turn does NOT drive the Session to `failed`; §5.1 is explicit that
 	// cancellation leaves the Session `idle`.
-	if (runs.length > 0 && runs.every((r) => r.status === 'failed')) {
+	if (turns.length > 0 && turns.every((r) => r.status === 'failed')) {
 		return 'failed'
 	}
 
-	// Otherwise — empty run set, or all runs terminated (succeeded / cancelled
+	// Otherwise — empty turn set, or all turns terminated (succeeded / cancelled
 	// / mixed with failed) — the Session is `idle`.
 	return 'idle'
 }

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

@@ -12,6 +12,7 @@
  */
 
 import { execFile } from 'node:child_process'
+import { readFileSync, realpathSync } from 'node:fs'
 import { realpath } from 'node:fs/promises'
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { promisify } from 'node:util'
@@ -21,6 +22,8 @@ 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 { resolveNamzuHome } from '../home.js'
+import { hashedSlugForCwd, slugForCwd } from '../paths.js'
 import type {
 	BranchWorkspaceParams,
 	CreateWorkspaceParams,
@@ -56,7 +59,8 @@ export interface GitWorktreeDriverConfig {
 	repoRoot: string
 	/**
 	 * Directory (absolute) where worktree checkouts live. Defaults to
-	 * `{repoRoot}/.namzu/worktrees` per session-hierarchy.md §7.2.
+	 * `<NAMZU_HOME>/projects/<slug>/worktrees/` for the repo root's project:
+	 * namzu never writes under the working directory.
 	 */
 	worktreesDir?: string
 	logger: Logger
@@ -74,7 +78,7 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 
 	constructor(config: GitWorktreeDriverConfig) {
 		this.repoRoot = resolve(config.repoRoot)
-		this.worktreesDir = resolve(config.worktreesDir ?? join(config.repoRoot, '.namzu', 'worktrees'))
+		this.worktreesDir = resolve(config.worktreesDir ?? defaultWorktreesDir(config.repoRoot))
 		this.log = config.logger.child({ [SCOPE_ATTRIBUTE]: 'session/workspace/git-worktree' })
 		this.exec = config.execFile ?? defaultExecFile
 	}
@@ -409,3 +413,28 @@ export function parseWorktreeList(
 	}
 	return null
 }
+
+/**
+ * `<NAMZU_HOME>/projects/<slug>/worktrees/` for a repository: the project's
+ * slug, or its hashed form when `project.json` under the plain slug belongs
+ * to a different directory (the rule `ensureProject` applies).
+ */
+export function defaultWorktreesDir(repoRoot: string): string {
+	let cwd: string
+	try {
+		cwd = realpathSync(repoRoot)
+	} catch {
+		cwd = resolve(repoRoot)
+	}
+	const home = resolveNamzuHome()
+	let slug = slugForCwd(cwd)
+	try {
+		const document = JSON.parse(
+			readFileSync(join(home, 'projects', slug, 'project.json'), 'utf8'),
+		) as { cwd?: unknown }
+		if (document.cwd !== cwd) slug = hashedSlugForCwd(cwd)
+	} catch {
+		// No project document yet: the plain slug is the project's.
+	}
+	return join(home, 'projects', slug, 'worktrees')
+}

package/src/session/workspace/index.ts

@@ -1,6 +1,6 @@
 // Sub-barrel for the workspace module (Convention #4).
 // Shape types live under `types/workspace/`; runtime machinery (drivers,
-// registry, path-builder, git-worktree) lives in sibling files under
+// registry, git-worktree, shared session workspace) lives in sibling files under
 // `session/workspace/`.
 
 export type {
@@ -17,16 +17,13 @@ export type {
 	WorkspaceInspection,
 } from './driver.js'
 
-export { DefaultPathBuilder } from './path-builder.js'
-export type { PathBuilder } from './path-builder.js'
-
 export { WorkspaceBackendRegistry } from './registry.js'
 
 export { GitWorktreeDriver, parseWorktreeList } from './git-worktree.js'
 export type { ExecFile, ExecFileResult, GitWorktreeDriverConfig } from './git-worktree.js'
 
-export { SharedRunWorkspace } from './shared-run.js'
+export { SharedSessionWorkspace } from './shared-session.js'
 export type {
-	RegisterSharedRunPlanInput,
-	SharedRunWorkspaceConfig,
-} from './shared-run.js'
+	RegisterSharedSessionPlanInput,
+	SharedSessionWorkspaceConfig,
+} from './shared-session.js'