@caupulican/pi-adaptative 0.81.37 → 0.81.39

package/dist/core/tools/windows-shell-engine.js

@@ -0,0 +1,153 @@
+/**
+ * The `python-engine` tier: per-command spawn of the bundled `pi-shell-engine` (D3 in the
+ * blueprint). Wires the frozen §1.2/§1.3 stdin-JSON-request / 0x1e-framed-stdout protocol into a
+ * `BashOperations`, threads `WindowsShellState` through both directions (D4), and degrades to a
+ * named, actionable error when the Python runtime is not ready — the PowerShell floor keeps
+ * working regardless (the router never routes simple commands here when the engine is off).
+ */
+import { join } from "node:path";
+import { getBundledResourcesDir } from "../../config.js";
+import { spawnProcess, waitForChildProcessWithTermination } from "../../utils/child-process.js";
+import { getShellEnv, trackDetachedChildPid, untrackDetachedChildPid } from "../../utils/shell.js";
+import { ensurePythonRuntime } from "../python-runtime.js";
+import { applyEngineFrame, getOrCreateWindowsShellState, mergeEffectiveEnv, resolveEffectiveCwd, } from "./windows-shell-state.js";
+const ENGINE_FRAME_SENTINEL = 0x1e;
+export class WindowsShellEngineFailure extends Error {
+    capturedOutput;
+    constructor(message, capturedOutput) {
+        super(message);
+        this.name = "WindowsShellEngineFailure";
+        this.capturedOutput = capturedOutput;
+    }
+}
+function resolveEngineScriptPath() {
+    return join(getBundledResourcesDir(), "runtimes", "pi-shell-engine", "main.py");
+}
+const MAX_CONTROL_FRAME_BYTES = 64 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Parse the terminal frame from the dedicated control stream. Command output is never retained here. */
+function parseControlFrame(buffer) {
+    if (buffer.length < 2 || buffer[buffer.length - 1] !== ENGINE_FRAME_SENTINEL)
+        return undefined;
+    const openIndex = buffer.lastIndexOf(ENGINE_FRAME_SENTINEL, buffer.length - 2);
+    if (openIndex === -1)
+        return undefined;
+    try {
+        const raw = JSON.parse(buffer.subarray(openIndex + 1, buffer.length - 1).toString("utf8"));
+        if (!isRecord(raw))
+            return undefined;
+        if (typeof raw.exitCode !== "number" || !Number.isInteger(raw.exitCode))
+            return undefined;
+        if (typeof raw.cwd !== "string" || !isRecord(raw.envDelta))
+            return undefined;
+        if (raw.unsupported !== null && !isRecord(raw.unsupported))
+            return undefined;
+        if (raw.unsupported !== null &&
+            (raw.unsupported.code !== "unsupported" ||
+                typeof raw.unsupported.construct !== "string" ||
+                typeof raw.unsupported.message !== "string"))
+            return undefined;
+        for (const value of Object.values(raw.envDelta)) {
+            if (value !== null && typeof value !== "string")
+                return undefined;
+        }
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
+function degradationError(outcome) {
+    return new Error(`The Windows shell engine (Python) is unavailable: ${outcome.reason} The simple-command PowerShell floor still works; fix the Python runtime (uv/network) to restore pipelines, redirection, expansion, and chaining.`);
+}
+/**
+ * Create the `python-engine` tier `BashOperations` for one bash-tool session. `exec`'s `command`
+ * argument is the RAW Bash source from the `python-engine` route (never PowerShell-translated).
+ */
+export function createWindowsShellEngineOperations(sessionKey, options = {}) {
+    const resolveRuntime = options.resolveRuntime ?? (() => ensurePythonRuntime({ silent: true }));
+    const engineScriptPath = options.engineScriptPath ?? resolveEngineScriptPath();
+    const getState = options.getState ?? getOrCreateWindowsShellState;
+    const spawn = options.spawn ?? spawnProcess;
+    return {
+        async exec(command, cwd, { onData, signal, timeout, env }) {
+            const runtime = await resolveRuntime();
+            if (runtime.status !== "ready")
+                throw degradationError(runtime);
+            const state = getState(sessionKey);
+            const effectiveCwd = resolveEffectiveCwd(state, cwd);
+            const effectiveEnv = mergeEffectiveEnv(state, env ?? getShellEnv());
+            const timeoutMs = timeout !== undefined && timeout > 0 ? timeout * 1000 : undefined;
+            // The engine's own soft deadline must fire and emit its cooperative exit-124 frame (which
+            // preserves partial output) BEFORE the hard tree-kill backstop below, or the hard kill
+            // always wins the race and the soft path never gets to run. Give it a head start; the hard
+            // kill still bounds a hung engine that never reads its own deadline.
+            const requestTimeoutMs = timeoutMs !== undefined ? Math.max(timeoutMs - 500, 500) : undefined;
+            const request = {
+                command,
+                cwd: effectiveCwd,
+                env: effectiveEnv,
+                ...(requestTimeoutMs !== undefined ? { timeoutMs: requestTimeoutMs } : {}),
+            };
+            const child = spawn(runtime.pythonPath, ["-B", engineScriptPath], {
+                cwd: effectiveCwd,
+                env: {
+                    ...effectiveEnv,
+                    PYTHONDONTWRITEBYTECODE: "1",
+                    PYTHONIOENCODING: "utf-8",
+                    PYTHONUNBUFFERED: "1",
+                    PYTHONUTF8: "1",
+                },
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            if (child.pid)
+                trackDetachedChildPid(child.pid);
+            let controlBuffer = Buffer.alloc(0);
+            let controlOverflow = false;
+            // Command output is the data stream: forward it immediately and never retain a
+            // second full copy merely to find the terminal frame.
+            child.stdout?.on("data", (chunk) => {
+                onData(chunk);
+            });
+            // stderr is the bounded control stream. The Python engine routes command stderr
+            // into stdout, so this channel contains only the terminal frame/diagnostics.
+            child.stderr?.on("data", (chunk) => {
+                if (controlOverflow)
+                    return;
+                if (controlBuffer.length + chunk.length > MAX_CONTROL_FRAME_BYTES) {
+                    controlOverflow = true;
+                    return;
+                }
+                controlBuffer = Buffer.concat([controlBuffer, chunk]);
+            });
+            try {
+                child.stdin?.end(JSON.stringify(request), "utf8");
+                const terminal = await waitForChildProcessWithTermination(child, {
+                    signal,
+                    timeoutMs,
+                    killGraceMs: 2_000,
+                });
+                if (signal?.aborted)
+                    throw new Error("aborted");
+                const frame = controlOverflow ? undefined : parseControlFrame(controlBuffer);
+                if (!frame) {
+                    const capturedOutput = controlOverflow
+                        ? `control frame exceeded ${MAX_CONTROL_FRAME_BYTES} bytes`
+                        : controlBuffer.toString("utf8");
+                    throw new WindowsShellEngineFailure(`Windows shell engine failed (process exit ${terminal.code ?? "null"}) without a parseable control frame.\n${capturedOutput}`, capturedOutput);
+                }
+                applyEngineFrame(state, frame);
+                if (frame.unsupported)
+                    throw new Error(frame.unsupported.message);
+                return { exitCode: frame.exitCode };
+            }
+            finally {
+                if (child.pid)
+                    untrackDetachedChildPid(child.pid);
+            }
+        },
+    };
+}
+//# sourceMappingURL=windows-shell-engine.js.map

package/dist/core/tools/windows-shell-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-shell-engine.js","sourceRoot":"","sources":["../../../src/core/tools/windows-shell-engine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `python-engine` tier: per-command spawn of the bundled `pi-shell-engine` (D3 in the\n * blueprint). Wires the frozen §1.2/§1.3 stdin-JSON-request / 0x1e-framed-stdout protocol into a\n * `BashOperations`, threads `WindowsShellState` through both directions (D4), and degrades to a\n * named, actionable error when the Python runtime is not ready — the PowerShell floor keeps\n * working regardless (the router never routes simple commands here when the engine is off).\n */\n\nimport type { ChildProcess, SpawnOptions } from \"node:child_process\";\nimport { join } from \"node:path\";\nimport { getBundledResourcesDir } from \"../../config.ts\";\nimport { spawnProcess, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport { getShellEnv, trackDetachedChildPid, untrackDetachedChildPid } from \"../../utils/shell.ts\";\nimport { ensurePythonRuntime, type PythonRuntimeOutcome } from \"../python-runtime.ts\";\nimport type { BashOperations } from \"./bash.ts\";\nimport {\n\tapplyEngineFrame,\n\tgetOrCreateWindowsShellState,\n\tmergeEffectiveEnv,\n\tresolveEffectiveCwd,\n\ttype WindowsShellState,\n} from \"./windows-shell-state.ts\";\n\nconst ENGINE_FRAME_SENTINEL = 0x1e;\n\n/** The full §1.3 control-frame shape. */\nexport interface WindowsShellEngineFrame {\n\texitCode: number;\n\tcwd: string;\n\tenvDelta: Record<string, string | null>;\n\tunsupported: { code: \"unsupported\"; construct: string; message: string } | null;\n}\n\nexport class WindowsShellEngineFailure extends Error {\n\treadonly capturedOutput: string;\n\n\tconstructor(message: string, capturedOutput: string) {\n\t\tsuper(message);\n\t\tthis.name = \"WindowsShellEngineFailure\";\n\t\tthis.capturedOutput = capturedOutput;\n\t}\n}\n\nfunction resolveEngineScriptPath(): string {\n\treturn join(getBundledResourcesDir(), \"runtimes\", \"pi-shell-engine\", \"main.py\");\n}\n\nconst MAX_CONTROL_FRAME_BYTES = 64 * 1024;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Parse the terminal frame from the dedicated control stream. Command output is never retained here. */\nfunction parseControlFrame(buffer: Buffer): WindowsShellEngineFrame | undefined {\n\tif (buffer.length < 2 || buffer[buffer.length - 1] !== ENGINE_FRAME_SENTINEL) return undefined;\n\tconst openIndex = buffer.lastIndexOf(ENGINE_FRAME_SENTINEL, buffer.length - 2);\n\tif (openIndex === -1) return undefined;\n\ttry {\n\t\tconst raw: unknown = JSON.parse(buffer.subarray(openIndex + 1, buffer.length - 1).toString(\"utf8\"));\n\t\tif (!isRecord(raw)) return undefined;\n\t\tif (typeof raw.exitCode !== \"number\" || !Number.isInteger(raw.exitCode)) return undefined;\n\t\tif (typeof raw.cwd !== \"string\" || !isRecord(raw.envDelta)) return undefined;\n\t\tif (raw.unsupported !== null && !isRecord(raw.unsupported)) return undefined;\n\t\tif (\n\t\t\traw.unsupported !== null &&\n\t\t\t(raw.unsupported.code !== \"unsupported\" ||\n\t\t\t\ttypeof raw.unsupported.construct !== \"string\" ||\n\t\t\t\ttypeof raw.unsupported.message !== \"string\")\n\t\t)\n\t\t\treturn undefined;\n\t\tfor (const value of Object.values(raw.envDelta)) {\n\t\t\tif (value !== null && typeof value !== \"string\") return undefined;\n\t\t}\n\t\treturn raw as unknown as WindowsShellEngineFrame;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nexport interface WindowsShellEngineOptions {\n\t/** Override for tests: resolves the Python runtime outcome. Default: `ensurePythonRuntime`. */\n\tresolveRuntime?: () => Promise<PythonRuntimeOutcome>;\n\t/** Override for tests: absolute path to the engine's `main.py`. Default: the bundled runtime. */\n\tengineScriptPath?: string;\n\t/** Override for tests: the per-session state store lookup. Default: the shared module store. */\n\tgetState?: (sessionKey: string) => WindowsShellState;\n\t/** Override for tests: spawns the engine child process. Default: `spawnProcess` (cross-spawn on win32). */\n\tspawn?: (command: string, args: string[], options: SpawnOptions) => ChildProcess;\n}\n\nfunction degradationError(\n\toutcome: Extract<PythonRuntimeOutcome, { status: \"offline\" | \"uv-unavailable\" | \"python-unavailable\" }>,\n) {\n\treturn new Error(\n\t\t`The Windows shell engine (Python) is unavailable: ${outcome.reason} The simple-command PowerShell floor still works; fix the Python runtime (uv/network) to restore pipelines, redirection, expansion, and chaining.`,\n\t);\n}\n\n/**\n * Create the `python-engine` tier `BashOperations` for one bash-tool session. `exec`'s `command`\n * argument is the RAW Bash source from the `python-engine` route (never PowerShell-translated).\n */\nexport function createWindowsShellEngineOperations(\n\tsessionKey: string,\n\toptions: WindowsShellEngineOptions = {},\n): BashOperations {\n\tconst resolveRuntime = options.resolveRuntime ?? (() => ensurePythonRuntime({ silent: true }));\n\tconst engineScriptPath = options.engineScriptPath ?? resolveEngineScriptPath();\n\tconst getState = options.getState ?? getOrCreateWindowsShellState;\n\tconst spawn = options.spawn ?? spawnProcess;\n\n\treturn {\n\t\tasync exec(command, cwd, { onData, signal, timeout, env }) {\n\t\t\tconst runtime = await resolveRuntime();\n\t\t\tif (runtime.status !== \"ready\") throw degradationError(runtime);\n\n\t\t\tconst state = getState(sessionKey);\n\t\t\tconst effectiveCwd = resolveEffectiveCwd(state, cwd);\n\t\t\tconst effectiveEnv = mergeEffectiveEnv(state, env ?? getShellEnv());\n\t\t\tconst timeoutMs = timeout !== undefined && timeout > 0 ? timeout * 1000 : undefined;\n\t\t\t// The engine's own soft deadline must fire and emit its cooperative exit-124 frame (which\n\t\t\t// preserves partial output) BEFORE the hard tree-kill backstop below, or the hard kill\n\t\t\t// always wins the race and the soft path never gets to run. Give it a head start; the hard\n\t\t\t// kill still bounds a hung engine that never reads its own deadline.\n\t\t\tconst requestTimeoutMs = timeoutMs !== undefined ? Math.max(timeoutMs - 500, 500) : undefined;\n\n\t\t\tconst request = {\n\t\t\t\tcommand,\n\t\t\t\tcwd: effectiveCwd,\n\t\t\t\tenv: effectiveEnv,\n\t\t\t\t...(requestTimeoutMs !== undefined ? { timeoutMs: requestTimeoutMs } : {}),\n\t\t\t};\n\n\t\t\tconst child = spawn(runtime.pythonPath, [\"-B\", engineScriptPath], {\n\t\t\t\tcwd: effectiveCwd,\n\t\t\t\tenv: {\n\t\t\t\t\t...effectiveEnv,\n\t\t\t\t\tPYTHONDONTWRITEBYTECODE: \"1\",\n\t\t\t\t\tPYTHONIOENCODING: \"utf-8\",\n\t\t\t\t\tPYTHONUNBUFFERED: \"1\",\n\t\t\t\t\tPYTHONUTF8: \"1\",\n\t\t\t\t},\n\t\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\t});\n\t\t\tif (child.pid) trackDetachedChildPid(child.pid);\n\n\t\t\tlet controlBuffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);\n\t\t\tlet controlOverflow = false;\n\n\t\t\t// Command output is the data stream: forward it immediately and never retain a\n\t\t\t// second full copy merely to find the terminal frame.\n\t\t\tchild.stdout?.on(\"data\", (chunk: Buffer) => {\n\t\t\t\tonData(chunk);\n\t\t\t});\n\t\t\t// stderr is the bounded control stream. The Python engine routes command stderr\n\t\t\t// into stdout, so this channel contains only the terminal frame/diagnostics.\n\t\t\tchild.stderr?.on(\"data\", (chunk: Buffer) => {\n\t\t\t\tif (controlOverflow) return;\n\t\t\t\tif (controlBuffer.length + chunk.length > MAX_CONTROL_FRAME_BYTES) {\n\t\t\t\t\tcontrolOverflow = true;\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tcontrolBuffer = Buffer.concat([controlBuffer, chunk]);\n\t\t\t});\n\n\t\t\ttry {\n\t\t\t\tchild.stdin?.end(JSON.stringify(request), \"utf8\");\n\t\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\t\tsignal,\n\t\t\t\t\ttimeoutMs,\n\t\t\t\t\tkillGraceMs: 2_000,\n\t\t\t\t});\n\t\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\n\t\t\t\tconst frame = controlOverflow ? undefined : parseControlFrame(controlBuffer);\n\t\t\t\tif (!frame) {\n\t\t\t\t\tconst capturedOutput = controlOverflow\n\t\t\t\t\t\t? `control frame exceeded ${MAX_CONTROL_FRAME_BYTES} bytes`\n\t\t\t\t\t\t: controlBuffer.toString(\"utf8\");\n\t\t\t\t\tthrow new WindowsShellEngineFailure(\n\t\t\t\t\t\t`Windows shell engine failed (process exit ${terminal.code ?? \"null\"}) without a parseable control frame.\\n${capturedOutput}`,\n\t\t\t\t\t\tcapturedOutput,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tapplyEngineFrame(state, frame);\n\t\t\t\tif (frame.unsupported) throw new Error(frame.unsupported.message);\n\t\t\t\treturn { exitCode: frame.exitCode };\n\t\t\t} finally {\n\t\t\t\tif (child.pid) untrackDetachedChildPid(child.pid);\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/core/tools/windows-shell-state.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-session Windows shell-engine state (D4 — the engine is the sole state mutator).
+ *
+ * `cwd`/`envDelta` are threaded into every `python-engine` invocation and updated from the
+ * engine's control frame after each run; the PS tier consumes the same state through the
+ * EXISTING `shell-session.ts` seams (`lastRequestedCwd` re-entry, `shallowEnvEquals` respawn).
+ * This module owns no process/spawn logic — it is pure state carriage.
+ */
+export interface WindowsShellState {
+    cwd: string;
+    /** Host-requested cwd used to detect an intentional caller cwd change. */
+    hostCwd?: string;
+    envDelta: Record<string, string | null>;
+}
+/** The engine control-frame shape this module consumes (subset of the full §1.3 frame). */
+export interface EngineFrameState {
+    cwd: string;
+    envDelta: Record<string, string | null>;
+}
+/** Get or lazily create the per-session-key Windows shell state. */
+export declare function getOrCreateWindowsShellState(sessionKey: string): WindowsShellState;
+/** Drop a session's engine state (agent teardown). Safe to call for keys that never ran. */
+export declare function disposeWindowsShellState(sessionKey: string): void;
+/**
+ * Fold an engine control frame into the session state: `cwd` is set verbatim; `envDelta` entries
+ * apply string => set, `null` => delete (§1.3).
+ */
+export declare function applyEngineFrame(state: WindowsShellState, frame: EngineFrameState): void;
+/**
+ * The cwd a NEXT call (engine or PS tier) must use: the state-adjusted cwd once the engine has run
+ * at least one `cd`, otherwise the host-requested cwd. Both tiers call this with the SAME session
+ * state so a `cd` in the engine is observed by the very next PS-tier call.
+ */
+export declare function resolveEffectiveCwd(state: WindowsShellState, requestedCwd: string): string;
+/**
+ * The env a NEXT call (engine or PS tier) must use: the base env plus every `export`/`unset` the
+ * engine has applied so far.
+ */
+export declare function mergeEffectiveEnv(state: WindowsShellState, baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//# sourceMappingURL=windows-shell-state.d.ts.map

package/dist/core/tools/windows-shell-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-shell-state.d.ts","sourceRoot":"","sources":["../../../src/core/tools/windows-shell-state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACxC;AAED,4FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACxC;AAID,oEAAoE;AACpE,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAOlF;AAED,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAEjE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAKxF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAOzG","sourcesContent":["/**\n * Per-session Windows shell-engine state (D4 — the engine is the sole state mutator).\n *\n * `cwd`/`envDelta` are threaded into every `python-engine` invocation and updated from the\n * engine's control frame after each run; the PS tier consumes the same state through the\n * EXISTING `shell-session.ts` seams (`lastRequestedCwd` re-entry, `shallowEnvEquals` respawn).\n * This module owns no process/spawn logic — it is pure state carriage.\n */\n\nexport interface WindowsShellState {\n\tcwd: string;\n\t/** Host-requested cwd used to detect an intentional caller cwd change. */\n\thostCwd?: string;\n\tenvDelta: Record<string, string | null>;\n}\n\n/** The engine control-frame shape this module consumes (subset of the full §1.3 frame). */\nexport interface EngineFrameState {\n\tcwd: string;\n\tenvDelta: Record<string, string | null>;\n}\n\nconst windowsShellStates = new Map<string, WindowsShellState>();\n\n/** Get or lazily create the per-session-key Windows shell state. */\nexport function getOrCreateWindowsShellState(sessionKey: string): WindowsShellState {\n\tlet state = windowsShellStates.get(sessionKey);\n\tif (!state) {\n\t\tstate = { cwd: \"\", envDelta: {} };\n\t\twindowsShellStates.set(sessionKey, state);\n\t}\n\treturn state;\n}\n\n/** Drop a session's engine state (agent teardown). Safe to call for keys that never ran. */\nexport function disposeWindowsShellState(sessionKey: string): void {\n\twindowsShellStates.delete(sessionKey);\n}\n\n/**\n * Fold an engine control frame into the session state: `cwd` is set verbatim; `envDelta` entries\n * apply string => set, `null` => delete (§1.3).\n */\nexport function applyEngineFrame(state: WindowsShellState, frame: EngineFrameState): void {\n\tstate.cwd = frame.cwd;\n\tfor (const [key, value] of Object.entries(frame.envDelta)) {\n\t\tstate.envDelta[key] = value;\n\t}\n}\n\n/**\n * The cwd a NEXT call (engine or PS tier) must use: the state-adjusted cwd once the engine has run\n * at least one `cd`, otherwise the host-requested cwd. Both tiers call this with the SAME session\n * state so a `cd` in the engine is observed by the very next PS-tier call.\n */\nexport function resolveEffectiveCwd(state: WindowsShellState, requestedCwd: string): string {\n\tif (state.hostCwd !== requestedCwd) {\n\t\tstate.hostCwd = requestedCwd;\n\t\tstate.cwd = requestedCwd;\n\t}\n\treturn state.cwd;\n}\n\n/**\n * The env a NEXT call (engine or PS tier) must use: the base env plus every `export`/`unset` the\n * engine has applied so far.\n */\nexport function mergeEffectiveEnv(state: WindowsShellState, baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv {\n\tconst merged: NodeJS.ProcessEnv = { ...baseEnv };\n\tfor (const [key, value] of Object.entries(state.envDelta)) {\n\t\tif (value === null) delete merged[key];\n\t\telse merged[key] = value;\n\t}\n\treturn merged;\n}\n"]}

package/dist/core/tools/windows-shell-state.js

@@ -0,0 +1,59 @@
+/**
+ * Per-session Windows shell-engine state (D4 — the engine is the sole state mutator).
+ *
+ * `cwd`/`envDelta` are threaded into every `python-engine` invocation and updated from the
+ * engine's control frame after each run; the PS tier consumes the same state through the
+ * EXISTING `shell-session.ts` seams (`lastRequestedCwd` re-entry, `shallowEnvEquals` respawn).
+ * This module owns no process/spawn logic — it is pure state carriage.
+ */
+const windowsShellStates = new Map();
+/** Get or lazily create the per-session-key Windows shell state. */
+export function getOrCreateWindowsShellState(sessionKey) {
+    let state = windowsShellStates.get(sessionKey);
+    if (!state) {
+        state = { cwd: "", envDelta: {} };
+        windowsShellStates.set(sessionKey, state);
+    }
+    return state;
+}
+/** Drop a session's engine state (agent teardown). Safe to call for keys that never ran. */
+export function disposeWindowsShellState(sessionKey) {
+    windowsShellStates.delete(sessionKey);
+}
+/**
+ * Fold an engine control frame into the session state: `cwd` is set verbatim; `envDelta` entries
+ * apply string => set, `null` => delete (§1.3).
+ */
+export function applyEngineFrame(state, frame) {
+    state.cwd = frame.cwd;
+    for (const [key, value] of Object.entries(frame.envDelta)) {
+        state.envDelta[key] = value;
+    }
+}
+/**
+ * The cwd a NEXT call (engine or PS tier) must use: the state-adjusted cwd once the engine has run
+ * at least one `cd`, otherwise the host-requested cwd. Both tiers call this with the SAME session
+ * state so a `cd` in the engine is observed by the very next PS-tier call.
+ */
+export function resolveEffectiveCwd(state, requestedCwd) {
+    if (state.hostCwd !== requestedCwd) {
+        state.hostCwd = requestedCwd;
+        state.cwd = requestedCwd;
+    }
+    return state.cwd;
+}
+/**
+ * The env a NEXT call (engine or PS tier) must use: the base env plus every `export`/`unset` the
+ * engine has applied so far.
+ */
+export function mergeEffectiveEnv(state, baseEnv) {
+    const merged = { ...baseEnv };
+    for (const [key, value] of Object.entries(state.envDelta)) {
+        if (value === null)
+            delete merged[key];
+        else
+            merged[key] = value;
+    }
+    return merged;
+}
+//# sourceMappingURL=windows-shell-state.js.map

package/dist/core/tools/windows-shell-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-shell-state.js","sourceRoot":"","sources":["../../../src/core/tools/windows-shell-state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA6B,CAAC;AAEhE,oEAAoE;AACpE,MAAM,UAAU,4BAA4B,CAAC,UAAkB,EAAqB;IACnF,IAAI,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,KAAK,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAClC,kBAAkB,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAED,4FAA4F;AAC5F,MAAM,UAAU,wBAAwB,CAAC,UAAkB,EAAQ;IAClE,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AAAA,CACtC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwB,EAAE,KAAuB,EAAQ;IACzF,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC7B,CAAC;AAAA,CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAwB,EAAE,YAAoB,EAAU;IAC3F,IAAI,KAAK,CAAC,OAAO,KAAK,YAAY,EAAE,CAAC;QACpC,KAAK,CAAC,OAAO,GAAG,YAAY,CAAC;QAC7B,KAAK,CAAC,GAAG,GAAG,YAAY,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC;AAAA,CACjB;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAwB,EAAE,OAA0B,EAAqB;IAC1G,MAAM,MAAM,GAAsB,EAAE,GAAG,OAAO,EAAE,CAAC;IACjD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["/**\n * Per-session Windows shell-engine state (D4 — the engine is the sole state mutator).\n *\n * `cwd`/`envDelta` are threaded into every `python-engine` invocation and updated from the\n * engine's control frame after each run; the PS tier consumes the same state through the\n * EXISTING `shell-session.ts` seams (`lastRequestedCwd` re-entry, `shallowEnvEquals` respawn).\n * This module owns no process/spawn logic — it is pure state carriage.\n */\n\nexport interface WindowsShellState {\n\tcwd: string;\n\t/** Host-requested cwd used to detect an intentional caller cwd change. */\n\thostCwd?: string;\n\tenvDelta: Record<string, string | null>;\n}\n\n/** The engine control-frame shape this module consumes (subset of the full §1.3 frame). */\nexport interface EngineFrameState {\n\tcwd: string;\n\tenvDelta: Record<string, string | null>;\n}\n\nconst windowsShellStates = new Map<string, WindowsShellState>();\n\n/** Get or lazily create the per-session-key Windows shell state. */\nexport function getOrCreateWindowsShellState(sessionKey: string): WindowsShellState {\n\tlet state = windowsShellStates.get(sessionKey);\n\tif (!state) {\n\t\tstate = { cwd: \"\", envDelta: {} };\n\t\twindowsShellStates.set(sessionKey, state);\n\t}\n\treturn state;\n}\n\n/** Drop a session's engine state (agent teardown). Safe to call for keys that never ran. */\nexport function disposeWindowsShellState(sessionKey: string): void {\n\twindowsShellStates.delete(sessionKey);\n}\n\n/**\n * Fold an engine control frame into the session state: `cwd` is set verbatim; `envDelta` entries\n * apply string => set, `null` => delete (§1.3).\n */\nexport function applyEngineFrame(state: WindowsShellState, frame: EngineFrameState): void {\n\tstate.cwd = frame.cwd;\n\tfor (const [key, value] of Object.entries(frame.envDelta)) {\n\t\tstate.envDelta[key] = value;\n\t}\n}\n\n/**\n * The cwd a NEXT call (engine or PS tier) must use: the state-adjusted cwd once the engine has run\n * at least one `cd`, otherwise the host-requested cwd. Both tiers call this with the SAME session\n * state so a `cd` in the engine is observed by the very next PS-tier call.\n */\nexport function resolveEffectiveCwd(state: WindowsShellState, requestedCwd: string): string {\n\tif (state.hostCwd !== requestedCwd) {\n\t\tstate.hostCwd = requestedCwd;\n\t\tstate.cwd = requestedCwd;\n\t}\n\treturn state.cwd;\n}\n\n/**\n * The env a NEXT call (engine or PS tier) must use: the base env plus every `export`/`unset` the\n * engine has applied so far.\n */\nexport function mergeEffectiveEnv(state: WindowsShellState, baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv {\n\tconst merged: NodeJS.ProcessEnv = { ...baseEnv };\n\tfor (const [key, value] of Object.entries(state.envDelta)) {\n\t\tif (value === null) delete merged[key];\n\t\telse merged[key] = value;\n\t}\n\treturn merged;\n}\n"]}

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

@@ -0,0 +1,24 @@
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+import type { ResolvedWorktreeSyncSettings } from "../settings-manager.ts";
+import { type WorktreeSyncEngineDeps } from "../worktree-sync/git-engine.ts";
+declare const worktreeSyncSchema: Type.TObject<{
+    action: Type.TUnion<[Type.TLiteral<"status">, Type.TLiteral<"git_status">, Type.TLiteral<"git_diff">, Type.TLiteral<"git_add">, Type.TLiteral<"git_commit">, Type.TLiteral<"check">, Type.TLiteral<"create_lane">, Type.TLiteral<"sync">, Type.TLiteral<"continue">, Type.TLiteral<"abort_sync">, Type.TLiteral<"land">, Type.TLiteral<"release_lane">, Type.TLiteral<"reconcile">]>;
+    laneKey: Type.TOptional<Type.TString>;
+    goalId: Type.TOptional<Type.TString>;
+    requirementId: Type.TOptional<Type.TString>;
+    paths: Type.TOptional<Type.TArray<Type.TString>>;
+    message: Type.TOptional<Type.TString>;
+    confirm: Type.TOptional<Type.TString>;
+}>;
+export type WorktreeSyncToolInput = Static<typeof worktreeSyncSchema>;
+export interface WorktreeSyncToolDeps {
+    engineDeps: () => WorktreeSyncEngineDeps;
+    settings: () => ResolvedWorktreeSyncSettings;
+    boundLaneKey: () => string | undefined;
+    /** True iff this is a worker session (see session-role.ts) -- narrows the action surface below. */
+    isWorker: () => boolean;
+}
+export declare function createWorktreeSyncToolDefinition(deps: WorktreeSyncToolDeps): ToolDefinition;
+export {};
+//# sourceMappingURL=worktree-sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-sync.d.ts","sourceRoot":"","sources":["../../../src/core/tools/worktree-sync.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AAE3E,OAAO,EAUN,KAAK,sBAAsB,EAC3B,MAAM,gCAAgC,CAAC;AA8DxC,QAAA,MAAM,kBAAkB;;;;;;;;EAA6B,CAAC;AAEtD,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,sBAAsB,CAAC;IACzC,QAAQ,EAAE,MAAM,4BAA4B,CAAC;IAC7C,YAAY,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACvC,mGAAmG;IACnG,QAAQ,EAAE,MAAM,OAAO,CAAC;CACxB;AAgED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,oBAAoB,GAAG,cAAc,CAiQ3F","sourcesContent":["import { isAbsolute, relative } from \"node:path\";\nimport { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport type { ResolvedWorktreeSyncSettings } from \"../settings-manager.ts\";\nimport type { ConflictWorklist, SyncStatus } from \"../worktree-sync/codes.ts\";\nimport {\n\tabortSync,\n\tbuildSyncStatus,\n\tcontinueSync,\n\tcreateLane,\n\tlandLane,\n\treconcile,\n\treleaseLane,\n\tresolveRepoContext,\n\tsyncLane,\n\ttype WorktreeSyncEngineDeps,\n} from \"../worktree-sync/git-engine.ts\";\nimport { resolveLaneMutationPath } from \"../worktree-sync/lane-gate.ts\";\nimport { readLane } from \"../worktree-sync/store.ts\";\n\n/**\n * `worktree_sync` -- the ENTIRE agent-facing surface of the worktree-per-lane workflow: a closed\n * action set over the engine (`core/worktree-sync/git-engine.ts`) so agents never improvise git\n * ceremony. Every outcome carries a tagged code in `details`; refusal text always names the exact\n * recovery step. See docs/worktree-sync.md for the workflow and the G1-G11 gate table.\n */\n\nfunction createWorktreeSyncSchema() {\n\treturn Type.Object(\n\t\t{\n\t\t\taction: Type.Union(\n\t\t\t\t[\n\t\t\t\t\tType.Literal(\"status\"),\n\t\t\t\t\tType.Literal(\"git_status\"),\n\t\t\t\t\tType.Literal(\"git_diff\"),\n\t\t\t\t\tType.Literal(\"git_add\"),\n\t\t\t\t\tType.Literal(\"git_commit\"),\n\t\t\t\t\tType.Literal(\"check\"),\n\t\t\t\t\tType.Literal(\"create_lane\"),\n\t\t\t\t\tType.Literal(\"sync\"),\n\t\t\t\t\tType.Literal(\"continue\"),\n\t\t\t\t\tType.Literal(\"abort_sync\"),\n\t\t\t\t\tType.Literal(\"land\"),\n\t\t\t\t\tType.Literal(\"release_lane\"),\n\t\t\t\t\tType.Literal(\"reconcile\"),\n\t\t\t\t],\n\t\t\t\t{\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"status: the deterministic full picture (epoch, hub, lock, per-lane freshness/staleness, advice). git_status/git_diff: read the bound lane with fixed argv. git_add: stage only explicitly validated paths inside the lane. git_commit: commit with a literal message. check: run only the owner-configured trusted check command. create_lane: new worktree+branch off main. sync: rebase current main into a lane (conflicts return a worklist and leave the rebase in progress). continue: verify resolved conflicts (zero markers, mechanically checked), stage, drive on. abort_sync: abort the in-progress rebase. land: the ONLY door to main -- serialized, freshness-checked, gate-command-verified, ff-only. release_lane: remove a fully-landed lane (discarding unlanded work needs confirm). reconcile: re-sync the registry with git reality.\",\n\t\t\t\t},\n\t\t\t),\n\t\t\tlaneKey: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t\"Target lane. Defaults to this session's bound lane (PI_WORKTREE_LANE) for sync/continue/abort_sync/land.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tgoalId: Type.Optional(\n\t\t\t\tType.String({ description: \"create_lane: goal to scope the auto-allocated lane key by.\" }),\n\t\t\t),\n\t\t\trequirementId: Type.Optional(Type.String({ description: \"create_lane: requirement this lane will work.\" })),\n\t\t\tpaths: Type.Optional(\n\t\t\t\tType.Array(Type.String(), {\n\t\t\t\t\tdescription: \"git_diff/git_add: explicit relative paths inside the bound lane.\",\n\t\t\t\t}),\n\t\t\t),\n\t\t\tmessage: Type.Optional(Type.String({ description: \"git_commit: literal commit message.\" })),\n\t\t\tconfirm: Type.Optional(\n\t\t\t\tType.String({\n\t\t\t\t\tdescription:\n\t\t\t\t\t\t'release_lane: pass exactly \"yes-discard-lane\" to release a lane that still has unlanded commits or dirty files (G11: never silent).',\n\t\t\t\t}),\n\t\t\t),\n\t\t},\n\t\t{ additionalProperties: false },\n\t);\n}\n\nconst worktreeSyncSchema = createWorktreeSyncSchema();\n\nexport type WorktreeSyncToolInput = Static<typeof worktreeSyncSchema>;\n\nexport interface WorktreeSyncToolDeps {\n\tengineDeps: () => WorktreeSyncEngineDeps;\n\tsettings: () => ResolvedWorktreeSyncSettings;\n\tboundLaneKey: () => string | undefined;\n\t/** True iff this is a worker session (see session-role.ts) -- narrows the action surface below. */\n\tisWorker: () => boolean;\n}\n\n/** Actions a worker session may run unconditionally -- read-only status plus the sync/conflict\n * cycle on its own bound lane. Everything else is refused as `role_forbidden`, EXCEPT `land`,\n * which is instead gated by the `worktreeSync.workerLand` setting (still subject to normal\n * ownership/freshness gating downstream when allowed). */\nconst WORKER_ALLOWED_ACTIONS: ReadonlySet<WorktreeSyncToolInput[\"action\"]> = new Set([\n\t\"status\",\n\t\"git_status\",\n\t\"git_diff\",\n\t\"git_add\",\n\t\"git_commit\",\n\t\"check\",\n\t\"sync\",\n\t\"continue\",\n\t\"abort_sync\",\n]);\n\nfunction formatWorklist(worklist: ConflictWorklist): string[] {\n\tconst lines = [\n\t\t`Conflicts at rebase step ${worklist.step}${worklist.stoppedAtCommit ? ` (replaying ${worklist.stoppedAtCommit.sha.slice(0, 12)}: ${worklist.stoppedAtCommit.subject})` : \"\"}:`,\n\t];\n\tfor (const file of worklist.files) {\n\t\tlines.push(`- ${file.path} [${file.kind}]`);\n\t}\n\tlines.push(\n\t\t'Resolve the zdiff3 hunks in exactly these files (base section included), save, then call {\"action\":\"continue\"}. Staging and marker verification are automatic.',\n\t);\n\treturn lines;\n}\n\nfunction formatStatus(status: SyncStatus): string[] {\n\tconst lines = [\n\t\t`epoch ${status.epoch} | main ${status.mainBranch}@${status.mainSha.slice(0, 12)}` +\n\t\t\t`${status.hub ? ` | hub ${status.hub.clean ? \"clean\" : \"has local changes\"}` : \" | hub: main not checked out\"}` +\n\t\t\t`${status.lock.held ? ` | LOCK held by pid ${status.lock.holder?.pid ?? \"?\"}` : \"\"}`,\n\t];\n\tfor (const lane of status.lanes) {\n\t\tconst flags = [\n\t\t\tlane.registrationStatus !== \"active\" ? lane.registrationStatus : undefined,\n\t\t\tlane.rebaseInProgress ? \"REBASE-IN-PROGRESS\" : undefined,\n\t\t\tlane.syncRequired ? \"SYNC-REQUIRED\" : lane.stale ? \"stale\" : \"fresh\",\n\t\t\tlane.dirty ? \"dirty\" : undefined,\n\t\t]\n\t\t\t.filter(Boolean)\n\t\t\t.join(\", \");\n\t\tlines.push(\n\t\t\t`- ${lane.laneKey} (${lane.branch}) +${lane.aheadOfMain}/-${lane.behindMain} [${flags}]` +\n\t\t\t\t`${lane.overlapWithLastLand.length > 0 ? ` overlap: ${lane.overlapWithLastLand.slice(0, 5).join(\", \")}` : \"\"}`,\n\t\t);\n\t}\n\tif (status.lanes.length === 0) lines.push(\"(no lanes)\");\n\tif (status.advice) lines.push(`advice: ${status.advice}`);\n\treturn lines;\n}\n\nconst WORKTREE_SYNC_PROMPT_GUIDELINES = [\n\t\"Work ONLY inside your lane worktree on your lane branch; never edit the hub checkout or touch main directly -- main moves exclusively through the land action.\",\n\t\"Commit your work on the lane branch, then land. Landing is refused while the lane is stale (G3): call sync first, resolve conflicts locally, then land.\",\n\t\"When a sync stops on conflicts, edit exactly the listed files, then call continue -- staging, marker verification, and rebase continuation are mechanical.\",\n\t\"After any other lane lands, your lane becomes stale; under the mandatory policy your file mutations are refused until you sync. git add/commit stay available to save WIP first.\",\n\t\"Check status when unsure -- it is the deterministic full picture; never infer sync state from raw git output.\",\n];\n\nexport function createWorktreeSyncToolDefinition(deps: WorktreeSyncToolDeps): ToolDefinition {\n\treturn {\n\t\tname: \"worktree_sync\",\n\t\tlabel: \"worktree_sync\",\n\t\tdescription:\n\t\t\t\"Hard-gated worktree-per-lane parallel work: each agent works in its own git worktree/branch; integration is always rebase-onto-main + ff-only land, serialized under one integration lock with the gate command verified at the exact landing tip. status/create_lane/sync/continue/abort_sync/land/release_lane/reconcile. Every outcome is a tagged code with the exact recovery step; landing while stale is structurally impossible.\",\n\t\tpromptSnippet: \"Coordinate parallel work: lane worktrees, rebase-onto-main sync, serialized gated landing.\",\n\t\tpromptGuidelines: WORKTREE_SYNC_PROMPT_GUIDELINES,\n\t\tparameters: worktreeSyncSchema,\n\t\texecutionMode: \"sequential\",\n\t\tasync execute(_toolCallId, input: WorktreeSyncToolInput, signal) {\n\t\t\tconst engineDeps: WorktreeSyncEngineDeps = { ...deps.engineDeps(), ...(signal ? { signal } : {}) };\n\t\t\tconst settings = deps.settings();\n\t\t\tconst laneKey = input.laneKey ?? deps.boundLaneKey();\n\n\t\t\tconst respond = (lines: string[], details: unknown) => ({\n\t\t\t\tcontent: [{ type: \"text\" as const, text: lines.join(\"\\n\") }],\n\t\t\t\tdetails: details as Record<string, unknown>,\n\t\t\t});\n\t\t\tconst needLane = (): string | undefined => {\n\t\t\t\tif (laneKey) return undefined;\n\t\t\t\treturn \"laneKey required: pass laneKey, or run inside a lane-bound session (PI_WORKTREE_LANE).\";\n\t\t\t};\n\n\t\t\tconst runTypedLaneAction = async (): Promise<ReturnType<typeof respond>> => {\n\t\t\t\tconst missingLane = needLane();\n\t\t\t\tif (missingLane) return respond([missingLane], { code: \"lane_not_found\", message: missingLane });\n\t\t\t\tconst context = await resolveRepoContext(engineDeps);\n\t\t\t\tif (\"code\" in context) return respond([`[${context.code}] ${context.message}`], context);\n\t\t\t\tconst lane = await readLane(context.paths, laneKey!);\n\t\t\t\tif (!lane || lane.status !== \"active\") {\n\t\t\t\t\tconst message = `active lane '${laneKey}' is not available`;\n\t\t\t\t\treturn respond([`[lane_not_found] ${message}`], { code: \"lane_not_found\", message });\n\t\t\t\t}\n\n\t\t\t\tconst requestedPaths = input.paths ?? [];\n\t\t\t\tconst gitPaths: string[] = [];\n\t\t\t\tfor (const requestedPath of requestedPaths) {\n\t\t\t\t\tif (!requestedPath || isAbsolute(requestedPath) || requestedPath.includes(\"\\0\")) {\n\t\t\t\t\t\tconst message = \"git path must be a non-empty relative path without NUL\";\n\t\t\t\t\t\treturn respond([`[path_outside_lane] ${message}`], { code: \"path_outside_lane\", message });\n\t\t\t\t\t}\n\t\t\t\t\tconst resolved = resolveLaneMutationPath(lane.worktreePath, requestedPath);\n\t\t\t\t\tif (!resolved) {\n\t\t\t\t\t\tconst message = `path '${requestedPath}' escapes the lane worktree`;\n\t\t\t\t\t\treturn respond([`[path_outside_lane] ${message}`], { code: \"path_outside_lane\", message });\n\t\t\t\t\t}\n\t\t\t\t\tgitPaths.push(relative(lane.worktreePath, resolved) || \".\");\n\t\t\t\t}\n\n\t\t\t\tlet command: string;\n\t\t\t\tlet args: string[];\n\t\t\t\tswitch (input.action) {\n\t\t\t\t\tcase \"git_status\":\n\t\t\t\t\t\tcommand = \"git\";\n\t\t\t\t\t\targs = [\"status\", \"--short\", \"--branch\"];\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"git_diff\":\n\t\t\t\t\t\tcommand = \"git\";\n\t\t\t\t\t\targs = [\"diff\", \"--\", ...gitPaths];\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"git_add\":\n\t\t\t\t\t\tif (gitPaths.length === 0) {\n\t\t\t\t\t\t\tconst message = \"git_add requires one or more explicit in-lane paths\";\n\t\t\t\t\t\t\treturn respond([`[path_outside_lane] ${message}`], { code: \"path_outside_lane\", message });\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcommand = \"git\";\n\t\t\t\t\t\targs = [\"add\", \"--\", ...gitPaths];\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"git_commit\":\n\t\t\t\t\t\tif (!input.message?.trim() || input.message.includes(\"\\0\")) {\n\t\t\t\t\t\t\tconst message = \"git_commit requires a non-empty literal message\";\n\t\t\t\t\t\t\treturn respond([`[git_failed] ${message}`], { code: \"git_failed\", message });\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcommand = \"git\";\n\t\t\t\t\t\targs = [\"commit\", \"-m\", input.message];\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"check\": {\n\t\t\t\t\t\tconst trustedCommand = settings.gateCommand?.trim();\n\t\t\t\t\t\tif (!trustedCommand) {\n\t\t\t\t\t\t\tconst message = \"no trusted worktree check is configured\";\n\t\t\t\t\t\t\treturn respond([`[gate_command_unset] ${message}`], { code: \"gate_command_unset\", message });\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst shell = process.platform === \"win32\" ? \"cmd\" : \"sh\";\n\t\t\t\t\t\tconst shellFlag = process.platform === \"win32\" ? \"/c\" : \"-c\";\n\t\t\t\t\t\tconst result = await engineDeps.exec(shell, [shellFlag, trustedCommand], {\n\t\t\t\t\t\t\tcwd: lane.worktreePath,\n\t\t\t\t\t\t\ttimeout: 900_000,\n\t\t\t\t\t\t\tsignal: engineDeps.signal,\n\t\t\t\t\t\t\tmaxBuffer: 1024 * 1024,\n\t\t\t\t\t\t});\n\t\t\t\t\t\tconst output = `${result.stdout}\\n${result.stderr}`.trim().slice(-8000);\n\t\t\t\t\t\tif (result.code !== 0) {\n\t\t\t\t\t\t\treturn respond([`[gate_failed] ${output || `trusted check exited ${result.code}`}`], {\n\t\t\t\t\t\t\t\tcode: \"gate_failed\",\n\t\t\t\t\t\t\t\texitCode: result.code,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn respond([output || \"trusted check passed\"], { code: \"ok\", action: input.action });\n\t\t\t\t\t}\n\t\t\t\t\tdefault:\n\t\t\t\t\t\treturn respond([\"typed lane action is unavailable for this request\"], { code: \"role_forbidden\" });\n\t\t\t\t}\n\n\t\t\t\tconst result = await engineDeps.exec(command, args, {\n\t\t\t\t\tcwd: lane.worktreePath,\n\t\t\t\t\ttimeout: 60_000,\n\t\t\t\t\tsignal: engineDeps.signal,\n\t\t\t\t\tmaxBuffer: 1024 * 1024,\n\t\t\t\t});\n\t\t\t\tconst output = `${result.stdout}\\n${result.stderr}`.trim().slice(-8000);\n\t\t\t\tif (result.code !== 0) {\n\t\t\t\t\treturn respond([`[git_failed] ${output || `${command} exited ${result.code}`}`], {\n\t\t\t\t\t\tcode: \"git_failed\",\n\t\t\t\t\t\taction: input.action,\n\t\t\t\t\t\texitCode: result.code,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\treturn respond([output || `${input.action} completed`], { code: \"ok\", action: input.action });\n\t\t\t};\n\n\t\t\tif (deps.isWorker()) {\n\t\t\t\tconst bound = deps.boundLaneKey();\n\t\t\t\tif (input.laneKey !== undefined && input.laneKey !== bound) {\n\t\t\t\t\tconst message = \"workers may only target their bound lane\";\n\t\t\t\t\treturn respond([message], { code: \"role_forbidden\", message });\n\t\t\t\t}\n\t\t\t\tconst landAllowed = input.action === \"land\" && settings.workerLand === \"allow\";\n\t\t\t\tif (!WORKER_ALLOWED_ACTIONS.has(input.action) && !landAllowed) {\n\t\t\t\t\tconst message =\n\t\t\t\t\t\tinput.action === \"land\"\n\t\t\t\t\t\t\t? 'workers may not land (worktreeSync.workerLand is \"deny\")'\n\t\t\t\t\t\t\t: `workers may not run action \"${input.action}\"`;\n\t\t\t\t\treturn respond([message], { code: \"role_forbidden\", message });\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tswitch (input.action) {\n\t\t\t\tcase \"git_status\":\n\t\t\t\tcase \"git_diff\":\n\t\t\t\tcase \"git_add\":\n\t\t\t\tcase \"git_commit\":\n\t\t\t\tcase \"check\":\n\t\t\t\t\treturn runTypedLaneAction();\n\t\t\t\tcase \"status\": {\n\t\t\t\t\tconst status = await buildSyncStatus(engineDeps, { policy: settings.syncPolicy });\n\t\t\t\t\tif (status.code !== \"ok\") return respond([`[${status.code}] ${status.message}`], status);\n\t\t\t\t\treturn respond(formatStatus(status), status);\n\t\t\t\t}\n\t\t\t\tcase \"create_lane\": {\n\t\t\t\t\tconst created = await createLane(engineDeps, {\n\t\t\t\t\t\t...(input.laneKey !== undefined ? { laneKey: input.laneKey } : {}),\n\t\t\t\t\t\t...(input.goalId !== undefined ? { goalId: input.goalId } : {}),\n\t\t\t\t\t\t...(input.requirementId !== undefined ? { requirementId: input.requirementId } : {}),\n\t\t\t\t\t});\n\t\t\t\t\tif (created.code !== \"ok\") return respond([`[${created.code}] ${created.message}`], created);\n\t\t\t\t\treturn respond(\n\t\t\t\t\t\t[\n\t\t\t\t\t\t\t`lane '${created.lane.laneKey}' created: branch ${created.lane.branch}, checkout ${created.lane.worktreePath}`,\n\t\t\t\t\t\t],\n\t\t\t\t\t\tcreated,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tcase \"sync\": {\n\t\t\t\t\tconst missing = needLane();\n\t\t\t\t\tif (missing) return respond([missing], { code: \"lane_not_found\", message: missing });\n\t\t\t\t\tconst synced = await syncLane(engineDeps, { laneKey: laneKey as string });\n\t\t\t\t\tif (synced.code === \"sync_clean\") {\n\t\t\t\t\t\treturn respond(\n\t\t\t\t\t\t\t[\n\t\t\t\t\t\t\t\tsynced.alreadyFresh\n\t\t\t\t\t\t\t\t\t? `lane '${synced.laneKey}' already contains current main -- nothing to do`\n\t\t\t\t\t\t\t\t\t: `lane '${synced.laneKey}' rebased onto current main (auto-continued ${synced.autoContinued} step(s))`,\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\tsynced,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tif (synced.code === \"sync_conflicts\") return respond(formatWorklist(synced.worklist), synced);\n\t\t\t\t\treturn respond(\n\t\t\t\t\t\t[`[${synced.code}] ${synced.message}${synced.paths ? `\\n${synced.paths.join(\"\\n\")}` : \"\"}`],\n\t\t\t\t\t\tsynced,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tcase \"continue\": {\n\t\t\t\t\tconst missing = needLane();\n\t\t\t\t\tif (missing) return respond([missing], { code: \"lane_not_found\", message: missing });\n\t\t\t\t\tconst continued = await continueSync(engineDeps, { laneKey: laneKey as string });\n\t\t\t\t\tif (continued.code === \"sync_clean\") {\n\t\t\t\t\t\treturn respond(\n\t\t\t\t\t\t\t[`lane '${continued.laneKey}' rebase completed -- lane is fresh relative to the synced main`],\n\t\t\t\t\t\t\tcontinued,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tif (continued.code === \"sync_conflicts\") return respond(formatWorklist(continued.worklist), continued);\n\t\t\t\t\treturn respond(\n\t\t\t\t\t\t[\n\t\t\t\t\t\t\t`[${continued.code}] ${continued.message}${continued.paths ? `\\n${continued.paths.join(\"\\n\")}` : \"\"}`,\n\t\t\t\t\t\t],\n\t\t\t\t\t\tcontinued,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tcase \"abort_sync\": {\n\t\t\t\t\tconst missing = needLane();\n\t\t\t\t\tif (missing) return respond([missing], { code: \"lane_not_found\", message: missing });\n\t\t\t\t\tconst aborted = await abortSync(engineDeps, { laneKey: laneKey as string });\n\t\t\t\t\tif (aborted.code !== \"ok\") return respond([`[${aborted.code}] ${aborted.message}`], aborted);\n\t\t\t\t\treturn respond(\n\t\t\t\t\t\t[`lane '${aborted.laneKey}' rebase aborted -- back to its pre-sync tip (still stale)`],\n\t\t\t\t\t\taborted,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tcase \"land\": {\n\t\t\t\t\tconst missing = needLane();\n\t\t\t\t\tif (missing) return respond([missing], { code: \"lane_not_found\", message: missing });\n\t\t\t\t\tconst landed = await landLane(engineDeps, {\n\t\t\t\t\t\tlaneKey: laneKey as string,\n\t\t\t\t\t\tgate: settings.gate,\n\t\t\t\t\t\t...(settings.gateCommand !== undefined ? { gateCommand: settings.gateCommand } : {}),\n\t\t\t\t\t\tgateTimeoutMs: settings.gateTimeoutMs,\n\t\t\t\t\t});\n\t\t\t\t\tif (landed.code !== \"ok\") {\n\t\t\t\t\t\treturn respond(\n\t\t\t\t\t\t\t[`[${landed.code}] ${landed.message}${landed.paths ? `\\n${landed.paths.join(\"\\n\")}` : \"\"}`],\n\t\t\t\t\t\t\tlanded,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\treturn respond(\n\t\t\t\t\t\t[\n\t\t\t\t\t\t\t`lane '${landed.laneKey}' LANDED: epoch ${landed.epoch}, main is now ${landed.mainSha.slice(0, 12)} (gate: ${landed.gate}). All other lanes must sync before their next land.`,\n\t\t\t\t\t\t],\n\t\t\t\t\t\tlanded,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tcase \"release_lane\": {\n\t\t\t\t\tconst missing = needLane();\n\t\t\t\t\tif (missing) return respond([missing], { code: \"lane_not_found\", message: missing });\n\t\t\t\t\tconst released = await releaseLane(engineDeps, {\n\t\t\t\t\t\tlaneKey: laneKey as string,\n\t\t\t\t\t\t...(input.confirm !== undefined ? { confirm: input.confirm } : {}),\n\t\t\t\t\t});\n\t\t\t\t\tif (released.code !== \"released\") return respond([`[${released.code}] ${released.message}`], released);\n\t\t\t\t\treturn respond([`lane '${released.laneKey}' released`], released);\n\t\t\t\t}\n\t\t\t\tcase \"reconcile\": {\n\t\t\t\t\tconst reconciled = await reconcile(engineDeps);\n\t\t\t\t\tif (reconciled.code !== \"reconciled\")\n\t\t\t\t\t\treturn respond([`[${reconciled.code}] ${reconciled.message}`], reconciled);\n\t\t\t\t\treturn respond(\n\t\t\t\t\t\t[\n\t\t\t\t\t\t\t`reconciled: ${reconciled.orphanedLaneKeys.length} orphaned, ${reconciled.reRegisteredLaneKeys.length} re-registered, ${reconciled.ownerClearedLaneKeys.length} owners cleared${reconciled.staleLockReleased ? \", stale lock released\" : \"\"}`,\n\t\t\t\t\t\t],\n\t\t\t\t\t\treconciled,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t};\n}\n"]}