@caupulican/pi-adaptative 0.81.37 → 0.81.39

package/dist/core/worktree-sync/lane-gate.js

@@ -0,0 +1,360 @@
+/**
+ * Lane gate: G8/G10 enforcement for a LANE-BOUND `pi` session (launched with
+ * `PI_WORKTREE_LANE=<key>`). RuntimeBuilder wraps the session's file-mutation tools (edit /
+ * write / bash) with {@link WorktreeLaneGate.checkMutation}; a lane that the active policy marks
+ * sync_required fails closed with the exact recovery step until it rebases main.
+ *
+ * Honesty boundary (unchanged from the tmux trust model): this is HARD for pi children -- the
+ * wrapper lives under the tool layer, not in the prompt -- and cooperative-only for foreign
+ * CLIs, whose backstop is the land CAS (G3): stale work simply cannot land.
+ *
+ * Determinism: the gate re-derives from git only when the epoch file actually changed (mtime
+ * fence) or while blocked; verdicts in between are cached. No polling, no timers.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { deriveLaneFacts, resolveRepoContext } from "./git-engine.js";
+import { readLane } from "./store.js";
+const SYNC_SAFE_GIT_SUBCOMMANDS = new Set([
+    "status",
+    "diff",
+    "log",
+    "show",
+    "add",
+    "commit",
+    "stash",
+    "rev-parse",
+    "ls-files",
+    "blame",
+    "grep",
+]);
+const MAIN_MUTATING_GIT_SUBCOMMANDS = new Set(["merge", "rebase", "reset", "commit", "branch", "update-ref", "push"]);
+/**
+ * Classify one bash command line for a lane-bound session (G10 + the sync_required allowlist).
+ * Tokenization is whitespace-naive by design -- deterministic and reviewable; shell-quoting
+ * tricks can evade it, which is the documented cooperative boundary (the land CAS cannot be
+ * evaded). Command POSITION still matters: `git` only begins an invocation at the start of the
+ * command or immediately after a shell separator (`&&`, `||`, `;`, `|`) -- a bare `git` token
+ * elsewhere (e.g. as a plain argument to `echo`) is not an invocation. Rules:
+ * - `git push` anywhere: refused (main moves only through the land gate; pushing is owner-only).
+ * - `git -C <path>` / `--git-dir` combined with a mutating subcommand: refused (escaping the
+ *   lane worktree to operate on another checkout, e.g. the hub).
+ * - `git branch -f/-M/-D <main>` / `git update-ref refs/heads/<main>`: refused.
+ * - Everything else: allowed; a read/commit-shaped git subcommand additionally stays allowed
+ *   while the lane is sync_required (committing WIP is the prescribed step BEFORE syncing).
+ */
+export function classifyLaneBashCommand(command, mainBranch) {
+    // This classifier is defense-in-depth, not a shell parser. Refuse compound
+    // syntax before any segment can return an allow verdict; otherwise `git
+    // status; git push` is approved by the first safe segment.
+    if (/[|;&<>$`(){}\n\r]/u.test(command)) {
+        return {
+            verdict: "main_mutation_refused",
+            reason: "compound shell syntax is refused in a lane; use typed worktree_sync actions",
+        };
+    }
+    if (/^\s*["']git["']\s/u.test(command)) {
+        return {
+            verdict: "main_mutation_refused",
+            reason: "quoted command names are refused in a lane; use the typed Git actions",
+        };
+    }
+    const segments = [command];
+    let allowedWhenSyncRequired = false;
+    for (const segment of segments) {
+        const tokens = segment.trim().split(/\s+/).filter(Boolean);
+        if (tokens[0] !== "git")
+            continue;
+        let j = 1;
+        let escapesWorktree = false;
+        // Skip git global options to find the subcommand; -C/--git-dir mark checkout escape.
+        while (j < tokens.length) {
+            const token = tokens[j] ?? "";
+            if (token === "-C" || token === "--git-dir" || token === "--work-tree") {
+                escapesWorktree = true;
+                j += 2;
+                continue;
+            }
+            if (token.startsWith("-C") && token !== "-C") {
+                escapesWorktree = true;
+                j += 1;
+                continue;
+            }
+            if (token.startsWith("--git-dir=") || token.startsWith("--work-tree=")) {
+                escapesWorktree = true;
+                j += 1;
+                continue;
+            }
+            if (token.startsWith("-")) {
+                j += 1;
+                continue;
+            }
+            break;
+        }
+        const subcommand = tokens[j] ?? "";
+        const rest = tokens.slice(j + 1);
+        if (subcommand === "push") {
+            return {
+                verdict: "main_mutation_refused",
+                reason: "git push is refused in a lane session; landing is the only integration path and pushing stays an owner action",
+            };
+        }
+        if (escapesWorktree && MAIN_MUTATING_GIT_SUBCOMMANDS.has(subcommand)) {
+            return {
+                verdict: "main_mutation_refused",
+                reason: `git -C/--git-dir with '${subcommand}' escapes the lane worktree; operate only on this lane (G10)`,
+            };
+        }
+        if (subcommand === "branch" &&
+            rest.some((token) => /^(?:-f|--force|-M|-m|-D|-d)$/.test(token)) &&
+            rest.includes(mainBranch)) {
+            return {
+                verdict: "main_mutation_refused",
+                reason: `git branch may not move/delete '${mainBranch}' from a lane; main moves only through the land gate (G10)`,
+            };
+        }
+        if (subcommand === "update-ref" && rest.some((token) => token === `refs/heads/${mainBranch}`)) {
+            return {
+                verdict: "main_mutation_refused",
+                reason: `git update-ref may not touch refs/heads/${mainBranch} from a lane (G10)`,
+            };
+        }
+        if (SYNC_SAFE_GIT_SUBCOMMANDS.has(subcommand))
+            allowedWhenSyncRequired = true;
+    }
+    return allowedWhenSyncRequired ? { verdict: "allowed_even_when_sync_required" } : { verdict: "allowed" };
+}
+/** Symlink-safe resolution of a path that may not exist yet: realpath the NEAREST EXISTING
+ * ancestor, then re-append the not-yet-existing tail literally (a not-yet-created file's own
+ * missing final component can never itself be a symlink escape). */
+function resolveSymlinkSafe(targetPath) {
+    if (existsSync(targetPath)) {
+        try {
+            return realpathSync(targetPath);
+        }
+        catch {
+            return targetPath;
+        }
+    }
+    const tail = [basename(targetPath)];
+    let ancestor = dirname(targetPath);
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            break; // reached the filesystem root without finding one
+        tail.unshift(basename(ancestor));
+        ancestor = parent;
+    }
+    let realAncestor;
+    try {
+        realAncestor = realpathSync(ancestor);
+    }
+    catch {
+        realAncestor = ancestor;
+    }
+    return join(realAncestor, ...tail);
+}
+/** Symlink-safe containment check (G-path): does `targetPath` resolve inside `worktreePath`? */
+export function isPathOutsideLane(targetPath, worktreePath) {
+    let realRoot;
+    try {
+        realRoot = realpathSync(worktreePath);
+    }
+    catch {
+        realRoot = worktreePath;
+    }
+    const resolvedTarget = resolveSymlinkSafe(targetPath);
+    return resolvedTarget !== realRoot && !resolvedTarget.startsWith(realRoot + sep);
+}
+/** Resolve a user-supplied relative lane path and reject symlink/parent escapes. */
+export function resolveLaneMutationPath(worktreePath, candidate) {
+    const target = resolve(worktreePath, candidate);
+    return isPathOutsideLane(target, worktreePath) ? undefined : target;
+}
+async function changedPaths(deps, cwd, base, ref) {
+    const result = await deps.exec("git", ["diff", "--name-only", `${base}..${ref}`, "--"], {
+        cwd,
+        timeout: 60_000,
+        maxBuffer: 1024 * 1024,
+    });
+    if (result.code !== 0)
+        return undefined;
+    return new Set(result.stdout
+        .split(/\r?\n/u)
+        .map((path) => path.trim())
+        .filter(Boolean));
+}
+function hardShellCommandAllowed(command, mainBranch, trustedGateCommand) {
+    const trimmed = command.trim();
+    if (trustedGateCommand && trimmed === trustedGateCommand.trim())
+        return true;
+    if (!/^git(?:\s|$)/u.test(trimmed))
+        return false;
+    const verdict = classifyLaneBashCommand(trimmed, mainBranch);
+    if (verdict.verdict === "main_mutation_refused")
+        return false;
+    const tokens = trimmed.split(/\s+/u);
+    const subcommand = tokens[1] ?? "";
+    if (!SYNC_SAFE_GIT_SUBCOMMANDS.has(subcommand) && subcommand !== "commit")
+        return false;
+    // Git path operands must not escape the lane checkout. The typed worktree
+    // actions are the authoritative route for path-sensitive add/diff operations;
+    // this final check prevents the common absolute/parent escape in the shell floor.
+    return !tokens.slice(2).some((token) => token.startsWith("/") || token.startsWith("..") || token.includes("/../"));
+}
+/**
+ * The G8 gate object RuntimeBuilder holds per lane-bound session. `checkMutation` is called by
+ * the wrapped edit/write/bash tools before every mutating execution.
+ */
+export class WorktreeLaneGate {
+    config;
+    _ctx;
+    _epochFileMtimeMs;
+    _cachedAllowed = false;
+    constructor(config) {
+        this.config = config;
+    }
+    async resolveContext() {
+        if (this._ctx)
+            return this._ctx;
+        const ctx = await resolveRepoContext(this.config.engineDeps());
+        if ("code" in ctx)
+            return undefined;
+        this._ctx = ctx;
+        return ctx;
+    }
+    /** Cheap fence: has the epoch file changed since the last allowed verdict? */
+    epochChanged(ctx) {
+        let mtimeMs;
+        try {
+            mtimeMs = statSync(ctx.paths.epochFile).mtimeMs;
+        }
+        catch {
+            mtimeMs = undefined;
+        }
+        if (mtimeMs === this._epochFileMtimeMs)
+            return false;
+        this._epochFileMtimeMs = mtimeMs;
+        return true;
+    }
+    async checkMutation(toolName, bashCommand, targetPath) {
+        const ctx = await this.resolveContext();
+        // No repo context (deleted repo, engine failure): fail OPEN for plain tools -- the land
+        // CAS still holds -- but the G10 bash rules below never depend on repo state.
+        const mainBranch = ctx?.mainBranch ?? "main";
+        if (this.config.hardShell && !ctx) {
+            return {
+                allowed: false,
+                code: "lane_state_unavailable",
+                message: "worktree-sync: lane state is unavailable; hard worker mutations fail closed",
+            };
+        }
+        if (toolName === "bash" && bashCommand !== undefined) {
+            if (this.config.hardShell &&
+                !hardShellCommandAllowed(bashCommand, mainBranch, this.config.trustedGateCommand?.())) {
+                return {
+                    allowed: false,
+                    code: "main_mutation_refused",
+                    message: "worktree-sync: unrestricted bash is unavailable in a hard worker lane; use typed worktree_sync actions",
+                };
+            }
+            const verdict = classifyLaneBashCommand(bashCommand, mainBranch);
+            if (verdict.verdict === "main_mutation_refused") {
+                return { allowed: false, code: "main_mutation_refused", message: `worktree-sync: ${verdict.reason}` };
+            }
+            if (verdict.verdict === "allowed_even_when_sync_required")
+                return { allowed: true };
+        }
+        if (!ctx)
+            return { allowed: true };
+        // G-path: an edit/write target must resolve INSIDE this lane's worktree (symlink-safe),
+        // checked BEFORE the staleness cache so a cached "allowed" verdict never short-circuits past
+        // it. No active lane record: existing fail-open stands (mirrors the readLane check below).
+        if ((toolName === "edit" || toolName === "write") && targetPath !== undefined) {
+            const laneForPath = await readLane(ctx.paths, this.config.laneKey);
+            if (laneForPath?.status === "active" && isPathOutsideLane(targetPath, laneForPath.worktreePath)) {
+                return {
+                    allowed: false,
+                    code: "path_outside_lane",
+                    message: `worktree-sync: '${targetPath}' resolves outside lane '${this.config.laneKey}' worktree (${laneForPath.worktreePath}); edit/write only inside your lane checkout`,
+                };
+            }
+        }
+        // G8: sync_required fails mutations closed. Re-derive only when the epoch moved or while
+        // blocked (a successful sync clears the block on the very next check).
+        if (this._cachedAllowed && !this.epochChanged(ctx))
+            return { allowed: true };
+        const deps = this.config.engineDeps();
+        const lane = await readLane(ctx.paths, this.config.laneKey);
+        if (!lane || lane.status !== "active") {
+            if (this.config.hardShell) {
+                return {
+                    allowed: false,
+                    code: "lane_state_unavailable",
+                    message: "worktree-sync: hard worker lane registration is missing or inactive; reconcile before mutating",
+                };
+            }
+            this._cachedAllowed = true;
+            return { allowed: true };
+        }
+        // Re-derive main tip: the cached ctx pins the sha from session start.
+        const fresh = await resolveRepoContext(deps);
+        if ("code" in fresh) {
+            if (this.config.hardShell) {
+                return {
+                    allowed: false,
+                    code: "lane_state_unavailable",
+                    message: "worktree-sync: Git context is unavailable; hard worker mutation refused",
+                };
+            }
+            this._cachedAllowed = true;
+            return { allowed: true };
+        }
+        this._ctx = fresh;
+        const facts = await deriveLaneFacts(deps, fresh, lane);
+        if (facts.fresh) {
+            this._cachedAllowed = true;
+            return { allowed: true };
+        }
+        const policy = this.config.policy();
+        let syncRequired = policy === "on_land_mandatory";
+        if (policy === "overlap_mandatory") {
+            // Epoch files are notification/diagnostic state only. Derive both sides from the
+            // current merge base so an overlap from land N remains enforced after unrelated land N+1.
+            const mergeBase = await deps.exec("git", ["merge-base", fresh.mainBranch, lane.branch], {
+                cwd: fresh.topLevel,
+                timeout: 60_000,
+                maxBuffer: 1024 * 1024,
+            });
+            if (mergeBase.code !== 0 || !mergeBase.stdout.trim()) {
+                syncRequired = true;
+            }
+            else {
+                const base = mergeBase.stdout.trim().split(/\s+/u)[0];
+                const lanePaths = await changedPaths(deps, fresh.topLevel, base, lane.branch);
+                const mainPaths = await changedPaths(deps, fresh.topLevel, base, fresh.mainBranch);
+                if (!lanePaths || !mainPaths) {
+                    syncRequired = true;
+                }
+                else {
+                    syncRequired = [...lanePaths].some((path) => mainPaths.has(path));
+                }
+            }
+        }
+        if (policy === "land_time_only")
+            syncRequired = false;
+        if (!syncRequired) {
+            this._cachedAllowed = true;
+            return { allowed: true };
+        }
+        this._cachedAllowed = false;
+        return {
+            allowed: false,
+            code: "sync_required",
+            message: `worktree-sync: lane '${this.config.laneKey}' must rebase main before further mutations ` +
+                `(main moved past this lane). Commit any WIP (git add/commit stay available), then call ` +
+                `worktree_sync {"action":"sync"}, resolve conflicts if any, and continue. (sync_required)`,
+        };
+    }
+}
+//# sourceMappingURL=lane-gate.js.map

package/dist/core/worktree-sync/lane-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lane-gate.js","sourceRoot":"","sources":["../../../src/core/worktree-sync/lane-gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Lane gate: G8/G10 enforcement for a LANE-BOUND `pi` session (launched with\n * `PI_WORKTREE_LANE=<key>`). RuntimeBuilder wraps the session's file-mutation tools (edit /\n * write / bash) with {@link WorktreeLaneGate.checkMutation}; a lane that the active policy marks\n * sync_required fails closed with the exact recovery step until it rebases main.\n *\n * Honesty boundary (unchanged from the tmux trust model): this is HARD for pi children -- the\n * wrapper lives under the tool layer, not in the prompt -- and cooperative-only for foreign\n * CLIs, whose backstop is the land CAS (G3): stale work simply cannot land.\n *\n * Determinism: the gate re-derives from git only when the epoch file actually changed (mtime\n * fence) or while blocked; verdicts in between are cached. No polling, no timers.\n */\n\nimport { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { basename, dirname, join, resolve, sep } from \"node:path\";\nimport type { WorktreeSyncPolicy } from \"./codes.ts\";\nimport { deriveLaneFacts, type RepoContext, resolveRepoContext, type WorktreeSyncEngineDeps } from \"./git-engine.ts\";\nimport { readLane } from \"./store.ts\";\n\nexport type LaneBashVerdict =\n\t| { verdict: \"allowed\" }\n\t| { verdict: \"allowed_even_when_sync_required\" }\n\t| { verdict: \"main_mutation_refused\"; reason: string };\n\nconst SYNC_SAFE_GIT_SUBCOMMANDS = new Set([\n\t\"status\",\n\t\"diff\",\n\t\"log\",\n\t\"show\",\n\t\"add\",\n\t\"commit\",\n\t\"stash\",\n\t\"rev-parse\",\n\t\"ls-files\",\n\t\"blame\",\n\t\"grep\",\n]);\n\nconst MAIN_MUTATING_GIT_SUBCOMMANDS = new Set([\"merge\", \"rebase\", \"reset\", \"commit\", \"branch\", \"update-ref\", \"push\"]);\n\n/**\n * Classify one bash command line for a lane-bound session (G10 + the sync_required allowlist).\n * Tokenization is whitespace-naive by design -- deterministic and reviewable; shell-quoting\n * tricks can evade it, which is the documented cooperative boundary (the land CAS cannot be\n * evaded). Command POSITION still matters: `git` only begins an invocation at the start of the\n * command or immediately after a shell separator (`&&`, `||`, `;`, `|`) -- a bare `git` token\n * elsewhere (e.g. as a plain argument to `echo`) is not an invocation. Rules:\n * - `git push` anywhere: refused (main moves only through the land gate; pushing is owner-only).\n * - `git -C <path>` / `--git-dir` combined with a mutating subcommand: refused (escaping the\n *   lane worktree to operate on another checkout, e.g. the hub).\n * - `git branch -f/-M/-D <main>` / `git update-ref refs/heads/<main>`: refused.\n * - Everything else: allowed; a read/commit-shaped git subcommand additionally stays allowed\n *   while the lane is sync_required (committing WIP is the prescribed step BEFORE syncing).\n */\nexport function classifyLaneBashCommand(command: string, mainBranch: string): LaneBashVerdict {\n\t// This classifier is defense-in-depth, not a shell parser. Refuse compound\n\t// syntax before any segment can return an allow verdict; otherwise `git\n\t// status; git push` is approved by the first safe segment.\n\tif (/[|;&<>$`(){}\\n\\r]/u.test(command)) {\n\t\treturn {\n\t\t\tverdict: \"main_mutation_refused\",\n\t\t\treason: \"compound shell syntax is refused in a lane; use typed worktree_sync actions\",\n\t\t};\n\t}\n\tif (/^\\s*[\"']git[\"']\\s/u.test(command)) {\n\t\treturn {\n\t\t\tverdict: \"main_mutation_refused\",\n\t\t\treason: \"quoted command names are refused in a lane; use the typed Git actions\",\n\t\t};\n\t}\n\tconst segments = [command];\n\tlet allowedWhenSyncRequired = false;\n\tfor (const segment of segments) {\n\t\tconst tokens = segment.trim().split(/\\s+/).filter(Boolean);\n\t\tif (tokens[0] !== \"git\") continue;\n\t\tlet j = 1;\n\t\tlet escapesWorktree = false;\n\t\t// Skip git global options to find the subcommand; -C/--git-dir mark checkout escape.\n\t\twhile (j < tokens.length) {\n\t\t\tconst token = tokens[j] ?? \"\";\n\t\t\tif (token === \"-C\" || token === \"--git-dir\" || token === \"--work-tree\") {\n\t\t\t\tescapesWorktree = true;\n\t\t\t\tj += 2;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (token.startsWith(\"-C\") && token !== \"-C\") {\n\t\t\t\tescapesWorktree = true;\n\t\t\t\tj += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (token.startsWith(\"--git-dir=\") || token.startsWith(\"--work-tree=\")) {\n\t\t\t\tescapesWorktree = true;\n\t\t\t\tj += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (token.startsWith(\"-\")) {\n\t\t\t\tj += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\t\tconst subcommand = tokens[j] ?? \"\";\n\t\tconst rest = tokens.slice(j + 1);\n\t\tif (subcommand === \"push\") {\n\t\t\treturn {\n\t\t\t\tverdict: \"main_mutation_refused\",\n\t\t\t\treason:\n\t\t\t\t\t\"git push is refused in a lane session; landing is the only integration path and pushing stays an owner action\",\n\t\t\t};\n\t\t}\n\t\tif (escapesWorktree && MAIN_MUTATING_GIT_SUBCOMMANDS.has(subcommand)) {\n\t\t\treturn {\n\t\t\t\tverdict: \"main_mutation_refused\",\n\t\t\t\treason: `git -C/--git-dir with '${subcommand}' escapes the lane worktree; operate only on this lane (G10)`,\n\t\t\t};\n\t\t}\n\t\tif (\n\t\t\tsubcommand === \"branch\" &&\n\t\t\trest.some((token) => /^(?:-f|--force|-M|-m|-D|-d)$/.test(token)) &&\n\t\t\trest.includes(mainBranch)\n\t\t) {\n\t\t\treturn {\n\t\t\t\tverdict: \"main_mutation_refused\",\n\t\t\t\treason: `git branch may not move/delete '${mainBranch}' from a lane; main moves only through the land gate (G10)`,\n\t\t\t};\n\t\t}\n\t\tif (subcommand === \"update-ref\" && rest.some((token) => token === `refs/heads/${mainBranch}`)) {\n\t\t\treturn {\n\t\t\t\tverdict: \"main_mutation_refused\",\n\t\t\t\treason: `git update-ref may not touch refs/heads/${mainBranch} from a lane (G10)`,\n\t\t\t};\n\t\t}\n\t\tif (SYNC_SAFE_GIT_SUBCOMMANDS.has(subcommand)) allowedWhenSyncRequired = true;\n\t}\n\treturn allowedWhenSyncRequired ? { verdict: \"allowed_even_when_sync_required\" } : { verdict: \"allowed\" };\n}\n\n/** Symlink-safe resolution of a path that may not exist yet: realpath the NEAREST EXISTING\n * ancestor, then re-append the not-yet-existing tail literally (a not-yet-created file's own\n * missing final component can never itself be a symlink escape). */\nfunction resolveSymlinkSafe(targetPath: string): string {\n\tif (existsSync(targetPath)) {\n\t\ttry {\n\t\t\treturn realpathSync(targetPath);\n\t\t} catch {\n\t\t\treturn targetPath;\n\t\t}\n\t}\n\tconst tail: string[] = [basename(targetPath)];\n\tlet ancestor = dirname(targetPath);\n\twhile (!existsSync(ancestor)) {\n\t\tconst parent = dirname(ancestor);\n\t\tif (parent === ancestor) break; // reached the filesystem root without finding one\n\t\ttail.unshift(basename(ancestor));\n\t\tancestor = parent;\n\t}\n\tlet realAncestor: string;\n\ttry {\n\t\trealAncestor = realpathSync(ancestor);\n\t} catch {\n\t\trealAncestor = ancestor;\n\t}\n\treturn join(realAncestor, ...tail);\n}\n\n/** Symlink-safe containment check (G-path): does `targetPath` resolve inside `worktreePath`? */\nexport function isPathOutsideLane(targetPath: string, worktreePath: string): boolean {\n\tlet realRoot: string;\n\ttry {\n\t\trealRoot = realpathSync(worktreePath);\n\t} catch {\n\t\trealRoot = worktreePath;\n\t}\n\tconst resolvedTarget = resolveSymlinkSafe(targetPath);\n\treturn resolvedTarget !== realRoot && !resolvedTarget.startsWith(realRoot + sep);\n}\n\n/** Resolve a user-supplied relative lane path and reject symlink/parent escapes. */\nexport function resolveLaneMutationPath(worktreePath: string, candidate: string): string | undefined {\n\tconst target = resolve(worktreePath, candidate);\n\treturn isPathOutsideLane(target, worktreePath) ? undefined : target;\n}\n\nexport interface WorktreeLaneGateConfig {\n\tlaneKey: string;\n\tengineDeps: () => WorktreeSyncEngineDeps;\n\tpolicy: () => WorktreeSyncPolicy;\n\t/** Worker launches use a hard shell envelope: only lane-safe Git/WIP commands and the owner-configured\n\t * exact gate command may pass through bash. Interactive lane sessions retain the legacy cooperative\n\t * command surface while the typed worktree_sync actions are used for hard worker mutations. */\n\thardShell?: boolean;\n\ttrustedGateCommand?: () => string | undefined;\n}\n\nexport type LaneMutationCheck = { allowed: true } | { allowed: false; code: string; message: string };\n\nasync function changedPaths(\n\tdeps: WorktreeSyncEngineDeps,\n\tcwd: string,\n\tbase: string,\n\tref: string,\n): Promise<Set<string> | undefined> {\n\tconst result = await deps.exec(\"git\", [\"diff\", \"--name-only\", `${base}..${ref}`, \"--\"], {\n\t\tcwd,\n\t\ttimeout: 60_000,\n\t\tmaxBuffer: 1024 * 1024,\n\t});\n\tif (result.code !== 0) return undefined;\n\treturn new Set(\n\t\tresult.stdout\n\t\t\t.split(/\\r?\\n/u)\n\t\t\t.map((path) => path.trim())\n\t\t\t.filter(Boolean),\n\t);\n}\n\nfunction hardShellCommandAllowed(command: string, mainBranch: string, trustedGateCommand?: string): boolean {\n\tconst trimmed = command.trim();\n\tif (trustedGateCommand && trimmed === trustedGateCommand.trim()) return true;\n\tif (!/^git(?:\\s|$)/u.test(trimmed)) return false;\n\tconst verdict = classifyLaneBashCommand(trimmed, mainBranch);\n\tif (verdict.verdict === \"main_mutation_refused\") return false;\n\tconst tokens = trimmed.split(/\\s+/u);\n\tconst subcommand = tokens[1] ?? \"\";\n\tif (!SYNC_SAFE_GIT_SUBCOMMANDS.has(subcommand) && subcommand !== \"commit\") return false;\n\t// Git path operands must not escape the lane checkout. The typed worktree\n\t// actions are the authoritative route for path-sensitive add/diff operations;\n\t// this final check prevents the common absolute/parent escape in the shell floor.\n\treturn !tokens.slice(2).some((token) => token.startsWith(\"/\") || token.startsWith(\"..\") || token.includes(\"/../\"));\n}\n\n/**\n * The G8 gate object RuntimeBuilder holds per lane-bound session. `checkMutation` is called by\n * the wrapped edit/write/bash tools before every mutating execution.\n */\nexport class WorktreeLaneGate {\n\tprivate readonly config: WorktreeLaneGateConfig;\n\tprivate _ctx: RepoContext | undefined;\n\tprivate _epochFileMtimeMs: number | undefined;\n\tprivate _cachedAllowed = false;\n\n\tconstructor(config: WorktreeLaneGateConfig) {\n\t\tthis.config = config;\n\t}\n\n\tprivate async resolveContext(): Promise<RepoContext | undefined> {\n\t\tif (this._ctx) return this._ctx;\n\t\tconst ctx = await resolveRepoContext(this.config.engineDeps());\n\t\tif (\"code\" in ctx) return undefined;\n\t\tthis._ctx = ctx;\n\t\treturn ctx;\n\t}\n\n\t/** Cheap fence: has the epoch file changed since the last allowed verdict? */\n\tprivate epochChanged(ctx: RepoContext): boolean {\n\t\tlet mtimeMs: number | undefined;\n\t\ttry {\n\t\t\tmtimeMs = statSync(ctx.paths.epochFile).mtimeMs;\n\t\t} catch {\n\t\t\tmtimeMs = undefined;\n\t\t}\n\t\tif (mtimeMs === this._epochFileMtimeMs) return false;\n\t\tthis._epochFileMtimeMs = mtimeMs;\n\t\treturn true;\n\t}\n\n\tasync checkMutation(toolName: string, bashCommand?: string, targetPath?: string): Promise<LaneMutationCheck> {\n\t\tconst ctx = await this.resolveContext();\n\t\t// No repo context (deleted repo, engine failure): fail OPEN for plain tools -- the land\n\t\t// CAS still holds -- but the G10 bash rules below never depend on repo state.\n\t\tconst mainBranch = ctx?.mainBranch ?? \"main\";\n\t\tif (this.config.hardShell && !ctx) {\n\t\t\treturn {\n\t\t\t\tallowed: false,\n\t\t\t\tcode: \"lane_state_unavailable\",\n\t\t\t\tmessage: \"worktree-sync: lane state is unavailable; hard worker mutations fail closed\",\n\t\t\t};\n\t\t}\n\n\t\tif (toolName === \"bash\" && bashCommand !== undefined) {\n\t\t\tif (\n\t\t\t\tthis.config.hardShell &&\n\t\t\t\t!hardShellCommandAllowed(bashCommand, mainBranch, this.config.trustedGateCommand?.())\n\t\t\t) {\n\t\t\t\treturn {\n\t\t\t\t\tallowed: false,\n\t\t\t\t\tcode: \"main_mutation_refused\",\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t\"worktree-sync: unrestricted bash is unavailable in a hard worker lane; use typed worktree_sync actions\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst verdict = classifyLaneBashCommand(bashCommand, mainBranch);\n\t\t\tif (verdict.verdict === \"main_mutation_refused\") {\n\t\t\t\treturn { allowed: false, code: \"main_mutation_refused\", message: `worktree-sync: ${verdict.reason}` };\n\t\t\t}\n\t\t\tif (verdict.verdict === \"allowed_even_when_sync_required\") return { allowed: true };\n\t\t}\n\t\tif (!ctx) return { allowed: true };\n\n\t\t// G-path: an edit/write target must resolve INSIDE this lane's worktree (symlink-safe),\n\t\t// checked BEFORE the staleness cache so a cached \"allowed\" verdict never short-circuits past\n\t\t// it. No active lane record: existing fail-open stands (mirrors the readLane check below).\n\t\tif ((toolName === \"edit\" || toolName === \"write\") && targetPath !== undefined) {\n\t\t\tconst laneForPath = await readLane(ctx.paths, this.config.laneKey);\n\t\t\tif (laneForPath?.status === \"active\" && isPathOutsideLane(targetPath, laneForPath.worktreePath)) {\n\t\t\t\treturn {\n\t\t\t\t\tallowed: false,\n\t\t\t\t\tcode: \"path_outside_lane\",\n\t\t\t\t\tmessage: `worktree-sync: '${targetPath}' resolves outside lane '${this.config.laneKey}' worktree (${laneForPath.worktreePath}); edit/write only inside your lane checkout`,\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\t// G8: sync_required fails mutations closed. Re-derive only when the epoch moved or while\n\t\t// blocked (a successful sync clears the block on the very next check).\n\t\tif (this._cachedAllowed && !this.epochChanged(ctx)) return { allowed: true };\n\n\t\tconst deps = this.config.engineDeps();\n\t\tconst lane = await readLane(ctx.paths, this.config.laneKey);\n\t\tif (!lane || lane.status !== \"active\") {\n\t\t\tif (this.config.hardShell) {\n\t\t\t\treturn {\n\t\t\t\t\tallowed: false,\n\t\t\t\t\tcode: \"lane_state_unavailable\",\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t\"worktree-sync: hard worker lane registration is missing or inactive; reconcile before mutating\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tthis._cachedAllowed = true;\n\t\t\treturn { allowed: true };\n\t\t}\n\t\t// Re-derive main tip: the cached ctx pins the sha from session start.\n\t\tconst fresh = await resolveRepoContext(deps);\n\t\tif (\"code\" in fresh) {\n\t\t\tif (this.config.hardShell) {\n\t\t\t\treturn {\n\t\t\t\t\tallowed: false,\n\t\t\t\t\tcode: \"lane_state_unavailable\",\n\t\t\t\t\tmessage: \"worktree-sync: Git context is unavailable; hard worker mutation refused\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tthis._cachedAllowed = true;\n\t\t\treturn { allowed: true };\n\t\t}\n\t\tthis._ctx = fresh;\n\t\tconst facts = await deriveLaneFacts(deps, fresh, lane);\n\t\tif (facts.fresh) {\n\t\t\tthis._cachedAllowed = true;\n\t\t\treturn { allowed: true };\n\t\t}\n\n\t\tconst policy = this.config.policy();\n\t\tlet syncRequired = policy === \"on_land_mandatory\";\n\t\tif (policy === \"overlap_mandatory\") {\n\t\t\t// Epoch files are notification/diagnostic state only. Derive both sides from the\n\t\t\t// current merge base so an overlap from land N remains enforced after unrelated land N+1.\n\t\t\tconst mergeBase = await deps.exec(\"git\", [\"merge-base\", fresh.mainBranch, lane.branch], {\n\t\t\t\tcwd: fresh.topLevel,\n\t\t\t\ttimeout: 60_000,\n\t\t\t\tmaxBuffer: 1024 * 1024,\n\t\t\t});\n\t\t\tif (mergeBase.code !== 0 || !mergeBase.stdout.trim()) {\n\t\t\t\tsyncRequired = true;\n\t\t\t} else {\n\t\t\t\tconst base = mergeBase.stdout.trim().split(/\\s+/u)[0];\n\t\t\t\tconst lanePaths = await changedPaths(deps, fresh.topLevel, base, lane.branch);\n\t\t\t\tconst mainPaths = await changedPaths(deps, fresh.topLevel, base, fresh.mainBranch);\n\t\t\t\tif (!lanePaths || !mainPaths) {\n\t\t\t\t\tsyncRequired = true;\n\t\t\t\t} else {\n\t\t\t\t\tsyncRequired = [...lanePaths].some((path) => mainPaths.has(path));\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tif (policy === \"land_time_only\") syncRequired = false;\n\n\t\tif (!syncRequired) {\n\t\t\tthis._cachedAllowed = true;\n\t\t\treturn { allowed: true };\n\t\t}\n\t\tthis._cachedAllowed = false;\n\t\treturn {\n\t\t\tallowed: false,\n\t\t\tcode: \"sync_required\",\n\t\t\tmessage:\n\t\t\t\t`worktree-sync: lane '${this.config.laneKey}' must rebase main before further mutations ` +\n\t\t\t\t`(main moved past this lane). Commit any WIP (git add/commit stay available), then call ` +\n\t\t\t\t`worktree_sync {\"action\":\"sync\"}, resolve conflicts if any, and continue. (sync_required)`,\n\t\t};\n\t}\n}\n"]}

package/dist/core/worktree-sync/runtime.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Worktree-sync runtime composition: the pieces main.ts / RuntimeBuilder wire together.
+ *
+ * The lane binding is an ENVIRONMENT contract: a session launched with `PI_WORKTREE_LANE=<key>`
+ * (set by the `--worktree-lane` CLI flag, or directly by any launcher -- tmux panes inherit it
+ * from the launch command line) is lane-bound: its file-mutation tools run behind the lane gate
+ * (G8/G10) and its epoch watcher injects staleness notices. The env form is deliberate -- it
+ * crosses EVERY process boundary (tmux, exec, nested shells) without per-launcher plumbing.
+ */
+import type { SettingsManager } from "../settings-manager.ts";
+import { type WorktreeSyncEngineDeps } from "./git-engine.ts";
+export declare const PI_WORKTREE_LANE_ENV = "PI_WORKTREE_LANE";
+/** The lane this process is bound to, from the cross-process env contract. Invalid values are
+ * ignored (never a crash on a malformed env). */
+export declare function getBoundWorktreeLaneKey(env?: NodeJS.ProcessEnv): string | undefined;
+export interface WorktreeSyncEngineConfig {
+    cwd: string;
+    agentDir: string;
+    settingsManager: SettingsManager;
+    sessionId?: string;
+    signal?: AbortSignal;
+}
+/** Build production engine deps from session facts + resolved settings. */
+export declare function buildWorktreeSyncEngineDeps(config: WorktreeSyncEngineConfig): WorktreeSyncEngineDeps;
+export interface WorktreeSyncRuntimeConfig extends WorktreeSyncEngineConfig {
+    /** Structural notice injection into the running session (host `sendCustomMessage` seam):
+     * "steer" mid-turn, trigger a turn when idle -- the host closure decides the mechanics. */
+    notify: (text: string) => void;
+    /** Diagnostics sink for startup-reconcile findings (never throws into the session). */
+    onDiagnostic?: (message: string) => void;
+}
+export interface WorktreeSyncRuntimeHandle {
+    stop(): void;
+}
+/**
+ * Start the per-session worktree-sync runtime (main.ts composition root):
+ * 1. one startup reconcile pass (registry vs git reality -- orphans marked, lost lanes
+ *    re-registered, dead owners cleared, provably-stale lock released), and
+ * 2. for a LANE-BOUND session, the epoch watcher: a land anywhere on this machine injects a
+ *    deterministic staleness notice into this session promptly (the pull-guaranteed channel is
+ *    still the lane gate + turn-start checks -- enforcement never rides on the watcher).
+ *
+ * No-op when worktree-sync is disabled. Never throws: this runs at session start and a broken
+ * repo state must surface as a diagnostic, not a startup crash.
+ */
+export declare function startWorktreeSyncRuntime(config: WorktreeSyncRuntimeConfig): Promise<WorktreeSyncRuntimeHandle>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/core/worktree-sync/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/core/worktree-sync/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAIN,KAAK,sBAAsB,EAC3B,MAAM,iBAAiB,CAAC;AAGzB,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAIvD;iDACiD;AACjD,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAGhG;AAED,MAAM,WAAW,wBAAwB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,eAAe,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,2EAA2E;AAC3E,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,wBAAwB,GAAG,sBAAsB,CAapG;AAED,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IAC1E;+FAC2F;IAC3F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,yBAAyB;IACzC,IAAI,IAAI,IAAI,CAAC;CACb;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA6CpH","sourcesContent":["/**\n * Worktree-sync runtime composition: the pieces main.ts / RuntimeBuilder wire together.\n *\n * The lane binding is an ENVIRONMENT contract: a session launched with `PI_WORKTREE_LANE=<key>`\n * (set by the `--worktree-lane` CLI flag, or directly by any launcher -- tmux panes inherit it\n * from the launch command line) is lane-bound: its file-mutation tools run behind the lane gate\n * (G8/G10) and its epoch watcher injects staleness notices. The env form is deliberate -- it\n * crosses EVERY process boundary (tmux, exec, nested shells) without per-launcher plumbing.\n */\n\nimport { worktreesDir } from \"../agent-paths.ts\";\nimport type { SettingsManager } from \"../settings-manager.ts\";\nimport {\n\tcreateDefaultWorktreeSyncExec,\n\treconcile,\n\tresolveRepoContext,\n\ttype WorktreeSyncEngineDeps,\n} from \"./git-engine.ts\";\nimport { type EpochWatcherHandle, startEpochWatcher } from \"./watcher.ts\";\n\nexport const PI_WORKTREE_LANE_ENV = \"PI_WORKTREE_LANE\";\n\nconst LANE_KEY_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;\n\n/** The lane this process is bound to, from the cross-process env contract. Invalid values are\n * ignored (never a crash on a malformed env). */\nexport function getBoundWorktreeLaneKey(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_WORKTREE_LANE_ENV]?.trim();\n\treturn value && LANE_KEY_RE.test(value) ? value : undefined;\n}\n\nexport interface WorktreeSyncEngineConfig {\n\tcwd: string;\n\tagentDir: string;\n\tsettingsManager: SettingsManager;\n\tsessionId?: string;\n\tsignal?: AbortSignal;\n}\n\n/** Build production engine deps from session facts + resolved settings. */\nexport function buildWorktreeSyncEngineDeps(config: WorktreeSyncEngineConfig): WorktreeSyncEngineDeps {\n\tconst settings = config.settingsManager.getWorktreeSyncSettings();\n\treturn {\n\t\texec: createDefaultWorktreeSyncExec(),\n\t\tcwd: config.cwd,\n\t\tworktreesBaseDir: settings.worktreesRoot ?? worktreesDir(config.agentDir),\n\t\toptions: {\n\t\t\tmaxLanes: settings.maxLanes,\n\t\t\t...(settings.mainBranch !== undefined ? { mainBranchOverride: settings.mainBranch } : {}),\n\t\t},\n\t\t...(config.sessionId !== undefined ? { sessionId: config.sessionId } : {}),\n\t\t...(config.signal !== undefined ? { signal: config.signal } : {}),\n\t};\n}\n\nexport interface WorktreeSyncRuntimeConfig extends WorktreeSyncEngineConfig {\n\t/** Structural notice injection into the running session (host `sendCustomMessage` seam):\n\t * \"steer\" mid-turn, trigger a turn when idle -- the host closure decides the mechanics. */\n\tnotify: (text: string) => void;\n\t/** Diagnostics sink for startup-reconcile findings (never throws into the session). */\n\tonDiagnostic?: (message: string) => void;\n}\n\nexport interface WorktreeSyncRuntimeHandle {\n\tstop(): void;\n}\n\nconst NOOP_HANDLE: WorktreeSyncRuntimeHandle = { stop: () => {} };\n\n/**\n * Start the per-session worktree-sync runtime (main.ts composition root):\n * 1. one startup reconcile pass (registry vs git reality -- orphans marked, lost lanes\n *    re-registered, dead owners cleared, provably-stale lock released), and\n * 2. for a LANE-BOUND session, the epoch watcher: a land anywhere on this machine injects a\n *    deterministic staleness notice into this session promptly (the pull-guaranteed channel is\n *    still the lane gate + turn-start checks -- enforcement never rides on the watcher).\n *\n * No-op when worktree-sync is disabled. Never throws: this runs at session start and a broken\n * repo state must surface as a diagnostic, not a startup crash.\n */\nexport async function startWorktreeSyncRuntime(config: WorktreeSyncRuntimeConfig): Promise<WorktreeSyncRuntimeHandle> {\n\tconst settings = config.settingsManager.getWorktreeSyncSettings();\n\tif (!settings.enabled) return NOOP_HANDLE;\n\tconst deps = buildWorktreeSyncEngineDeps(config);\n\n\ttry {\n\t\tconst reconciled = await reconcile(deps);\n\t\tif (reconciled.code === \"reconciled\") {\n\t\t\tconst findings: string[] = [];\n\t\t\tif (reconciled.orphanedLaneKeys.length > 0)\n\t\t\t\tfindings.push(`orphaned: ${reconciled.orphanedLaneKeys.join(\", \")}`);\n\t\t\tif (reconciled.reRegisteredLaneKeys.length > 0) {\n\t\t\t\tfindings.push(`re-registered: ${reconciled.reRegisteredLaneKeys.join(\", \")}`);\n\t\t\t}\n\t\t\tif (reconciled.staleLockReleased) findings.push(\"released a stale integration lock\");\n\t\t\tif (findings.length > 0) config.onDiagnostic?.(`worktree-sync reconcile: ${findings.join(\"; \")}`);\n\t\t} else if (reconciled.code !== \"not_a_git_repo\" && reconciled.code !== \"default_branch_unresolved\") {\n\t\t\t// Now that the runtime starts in every session, these two codes are benign absence, not a\n\t\t\t// problem to surface: a non-repo cwd, or a repo whose default branch isn't named main/master.\n\t\t\t// Every other refusal still gets a diagnostic.\n\t\t\tconfig.onDiagnostic?.(`worktree-sync reconcile skipped: [${reconciled.code}] ${reconciled.message}`);\n\t\t}\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`worktree-sync reconcile failed: ${error instanceof Error ? error.message : String(error)}`,\n\t\t);\n\t}\n\n\tconst laneKey = getBoundWorktreeLaneKey();\n\tif (!laneKey) return NOOP_HANDLE;\n\n\tlet watcher: EpochWatcherHandle | undefined;\n\ttry {\n\t\tconst ctx = await resolveRepoContext(deps);\n\t\tif (!(\"code\" in ctx)) {\n\t\t\twatcher = startEpochWatcher({\n\t\t\t\tepochFile: ctx.paths.epochFile,\n\t\t\t\tlaneKey,\n\t\t\t\tnotify: config.notify,\n\t\t\t});\n\t\t}\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`worktree-sync watcher failed: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n\treturn { stop: () => watcher?.stop() };\n}\n"]}

package/dist/core/worktree-sync/runtime.js

@@ -0,0 +1,96 @@
+/**
+ * Worktree-sync runtime composition: the pieces main.ts / RuntimeBuilder wire together.
+ *
+ * The lane binding is an ENVIRONMENT contract: a session launched with `PI_WORKTREE_LANE=<key>`
+ * (set by the `--worktree-lane` CLI flag, or directly by any launcher -- tmux panes inherit it
+ * from the launch command line) is lane-bound: its file-mutation tools run behind the lane gate
+ * (G8/G10) and its epoch watcher injects staleness notices. The env form is deliberate -- it
+ * crosses EVERY process boundary (tmux, exec, nested shells) without per-launcher plumbing.
+ */
+import { worktreesDir } from "../agent-paths.js";
+import { createDefaultWorktreeSyncExec, reconcile, resolveRepoContext, } from "./git-engine.js";
+import { startEpochWatcher } from "./watcher.js";
+export const PI_WORKTREE_LANE_ENV = "PI_WORKTREE_LANE";
+const LANE_KEY_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/** The lane this process is bound to, from the cross-process env contract. Invalid values are
+ * ignored (never a crash on a malformed env). */
+export function getBoundWorktreeLaneKey(env = process.env) {
+    const value = env[PI_WORKTREE_LANE_ENV]?.trim();
+    return value && LANE_KEY_RE.test(value) ? value : undefined;
+}
+/** Build production engine deps from session facts + resolved settings. */
+export function buildWorktreeSyncEngineDeps(config) {
+    const settings = config.settingsManager.getWorktreeSyncSettings();
+    return {
+        exec: createDefaultWorktreeSyncExec(),
+        cwd: config.cwd,
+        worktreesBaseDir: settings.worktreesRoot ?? worktreesDir(config.agentDir),
+        options: {
+            maxLanes: settings.maxLanes,
+            ...(settings.mainBranch !== undefined ? { mainBranchOverride: settings.mainBranch } : {}),
+        },
+        ...(config.sessionId !== undefined ? { sessionId: config.sessionId } : {}),
+        ...(config.signal !== undefined ? { signal: config.signal } : {}),
+    };
+}
+const NOOP_HANDLE = { stop: () => { } };
+/**
+ * Start the per-session worktree-sync runtime (main.ts composition root):
+ * 1. one startup reconcile pass (registry vs git reality -- orphans marked, lost lanes
+ *    re-registered, dead owners cleared, provably-stale lock released), and
+ * 2. for a LANE-BOUND session, the epoch watcher: a land anywhere on this machine injects a
+ *    deterministic staleness notice into this session promptly (the pull-guaranteed channel is
+ *    still the lane gate + turn-start checks -- enforcement never rides on the watcher).
+ *
+ * No-op when worktree-sync is disabled. Never throws: this runs at session start and a broken
+ * repo state must surface as a diagnostic, not a startup crash.
+ */
+export async function startWorktreeSyncRuntime(config) {
+    const settings = config.settingsManager.getWorktreeSyncSettings();
+    if (!settings.enabled)
+        return NOOP_HANDLE;
+    const deps = buildWorktreeSyncEngineDeps(config);
+    try {
+        const reconciled = await reconcile(deps);
+        if (reconciled.code === "reconciled") {
+            const findings = [];
+            if (reconciled.orphanedLaneKeys.length > 0)
+                findings.push(`orphaned: ${reconciled.orphanedLaneKeys.join(", ")}`);
+            if (reconciled.reRegisteredLaneKeys.length > 0) {
+                findings.push(`re-registered: ${reconciled.reRegisteredLaneKeys.join(", ")}`);
+            }
+            if (reconciled.staleLockReleased)
+                findings.push("released a stale integration lock");
+            if (findings.length > 0)
+                config.onDiagnostic?.(`worktree-sync reconcile: ${findings.join("; ")}`);
+        }
+        else if (reconciled.code !== "not_a_git_repo" && reconciled.code !== "default_branch_unresolved") {
+            // Now that the runtime starts in every session, these two codes are benign absence, not a
+            // problem to surface: a non-repo cwd, or a repo whose default branch isn't named main/master.
+            // Every other refusal still gets a diagnostic.
+            config.onDiagnostic?.(`worktree-sync reconcile skipped: [${reconciled.code}] ${reconciled.message}`);
+        }
+    }
+    catch (error) {
+        config.onDiagnostic?.(`worktree-sync reconcile failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const laneKey = getBoundWorktreeLaneKey();
+    if (!laneKey)
+        return NOOP_HANDLE;
+    let watcher;
+    try {
+        const ctx = await resolveRepoContext(deps);
+        if (!("code" in ctx)) {
+            watcher = startEpochWatcher({
+                epochFile: ctx.paths.epochFile,
+                laneKey,
+                notify: config.notify,
+            });
+        }
+    }
+    catch (error) {
+        config.onDiagnostic?.(`worktree-sync watcher failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { stop: () => watcher?.stop() };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/core/worktree-sync/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/core/worktree-sync/runtime.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Worktree-sync runtime composition: the pieces main.ts / RuntimeBuilder wire together.\n *\n * The lane binding is an ENVIRONMENT contract: a session launched with `PI_WORKTREE_LANE=<key>`\n * (set by the `--worktree-lane` CLI flag, or directly by any launcher -- tmux panes inherit it\n * from the launch command line) is lane-bound: its file-mutation tools run behind the lane gate\n * (G8/G10) and its epoch watcher injects staleness notices. The env form is deliberate -- it\n * crosses EVERY process boundary (tmux, exec, nested shells) without per-launcher plumbing.\n */\n\nimport { worktreesDir } from \"../agent-paths.ts\";\nimport type { SettingsManager } from \"../settings-manager.ts\";\nimport {\n\tcreateDefaultWorktreeSyncExec,\n\treconcile,\n\tresolveRepoContext,\n\ttype WorktreeSyncEngineDeps,\n} from \"./git-engine.ts\";\nimport { type EpochWatcherHandle, startEpochWatcher } from \"./watcher.ts\";\n\nexport const PI_WORKTREE_LANE_ENV = \"PI_WORKTREE_LANE\";\n\nconst LANE_KEY_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;\n\n/** The lane this process is bound to, from the cross-process env contract. Invalid values are\n * ignored (never a crash on a malformed env). */\nexport function getBoundWorktreeLaneKey(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_WORKTREE_LANE_ENV]?.trim();\n\treturn value && LANE_KEY_RE.test(value) ? value : undefined;\n}\n\nexport interface WorktreeSyncEngineConfig {\n\tcwd: string;\n\tagentDir: string;\n\tsettingsManager: SettingsManager;\n\tsessionId?: string;\n\tsignal?: AbortSignal;\n}\n\n/** Build production engine deps from session facts + resolved settings. */\nexport function buildWorktreeSyncEngineDeps(config: WorktreeSyncEngineConfig): WorktreeSyncEngineDeps {\n\tconst settings = config.settingsManager.getWorktreeSyncSettings();\n\treturn {\n\t\texec: createDefaultWorktreeSyncExec(),\n\t\tcwd: config.cwd,\n\t\tworktreesBaseDir: settings.worktreesRoot ?? worktreesDir(config.agentDir),\n\t\toptions: {\n\t\t\tmaxLanes: settings.maxLanes,\n\t\t\t...(settings.mainBranch !== undefined ? { mainBranchOverride: settings.mainBranch } : {}),\n\t\t},\n\t\t...(config.sessionId !== undefined ? { sessionId: config.sessionId } : {}),\n\t\t...(config.signal !== undefined ? { signal: config.signal } : {}),\n\t};\n}\n\nexport interface WorktreeSyncRuntimeConfig extends WorktreeSyncEngineConfig {\n\t/** Structural notice injection into the running session (host `sendCustomMessage` seam):\n\t * \"steer\" mid-turn, trigger a turn when idle -- the host closure decides the mechanics. */\n\tnotify: (text: string) => void;\n\t/** Diagnostics sink for startup-reconcile findings (never throws into the session). */\n\tonDiagnostic?: (message: string) => void;\n}\n\nexport interface WorktreeSyncRuntimeHandle {\n\tstop(): void;\n}\n\nconst NOOP_HANDLE: WorktreeSyncRuntimeHandle = { stop: () => {} };\n\n/**\n * Start the per-session worktree-sync runtime (main.ts composition root):\n * 1. one startup reconcile pass (registry vs git reality -- orphans marked, lost lanes\n *    re-registered, dead owners cleared, provably-stale lock released), and\n * 2. for a LANE-BOUND session, the epoch watcher: a land anywhere on this machine injects a\n *    deterministic staleness notice into this session promptly (the pull-guaranteed channel is\n *    still the lane gate + turn-start checks -- enforcement never rides on the watcher).\n *\n * No-op when worktree-sync is disabled. Never throws: this runs at session start and a broken\n * repo state must surface as a diagnostic, not a startup crash.\n */\nexport async function startWorktreeSyncRuntime(config: WorktreeSyncRuntimeConfig): Promise<WorktreeSyncRuntimeHandle> {\n\tconst settings = config.settingsManager.getWorktreeSyncSettings();\n\tif (!settings.enabled) return NOOP_HANDLE;\n\tconst deps = buildWorktreeSyncEngineDeps(config);\n\n\ttry {\n\t\tconst reconciled = await reconcile(deps);\n\t\tif (reconciled.code === \"reconciled\") {\n\t\t\tconst findings: string[] = [];\n\t\t\tif (reconciled.orphanedLaneKeys.length > 0)\n\t\t\t\tfindings.push(`orphaned: ${reconciled.orphanedLaneKeys.join(\", \")}`);\n\t\t\tif (reconciled.reRegisteredLaneKeys.length > 0) {\n\t\t\t\tfindings.push(`re-registered: ${reconciled.reRegisteredLaneKeys.join(\", \")}`);\n\t\t\t}\n\t\t\tif (reconciled.staleLockReleased) findings.push(\"released a stale integration lock\");\n\t\t\tif (findings.length > 0) config.onDiagnostic?.(`worktree-sync reconcile: ${findings.join(\"; \")}`);\n\t\t} else if (reconciled.code !== \"not_a_git_repo\" && reconciled.code !== \"default_branch_unresolved\") {\n\t\t\t// Now that the runtime starts in every session, these two codes are benign absence, not a\n\t\t\t// problem to surface: a non-repo cwd, or a repo whose default branch isn't named main/master.\n\t\t\t// Every other refusal still gets a diagnostic.\n\t\t\tconfig.onDiagnostic?.(`worktree-sync reconcile skipped: [${reconciled.code}] ${reconciled.message}`);\n\t\t}\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(\n\t\t\t`worktree-sync reconcile failed: ${error instanceof Error ? error.message : String(error)}`,\n\t\t);\n\t}\n\n\tconst laneKey = getBoundWorktreeLaneKey();\n\tif (!laneKey) return NOOP_HANDLE;\n\n\tlet watcher: EpochWatcherHandle | undefined;\n\ttry {\n\t\tconst ctx = await resolveRepoContext(deps);\n\t\tif (!(\"code\" in ctx)) {\n\t\t\twatcher = startEpochWatcher({\n\t\t\t\tepochFile: ctx.paths.epochFile,\n\t\t\t\tlaneKey,\n\t\t\t\tnotify: config.notify,\n\t\t\t});\n\t\t}\n\t} catch (error) {\n\t\tconfig.onDiagnostic?.(`worktree-sync watcher failed: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n\treturn { stop: () => watcher?.stop() };\n}\n"]}