@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/runtime/git-env.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Helpers for safely invoking `git` subprocesses inside isolated working
+ * directories.
+ *
+ * ## Why this exists (AISDLC-68 → AISDLC-72)
+ *
+ * When a husky pre-push hook (or any nested git invocation) runs commands
+ * from inside `.worktrees/<id>/`, git exports `GIT_DIR`, `GIT_WORK_TREE`,
+ * and `GIT_INDEX_FILE` into the child process environment so subprocesses
+ * "stay" in the calling worktree's git context. That's the right behavior
+ * for normal subprocesses — but it's catastrophic for code that creates
+ * its own throwaway repository in a temp directory.
+ *
+ * Without sanitizing the environment:
+ *   - `execSync('git init', { cwd: tmpDir })` initializes the *parent*
+ *     worktree's index, not tmpDir's.
+ *   - `execSync('git commit', { cwd: tmpDir })` writes a commit onto the
+ *     *parent's* current branch using files from tmpDir — silently
+ *     corrupting the feature branch with leaked test artifacts.
+ *   - The pre-push hook that triggered this whole cascade then sees
+ *     unexpected commits and either fails or worse, ships them.
+ *
+ * The fix is uniform: strip `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE`
+ * from the inherited env at every site that runs `git` against an explicit
+ * `cwd`. PR #78 patched the tokens-studio adapter; AISDLC-72 sweeps the
+ * orchestrator + remaining test sites.
+ */
+/**
+ * Return a copy of `process.env` with the git-context env vars removed.
+ *
+ * Use this for any subprocess that runs `git` against an explicit `cwd`
+ * different from the calling process's CWD (temp repos, sibling repos,
+ * worktree-pool clones).
+ */
+export declare function cleanGitEnv(): NodeJS.ProcessEnv;
+/**
+ * Promisified `execFile('git', args, opts)` wrapper that strips the git
+ * context env vars before invocation. Use whenever the caller passes
+ * `cwd` (i.e. running git in a directory other than the parent process's
+ * CWD).
+ *
+ * Caller-supplied `opts.env` takes precedence — it's already explicit
+ * about what to inherit. We only inject `cleanGitEnv()` when no env was
+ * provided.
+ */
+export declare function gitExecFile(args: string[], opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+//# sourceMappingURL=git-env.d.ts.map

package/dist/runtime/git-env.js

@@ -0,0 +1,60 @@
+/**
+ * Helpers for safely invoking `git` subprocesses inside isolated working
+ * directories.
+ *
+ * ## Why this exists (AISDLC-68 → AISDLC-72)
+ *
+ * When a husky pre-push hook (or any nested git invocation) runs commands
+ * from inside `.worktrees/<id>/`, git exports `GIT_DIR`, `GIT_WORK_TREE`,
+ * and `GIT_INDEX_FILE` into the child process environment so subprocesses
+ * "stay" in the calling worktree's git context. That's the right behavior
+ * for normal subprocesses — but it's catastrophic for code that creates
+ * its own throwaway repository in a temp directory.
+ *
+ * Without sanitizing the environment:
+ *   - `execSync('git init', { cwd: tmpDir })` initializes the *parent*
+ *     worktree's index, not tmpDir's.
+ *   - `execSync('git commit', { cwd: tmpDir })` writes a commit onto the
+ *     *parent's* current branch using files from tmpDir — silently
+ *     corrupting the feature branch with leaked test artifacts.
+ *   - The pre-push hook that triggered this whole cascade then sees
+ *     unexpected commits and either fails or worse, ships them.
+ *
+ * The fix is uniform: strip `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE`
+ * from the inherited env at every site that runs `git` against an explicit
+ * `cwd`. PR #78 patched the tokens-studio adapter; AISDLC-72 sweeps the
+ * orchestrator + remaining test sites.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Return a copy of `process.env` with the git-context env vars removed.
+ *
+ * Use this for any subprocess that runs `git` against an explicit `cwd`
+ * different from the calling process's CWD (temp repos, sibling repos,
+ * worktree-pool clones).
+ */
+export function cleanGitEnv() {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    return env;
+}
+/**
+ * Promisified `execFile('git', args, opts)` wrapper that strips the git
+ * context env vars before invocation. Use whenever the caller passes
+ * `cwd` (i.e. running git in a directory other than the parent process's
+ * CWD).
+ *
+ * Caller-supplied `opts.env` takes precedence — it's already explicit
+ * about what to inherit. We only inject `cleanGitEnv()` when no env was
+ * provided.
+ */
+export async function gitExecFile(args, opts = {}) {
+    const env = opts.env ?? cleanGitEnv();
+    const { stdout, stderr } = await execFileAsync('git', args, { ...opts, env });
+    return { stdout, stderr };
+}
+//# sourceMappingURL=git-env.js.map

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+export { deterministicPort, allocatePort, allocateContiguousPorts, isPortFree, PortAllocationError, DEFAULT_BASE_PORT, PORT_RANGE_OFFSET_MIN, PORT_RANGE_OFFSET_MAX, type AllocatePortOptions, type AllocateContiguousOptions, } from './port-allocator.js';
+export { slugifyBranch, worktreePath, verifyOwnership, assertOwnership, isExistingWorktree, WorktreeOwnershipError, type OwnershipResult, } from './worktree.js';
+export { WorktreePoolManager, WorktreePoolError, DEFAULT_POOL_ROOT, DEFAULT_STALE_THRESHOLD_DAYS, type WorktreePoolSpec, type WorktreePoolManagerDeps, type AllocateOptions, type WorktreeHandle, } from './worktree-pool.js';
+export { readParallelismMode, isParallelismEnabled, FLAG_NAME as PARALLELISM_FLAG, type ParallelismMode, } from './parallelism-flag.js';
+export { cleanGitEnv, gitExecFile } from './git-env.js';
+export { ACCEPTED_SCHEMA_VERSIONS, DSSE_PAYLOAD_TYPE, buildPredicate, generateSigningKeyPair, paeEncode, sha1Hex, sha256Hex, signAttestation, validateTrustedReviewers, verifyAttestation, type AttestationPredicate, type DsseEnvelope, type DsseSignature, type ReviewerEntry, type SchemaVersion, type SubjectDigest, type TrustedReviewer, type VerifyResult, } from './attestations.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -0,0 +1,7 @@
+export { deterministicPort, allocatePort, allocateContiguousPorts, isPortFree, PortAllocationError, DEFAULT_BASE_PORT, PORT_RANGE_OFFSET_MIN, PORT_RANGE_OFFSET_MAX, } from './port-allocator.js';
+export { slugifyBranch, worktreePath, verifyOwnership, assertOwnership, isExistingWorktree, WorktreeOwnershipError, } from './worktree.js';
+export { WorktreePoolManager, WorktreePoolError, DEFAULT_POOL_ROOT, DEFAULT_STALE_THRESHOLD_DAYS, } from './worktree-pool.js';
+export { readParallelismMode, isParallelismEnabled, FLAG_NAME as PARALLELISM_FLAG, } from './parallelism-flag.js';
+export { cleanGitEnv, gitExecFile } from './git-env.js';
+export { ACCEPTED_SCHEMA_VERSIONS, DSSE_PAYLOAD_TYPE, buildPredicate, generateSigningKeyPair, paeEncode, sha1Hex, sha256Hex, signAttestation, validateTrustedReviewers, verifyAttestation, } from './attestations.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/parallelism-flag.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Feature-flag gate for RFC-0010 parallelism. Phases 1-4 shipped behind
+ * AI_SDLC_PARALLELISM=experimental; Phase 5 (hardening) added the runbook,
+ * chaos plan, and stuck-heartbeat detection. Per maintainer directive
+ * 2026-05-01 (AISDLC-116), the calendar-based 1-week soak gate from RFC-0010
+ * Phase 5 was dropped in favor of substantive readiness — pre-flight scan
+ * of orchestrator/_events.jsonl + recent commit history showed zero
+ * parallelism-related incidents — and the flag now defaults to 'on'.
+ *
+ * Backwards-compat envelope (preserved on purpose):
+ *   - unset                       → 'on'   (new default)
+ *   - 'on' | 'true' | '1'         → 'on'
+ *   - 'experimental'              → 'experimental'  (still honored for
+ *                                                    callers pinning the
+ *                                                    pre-promotion mode)
+ *   - 'off' | 'disabled' |
+ *     'false' | '0'               → 'off'  (explicit opt-out)
+ *   - any other string            → 'on'   (fail-on rather than fail-off
+ *                                           now that 'on' is the default;
+ *                                           prevents typos like
+ *                                           'enable' from silently
+ *                                           disabling parallelism)
+ */
+export declare const FLAG_NAME = "AI_SDLC_PARALLELISM";
+export type ParallelismMode = 'off' | 'experimental' | 'on';
+export declare function readParallelismMode(env?: NodeJS.ProcessEnv): ParallelismMode;
+export declare function isParallelismEnabled(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=parallelism-flag.d.ts.map

package/dist/runtime/parallelism-flag.js

@@ -0,0 +1,39 @@
+/**
+ * Feature-flag gate for RFC-0010 parallelism. Phases 1-4 shipped behind
+ * AI_SDLC_PARALLELISM=experimental; Phase 5 (hardening) added the runbook,
+ * chaos plan, and stuck-heartbeat detection. Per maintainer directive
+ * 2026-05-01 (AISDLC-116), the calendar-based 1-week soak gate from RFC-0010
+ * Phase 5 was dropped in favor of substantive readiness — pre-flight scan
+ * of orchestrator/_events.jsonl + recent commit history showed zero
+ * parallelism-related incidents — and the flag now defaults to 'on'.
+ *
+ * Backwards-compat envelope (preserved on purpose):
+ *   - unset                       → 'on'   (new default)
+ *   - 'on' | 'true' | '1'         → 'on'
+ *   - 'experimental'              → 'experimental'  (still honored for
+ *                                                    callers pinning the
+ *                                                    pre-promotion mode)
+ *   - 'off' | 'disabled' |
+ *     'false' | '0'               → 'off'  (explicit opt-out)
+ *   - any other string            → 'on'   (fail-on rather than fail-off
+ *                                           now that 'on' is the default;
+ *                                           prevents typos like
+ *                                           'enable' from silently
+ *                                           disabling parallelism)
+ */
+export const FLAG_NAME = 'AI_SDLC_PARALLELISM';
+export function readParallelismMode(env = process.env) {
+    const raw = env[FLAG_NAME]?.trim().toLowerCase();
+    if (raw === undefined || raw === '')
+        return 'on';
+    if (raw === 'experimental')
+        return 'experimental';
+    if (raw === 'off' || raw === 'disabled' || raw === 'false' || raw === '0')
+        return 'off';
+    // 'on' / 'true' / '1' / any other value → 'on' (default-on, fail-on)
+    return 'on';
+}
+export function isParallelismEnabled(env) {
+    return readParallelismMode(env) !== 'off';
+}
+//# sourceMappingURL=parallelism-flag.js.map

package/dist/runtime/port-allocator.d.ts

@@ -0,0 +1,32 @@
+export declare const DEFAULT_BASE_PORT = 3190;
+export declare const PORT_RANGE_OFFSET_MIN = 100;
+export declare const PORT_RANGE_OFFSET_MAX = 999;
+export interface AllocatePortOptions {
+    basePort?: number;
+    envOverride?: string | undefined;
+    isPortFree?: (port: number) => Promise<boolean>;
+}
+export interface AllocateContiguousOptions extends AllocatePortOptions {
+    count: number;
+}
+export declare class PortAllocationError extends Error {
+    readonly worktreePath: string;
+    readonly attemptedPorts: number[];
+    constructor(message: string, worktreePath: string, attemptedPorts: number[]);
+}
+/**
+ * Derive a deterministic port for `worktreePath` by hashing its absolute form with MD5
+ * and mapping the first two bytes into [basePort + PORT_RANGE_OFFSET_MIN,
+ * basePort + PORT_RANGE_OFFSET_MAX].
+ *
+ * **Collision risk**: the output space is only 900 ports wide. When called with multiple
+ * independent (e.g. mkdtemp-generated) paths, two or more paths may map to the same port.
+ * For n=3 paths the birthday probability is ~0.33%. Integration tests that need to assert
+ * port distinctness MUST use pre-chosen, manually-verified paths rather than random
+ * temporaries — see the module-level JSDoc for the recommended assertion pattern.
+ */
+export declare function deterministicPort(worktreePath: string, basePort?: number): number;
+export declare function allocatePort(worktreePath: string, options?: AllocatePortOptions): Promise<number>;
+export declare function allocateContiguousPorts(worktreePath: string, options: AllocateContiguousOptions): Promise<number[]>;
+export declare function isPortFree(port: number): Promise<boolean>;
+//# sourceMappingURL=port-allocator.d.ts.map

package/dist/runtime/port-allocator.js

@@ -0,0 +1,96 @@
+/**
+ * Deterministic port allocator for git worktrees.
+ *
+ * `deterministicPort` maps an absolute worktree path to a port number in a fixed
+ * 900-port range (DEFAULT_BASE_PORT + PORT_RANGE_OFFSET_MIN … PORT_RANGE_OFFSET_MAX)
+ * by hashing the path with MD5 and taking the first two bytes modulo the range span.
+ *
+ * **Hash-collision caveat**: the 900-port range is finite. When multiple worktree paths
+ * are fed through `deterministicPort` in a single test, birthday-paradox collisions are
+ * possible. For n=3 paths the probability is roughly (n*(n-1)/2) / span ≈ 0.33%. Over
+ * thousands of CI runs this causes spurious "distinct ports" assertion failures.
+ *
+ * **Integration-test guidance**: do NOT assert `new Set(ports).size === n` unless the
+ * test controls the exact path strings and has pre-verified they hash to distinct values.
+ * Instead assert:
+ *   - each port is in [DEFAULT_BASE_PORT + PORT_RANGE_OFFSET_MIN, DEFAULT_BASE_PORT + PORT_RANGE_OFFSET_MAX]
+ *   - calling allocatePort twice for the same path returns the same value (idempotency)
+ *   - ports[i] === deterministicPort(h.path) (the core deterministic-port property)
+ */
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { createServer } from 'node:net';
+export const DEFAULT_BASE_PORT = 3190;
+export const PORT_RANGE_OFFSET_MIN = 100;
+export const PORT_RANGE_OFFSET_MAX = 999;
+const PORT_RANGE_SPAN = PORT_RANGE_OFFSET_MAX - PORT_RANGE_OFFSET_MIN + 1;
+const COLLISION_PROBE_ATTEMPTS = 10;
+export class PortAllocationError extends Error {
+    worktreePath;
+    attemptedPorts;
+    constructor(message, worktreePath, attemptedPorts) {
+        super(message);
+        this.worktreePath = worktreePath;
+        this.attemptedPorts = attemptedPorts;
+        this.name = 'PortAllocationError';
+    }
+}
+/**
+ * Derive a deterministic port for `worktreePath` by hashing its absolute form with MD5
+ * and mapping the first two bytes into [basePort + PORT_RANGE_OFFSET_MIN,
+ * basePort + PORT_RANGE_OFFSET_MAX].
+ *
+ * **Collision risk**: the output space is only 900 ports wide. When called with multiple
+ * independent (e.g. mkdtemp-generated) paths, two or more paths may map to the same port.
+ * For n=3 paths the birthday probability is ~0.33%. Integration tests that need to assert
+ * port distinctness MUST use pre-chosen, manually-verified paths rather than random
+ * temporaries — see the module-level JSDoc for the recommended assertion pattern.
+ */
+export function deterministicPort(worktreePath, basePort = DEFAULT_BASE_PORT) {
+    const absolute = resolve(worktreePath);
+    const digest = createHash('md5').update(absolute).digest();
+    const offset = (((digest[0] << 8) | digest[1]) % PORT_RANGE_SPAN) + PORT_RANGE_OFFSET_MIN;
+    return basePort + offset;
+}
+export async function allocatePort(worktreePath, options = {}) {
+    const envValue = options.envOverride;
+    if (envValue !== undefined && envValue !== '') {
+        const parsed = Number.parseInt(envValue, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 65535) {
+            throw new PortAllocationError(`PORT environment override is not a valid TCP port: ${envValue}`, worktreePath, []);
+        }
+        return parsed;
+    }
+    const basePort = options.basePort ?? DEFAULT_BASE_PORT;
+    const start = deterministicPort(worktreePath, basePort);
+    const probe = options.isPortFree ?? isPortFree;
+    const attempted = [];
+    for (let i = 0; i < COLLISION_PROBE_ATTEMPTS; i++) {
+        const candidate = start + i;
+        attempted.push(candidate);
+        if (await probe(candidate)) {
+            return candidate;
+        }
+    }
+    throw new PortAllocationError(`No free port found after ${COLLISION_PROBE_ATTEMPTS} attempts starting at ${start}`, worktreePath, attempted);
+}
+export async function allocateContiguousPorts(worktreePath, options) {
+    if (options.count < 1 || options.count > 10) {
+        throw new PortAllocationError(`Contiguous port count must be between 1 and 10 (got ${options.count})`, worktreePath, []);
+    }
+    const first = await allocatePort(worktreePath, options);
+    return Array.from({ length: options.count }, (_, i) => first + i);
+}
+export function isPortFree(port) {
+    return new Promise((resolveProbe) => {
+        const server = createServer();
+        server.once('error', () => {
+            resolveProbe(false);
+        });
+        server.once('listening', () => {
+            server.close(() => resolveProbe(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+//# sourceMappingURL=port-allocator.js.map

package/dist/runtime/worktree-pool.d.ts

@@ -0,0 +1,86 @@
+export declare const DEFAULT_POOL_ROOT = "~/.ai-sdlc/worktrees";
+export declare const DEFAULT_STALE_THRESHOLD_DAYS = 14;
+export interface WorktreePoolSpec {
+    rootDir?: string;
+    staleThresholdDays?: number;
+    ownershipGuard?: 'strict' | 'advisory';
+}
+export interface AllocateOptions {
+    /** Base branch to create from (default 'origin/main'). */
+    baseBranch?: string;
+}
+export interface WorktreeHandle {
+    branch: string;
+    slug: string;
+    path: string;
+    /** True when allocate() created the worktree fresh; false when it adopted an existing one. */
+    created: boolean;
+}
+export declare class WorktreePoolError extends Error {
+    readonly branch: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, branch: string, cause?: unknown | undefined);
+}
+export interface WorktreePoolManagerDeps {
+    /** Override `git` calls in tests. */
+    git?: (args: string[], opts?: {
+        cwd?: string;
+    }) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Override clock for stale-threshold tests. */
+    now?: () => Date;
+}
+/**
+ * Manages a pool of git worktrees rooted at `rootDir`. Each worktree is named after
+ * `slugifyBranch(branch)`. The pool enforces cross-clone ownership (RFC §7.2) and supports
+ * allocate / adopt / reclaim plus a stale-threshold sweep (RFC §7.3).
+ */
+export declare class WorktreePoolManager {
+    readonly rootDir: string;
+    private readonly clonePath;
+    private readonly staleThresholdDays;
+    private readonly ownershipGuard;
+    private readonly git;
+    private readonly now;
+    constructor(clonePath: string, spec?: WorktreePoolSpec, deps?: WorktreePoolManagerDeps);
+    /**
+     * Allocate a worktree for `branch`. If one already exists at the expected path:
+     *   - ownership-verified → adopted (returned with `created: false`)
+     *   - ownership mismatch → throws WorktreeOwnershipError (or warns when guard is advisory)
+     * Otherwise a fresh worktree is created via `git worktree add`.
+     */
+    allocate(branch: string, options?: AllocateOptions): Promise<WorktreeHandle>;
+    /**
+     * Adopt an existing worktree at the slug-derived path. Throws if no worktree exists or
+     * if ownership verification fails (when guard is strict).
+     */
+    adopt(branch: string): Promise<WorktreeHandle>;
+    /**
+     * Destroy the worktree for `branch`. By default refuses to remove a worktree with
+     * uncommitted changes; callers that need to force MUST pass `{ force: true }`.
+     */
+    reclaim(branch: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Convenience hook called by the merge-gate when a PR for `branch` lands. Equivalent
+     * to `reclaim(branch)` with the default safety check.
+     */
+    cleanupOnMerge(branch: string): Promise<void>;
+    /**
+     * Enumerate worktree slugs currently present in the pool root. Does not verify ownership.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Reclaim worktrees whose mtime is older than `staleThresholdDays`. Dry-run by default;
+     * pass `{ apply: true }` to actually remove them. Returns the slugs considered stale.
+     */
+    reclaimStale(options?: {
+        apply?: boolean;
+    }): Promise<string[]>;
+    /** Forcibly remove a slug from the pool root without git involvement. Test/cleanup helper. */
+    _forceRemoveSlug(slug: string): Promise<void>;
+}
+//# sourceMappingURL=worktree-pool.d.ts.map

package/dist/runtime/worktree-pool.js

@@ -0,0 +1,204 @@
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { execFileAsync } from '../shared.js';
+import { assertOwnership, isExistingWorktree, slugifyBranch, verifyOwnership, WorktreeOwnershipError, } from './worktree.js';
+import { cleanGitEnv } from './git-env.js';
+export const DEFAULT_POOL_ROOT = '~/.ai-sdlc/worktrees';
+export const DEFAULT_STALE_THRESHOLD_DAYS = 14;
+export class WorktreePoolError extends Error {
+    branch;
+    cause;
+    constructor(message, branch, cause) {
+        super(message);
+        this.branch = branch;
+        this.cause = cause;
+        this.name = 'WorktreePoolError';
+    }
+}
+/**
+ * Manages a pool of git worktrees rooted at `rootDir`. Each worktree is named after
+ * `slugifyBranch(branch)`. The pool enforces cross-clone ownership (RFC §7.2) and supports
+ * allocate / adopt / reclaim plus a stale-threshold sweep (RFC §7.3).
+ */
+export class WorktreePoolManager {
+    rootDir;
+    clonePath;
+    staleThresholdDays;
+    ownershipGuard;
+    git;
+    now;
+    constructor(clonePath, spec = {}, deps = {}) {
+        this.clonePath = resolve(clonePath);
+        this.rootDir = expandHome(spec.rootDir ?? DEFAULT_POOL_ROOT);
+        this.staleThresholdDays = spec.staleThresholdDays ?? DEFAULT_STALE_THRESHOLD_DAYS;
+        this.ownershipGuard = spec.ownershipGuard ?? 'strict';
+        this.git =
+            deps.git ??
+                ((args, opts) => {
+                    // Strip leaked GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so worktree
+                    // operations bind to `clonePath`'s repo rather than a husky hook's
+                    // env (AISDLC-72).
+                    const merged = { env: cleanGitEnv(), ...opts };
+                    return execFileAsync('git', args, merged);
+                });
+        this.now = deps.now ?? (() => new Date());
+    }
+    /**
+     * Allocate a worktree for `branch`. If one already exists at the expected path:
+     *   - ownership-verified → adopted (returned with `created: false`)
+     *   - ownership mismatch → throws WorktreeOwnershipError (or warns when guard is advisory)
+     * Otherwise a fresh worktree is created via `git worktree add`.
+     */
+    async allocate(branch, options = {}) {
+        const slug = slugifyBranch(branch);
+        const path = join(this.rootDir, slug);
+        if (await isExistingWorktree(path)) {
+            return this.adopt(branch);
+        }
+        await mkdir(this.rootDir, { recursive: true });
+        const baseBranch = options.baseBranch ?? 'origin/main';
+        try {
+            await this.git(['worktree', 'add', path, '-b', branch, baseBranch], {
+                cwd: this.clonePath,
+            });
+        }
+        catch (err) {
+            throw new WorktreePoolError(`git worktree add failed for branch ${branch}: ${err.message}`, branch, err);
+        }
+        return { branch, slug, path, created: true };
+    }
+    /**
+     * Adopt an existing worktree at the slug-derived path. Throws if no worktree exists or
+     * if ownership verification fails (when guard is strict).
+     */
+    async adopt(branch) {
+        const slug = slugifyBranch(branch);
+        const path = join(this.rootDir, slug);
+        if (!(await isExistingWorktree(path))) {
+            throw new WorktreePoolError(`No existing worktree at ${path} for branch ${branch}`, branch);
+        }
+        if (this.ownershipGuard === 'strict') {
+            try {
+                await assertOwnership(path, this.clonePath);
+            }
+            catch (err) {
+                if (err instanceof WorktreeOwnershipError)
+                    throw err;
+                throw err;
+            }
+        }
+        else {
+            const result = await verifyOwnership(path, this.clonePath);
+            if (!result.owned) {
+                // Advisory: log via console.warn so operators see drift without failing.
+                // In production this would route to the structured event stream.
+                console.warn(`[WorktreePool] advisory ownership mismatch on ${path}: expected ${result.expectedClone}, got ${result.actualClone}`);
+            }
+        }
+        return { branch, slug, path, created: false };
+    }
+    /**
+     * Destroy the worktree for `branch`. By default refuses to remove a worktree with
+     * uncommitted changes; callers that need to force MUST pass `{ force: true }`.
+     */
+    async reclaim(branch, options = {}) {
+        const slug = slugifyBranch(branch);
+        const path = join(this.rootDir, slug);
+        if (!(await isExistingWorktree(path))) {
+            // Nothing to reclaim is not an error — idempotent.
+            return;
+        }
+        if (!options.force) {
+            // Refuse if there are uncommitted changes.
+            try {
+                const { stdout } = await this.git(['status', '--porcelain'], { cwd: path });
+                if (stdout.trim().length > 0) {
+                    throw new WorktreePoolError(`Refusing to reclaim ${path}: uncommitted changes present. Use force: true to override.`, branch);
+                }
+            }
+            catch (err) {
+                if (err instanceof WorktreePoolError)
+                    throw err;
+                // git status failure on a worktree we know exists is a real error.
+                throw new WorktreePoolError(`git status failed inside ${path}: ${err.message}`, branch, err);
+            }
+        }
+        const args = ['worktree', 'remove', path];
+        if (options.force)
+            args.push('--force');
+        try {
+            await this.git(args, { cwd: this.clonePath });
+        }
+        catch (err) {
+            throw new WorktreePoolError(`git worktree remove failed for ${path}: ${err.message}`, branch, err);
+        }
+    }
+    /**
+     * Convenience hook called by the merge-gate when a PR for `branch` lands. Equivalent
+     * to `reclaim(branch)` with the default safety check.
+     */
+    cleanupOnMerge(branch) {
+        return this.reclaim(branch);
+    }
+    /**
+     * Enumerate worktree slugs currently present in the pool root. Does not verify ownership.
+     */
+    async list() {
+        try {
+            const entries = await readdir(this.rootDir, { withFileTypes: true });
+            const result = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (await isExistingWorktree(join(this.rootDir, entry.name))) {
+                    result.push(entry.name);
+                }
+            }
+            return result;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+    }
+    /**
+     * Reclaim worktrees whose mtime is older than `staleThresholdDays`. Dry-run by default;
+     * pass `{ apply: true }` to actually remove them. Returns the slugs considered stale.
+     */
+    async reclaimStale(options = {}) {
+        const slugs = await this.list();
+        const cutoff = this.now().getTime() - this.staleThresholdDays * 24 * 60 * 60 * 1000;
+        const stale = [];
+        for (const slug of slugs) {
+            const path = join(this.rootDir, slug);
+            try {
+                const s = await stat(path);
+                if (s.mtimeMs < cutoff) {
+                    stale.push(slug);
+                    if (options.apply) {
+                        // Use git worktree prune-style remove; force because branch may have moved.
+                        await this.git(['worktree', 'remove', '--force', path], { cwd: this.clonePath });
+                    }
+                }
+            }
+            catch {
+                // Ignore missing or stat-failed paths.
+            }
+        }
+        return stale;
+    }
+    /** Forcibly remove a slug from the pool root without git involvement. Test/cleanup helper. */
+    async _forceRemoveSlug(slug) {
+        await rm(join(this.rootDir, slug), { recursive: true, force: true });
+    }
+}
+function expandHome(p) {
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    if (p === '~')
+        return homedir();
+    return p;
+}
+//# sourceMappingURL=worktree-pool.js.map

package/dist/runtime/worktree.d.ts

@@ -0,0 +1,25 @@
+export declare class WorktreeOwnershipError extends Error {
+    readonly worktreePath: string;
+    readonly expectedClone: string;
+    readonly actualClone: string | null;
+    constructor(message: string, worktreePath: string, expectedClone: string, actualClone: string | null);
+}
+export declare function slugifyBranch(branch: string): string;
+export declare function worktreePath(rootDir: string, branch: string): string;
+export interface OwnershipResult {
+    owned: boolean;
+    expectedClone: string;
+    actualClone: string | null;
+    reason?: 'pointer-missing' | 'pointer-malformed' | 'cross-clone' | 'ok';
+}
+/**
+ * Verify a worktree at `worktreePath` was created from the clone at `expectedClonePath`.
+ *
+ * A git worktree contains a `.git` *file* (not directory) that points at the parent clone's
+ * `.git/worktrees/<name>/` directory. We parse the pointer and confirm it resolves under
+ * `expectedClonePath/.git/worktrees/`. Any mismatch returns owned=false with a structured reason.
+ */
+export declare function verifyOwnership(worktreePathArg: string, expectedClonePath: string): Promise<OwnershipResult>;
+export declare function assertOwnership(worktreePathArg: string, expectedClonePath: string): Promise<void>;
+export declare function isExistingWorktree(worktreePathArg: string): Promise<boolean>;
+//# sourceMappingURL=worktree.d.ts.map