@zq-silk/yui 2.22.0 → 2.25.0

package/dist/controller/runtime.js

@@ -27,7 +27,7 @@ import { launchBrokerForHome } from "../runtime/launchBroker.js";
 import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { classifyRuntimeProcessExit, validateRuntimeProcessExitObservation } from "../runtime/processExitObservation.js";
 import { replayRuntimeProcessExitOutbox } from "../runtime/processExitOutbox.js";
-import { providerRetryPrompt } from "../runtime/providerRetry.js";
+import { providerRetryContext } from "../runtime/providerRetry.js";
 import { createRuntimeObservation, runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
 import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 import { managedRuntimeRoot } from "../storage/homeLayout.js";
@@ -60,6 +60,13 @@ import { ephemeralDomainFromEnvironment, recordEphemeralTmuxTarget } from "./dom
 import { createEphemeralResourceReaper } from "./ephemeralResourceReaper.js";
 import { AgentHostProviderSessionBusyError, AgentHostProviderTurnFenceError, FileSchedulerStoreAdapter } from "./fileSchedulerStoreAdapter.js";
 import { deliverGlobalInputs } from "./globalInputDelivery.js";
+import { HostUpgradeCoordinator } from "./hostUpgrade.js";
+import { createHostLifecycleChecks } from "./hostLifecycleChecks.js";
+import { createControllerHostLifecycle } from "./hostLifecycle.js";
+import { createNonBlockingChecks } from "../runtime/lifecycleChecks.js";
+import { AGENT_HOST_IMPLEMENTATION } from "../runtime/agentHostImplementation.js";
+import { builtinAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
+import { sendAgentHostUpgradeControl } from "../runtime/agentHost.js";
 import { authorizeJobStart } from "./jobControl.js";
 import { authorizeGlobalJobStart, createJobDefinitionControl } from "./jobDefinitionControl.js";
 import { reconcileTaskDelegation } from "./jobTaskDelegationControl.js";
@@ -198,7 +205,7 @@ async function createFileTaskControllerRuntime(home, options) {
             ?? new AgentConfigurationCatalogService(home, {
                 environment: options.environment ?? process.env
             });
-        const sessionHost = options.sessionHost ?? new TmuxSessionHost(planner, tmux, {
+        const rawSessionHost = options.sessionHost ?? new TmuxSessionHost(planner, tmux, {
             validateLaunch: async (request) => {
                 const agent = store.getConfiguredAgent(request.agentId);
                 if (agent === null)
@@ -267,13 +274,13 @@ async function createFileTaskControllerRuntime(home, options) {
                     globalInstallPaths: [process.execPath]
                 }
             });
-        const lifecycleHost = {
-            inspectOwner: (owner) => (sessionHost.inspectOwner(owner)),
-            ...(sessionHost.inspectOwners === undefined
-                ? {}
-                : {
-                    inspectOwners: (owners) => sessionHost.inspectOwners(owners)
-                }),
+        const hostStateChecks = createNonBlockingChecks([{
+                id: "host-version-hint",
+                run: (_transition, signal) => { if (!signal.aborted)
+                    hostLifecycleChecks.notify("host-observed"); }
+            }], options.onError);
+        const controllerHosts = createControllerHostLifecycle(rawSessionHost, {
+            after: hostStateChecks,
             stopOwner: (owner) => {
                 // Issue 03: the durable `stopped` transition is gated on physical
                 // exit proof. A blocked result keeps the Session non-terminal and
@@ -287,7 +294,9 @@ async function createFileTaskControllerRuntime(home, options) {
                     return result.outcome === "stop-confirmed";
                 });
             },
-        };
+        });
+        const sessionHost = controllerHosts.port;
+        const lifecycleHost = sessionHost;
         const resourceActivity = createRuntimeResourceActivityTracker();
         let runningRuntime;
         let runningController;
@@ -298,6 +307,32 @@ async function createFileTaskControllerRuntime(home, options) {
             },
             runtimeIsolation
         });
+        const hostUpgrades = new HostUpgradeCoordinator(store, AGENT_HOST_IMPLEMENTATION, {
+            inspect: owner => inspectAgentHost({ home, ...owner }),
+            control: async (owner, type, request) => {
+                const send = async () => {
+                    const result = await sendAgentHostUpgradeControl({
+                        home, ...owner, control: { protocol: AGENT_HOST_CONTROL_PROTOCOL, type, ...request }
+                    });
+                    if (result.outcome === "rejected")
+                        throw new Error(result.failure?.detail ?? "Host upgrade control rejected.");
+                    return result.snapshot;
+                };
+                return type === "finish-upgrade" ? controllerHosts.requestExit(owner, send) : send();
+            },
+            hostState: async (owner) => (await sessionHost.inspectOwner(owner)).state,
+            endpoint: builtinAgentEndpointImplementation,
+            restore: async (owner, request, effective, assertCurrent) => {
+                const workspace = owner.scope === "task" ? currentDesiredManagedWorkspace(store, owner.taskId, owner.roleName) : undefined;
+                await launchCoordinator.prepare({
+                    owner, agentId: request.agentId, adapterId: request.adapterId, effective,
+                    workspace: effective.workspace.root, mode: "resume", nativeSessionId: request.nativeSessionId,
+                    ...(workspace === undefined ? {} : { managedWorkspace: workspace }),
+                    ...(effective.executionAuthority === "planning" ? { workspaceFree: true } : {})
+                }, assertCurrent);
+            }
+        });
+        const hostLifecycleChecks = createHostLifecycleChecks(hostUpgrades, options.onError);
         // One inventory scan per scheduler pass. When the inventory worker is active
         // the blocking /proc scan runs there; otherwise it runs on the main thread.
         const scanInventory = (panes) => inventoryClient !== undefined
@@ -588,10 +623,22 @@ async function createFileTaskControllerRuntime(home, options) {
         let messageHealthHosts = [];
         const running = await startFileTaskController(home, workerMaintenance
             ? workerSchedulerStore(schedulerStore, asyncStoreClient)
-            : schedulerStore, delivery, (method, params) => method === "task.role-capabilities"
-            ? readTaskAgentCapabilities(store, catalogs, params)
-            : method === "web.start" || method === "web.stop" || method === "web.status"
-                ? web.dispatch(method, params) : lifecycleDispatcher(method, params), {
+            : schedulerStore, delivery, (method, params) => method === "runtime.host-upgrade-status"
+            ? hostUpgrades.status().then(hosts => ({ hosts }))
+            : method === "runtime.upgrade-hosts"
+                ? (params.generation === AGENT_HOST_IMPLEMENTATION.generation
+                    ? hostUpgrades.request().then(hosts => ({ hosts }))
+                    : Promise.reject(new Error("Host upgrade target is not this Controller's verified loaded generation.")))
+                : method === "task.role-capabilities"
+                    ? readTaskAgentCapabilities(store, catalogs, params)
+                    : method === "web.start" || method === "web.stop" || method === "web.status"
+                        ? web.dispatch(method, params) : Promise.resolve(lifecycleDispatcher(method, params)).then(result => {
+                        if (["runtime.ensure-role-session", "runtime.process-exit-observe",
+                            "runtime.host-observation-apply", "runtime.observation-apply"].includes(method)) {
+                            hostLifecycleChecks.notify("host-observed");
+                        }
+                        return result;
+                    }), {
             intervalMs: options.intervalMs
                 ?? reconciliationIntervalMilliseconds(store.getConfig().reconciliationIntervalSeconds),
             signalWindowMs: options.signalWindowMs,
@@ -610,6 +657,7 @@ async function createFileTaskControllerRuntime(home, options) {
             diagnosticMetrics: options.diagnosticMetrics,
             onRequestDiagnostic: options.onRequestDiagnostic,
             lifecycleHost,
+            lifecycleChecks: hostLifecycleChecks,
             providerRetry: createProviderRetryHooks(home, store, {
                 now: options.now,
                 onError: options.onError,
@@ -704,7 +752,9 @@ async function createFileTaskControllerRuntime(home, options) {
         }
         let resourceClose;
         const closeResources = () => {
-            resourceClose ??= closeTelemetry().finally(() => Promise.all([
+            hostStateChecks.close();
+            hostLifecycleChecks.close();
+            resourceClose ??= hostUpgrades.close().then(() => closeTelemetry()).finally(() => Promise.all([
                 web.close(),
                 kernel.close(),
                 asyncStoreClient?.close() ?? Promise.resolve(),
@@ -845,7 +895,8 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             const retry = binding?.retry;
             return { recorded: true, ...(retry?.currentAttemptId === value.attemptId && value.boundedText !== undefined
                     ? { retryInput: {
-                            text: providerRetryPrompt(retry, value.boundedText),
+                            text: value.boundedText,
+                            ...(retry.failedNativeTurnId === undefined ? {} : { context: providerRetryContext(retry) }),
                             ...(retry.failedNativeTurnId === undefined ? {} : { expectedFailedNativeTurnId: retry.failedNativeTurnId })
                         } } : {}) };
         }

package/dist/controller/sessionNotify.js

@@ -2,10 +2,9 @@ import { callController } from "../core/controllerClient.js";
 import { FileRuntimeEventInbox } from "./runtimeEventInbox.js";
 import { transportAgentResult } from "../domain/agentResultTransport.js";
 import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
-import { setCodexThreadName } from "../execution/codexThreadNaming.js";
 import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 /** Hidden CLI entrypoint used by Codex's structured notify hook. */
-export async function runSessionNotifyCommand(payloadArgument, environment = process.env, call, setThreadName = setCodexThreadName) {
+export async function runSessionNotifyCommand(payloadArgument, environment = process.env, call) {
     const params = parseCodexSessionNotification(payloadArgument, environment);
     // Old global TUIs can still emit their invocation-local hook. It is not
     // evidence of a shared-daemon Thread's identity or process lifecycle.
@@ -15,7 +14,7 @@ export async function runSessionNotifyCommand(payloadArgument, environment = pro
     const home = requireText(environment.YUI_HOME, "YUI_HOME");
     // The caller reports native identity; durable state supplies the current AgentRun.
     const current = currentNotifyRun(home, params);
-    const enqueued = new FileRuntimeEventInbox(home).enqueueRunTerminal({
+    new FileRuntimeEventInbox(home).enqueueRunTerminal({
         scope: params.scope,
         ...(params.scope === "task" ? { taskId: params.taskId } : {}),
         roleName: params.roleName,
@@ -42,11 +41,9 @@ export async function runSessionNotifyCommand(payloadArgument, environment = pro
                 roleName: params.roleName
             })
     }, { timeoutMs: 100 }).catch(() => { });
-    if (enqueued.created && shouldSetThreadName(home, params, current.runId)) {
-        const request = threadNameRequest(params, environment);
-        if (request !== null)
-            await setThreadName(request).catch(() => { });
-    }
+    // Title synchronization belongs to the Host's separately fenced metadata
+    // lane. A terminal notification is neither a rename receipt nor permission
+    // to replay an unknown write or overwrite a native user's name.
 }
 /**
  * Resolve the active AgentRun only when the notifying native Session matches.
@@ -130,44 +127,6 @@ function requireText(value, label) {
         throw new Error(`${label} is invalid.`);
     return text;
 }
-function shouldSetThreadName(home, params, runId) {
-    if (params.scope !== "task"
-        || params.title === undefined
-        || runId === undefined)
-        return false;
-    try {
-        const store = openCurrentTaskStore(home);
-        return store.getRun(params.taskId, runId)?.mode === "new";
-    }
-    catch {
-        return false;
-    }
-}
-function threadNameRequest(params, environment) {
-    if (params.title === undefined)
-        return null;
-    const command = environment.YUI_AGENT_COMMAND;
-    const encodedBaseArgs = environment.YUI_AGENT_BASE_ARGS;
-    if (command === undefined || encodedBaseArgs === undefined)
-        return null;
-    try {
-        const parsed = JSON.parse(encodedBaseArgs);
-        if (!Array.isArray(parsed)
-            || parsed.some((value) => typeof value !== "string" || value.includes("\0"))) {
-            return null;
-        }
-        return {
-            command: requireText(command, "YUI_AGENT_COMMAND"),
-            baseArgs: parsed,
-            environment,
-            threadId: params.nativeSessionId,
-            name: params.title
-        };
-    }
-    catch {
-        return null;
-    }
-}
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/execution/codexThreadNaming.js

@@ -2,52 +2,64 @@ import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { codexClientInitialization } from "../runtime/codexAppServerRuntime.js";
 const DEFAULT_TIMEOUT_MS = 1_000;
-export async function setCodexThreadName(request) {
-    const timeoutMs = threadNameTimeout(request.timeoutMs);
-    const client = await CodexNamingClient.start(request.command, request.environment, request.baseArgs ?? [], timeoutMs);
-    try {
-        await withTimeout(client.request("thread/name/set", {
-            threadId: requiredText(request.threadId, "Codex thread id"),
-            name: requiredThreadName(request.name)
-        }), timeoutMs, "Timed out setting Codex thread name.");
-    }
-    finally {
-        client.close();
-    }
-}
-class CodexNamingClient {
+export class CodexNamingClient {
     child;
+    accountHome;
+    exited;
     #pending = new Map();
     #stderr = [];
     #nextId = 1;
     #closed = false;
-    constructor(child) {
+    #deadline;
+    constructor(child, timeoutMs) {
         this.child = child;
+        this.exited = new Promise(resolve => child.once("close", () => resolve()));
+        this.#deadline = setTimeout(() => {
+            this.#failAll(new Error("Native title metadata process deadline exceeded; effect may be unknown."));
+            this.close("SIGKILL");
+        }, timeoutMs);
         const output = createInterface({ input: child.stdout });
-        output.on("line", (line) => { this.#receive(line); });
+        output.on("line", (line) => {
+            try {
+                if (Buffer.byteLength(line) > 1_048_576)
+                    throw new Error("Native title reply exceeds its bound.");
+                this.#receive(line);
+            }
+            catch (error) {
+                this.#failAll(error instanceof Error ? error : new Error(String(error)));
+                this.close();
+            }
+        });
+        child.stdout.on("error", error => { this.#failAll(error); this.close(); });
         child.stderr.setEncoding("utf8");
         child.stderr.on("data", (chunk) => {
             this.#stderr.push(chunk);
             if (this.#stderr.join("").length > 16_384)
                 this.#stderr.shift();
         });
-        child.on("error", (error) => { this.#failAll(error); });
+        child.on("error", (error) => { this.#failAll(error); this.close(); });
+        child.stdin.on("error", (error) => { this.#failAll(error); this.close(); });
         child.on("exit", (code, signal) => {
+            clearTimeout(this.#deadline);
             if (this.#closed)
                 return;
+            this.#closed = true;
             const detail = this.#stderr.join("").trim();
             this.#failAll(new Error(`Codex App Server exited (${code ?? signal ?? "unknown"})${detail.length === 0 ? "" : `: ${detail}`}`));
         });
     }
     static async start(command, environment, baseArgs, timeoutMs) {
-        const client = new CodexNamingClient(spawn(command, [...baseArgs, "app-server", "--stdio"], { env: environment, stdio: ["pipe", "pipe", "pipe"] }));
+        const deadlineMs = threadNameTimeout(timeoutMs);
+        const client = new CodexNamingClient(spawn(command, [...baseArgs, "app-server", "--listen", "stdio://"], { env: environment, stdio: ["pipe", "pipe", "pipe"] }), deadlineMs);
         try {
-            await withTimeout(client.request("initialize", codexClientInitialization()), timeoutMs, "Timed out initializing Codex App Server for thread naming.");
+            const initialized = await withTimeout(client.request("initialize", codexClientInitialization()), timeoutMs, "Timed out initializing Codex App Server for thread naming.");
+            client.accountHome = typeof initialized.codexHome === "string" ? initialized.codexHome : undefined;
             client.notify("initialized", {});
             return client;
         }
         catch (error) {
             client.close();
+            await client.exited;
             throw error;
         }
     }
@@ -63,11 +75,19 @@ class CodexNamingClient {
     notify(method, params) {
         this.#write({ method, params });
     }
-    close() {
+    close(signal = "SIGTERM") {
         if (this.#closed)
             return;
         this.#closed = true;
-        this.child.kill("SIGTERM");
+        clearTimeout(this.#deadline);
+        this.child.kill(signal);
+        // An owned metadata process must not survive a lost reply or ignored TERM.
+        const reap = setTimeout(() => {
+            if (this.child.exitCode === null && this.child.signalCode === null)
+                this.child.kill("SIGKILL");
+        }, 250);
+        reap.unref();
+        this.child.once("exit", () => clearTimeout(reap));
         this.#failAll(new Error("Codex App Server closed."));
     }
     #write(value) {
@@ -94,13 +114,20 @@ class CodexNamingClient {
             }
             return;
         }
-        this.#pending.delete(message.id);
-        if (message.error !== undefined) {
-            const error = object(message.error, "Codex App Server error");
-            pending.reject(new Error(typeof error.message === "string" ? error.message : "Codex App Server request failed."));
+        try {
+            if (message.error !== undefined) {
+                const error = object(message.error, "Codex App Server error");
+                pending.reject(new Error(typeof error.message === "string" ? error.message : "Codex App Server request failed."));
+            }
+            else {
+                pending.resolve(object(message.result, "Codex App Server result"));
+            }
+        }
+        catch (error) {
+            pending.reject(error instanceof Error ? error : new Error(String(error)));
         }
-        else {
-            pending.resolve(object(message.result, "Codex App Server result"));
+        finally {
+            this.#pending.delete(message.id);
         }
     }
     #failAll(error) {
@@ -115,22 +142,6 @@ function object(value, label) {
     }
     return value;
 }
-function requiredText(value, label) {
-    if (typeof value !== "string" || value.trim().length === 0) {
-        throw new Error(`${label} is invalid.`);
-    }
-    return value;
-}
-function requiredThreadName(value) {
-    if (typeof value !== "string" || value.includes("\0")) {
-        throw new Error("Codex thread name is invalid.");
-    }
-    const normalized = value.trim();
-    if (normalized.length === 0 || normalized.length > 1_024) {
-        throw new Error("Codex thread name is invalid.");
-    }
-    return normalized;
-}
 function threadNameTimeout(value) {
     if (value === undefined)
         return DEFAULT_TIMEOUT_MS;

package/dist/executor/fileRoleLaunchPlanner.js

@@ -17,7 +17,7 @@ import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
 import { builtinAgentEndpointImplementation, validateAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
 import { builtinAgentDriverRegistry, builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { assertProviderConversationReplaceable } from "../runtime/providerRuntimeIdentity.js";
-import { globalRoleSessionTitle, resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
+import { globalRoleSessionTitle, taskRoleSessionTitle, resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
 import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
@@ -225,7 +225,11 @@ export class FileRoleLaunchPlanner {
             instanceCode: role.instanceCode,
             generatedTitle: existing?.generatedTitle
         }), input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, {
-            purpose
+            purpose,
+            nativeGeneratedTitle: taskRoleSessionTitle(task, role.name, {
+                executionAuthority: (input.mode === "resume" ? existing?.effective : effective)?.executionAuthority,
+                instanceCode: role.instanceCode
+            })
         });
     }
     planGlobalRole(input) {
@@ -258,7 +262,10 @@ export class FileRoleLaunchPlanner {
             : existing?.generatedTitle !== undefined && existing.title === existing.generatedTitle
                 ? globalRoleSessionTitle(role.name, new Date(existing.createdAt), this.store.getConfig().timeZone, role.instanceCode)
                     ?? `Yui ${role.name}`
-                : undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, { purpose: "execution" });
+                : undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, { purpose: "execution",
+            nativeGeneratedTitle: globalRoleSessionTitle(role.name, input.mode === "resume" && existing !== undefined ? new Date(existing.createdAt) : this.#now(), this.store.getConfig().timeZone, role.instanceCode)
+                ?? (input.mode === "resume" ? `Yui ${role.name}` : undefined)
+        });
     }
     #compile(role, input, owner, sessionTitle, knownNativeSessionId, effective, sessionPolicy) {
         const launchRole = effectiveRoleForLaunch(role, effective);
@@ -570,6 +577,14 @@ export class FileRoleLaunchPlanner {
                 YUI_DRIVER_ID: driver.id,
                 YUI_WORKSPACE: effectiveWorkspace,
                 YUI_SESSION_MANIFEST: sessionContext.sessionManifestPath,
+                // A proposal only. The independent metadata lane must prove native
+                // ownership; planning never reads/waits on title effects.
+                ...(configured.adapterId !== "codex" || sessionPolicy.nativeGeneratedTitle === undefined ? {} : {
+                    YUI_NATIVE_TITLE_PROPOSAL: sessionPolicy.nativeGeneratedTitle
+                }),
+                ...(configured.adapterId !== "codex" || input.mode !== "resume" || existingSession?.title === undefined ? {} : {
+                    YUI_NATIVE_TITLE_LOCAL: existingSession.title
+                }),
                 ...(configured.adapterId === "codex"
                     ? { YUI_AGENT_BASE_ARGS: JSON.stringify(configured.baseArgs) }
                     : {}),

package/dist/integration/gitIntegrationService.js

@@ -64,7 +64,7 @@ export class GitIntegrationService {
     environment;
     runtimeIsolation;
     #resourceRegistrarValue;
-    constructor(home, store, git = new NodeGitWorkspace(), now = () => new Date(), environment = process.env, runtimeIsolation = defaultIntegrationRuntimeIsolation(home, store.getHomeIdentity().homeId), jobPort) {
+    constructor(home, store, git = new NodeGitWorkspace(() => store.getConfig()), now = () => new Date(), environment = process.env, runtimeIsolation = defaultIntegrationRuntimeIsolation(home, store.getHomeIdentity().homeId), jobPort) {
         this.store = store;
         this.git = git;
         this.now = now;

package/dist/kernel/builtinCapabilities.js

@@ -324,14 +324,14 @@ export function createBuiltinCapabilities(host, store, jobs, signal = () => unde
                     ...(params.encoding === undefined ? {} : { encoding: params.encoding }),
                     ...(params.message === undefined ? {} : { message: params.message }),
                     ...(params.expectedHead === undefined ? {} : { expectedHead: params.expectedHead })
-                });
+                }, () => store.getConfig());
             if (name === "artifact.read")
                 return readArtifactCapability(store.rootDirectory(), taskId, {
                     relativePath: params.relativePath,
                     ...(params.commit === undefined ? {} : { commit: params.commit })
-                });
+                }, () => store.getConfig());
             if (name === "artifact.list")
-                return listArtifactsCapability(store.rootDirectory(), taskId);
+                return listArtifactsCapability(store.rootDirectory(), taskId, () => store.getConfig());
             if (name === "environment.prepare")
                 return resources.prepare(taskId, params.plan);
             if (name === "environment.adopt")

package/dist/repository/gitCommand.js

@@ -0,0 +1,153 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { DEFAULT_GIT_LOCAL_TIMEOUT_SECONDS } from "../config/gitConfig.js";
+export const LOCAL_GIT_TIMEOUT_MS = DEFAULT_GIT_LOCAL_TIMEOUT_SECONDS * 1_000;
+/** Retain process facts independently of Git's last progress/error output. */
+export class GitCommandError extends Error {
+    timeoutKind;
+    budget;
+    elapsedMs;
+    code;
+    exitCode;
+    signal;
+    stdout;
+    stderr;
+    stderrTruncated;
+    constructor(cause, timeoutKind, budget, elapsedMs, output) {
+        const failure = cause;
+        const code = failure?.code ?? output.exitCode;
+        const exitCode = output.exitCode;
+        const stderr = output.stderr.toString("utf8").trim();
+        const reasons = [
+            ...(timeoutKind === undefined ? [] : [
+                `${timeoutKind === "inactivity" ? "no-progress timeout" : "total timeout"} after `
+                    + `${timeoutKind === "inactivity" ? budget.inactivityMs : budget.totalMs} ms`
+            ]),
+            ...(exitCode === null ? [] : [`exit code ${exitCode}`]),
+            ...(output.signal === null ? [] : [`signal ${output.signal}`]),
+            ...(typeof code === "string" ? [`${code}: ${failure?.message ?? "process error"}`] : [])
+        ];
+        if (reasons.length === 0)
+            reasons.push(failure?.message ?? "unknown process failure");
+        super(`Git command failed (${reasons.join("; ")}; elapsed ${elapsedMs} ms)`
+            + (stderr.length === 0 ? "." : `: ${output.stderrTruncated ? "[stderr tail; earlier output omitted] " : ""}${stderr}`), { cause });
+        this.timeoutKind = timeoutKind;
+        this.budget = budget;
+        this.elapsedMs = elapsedMs;
+        this.name = "GitCommandError";
+        this.code = code;
+        this.exitCode = exitCode;
+        this.signal = output.signal;
+        this.stdout = output.stdout;
+        this.stderr = stderr;
+        this.stderrTruncated = output.stderrTruncated;
+    }
+}
+/**
+ * One buffered invocation, never retried. Output refreshes only the inactivity
+ * clock; the total deadline never moves. At the hard deadline, kill the owned
+ * process group (including transport helpers) before reporting completion.
+ */
+export async function executeGitCommand(program, args, options = {}) {
+    const budget = options.budget ?? { totalMs: LOCAL_GIT_TIMEOUT_MS };
+    for (const value of [budget.totalMs, ...(budget.inactivityMs === undefined ? [] : [budget.inactivityMs])]) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647) {
+            throw new TypeError("Git timeout budgets must be positive integer milliseconds within the timer range.");
+        }
+    }
+    const started = performance.now();
+    const child = spawn(program, args, {
+        ...(options.environment === undefined ? {} : { env: options.environment }),
+        detached: process.platform !== "win32",
+        windowsHide: true
+    });
+    const maxBuffer = options.maxBuffer ?? 1024 * 1024;
+    const chunks = { stdout: [], stderr: [] };
+    const sizes = { stdout: 0, stderr: 0 };
+    let stderrTruncated = false;
+    let failure;
+    let timeoutKind;
+    let terminationError;
+    const terminate = () => {
+        try {
+            if (child.pid !== undefined && process.platform !== "win32") {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch (error) {
+                    if (error.code !== "ESRCH")
+                        throw error;
+                }
+            }
+            else {
+                child.kill("SIGKILL");
+            }
+        }
+        catch (error) {
+            terminationError = error;
+            child.kill("SIGKILL");
+        }
+    };
+    const expire = (kind) => {
+        if (timeoutKind !== undefined || failure !== undefined)
+            return;
+        timeoutKind = kind;
+        terminate();
+    };
+    child.once("error", error => { failure ??= error; });
+    const completion = new Promise(settle => {
+        child.once("close", (exitCode, signal) => settle({
+            // A negative close code is an OS spawn error, not a process exit.
+            exitCode: exitCode !== null && exitCode >= 0 ? exitCode : null, signal
+        }));
+    });
+    const totalTimer = setTimeout(() => expire("total"), budget.totalMs);
+    const inactivityTimer = budget.inactivityMs === undefined
+        ? undefined : setTimeout(() => expire("inactivity"), budget.inactivityMs);
+    const collect = (stream, chunk) => {
+        if (chunk.length === 0)
+            return;
+        if (timeoutKind === undefined && failure === undefined)
+            inactivityTimer?.refresh();
+        if (stream === "stderr" && options.stderrTail) {
+            const limit = Math.min(maxBuffer, 64 * 1024);
+            stderrTruncated ||= sizes.stderr + chunk.length > limit;
+            const tail = Buffer.concat([...chunks.stderr, chunk]);
+            chunks.stderr = [tail.subarray(Math.max(0, tail.length - limit))];
+            sizes.stderr = Math.min(limit, tail.length);
+            return;
+        }
+        const remaining = maxBuffer - sizes[stream];
+        if (remaining > 0) {
+            chunks[stream].push(chunk.subarray(0, remaining));
+            sizes[stream] += Math.min(chunk.length, remaining);
+        }
+        if (chunk.length > remaining && failure === undefined) {
+            failure = Object.assign(new Error(`${stream} maxBuffer length exceeded (${maxBuffer} bytes).`), { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" });
+            terminate();
+        }
+    };
+    child.stdout.on("data", chunk => collect("stdout", chunk));
+    child.stderr.on("data", chunk => collect("stderr", chunk));
+    child.stdin.on("error", error => {
+        failure ??= error;
+        terminate();
+    });
+    try {
+        child.stdin.end(options.input);
+        const status = await completion;
+        const result = { stdout: Buffer.concat(chunks.stdout), stderr: Buffer.concat(chunks.stderr), stderrTruncated };
+        if (failure !== undefined || timeoutKind !== undefined || status.exitCode !== 0 || status.signal !== null) {
+            const error = new GitCommandError(failure, timeoutKind, budget, Math.round(performance.now() - started), { ...result, ...status });
+            if (terminationError !== undefined) {
+                throw new AggregateError([error, terminationError], `${error.message} Process-group termination failed; helper effects are unconfirmed.`, { cause: error });
+            }
+            throw error;
+        }
+        return result;
+    }
+    finally {
+        clearTimeout(totalTimer);
+        clearTimeout(inactivityTimer);
+    }
+}

package/dist/repository/gitCompatibility.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { realpathSync, statSync } from "node:fs";
 import { resolveExecutable } from "../external/pinnedCommandRunner.js";
+import { DEFAULT_GIT_LOCAL_TIMEOUT_SECONDS } from "../config/gitConfig.js";
 // The fetch isolation boundary needs --no-write-fetch-head. Older Git cannot
 // implement it by saving/restoring FETCH_HEAD without racing another writer.
 export const MINIMUM_GIT_VERSION = "2.29.0";
@@ -17,7 +18,7 @@ export function gitVersionSupport(output) {
 }
 let cached;
 /** Pin the executable checked, reusing only an unchanged on-disk identity. */
-export function supportedGit() {
+export function supportedGit(timeoutMs = DEFAULT_GIT_LOCAL_TIMEOUT_SECONDS * 1_000) {
     const selected = resolveExecutable("git", process.env.PATH);
     if (selected === undefined)
         throw new Error("Git executable not found in PATH; install a supported Git before retrying. No Git operation was started.");
@@ -27,7 +28,7 @@ export function supportedGit() {
     if (cached?.identity === identity)
         return cached;
     const output = execFileSync(path, ["--version"], {
-        encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "pipe"]
+        encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"]
     });
     const support = gitVersionSupport(output);
     if (!support.supported) {