@caupulican/pi-adaptative 0.81.42 → 0.84.1

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

@@ -1 +1 @@
-{"version":3,"file":"windows-shell-engine.d.ts","sourceRoot":"","sources":["../../../src/core/tools/windows-shell-engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKrE,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAKN,KAAK,iBAAiB,EACtB,MAAM,0BAA0B,CAAC;AAIlC,0CAAyC;AACzC,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,WAAW,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChF;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,YAAY,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAIlD;CACD;AAmCD,MAAM,WAAW,yBAAyB;IACzC,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrD,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACrD,2GAA2G;IAC3G,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;CACjF;AAUD;;;GAGG;AACH,wBAAgB,kCAAkC,CACjD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,yBAA8B,GACrC,cAAc,CAwFhB","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 { isRecordObject } from \"../util/value-guards.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\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 (!isRecordObject(raw)) return undefined;\n\t\tif (typeof raw.exitCode !== \"number\" || !Number.isInteger(raw.exitCode)) return undefined;\n\t\tif (typeof raw.cwd !== \"string\" || !isRecordObject(raw.envDelta)) return undefined;\n\t\tif (raw.unsupported !== null && !isRecordObject(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"]}
+{"version":3,"file":"windows-shell-engine.d.ts","sourceRoot":"","sources":["../../../src/core/tools/windows-shell-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMrE,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EAKN,KAAK,iBAAiB,EACtB,MAAM,0BAA0B,CAAC;AAMlC,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,WAAW,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChF;AAiCD,qBAAa,yBAA0B,SAAQ,KAAK;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,YAAY,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAIlD;CACD;AAsED,MAAM,WAAW,yBAAyB;IACzC,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrD,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACrD,sFAAsF;IACtF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,KAAK,YAAY,CAAC;IACjF,2FAA2F;IAC3F,qBAAqB,CAAC,EAAE,MAAM,MAAM,CAAC;CACrC;AAoSD,+FAA+F;AAC/F,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKlE;AAED,+DAA+D;AAC/D,wBAAgB,kCAAkC,CACjD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,yBAA8B,GACrC,cAAc,CAQhB"}

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

@@ -1,20 +1,29 @@
 /**
- * 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).
+ * Persistent Windows Python shell-engine sessions.
+ *
+ * One coordinator process is keyed to each agent session. Requests are serialized as JSON lines;
+ * Node remains the sole owner of cwd/environment state and derives each request only after the
+ * preceding terminal frame has been applied. Command bytes stream on stdout, followed by a
+ * request-specific output barrier. A correlated control frame arrives on stderr. Requiring both
+ * channels before settlement prevents cross-pipe tail loss and stale-frame reuse.
+ *
+ * Timeout, abort, protocol failure, or coordinator death resets the whole process tree. The next
+ * request starts a clean coordinator from the last state Node actually acknowledged.
  */
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { dirname, 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 { spawnProcess } from "../../utils/child-process.js";
+import { getShellConfig, getShellEnv } from "../../utils/shell.js";
 import { ensurePythonRuntime } from "../python-runtime.js";
 import { isRecordObject } from "../util/value-guards.js";
+import { PersistentProcessCoordinator } from "./persistent-process-coordinator.js";
+import { tokenizeShellCommand } from "./shell-command-parser.js";
 import { applyEngineFrame, getOrCreateWindowsShellState, mergeEffectiveEnv, resolveEffectiveCwd, } from "./windows-shell-state.js";
 const ENGINE_FRAME_SENTINEL = 0x1e;
+const MAX_CONTROL_FRAME_BYTES = 64 * 1024;
+const SOFT_DEADLINE_HEADSTART_MS = 100;
 export class WindowsShellEngineFailure extends Error {
-    capturedOutput;
     constructor(message, capturedOutput) {
         super(message);
         this.name = "WindowsShellEngineFailure";
@@ -24,128 +33,341 @@ export class WindowsShellEngineFailure extends Error {
 function resolveEngineScriptPath() {
     return join(getBundledResourcesDir(), "runtimes", "pi-shell-engine", "main.py");
 }
-const MAX_CONTROL_FRAME_BYTES = 64 * 1024;
-/** Parse the terminal frame from the dedicated control stream. Command output is never retained here. */
+function invokesPowerShellScript(command) {
+    const tokens = tokenizeShellCommand(command);
+    // An unparseable command is already heading to the authoritative Python parser;
+    // resolve conservatively so script adaptation cannot lose an explicit host choice.
+    if (!tokens)
+        return /\.ps1\b/iu.test(command);
+    let atCommandStart = true;
+    let skipRedirectTarget = false;
+    for (const token of tokens) {
+        if (token.kind === "operator" || token.kind === "pipe") {
+            atCommandStart = true;
+            skipRedirectTarget = false;
+            continue;
+        }
+        if (token.kind === "redirect") {
+            skipRedirectTarget = !/^\d*[<>]&[\d-]+$/u.test(token.value);
+            continue;
+        }
+        if (skipRedirectTarget) {
+            skipRedirectTarget = false;
+            continue;
+        }
+        if (!atCommandStart || /^[A-Za-z_][A-Za-z0-9_]*=/u.test(token.value))
+            continue;
+        if (token.value.toLowerCase().endsWith(".ps1"))
+            return true;
+        atCommandStart = false;
+    }
+    return false;
+}
 function parseControlFrame(buffer) {
-    if (buffer.length < 2 || buffer[buffer.length - 1] !== ENGINE_FRAME_SENTINEL)
+    const frameStart = buffer.indexOf(ENGINE_FRAME_SENTINEL);
+    if (frameStart === -1)
         return undefined;
-    const openIndex = buffer.lastIndexOf(ENGINE_FRAME_SENTINEL, buffer.length - 2);
-    if (openIndex === -1)
+    const closeIndex = buffer.indexOf(ENGINE_FRAME_SENTINEL, frameStart + 1);
+    if (closeIndex === -1)
         return undefined;
     try {
-        const raw = JSON.parse(buffer.subarray(openIndex + 1, buffer.length - 1).toString("utf8"));
-        if (!isRecordObject(raw))
-            return undefined;
-        if (typeof raw.exitCode !== "number" || !Number.isInteger(raw.exitCode))
-            return undefined;
-        if (typeof raw.cwd !== "string" || !isRecordObject(raw.envDelta))
-            return undefined;
-        if (raw.unsupported !== null && !isRecordObject(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;
+        const raw = JSON.parse(buffer.subarray(frameStart + 1, closeIndex).toString("utf8"));
+        if (isRecordObject(raw) &&
+            typeof raw.requestId === "string" &&
+            /^[0-9a-f]{16}$/u.test(raw.requestId) &&
+            typeof raw.exitCode === "number" &&
+            Number.isInteger(raw.exitCode) &&
+            typeof raw.cwd === "string" &&
+            isRecordObject(raw.envDelta) &&
+            (raw.unsupported === null || isRecordObject(raw.unsupported)) &&
+            (raw.unsupported === null ||
+                (raw.unsupported.code === "unsupported" &&
+                    typeof raw.unsupported.construct === "string" &&
+                    typeof raw.unsupported.message === "string")) &&
+            Object.values(raw.envDelta).every((value) => value === null || typeof value === "string")) {
+            return {
+                kind: "frame",
+                frame: raw,
+                frameStart,
+                frameEnd: closeIndex + 1,
+            };
         }
-        return raw;
     }
     catch {
-        return undefined;
+        // A complete delimited record that is not JSON is a terminal protocol fault.
     }
+    return { kind: "invalid" };
 }
 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;
+class PersistentWindowsShellEngineSession {
+    constructor(key, options) {
+        this.coordinator = new PersistentProcessCoordinator();
+        this.activeExec = null;
+        this.disposed = false;
+        this.key = key;
+        this.resolveRuntime = options.resolveRuntime ?? (() => ensurePythonRuntime({ silent: true }));
+        this.engineScriptPath = options.engineScriptPath ?? resolveEngineScriptPath();
+        this.getState = options.getState ?? getOrCreateWindowsShellState;
+        this.spawn = options.spawn ?? spawnProcess;
+        this.resolvePowerShellPath =
+            options.resolvePowerShellPath ??
+                (() => (process.platform === "win32" ? getShellConfig(undefined, "powershell").shell : "powershell"));
+    }
+    exec(command, cwd, options) {
+        return this.coordinator.runSerialized(() => this.execNow(command, cwd, options));
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const active = this.activeExec;
+        this.coordinator.dispose();
+        active?.fail(new Error(`Windows shell engine session "${this.key}" is disposed`));
+    }
+    async execNow(command, cwd, { onData, signal, timeout, env }) {
+        if (this.disposed)
+            throw new Error(`Windows shell engine session "${this.key}" is disposed`);
+        if (signal?.aborted)
+            throw new Error("aborted");
+        const state = this.getState(this.key);
+        const effectiveCwd = resolveEffectiveCwd(state, cwd);
+        const effectiveEnv = mergeEffectiveEnv(state, env ?? getShellEnv());
+        const child = await this.ensureChild(effectiveEnv);
+        if (this.disposed) {
+            this.killChild();
+            throw new Error(`Windows shell engine session "${this.key}" is disposed`);
+        }
+        if (signal?.aborted) {
+            this.killChild();
+            throw new Error("aborted");
+        }
+        if (!child.stdin || !child.stdout || !child.stderr || child !== this.coordinator.child) {
+            this.killChild();
+            throw new Error("Failed to start Windows shell engine coordinator");
+        }
+        const timeoutMs = timeout !== undefined && timeout > 0 ? timeout * 1000 : undefined;
+        const requestTimeoutMs = timeoutMs !== undefined ? Math.max(timeoutMs - SOFT_DEADLINE_HEADSTART_MS, 1) : undefined;
+        const requestId = randomBytes(8).toString("hex");
+        const request = {
+            requestId,
+            command,
+            cwd: effectiveCwd,
+            env: effectiveEnv,
+            ...(invokesPowerShellScript(command) ? { powershellPath: this.resolvePowerShellPath() } : {}),
+            ...(requestTimeoutMs !== undefined ? { timeoutMs: requestTimeoutMs } : {}),
+        };
+        const outputBarrier = Buffer.from(`\x1e${requestId}\x1e`, "latin1");
+        this.coordinator.setLoopRef(true);
+        try {
+            return await new Promise((resolve, reject) => {
+                let settled = false;
+                let pendingOutput = Buffer.alloc(0);
+                let controlBuffer = Buffer.alloc(0);
+                let controlOverflow = false;
+                let sawOutputBarrier = false;
+                let controlFrame;
+                let completionScheduled = false;
+                let timeoutTimer;
+                const settle = (finish) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timeoutTimer)
+                        clearTimeout(timeoutTimer);
+                    if (signal)
+                        signal.removeEventListener("abort", onAbort);
+                    if (this.activeExec === active)
+                        this.activeExec = null;
+                    finish();
+                };
+                const emitPending = (upTo) => {
+                    if (upTo <= 0)
+                        return;
+                    onData(pendingOutput.subarray(0, upTo));
+                    pendingOutput = pendingOutput.subarray(upTo);
+                };
+                const capturedControl = () => controlOverflow
+                    ? `control frame exceeded ${MAX_CONTROL_FRAME_BYTES} bytes`
+                    : controlBuffer.toString("utf8");
+                const failAndReset = (error) => {
+                    if (settled)
+                        return;
+                    emitPending(pendingOutput.length);
+                    this.killChild();
+                    settle(() => reject(error));
+                };
+                const protocolFailure = (message) => {
+                    const capturedOutput = capturedControl();
+                    return new WindowsShellEngineFailure(`${message}\n${capturedOutput}`, capturedOutput);
+                };
+                const maybeComplete = () => {
+                    if (!sawOutputBarrier || !controlFrame || settled || completionScheduled)
+                        return;
+                    completionScheduled = true;
+                    // stdout and stderr are independent pipes. Keep this request active through the
+                    // next check phase so already-delivered post-barrier bytes are rejected here,
+                    // never forwarded into a queued request that starts in a promise microtask.
+                    setImmediate(() => {
+                        if (settled || this.activeExec !== active || !controlFrame)
+                            return;
+                        applyEngineFrame(state, controlFrame);
+                        if (controlFrame.unsupported) {
+                            settle(() => reject(new Error(controlFrame?.unsupported?.message ?? "Unsupported shell construct")));
+                            return;
+                        }
+                        settle(() => resolve({ exitCode: controlFrame?.exitCode ?? null }));
+                    });
+                };
+                const onAbort = () => failAndReset(new Error("aborted"));
+                const active = {
+                    onStdout: (data) => {
+                        if (sawOutputBarrier) {
+                            failAndReset(protocolFailure("Windows shell engine emitted output after its terminal barrier."));
+                            return;
+                        }
+                        pendingOutput = pendingOutput.length === 0 ? data : Buffer.concat([pendingOutput, data]);
+                        const barrierIndex = pendingOutput.indexOf(outputBarrier);
+                        if (barrierIndex !== -1) {
+                            emitPending(barrierIndex);
+                            pendingOutput = pendingOutput.subarray(outputBarrier.length);
+                            if (pendingOutput.length > 0) {
+                                failAndReset(protocolFailure("Windows shell engine emitted bytes after its terminal barrier."));
+                                return;
+                            }
+                            sawOutputBarrier = true;
+                            maybeComplete();
+                            return;
+                        }
+                        emitPending(pendingOutput.length - (outputBarrier.length - 1));
+                    },
+                    onStderr: (data) => {
+                        if (controlOverflow)
+                            return;
+                        if (controlBuffer.length + data.length > MAX_CONTROL_FRAME_BYTES) {
+                            controlOverflow = true;
+                            failAndReset(protocolFailure("Windows shell engine control frame overflowed."));
+                            return;
+                        }
+                        controlBuffer = controlBuffer.length === 0 ? data : Buffer.concat([controlBuffer, data]);
+                        const parsed = parseControlFrame(controlBuffer);
+                        if (!parsed)
+                            return;
+                        if (parsed.kind === "invalid") {
+                            failAndReset(protocolFailure("Windows shell engine returned a malformed control frame."));
+                            return;
+                        }
+                        if (parsed.frame.requestId !== requestId) {
+                            failAndReset(protocolFailure(`Windows shell engine returned stale control frame ${parsed.frame.requestId}; expected ${requestId}.`));
+                            return;
+                        }
+                        if (controlBuffer.subarray(parsed.frameEnd).toString("utf8").trim().length > 0) {
+                            failAndReset(protocolFailure("Windows shell engine emitted trailing control bytes."));
+                            return;
+                        }
+                        controlFrame = parsed.frame;
+                        maybeComplete();
+                    },
+                    onChildClose: (code) => {
+                        const capturedOutput = capturedControl();
+                        emitPending(pendingOutput.length);
+                        settle(() => reject(new WindowsShellEngineFailure(`Windows shell engine coordinator exited (${code ?? "null"}) before a complete terminal handoff.\n${capturedOutput}`, capturedOutput)));
+                    },
+                    fail: (error) => failAndReset(error),
+                };
+                this.activeExec = active;
+                if (signal)
+                    signal.addEventListener("abort", onAbort, { once: true });
+                if (timeoutMs !== undefined) {
+                    timeoutTimer = setTimeout(() => failAndReset(new Error(`timeout:${timeout}`)), timeoutMs);
                 }
-                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);
+                try {
+                    child.stdin?.write(`${JSON.stringify(request)}\n`, "utf8", (error) => {
+                        if (!error)
+                            return;
+                        failAndReset(new Error(`Failed to write to Windows shell engine coordinator: ${error.message}`));
+                    });
                 }
-                applyEngineFrame(state, frame);
-                if (frame.unsupported)
-                    throw new Error(frame.unsupported.message);
-                return { exitCode: frame.exitCode };
-            }
-            finally {
-                if (child.pid)
-                    untrackDetachedChildPid(child.pid);
-            }
-        },
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    failAndReset(new Error(`Failed to write to Windows shell engine coordinator: ${message}`));
+                }
+            });
+        }
+        finally {
+            this.coordinator.setLoopRef(false);
+        }
+    }
+    async ensureChild(env) {
+        if (this.coordinator.child)
+            return this.coordinator.child;
+        const runtime = await this.resolveRuntime();
+        if (runtime.status !== "ready")
+            throw degradationError(runtime);
+        if (this.disposed)
+            throw new Error(`Windows shell engine session "${this.key}" is disposed`);
+        const child = this.spawn(runtime.pythonPath, ["-B", this.engineScriptPath, "--server"], {
+            cwd: dirname(this.engineScriptPath),
+            env: {
+                ...env,
+                PYTHONDONTWRITEBYTECODE: "1",
+                PYTHONIOENCODING: "utf-8",
+                PYTHONUNBUFFERED: "1",
+                PYTHONUTF8: "1",
+            },
+            detached: process.platform !== "win32",
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        this.coordinator.attach(child, {
+            onStdout: (data) => {
+                const active = this.activeExec;
+                if (active)
+                    active.onStdout(data);
+                else if (data.length > 0)
+                    this.killChild();
+            },
+            onStderr: (data) => {
+                const active = this.activeExec;
+                if (active)
+                    active.onStderr(data);
+                else if (data.length > 0)
+                    this.killChild();
+            },
+            onError: (error) => this.activeExec?.fail(error),
+            onClose: (code) => this.activeExec?.onChildClose(code),
+        });
+        return child;
+    }
+    killChild() {
+        this.coordinator.kill();
+    }
+}
+const engineSessions = new Map();
+function acquireWindowsShellEngineSession(key, options) {
+    const existing = engineSessions.get(key);
+    if (existing)
+        return existing;
+    const session = new PersistentWindowsShellEngineSession(key, options);
+    engineSessions.set(key, session);
+    return session;
+}
+/** Kill and forget a Python coordinator. The next call for this key starts a clean process. */
+export function disposeWindowsShellEngineSession(key) {
+    const session = engineSessions.get(key);
+    if (!session)
+        return;
+    engineSessions.delete(key);
+    session.dispose();
+}
+/** Create the Python-engine tier for one bash-tool session. */
+export function createWindowsShellEngineOperations(sessionKey, options = {}) {
+    return {
+        // Resolve through the registry for every command. Session teardown (for example after
+        // credential/environment changes) deletes only this tenant's entry; an already-built tool
+        // then lazily acquires a fresh coordinator instead of retaining the disposed instance.
+        exec: (command, cwd, execOptions) => acquireWindowsShellEngineSession(sessionKey, options).exec(command, cwd, execOptions),
     };
 }
 //# sourceMappingURL=windows-shell-engine.js.map