@namzu/sdk 0.1.8 → 0.3.0

package/src/session/summary/ref.ts

@@ -0,0 +1,104 @@
+/**
+ * SessionSummaryRef — the structured pointer a parent session sees when a
+ * sub-session completes. Kernel-owned terminalization primitive: the only
+ * producer is {@link SessionSummaryMaterializer.materialize} (see
+ * `./materialize.ts`). See session-hierarchy.md §4.7 (shape) and §8.1
+ * (emission invariant).
+ *
+ * The `materializedBy: 'kernel'` literal field is load-bearing — combined
+ * with the opaque {@link SummaryId} brand (mintable only by
+ * `generateSummaryId`), it enforces at the type level that no agent or tool
+ * can construct a valid `SessionSummaryRef`. `SessionStore.recordSummary`
+ * only accepts `SessionSummaryRef & { materializedBy: 'kernel' }`, so even a
+ * payload shaped correctly would fail the structural check.
+ *
+ * This is Convention #0 load-bearing: there is no "tool" path to emit a
+ * summary; the parent agent sees only what the kernel seals.
+ */
+
+import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { SummaryId } from '../../types/session/ids.js'
+import type { DeliverableRef } from './deliverable.js'
+
+/**
+ * Max characters allowed for {@link SessionSummaryRef.agentSummary}. See
+ * session-hierarchy.md §4.7 — the agent's narration is bounded to keep
+ * parent prompts token-finite regardless of the child's transcript length.
+ */
+export const AGENT_SUMMARY_MAX_CHARS = 4000
+
+export type SessionSummaryOutcomeStatus = 'succeeded' | 'partial' | 'failed'
+
+export interface SessionSummaryOutcome {
+	readonly status: SessionSummaryOutcomeStatus
+	/** Short human-readable one-liner. Optional per pattern doc §4.7. */
+	readonly verdict?: string
+}
+
+export interface SessionSummaryKeyDecision {
+	readonly at: Date
+	readonly summary: string
+}
+
+/**
+ * Structured completion pointer emitted by the kernel when a sub-session
+ * terminalizes. See session-hierarchy.md §4.7 and §8.1.
+ *
+ * Readonly across the board — the record is immutable once sealed.
+ */
+export interface SessionSummaryRef {
+	readonly id: SummaryId
+	readonly sessionRef: SessionId
+	readonly tenantId: TenantId
+	readonly outcome: SessionSummaryOutcome
+	readonly deliverables: readonly DeliverableRef[]
+	/** Agent's own narration; bounded to {@link AGENT_SUMMARY_MAX_CHARS}. */
+	readonly agentSummary: string
+	readonly keyDecisions: readonly SessionSummaryKeyDecision[]
+	/** When the summary was materialized. */
+	readonly at: Date
+	/**
+	 * Literal `'kernel'` — enforces kernel-only emission at the type level.
+	 * See the module header for the invariant rationale.
+	 */
+	readonly materializedBy: 'kernel'
+}
+
+/**
+ * Raised by {@link SessionSummaryMaterializer.materialize} when the provided
+ * `agentSummary` exceeds {@link AGENT_SUMMARY_MAX_CHARS}. Convention #5
+ * deny-by-default — the kernel does not truncate silently.
+ */
+export class AgentSummaryTooLongError extends Error {
+	readonly details: {
+		readonly actual: number
+		readonly max: number
+	}
+
+	constructor(details: { actual: number; max: number }) {
+		super(`agentSummary ${details.actual} chars exceeds max ${details.max}`)
+		this.name = 'AgentSummaryTooLongError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised when {@link SessionSummaryMaterializer.materialize} is invoked
+ * against a session that already has a persisted summary. Re-materialization
+ * would duplicate history — callers wanting to append must open a new
+ * intervention sub-session (see session-hierarchy.md §4.5).
+ */
+export class SessionAlreadySummarizedError extends Error {
+	readonly details: {
+		readonly sessionId: SessionId
+		readonly existingSummaryId: SummaryId
+	}
+
+	constructor(details: { sessionId: SessionId; existingSummaryId: SummaryId }) {
+		super(
+			`Session ${details.sessionId} already has summary ${details.existingSummaryId}; re-materialization rejected`,
+		)
+		this.name = 'SessionAlreadySummarizedError'
+		this.details = details
+	}
+}

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

@@ -0,0 +1,258 @@
+import { describe, expect, it, vi } from 'vitest'
+import { WorkspaceBackendError } from '../../errors.js'
+import {
+	type ExecFile,
+	type ExecFileResult,
+	GitWorktreeDriver,
+	parseWorktreeList,
+} from '../git-worktree.js'
+import type { WorkspaceRef } from '../ref.js'
+
+function stubLogger() {
+	return {
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		child() {
+			return stubLogger()
+		},
+	}
+}
+
+function okExec(stdout = '', stderr = ''): ExecFileResult {
+	return { stdout, stderr }
+}
+
+describe('GitWorktreeDriver', () => {
+	it('create: invokes `git worktree add` with argv array (no shell interpolation)', async () => {
+		const calls: Array<{ file: string; args: readonly string[] }> = []
+		const exec: ExecFile = async (file, args) => {
+			calls.push({ file, args: [...args] })
+			return okExec()
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		const ref = await driver.create({ label: 'foo', baseRef: 'main' })
+
+		expect(ref.id.startsWith('wsp_')).toBe(true)
+		expect(ref.meta.backend).toBe('git-worktree')
+		expect(ref.meta.branch).toBe('namzu/foo')
+		expect(calls).toHaveLength(1)
+		const call = calls[0]
+		if (!call) throw new Error('missing call')
+		expect(call.file).toBe('git')
+		expect(call.args).toEqual([
+			'-C',
+			'/repo',
+			'worktree',
+			'add',
+			'-b',
+			'namzu/foo',
+			'/repo/.namzu/worktrees/foo',
+			'main',
+		])
+	})
+
+	it('create: omits baseRef argv slot when not supplied', async () => {
+		const calls: Array<{ file: string; args: readonly string[] }> = []
+		const exec: ExecFile = async (file, args) => {
+			calls.push({ file, args: [...args] })
+			return okExec()
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		await driver.create({ label: 'bar' })
+		const call = calls[0]
+		if (!call) throw new Error('missing call')
+		expect(call.args.at(-1)).toBe('/repo/.namzu/worktrees/bar')
+	})
+
+	it('create: wraps failures in WorkspaceBackendError', async () => {
+		const exec: ExecFile = async () => {
+			throw new Error('invalid baseRef')
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		await expect(driver.create({ baseRef: 'does-not-exist' })).rejects.toBeInstanceOf(
+			WorkspaceBackendError,
+		)
+	})
+
+	it('dispose: removes worktree with --force', async () => {
+		const calls: Array<readonly string[]> = []
+		const exec: ExecFile = async (_file, args) => {
+			calls.push(args)
+			return okExec()
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		const ref: WorkspaceRef = {
+			id: 'wsp_x' as unknown as WorkspaceRef['id'],
+			meta: {
+				backend: 'git-worktree',
+				repoRoot: '/repo',
+				branch: 'namzu/x',
+				worktreePath: '/repo/.namzu/worktrees/x',
+			},
+			createdAt: new Date(),
+		}
+		await driver.dispose(ref)
+		expect(calls[0]).toEqual([
+			'-C',
+			'/repo',
+			'worktree',
+			'remove',
+			'/repo/.namzu/worktrees/x',
+			'--force',
+		])
+	})
+
+	it('dispose: tolerates missing worktree ("not a working tree")', async () => {
+		const exec: ExecFile = async () => {
+			throw new Error("'/tmp/gone' is not a working tree")
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		const ref: WorkspaceRef = {
+			id: 'wsp_x' as unknown as WorkspaceRef['id'],
+			meta: {
+				backend: 'git-worktree',
+				repoRoot: '/repo',
+				branch: 'namzu/x',
+				worktreePath: '/tmp/gone',
+			},
+			createdAt: new Date(),
+		}
+		// Must NOT throw — roadmap Risk #3 mitigation.
+		await expect(driver.dispose(ref)).resolves.toBeUndefined()
+	})
+
+	it('dispose: surfaces unexpected failures as WorkspaceBackendError', async () => {
+		const exec: ExecFile = async () => {
+			throw new Error('fatal: permission denied')
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		const ref: WorkspaceRef = {
+			id: 'wsp_x' as unknown as WorkspaceRef['id'],
+			meta: {
+				backend: 'git-worktree',
+				repoRoot: '/repo',
+				branch: 'namzu/x',
+				worktreePath: '/repo/.namzu/worktrees/x',
+			},
+			createdAt: new Date(),
+		}
+		await expect(driver.dispose(ref)).rejects.toBeInstanceOf(WorkspaceBackendError)
+	})
+
+	it('inspect: parses list output and detects clean tree', async () => {
+		const listStdout = [
+			'worktree /repo/.namzu/worktrees/x',
+			'HEAD abc123',
+			'branch refs/heads/namzu/x',
+			'',
+		].join('\n')
+		let callIndex = 0
+		const exec: ExecFile = async (_file, args) => {
+			callIndex++
+			if (args.includes('list')) return okExec(listStdout)
+			if (args.includes('status')) return okExec('')
+			throw new Error(`unexpected call ${callIndex}`)
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		const ref: WorkspaceRef = {
+			id: 'wsp_x' as unknown as WorkspaceRef['id'],
+			meta: {
+				backend: 'git-worktree',
+				repoRoot: '/repo',
+				branch: 'namzu/x',
+				worktreePath: '/repo/.namzu/worktrees/x',
+			},
+			createdAt: new Date(),
+		}
+		const inspection = await driver.inspect(ref)
+		expect(inspection.exists).toBe(true)
+		expect(inspection.isDirty).toBe(false)
+	})
+
+	it('inspect: reports dirty when status --porcelain has output', async () => {
+		const listStdout = [
+			'worktree /repo/.namzu/worktrees/x',
+			'HEAD abc123',
+			'branch refs/heads/namzu/x',
+			'',
+		].join('\n')
+		const exec: ExecFile = async (_file, args) => {
+			if (args.includes('list')) return okExec(listStdout)
+			if (args.includes('status')) return okExec(' M path/to/file\n')
+			throw new Error('unexpected')
+		}
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		const ref: WorkspaceRef = {
+			id: 'wsp_x' as unknown as WorkspaceRef['id'],
+			meta: {
+				backend: 'git-worktree',
+				repoRoot: '/repo',
+				branch: 'namzu/x',
+				worktreePath: '/repo/.namzu/worktrees/x',
+			},
+			createdAt: new Date(),
+		}
+		const inspection = await driver.inspect(ref)
+		expect(inspection.isDirty).toBe(true)
+	})
+})
+
+describe('parseWorktreeList', () => {
+	it('returns null when the target path is absent', () => {
+		const stdout = ['worktree /other', 'HEAD abc', 'branch refs/heads/main', ''].join('\n')
+		expect(parseWorktreeList(stdout, '/missing')).toBeNull()
+	})
+
+	it('extracts head + branch for the matching entry', () => {
+		const stdout = [
+			'worktree /repo/.namzu/worktrees/x',
+			'HEAD deadbeef',
+			'branch refs/heads/namzu/x',
+			'',
+			'worktree /other',
+			'HEAD abc',
+			'bare',
+			'',
+		].join('\n')
+		const entry = parseWorktreeList(stdout, '/repo/.namzu/worktrees/x')
+		expect(entry).toEqual({
+			path: '/repo/.namzu/worktrees/x',
+			head: 'deadbeef',
+			branch: 'refs/heads/namzu/x',
+		})
+	})
+})

package/src/session/workspace/__tests__/path-builder.test.ts

@@ -0,0 +1,51 @@
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { ProjectId, RunId, SessionId } from '../../../types/ids/index.js'
+import type { SubSessionId } from '../../../types/session/ids.js'
+import { DefaultPathBuilder } from '../path-builder.js'
+
+const projectId = 'prj_abc' as ProjectId
+const sessionId = 'ses_xyz' as SessionId
+const subSessionId = 'sub_qqq' as SubSessionId
+const runId = 'run_rrr' as RunId
+
+describe('DefaultPathBuilder', () => {
+	it('rootDir returns the injected root verbatim', () => {
+		const pb = new DefaultPathBuilder('/tmp/ns')
+		expect(pb.rootDir()).toBe('/tmp/ns')
+	})
+
+	it('projectDir resolves to {root}/projects/{projectId}', () => {
+		const pb = new DefaultPathBuilder('/tmp/ns')
+		expect(pb.projectDir(projectId)).toBe(join('/tmp/ns', 'projects', projectId))
+	})
+
+	it('sessionDir resolves to {root}/projects/{projectId}/sessions/{sessionId}', () => {
+		const pb = new DefaultPathBuilder('/tmp/ns')
+		expect(pb.sessionDir(projectId, sessionId)).toBe(
+			join('/tmp/ns', 'projects', projectId, 'sessions', sessionId),
+		)
+	})
+
+	it('subSessionDir nests under session/subsessions/{subSessionId}', () => {
+		const pb = new DefaultPathBuilder('/tmp/ns')
+		expect(pb.subSessionDir(projectId, sessionId, subSessionId)).toBe(
+			join('/tmp/ns', 'projects', projectId, 'sessions', sessionId, 'subsessions', subSessionId),
+		)
+	})
+
+	it('runDir nests under session/runs/{runId}', () => {
+		const pb = new DefaultPathBuilder('/tmp/ns')
+		expect(pb.runDir(projectId, sessionId, runId)).toBe(
+			join('/tmp/ns', 'projects', projectId, 'sessions', sessionId, 'runs', runId),
+		)
+	})
+
+	it('root injection is per-instance (does not mutate global state)', () => {
+		const a = new DefaultPathBuilder('/tmp/a')
+		const b = new DefaultPathBuilder('/tmp/b')
+		expect(a.rootDir()).toBe('/tmp/a')
+		expect(b.rootDir()).toBe('/tmp/b')
+		expect(a.projectDir(projectId)).not.toBe(b.projectDir(projectId))
+	})
+})

package/src/session/workspace/driver.ts

@@ -0,0 +1,60 @@
+/**
+ * WorkspaceBackendDriver — pluggable backend contract for workspace
+ * provisioning. See session-hierarchy.md §7.1.
+ *
+ * Every Session persists a {@link WorkspaceRef}; the driver owns the
+ * underlying filesystem/container/etc. semantics. Phase 3 ships the
+ * git-worktree reference implementation (`git-worktree.ts`); tmpfs,
+ * container, and shared variants slot behind this same interface in a
+ * later phase (Convention #10: provider abstraction).
+ */
+
+import type { WorkspaceBackendKind, WorkspaceRef } from './ref.js'
+
+/**
+ * Params for {@link WorkspaceBackendDriver.create}. `baseRef` selects the
+ * commit / branch the workspace should track; when absent the driver
+ * provisions from the backend's default (e.g. the current branch of the
+ * repo for git-worktree).
+ */
+export interface CreateWorkspaceParams {
+	baseRef?: string
+	label?: string
+}
+
+/**
+ * Params for {@link WorkspaceBackendDriver.branch}. `label` is a free-form
+ * tag embedded into the new workspace name so operators can trace provenance
+ * without reaching into the driver's internal naming scheme.
+ */
+export interface BranchWorkspaceParams {
+	label?: string
+}
+
+/**
+ * Snapshot returned by {@link WorkspaceBackendDriver.inspect}. `exists` is
+ * `false` when the underlying resource has been disposed out-of-band (e.g.
+ * manual `git worktree remove` on disk); consumers can use it to detect
+ * divergence between the persisted {@link WorkspaceRef} and the backend.
+ */
+export interface WorkspaceInspection {
+	exists: boolean
+	currentRef: string
+	isDirty: boolean
+}
+
+/**
+ * Backend driver contract. All methods are async and may throw
+ * {@link WorkspaceBackendError} on I/O failures. `dispose` is idempotent —
+ * calling it against an already-disposed ref is not an error (mitigates
+ * roadmap Risk #3: broadcast rollback must not fail on partial state).
+ */
+export interface WorkspaceBackendDriver {
+	readonly kind: WorkspaceBackendKind
+	create(params: CreateWorkspaceParams): Promise<WorkspaceRef>
+	branch(source: WorkspaceRef, params: BranchWorkspaceParams): Promise<WorkspaceRef>
+	dispose(ref: WorkspaceRef): Promise<void>
+	inspect(ref: WorkspaceRef): Promise<WorkspaceInspection>
+}
+
+export type { WorkspaceBackendKind } from './ref.js'

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

@@ -0,0 +1,209 @@
+/**
+ * GitWorktreeDriver — reference implementation of
+ * {@link WorkspaceBackendDriver} backed by `git worktree`.
+ *
+ * See session-hierarchy.md §7.2 (Git-worktree reference backend).
+ *
+ * Safety: every subprocess invocation uses `execFile` with an argv array —
+ * no shell interpolation — so caller-supplied `label`/`baseRef` strings
+ * cannot escape their argument slot. Failures surface as
+ * {@link WorkspaceBackendError} carrying the underlying cause.
+ */
+
+import { execFile } from 'node:child_process'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { generateWorkspaceId } from '../../utils/id.js'
+import type { Logger } from '../../utils/logger.js'
+import { WorkspaceBackendError } from '../errors.js'
+import type {
+	BranchWorkspaceParams,
+	CreateWorkspaceParams,
+	WorkspaceBackendDriver,
+	WorkspaceInspection,
+} from './driver.js'
+import type { GitWorktreeBackendMeta, WorkspaceRef } from './ref.js'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Minimal shape of `execFile`'s promisified result — allows tests to stub
+ * via dependency injection without pulling in the full `ChildProcess` type.
+ */
+export interface ExecFileResult {
+	stdout: string
+	stderr: string
+}
+
+/**
+ * Async exec callable used by {@link GitWorktreeDriver}. Matches the shape
+ * of `promisify(execFile)` for the argv-array overload. Injected via the
+ * constructor so tests can stub without touching `child_process`.
+ */
+export type ExecFile = (file: string, args: readonly string[]) => Promise<ExecFileResult>
+
+const defaultExecFile: ExecFile = async (file, args) => execFileAsync(file, [...args])
+
+/**
+ * Configuration for {@link GitWorktreeDriver}.
+ */
+export interface GitWorktreeDriverConfig {
+	/** Absolute path to the repo root whose `.git` backs the worktrees. */
+	repoRoot: string
+	/**
+	 * Directory (absolute) where worktree checkouts live. Defaults to
+	 * `{repoRoot}/.namzu/worktrees` per session-hierarchy.md §7.2.
+	 */
+	worktreesDir?: string
+	logger: Logger
+	/** Test-seam: inject a stub `execFile` implementation. */
+	execFile?: ExecFile
+}
+
+export class GitWorktreeDriver implements WorkspaceBackendDriver {
+	readonly kind = 'git-worktree' as const
+
+	private readonly repoRoot: string
+	private readonly worktreesDir: string
+	private readonly log: Logger
+	private readonly exec: ExecFile
+
+	constructor(config: GitWorktreeDriverConfig) {
+		this.repoRoot = config.repoRoot
+		this.worktreesDir = config.worktreesDir ?? join(config.repoRoot, '.namzu', 'worktrees')
+		this.log = config.logger.child({ component: 'GitWorktreeDriver' })
+		this.exec = config.execFile ?? defaultExecFile
+	}
+
+	async create(params: CreateWorkspaceParams): Promise<WorkspaceRef> {
+		const id = generateWorkspaceId()
+		const label = params.label ?? id
+		const branch = `namzu/${label}`
+		const worktreePath = join(this.worktreesDir, label)
+
+		const argv = ['-C', this.repoRoot, 'worktree', 'add', '-b', branch, worktreePath]
+		if (params.baseRef !== undefined) {
+			argv.push(params.baseRef)
+		}
+
+		try {
+			await this.exec('git', argv)
+		} catch (cause) {
+			throw new WorkspaceBackendError({ op: 'create', kind: this.kind, cause })
+		}
+
+		const meta: GitWorktreeBackendMeta = {
+			backend: 'git-worktree',
+			repoRoot: this.repoRoot,
+			branch,
+			worktreePath,
+		}
+
+		this.log.info('git-worktree created', { id, branch, worktreePath })
+		return {
+			id,
+			meta,
+			createdAt: new Date(),
+		}
+	}
+
+	async branch(source: WorkspaceRef, params: BranchWorkspaceParams): Promise<WorkspaceRef> {
+		// Branch from the source worktree's current branch. The source's
+		// `meta.branch` is the ref we base off.
+		return this.create({ baseRef: source.meta.branch, label: params.label })
+	}
+
+	async dispose(ref: WorkspaceRef): Promise<void> {
+		// Tolerate missing directories per roadmap Risk #3 mitigation: the
+		// broadcast-rollback compensating step calls dispose on partially
+		// provisioned refs and must not propagate "already gone" errors.
+		try {
+			await this.exec('git', [
+				'-C',
+				this.repoRoot,
+				'worktree',
+				'remove',
+				ref.meta.worktreePath,
+				'--force',
+			])
+			this.log.info('git-worktree disposed', { id: ref.id, 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,
+				})
+				return
+			}
+			throw new WorkspaceBackendError({ op: 'dispose', kind: this.kind, cause })
+		}
+	}
+
+	async inspect(ref: WorkspaceRef): Promise<WorkspaceInspection> {
+		let listStdout: string
+		try {
+			const result = await this.exec('git', [
+				'-C',
+				this.repoRoot,
+				'worktree',
+				'list',
+				'--porcelain',
+			])
+			listStdout = result.stdout
+		} catch (cause) {
+			throw new WorkspaceBackendError({ op: 'inspect:list', kind: this.kind, cause })
+		}
+
+		const entry = parseWorktreeList(listStdout, ref.meta.worktreePath)
+		if (!entry) {
+			return { exists: false, currentRef: ref.meta.branch, isDirty: false }
+		}
+
+		let statusStdout: string
+		try {
+			const result = await this.exec('git', ['-C', ref.meta.worktreePath, 'status', '--porcelain'])
+			statusStdout = result.stdout
+		} catch (cause) {
+			throw new WorkspaceBackendError({ op: 'inspect:status', kind: this.kind, cause })
+		}
+
+		return {
+			exists: true,
+			currentRef: entry.branch ?? entry.head ?? ref.meta.branch,
+			isDirty: statusStdout.trim().length > 0,
+		}
+	}
+}
+
+/**
+ * Parses `git worktree list --porcelain` output, returning the record for
+ * `worktreePath` or `null` when absent. Exported for tests.
+ */
+export function parseWorktreeList(
+	stdout: string,
+	worktreePath: string,
+): { path: string; head?: string; branch?: string } | null {
+	const blocks = stdout.split(/\n\n+/)
+	for (const block of blocks) {
+		const lines = block.split('\n').filter((l) => l.length > 0)
+		let path: string | undefined
+		let head: string | undefined
+		let branch: string | undefined
+		for (const line of lines) {
+			if (line.startsWith('worktree ')) path = line.slice('worktree '.length)
+			else if (line.startsWith('HEAD ')) head = line.slice('HEAD '.length)
+			else if (line.startsWith('branch ')) branch = line.slice('branch '.length)
+		}
+		if (path === worktreePath) {
+			return {
+				path,
+				...(head !== undefined && { head }),
+				...(branch !== undefined && { branch }),
+			}
+		}
+	}
+	return null
+}