@zq-silk/yui 2.2.0 → 2.4.0

package/dist/integration/gitIntegrationService.js

@@ -3,19 +3,19 @@ import { lstat, mkdir, open, realpath, rm, stat } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { selectEnvironment } from "../agent/launchEnvironment.js";
-import { controllerSocketPath } from "../core/controllerEndpoint.js";
 import { durableJobIdempotencyKey } from "../job/durableJob.js";
 import { readRuntimeIdentity } from "../release/runtimeRelease.js";
+import { compatibleGitArguments, supportedGit } from "../repository/gitCompatibility.js";
+import { readGitWorktrees } from "../repository/gitWorktreeInventory.js";
 import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { acquireProjectMaintenanceLocks } from "../repository/projectMaintenanceLock.js";
 import { taskWorkspaceRefSegment } from "../repository/taskWorkspaceIdentity.js";
-import { integrationWorkspaceRoot } from "../repository/taskWorkspacePreparer.js";
+import { FileTaskWorkspacePreparer, integrationWorkspaceRoot } from "../repository/taskWorkspacePreparer.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
-import { FileTaskRuntimeIsolation } from "../runtime/taskRuntimeIsolation.js";
-import { integrationTmuxSocketRoot, managedIntegrationRuntimeRoot } from "../storage/homeLayout.js";
+import { integrationTmuxSocketRoot } from "../storage/homeLayout.js";
+import { defaultIntegrationRuntimeIsolation } from "../runtime/integrationRuntimeIsolation.js";
 import { advanceTaskProjectCommit } from "../task/task.js";
 import { taskIntegrationSettlementCheckout, taskIntegrationTargetCheckout } from "../task/taskAuthority.js";
-import { yuiTmuxServerName } from "../tmux/tmuxManager.js";
 import { recordGateArtifactReuse } from "../verification/gateArtifact.js";
 import { touchGateArtifact } from "../verification/gateArtifactStore.js";
 import { beginGateVerification, checkResultsFromGateArtifact, checkResultsFromGateJob, gateIdentityForCandidate, lookupReusableGateArtifact, recordGateArtifactFromJob, recordGateArtifactFromStepOutcomes, resolveVerificationGate, runGateStepsInProcess } from "../verification/verificationGateService.js";
@@ -370,12 +370,9 @@ export class GitIntegrationService {
                 throw new Error("Integration changed before cleanup; read its current record.");
             }
             integration = current;
-            const activeJob = this.store.listDurableJobs(integration.taskId).find(job => job.owner.kind === "integration-attempt" && job.owner.integrationAttemptId === integration.id
-                && (job.status === "queued" || job.status === "running"
-                    || (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined)));
-            if (activeJob !== undefined) {
-                throw new Error(`Integration ${integration.id} has an active DurableJob: ${activeJob.id}/${activeJob.status}.`);
-            }
+            const managedWorkspace = this.store.getIntegrationWorkspace(integration.taskId, integration.id);
+            if (managedWorkspace === null)
+                return "missing";
             const task = this.store.getTask(integration.taskId);
             if (task === null || !task.projectBindings.some(({ projectId }) => projectId === integration.projectId)) {
                 throw new Error(`Integration Task Project is unavailable: ${integration.id}.`);
@@ -387,42 +384,8 @@ export class GitIntegrationService {
             if (taskRepository === undefined) {
                 throw new Error(`Integration Task clone is unavailable: ${task.id}/${project.id}.`);
             }
-            const managedWorkspace = this.store.getIntegrationWorkspace(integration.taskId, integration.id);
-            if (managedWorkspace !== null) {
-                const runtime = this.#runtimePreparation(integration, managedWorkspace);
-                this.runtimeIsolation.cleanup(runtime, integration.status === "committed" ? "completion" : "failure");
-            }
-            const recorded = managedWorkspace?.entries[0];
-            const directory = recorded?.directory
-                ?? task.projectBindings.find(({ projectId }) => projectId === integration.projectId)?.directory;
-            if (directory === undefined) {
-                throw new Error(`Integration Project binding is unavailable: ${task.id}/${project.id}.`);
-            }
-            const result = await this.git.removeIntegrationWorktree({
-                repositoryPath: taskRepository,
-                container: recorded !== undefined
-                    ? dirname(recorded.path)
-                    : integrationWorkspaceRoot(this.home, task.id, integration.id),
-                directory,
-                taskSegment: taskWorkspaceRefSegment(task),
-                integrationId: integration.id,
-                discardChanges: integration.status === "failed"
-            });
-            if (result !== "dirty") {
-                if (managedWorkspace !== null) {
-                    this.#resourceRegistrar().markWorkspaceDeleted(managedWorkspace);
-                }
-                await rm(integrationCheckDirectory(this.home, task.id, integration.id), {
-                    recursive: true,
-                    force: true
-                });
-                this.store.removeManagedWorkspace({
-                    type: "integration-attempt",
-                    taskId: integration.taskId,
-                    integrationAttemptId: integration.id
-                });
-            }
-            return result;
+            return await new FileTaskWorkspacePreparer(this.home, this.store, this.git, this.now)
+                .cleanupIntegrationWorkspace(task.id, integration.id, { runtimeIsolation: this.runtimeIsolation });
         }
         finally {
             release();
@@ -1024,26 +987,6 @@ function isNodeCode(error, code) {
         && "code" in error
         && error.code === code;
 }
-function defaultIntegrationRuntimeIsolation(home, homeId) {
-    const controlHome = resolve(home);
-    const runtimeRoot = managedIntegrationRuntimeRoot(controlHome);
-    return new FileTaskRuntimeIsolation({
-        // The integration check's provider data/cache/tmp live in a dedicated Home
-        // partition — the same isolation contract every Task runtime obeys — not in
-        // a system-wide `/tmp` root. Only the tmux socket ENDPOINT stays a short
-        // `/tmp` path (see `integrationCheckEnvironment`) for the `sockaddr_un`
-        // budget; ordinary runtime state is now Yui-managed under Home.
-        runtimeRoot,
-        pathLayout: "compact",
-        controlPlane: {
-            yuiHome: controlHome,
-            managedRuntimeRoot: runtimeRoot,
-            controllerSocketPath: controllerSocketPath(homeId),
-            tmuxNamespace: yuiTmuxServerName(controlHome),
-            globalInstallPaths: [process.execPath]
-        }
-    });
-}
 /**
  * Reuse is enabled only for an immutable installed release. Development
  * checkouts have no content-addressed release identity, so they return.
@@ -1106,8 +1049,10 @@ function integrationCheckDirectory(home, taskId, integrationId) {
     return join(home, "artifacts", "integration-checks", taskId, integrationId);
 }
 async function git(args) {
+    const program = supportedGit();
+    const invocation = compatibleGitArguments(args);
     try {
-        const result = await executeFile("git", [...args], {
+        const result = await executeFile(program.path, invocation, {
             encoding: "utf8",
             maxBuffer: 16 * 1024 * 1024,
             timeout: 120_000
@@ -1241,15 +1186,6 @@ async function advanceTargetRef(repositoryPath, targetRef, candidateCommit, expe
     }
 }
 async function checkedOutWorktreePaths(repositoryPath, targetRef) {
-    const porcelain = (await git([
-        "-C", repositoryPath, "worktree", "list", "--porcelain"
-    ])).trim();
-    if (porcelain.length === 0)
-        return [];
-    return porcelain.split(/\n\n+/u).flatMap((record) => {
-        const lines = record.split("\n");
-        const path = lines.find((line) => line.startsWith("worktree "))?.slice("worktree ".length);
-        const branch = lines.find((line) => line.startsWith("branch "))?.slice("branch ".length);
-        return path !== undefined && branch === targetRef ? [path] : [];
-    });
+    return (await readGitWorktrees(repositoryPath))
+        .filter(record => record.branch === targetRef).map(record => record.path);
 }

package/dist/integration/integrationSourceApplication.js

@@ -3,6 +3,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { promisify } from "node:util";
+import { gitOutputLine, supportedGit } from "../repository/gitCompatibility.js";
 import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { recordIntegrationConflict, requireResolutionDecision, updateIntegrationAttempt } from "./integrationAttempt.js";
 const execute = promisify(execFile);
@@ -281,7 +282,7 @@ async function hasExactRefReceipt(path, branch, before, action) {
 }
 const actionId = () => `yui-integration-${randomBytes(16).toString("hex")}`;
 async function gitPath(path, name) {
-    const value = (await command(path, ["rev-parse", "--git-path", name])).trim();
+    const value = gitOutputLine(await command(path, ["rev-parse", "--git-path", name]));
     return isAbsolute(value) ? value : resolve(path, value);
 }
 async function conflicts(path) {
@@ -300,8 +301,9 @@ async function succeeds(path, args, action) {
     }
 }
 async function command(path, args, action) {
+    const program = supportedGit();
     try {
-        return (await execute("git", [
+        return (await execute(program.path, [
             "-C", path, "-c", "user.name=Yui", "-c", "user.email=yui@local",
             "-c", "core.editor=true", "-c", "rebase.backend=merge", ...args
         ], {

package/dist/job/httpPreview.js

@@ -0,0 +1,61 @@
+import { join } from "node:path";
+import { lstatSync, mkdirSync, rmdirSync, unlinkSync } from "node:fs";
+import { jobPreviewSocketRoot } from "../storage/homeLayout.js";
+/** An opt-in launch contract, not a second service registry. The Job remains
+ * the sole owner of the process, cancellation and exit evidence. */
+export function isHttpPreview(env) {
+    return env.YUI_HTTP_PREVIEW === "1";
+}
+export function validateHttpPreview(env, steps) {
+    if (env.YUI_HTTP_PREVIEW !== undefined && !isHttpPreview(env)) {
+        throw new Error("YUI_HTTP_PREVIEW must be 1 when supplied.");
+    }
+    if (env.YUI_PREVIEW_SOCKET !== undefined || steps.some(step => step.env?.YUI_PREVIEW_SOCKET !== undefined || step.env?.YUI_HTTP_PREVIEW !== undefined)) {
+        throw new Error("Preview environment is Job-scoped; YUI_PREVIEW_SOCKET is assigned by the runner.");
+    }
+    if (isHttpPreview(env) && steps.length !== 1) {
+        throw new Error("An HTTP preview Job must have exactly one foreground service step.");
+    }
+}
+export function httpPreviewSocket(artifactDir) {
+    return join(jobPreviewSocketRoot(artifactDir), "http.sock");
+}
+export function assertHttpPreviewSocket(artifactDir) {
+    const dir = jobPreviewSocketRoot(artifactDir);
+    return assertSocketAt(dir);
+}
+function assertSocketAt(dir) {
+    const parent = lstatSync(dir);
+    const path = join(dir, "http.sock");
+    const socket = lstatSync(path);
+    if (!parent.isDirectory() || parent.uid !== process.getuid?.() || (parent.mode & 0o077)
+        || !socket.isSocket() || socket.uid !== parent.uid) {
+        throw new Error("Preview endpoint is not an owned Unix socket.");
+    }
+    return path;
+}
+/** Exclusive creation; never adopt or unlink another process's old endpoint.
+ * Cleanup checks the exact directory inode and removes no unknown contents. */
+export function prepareHttpPreview(artifactDir) {
+    const dir = jobPreviewSocketRoot(artifactDir);
+    mkdirSync(dir, { mode: 0o700 });
+    const owner = lstatSync(dir);
+    return {
+        socket: join(dir, "http.sock"),
+        cleanup() {
+            const current = lstatSync(dir);
+            if (!current.isDirectory() || current.dev !== owner.dev || current.ino !== owner.ino) {
+                throw new Error(`Preview owner changed; retained endpoint: ${dir}`);
+            }
+            try {
+                const path = assertSocketAt(dir);
+                unlinkSync(path);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            rmdirSync(dir);
+        }
+    };
+}

package/dist/job/jobCleanupInspection.js

@@ -0,0 +1,67 @@
+import { isAbsolute, join, resolve } from "node:path";
+import { processGenerationIsLive } from "../core/fileLockOwner.js";
+import { scanProcessPathRefs } from "../resources/liveReferences.js";
+import { inspectTaskRuntimeCleanupClaims, parseTaskRuntimeIsolationDescriptor, YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR } from "../runtime/taskRuntimeIsolation.js";
+/** Result uncertainty and physical occupancy are different facts. Reuse the
+ * recorded process generation and resource scanner, without rewriting the Job
+ * or treating acknowledgement as stop evidence. Every cleanup reads this anew.
+ */
+export function jobCleanupBlocker(job, home, phase = "before-removal") {
+    if (job.status === "queued" || job.status === "running")
+        return `DurableJob is ${job.status}.`;
+    if (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined) {
+        return "Unknown Job result requires explicit acknowledgement.";
+    }
+    if (job.status !== "unknown-needs-attention" && job.startedAt === undefined
+        && job.process === undefined && job.operation.effect === "none")
+        return undefined;
+    if (job.process === undefined || home === undefined) {
+        return "Job has no exact process/Home evidence for physical inspection.";
+    }
+    try {
+        if (processGenerationIsLive(job.process.pid, job.process.startIdentity)) {
+            return "The exact Job runner process is still live.";
+        }
+        // A reusable idle Role can share this workspace. Its exact-owner stop is
+        // allowed only after result/runner checks; path references must then be
+        // rechecked before any child deletion or ordinary archive commit.
+        if (phase === "before-role-stop")
+            return undefined;
+        // Steps may outlive a killed runner. Their cwd, logs and isolated runtime
+        // paths remain protective references; no process is signalled here.
+        const paths = [job.workspace, join(resolve(home), "artifacts", "jobs", job.taskId, job.id),
+            ...["TMPDIR", "XDG_DATA_HOME", "XDG_CACHE_HOME"].flatMap(key => {
+                const path = job.env[key];
+                return path !== undefined && isAbsolute(path) ? [path] : [];
+            })];
+        const serialized = job.env[YUI_TASK_RUNTIME_ISOLATION_DESCRIPTOR];
+        if (serialized !== undefined) {
+            const descriptor = parseTaskRuntimeIsolationDescriptor(serialized);
+            const owner = descriptor.workspace.owner;
+            if (descriptor.taskId !== job.taskId || descriptor.workspace.root !== job.workspace
+                || owner.type !== job.owner.kind
+                || (owner.type === "integration-attempt" && job.owner.kind === "integration-attempt"
+                    && owner.integrationAttemptId !== job.owner.integrationAttemptId)
+                || (owner.type === "work-item" && job.owner.kind === "work-item"
+                    && owner.workItemId !== job.owner.workItemId)) {
+                return "Job runtime descriptor does not match its exact owner/workspace.";
+            }
+            const claims = inspectTaskRuntimeCleanupClaims(descriptor);
+            const uncertain = claims.find(claim => claim.ownership !== "owned" || claim.state !== "inactive");
+            if (uncertain !== undefined)
+                return `Job runtime cleanup claim is unverified: ${uncertain.id}.`;
+            // cwd/fd references follow rename, unlike the recorded environment.
+            // Use the same exact claim inventory as deletion, before archive commits.
+            paths.push(descriptor.roots.runtime, ...claims.map(claim => claim.id));
+        }
+        const scan = scanProcessPathRefs(paths);
+        if (scan.diagnostics.some(diagnostic => diagnostic.severity === "error")
+            || [...scan.refs.values()].some(refs => refs.length > 0)) {
+            return "Job workspace/log/runtime references are still live or unverified.";
+        }
+    }
+    catch (error) {
+        return `Job physical inspection is unavailable: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    return undefined;
+}

package/dist/job/jobRunner.js

@@ -12,6 +12,7 @@ import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, ut
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { jobStepDirectory } from "./stepDirectory.js";
+import { prepareHttpPreview, isHttpPreview } from "./httpPreview.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
 const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
@@ -108,6 +109,7 @@ export async function runDurableJobRunner(specPath) {
     let exitCode = 0;
     let signal = null;
     let failedStep;
+    let preview;
     try {
         for (let index = 0; index < spec.steps.length; index += 1) {
             if (cancelled || existsSync(cancelPath)) {
@@ -134,13 +136,16 @@ export async function runDurableJobRunner(specPath) {
                 const stepEnv = step.env === undefined
                     ? spec.env
                     : { ...spec.env, ...step.env };
+                const launchEnv = isHttpPreview(spec.env)
+                    ? { ...stepEnv, YUI_PREVIEW_SOCKET: (preview ??= prepareHttpPreview(artifactDir)).socket }
+                    : stepEnv;
                 // f4: a new process group (detached) lets the runner kill the whole
                 // step tree on timeout or cancel, for both argv and shell forms.
                 if (step.argv !== undefined) {
                     const [file, ...args] = step.argv;
                     child = spawn(file, args, {
                         cwd: stepCwd,
-                        env: stepEnv,
+                        env: launchEnv,
                         stdio: ["ignore", logFd, logFd],
                         detached: true
                     });
@@ -148,13 +153,14 @@ export async function runDurableJobRunner(specPath) {
                 else {
                     child = spawn("/bin/sh", ["-lc", step.command], {
                         cwd: stepCwd,
-                        env: stepEnv,
+                        env: launchEnv,
                         stdio: ["ignore", logFd, logFd],
                         detached: true
                     });
                 }
             }
             catch (error) {
+                writeFileSync(logFd, `Unable to start Job step: ${error instanceof Error ? error.message : String(error)}\n`);
                 closeSync(logFd);
                 completedSteps.push({
                     name: step.name,
@@ -231,6 +237,10 @@ export async function runDurableJobRunner(specPath) {
     }
     finally {
         clearInterval(heartbeatTimer);
+        // The foreground step has settled. Withdraw only its exact endpoint;
+        // existing Job/resource checks still own surviving descendant evidence.
+        // Failed socket cleanup retains evidence instead of publishing success.
+        preview?.cleanup();
         // f2/rr5: Do NOT remove the signal handlers here. A repeated SIGTERM
         // between the step loop and the exit.json write must still hit the
         // idempotent handler (which ignores it) rather than the default handler

package/dist/kernel/builtinCapabilities.js

@@ -59,7 +59,8 @@ const definitions = [
     {
         name: "artifact.save", summary: "Save a file artifact by relativePath into the Task's local Git repository; returns a commit-pinned reference.",
         effect: "local-mutation", requiredPermissions: ["task:read"], source: "artifacts.saveArtifactCapability",
-        inputSchema: object({ taskId: text, relativePath: text, content: { type: "string" }, message: text, expectedHead: text }, ["taskId", "relativePath", "content"]),
+        inputSchema: object({ taskId: text, relativePath: text, content: { type: "string" },
+            encoding: { enum: ["utf8", "base64"] }, message: text, expectedHead: text }, ["taskId", "relativePath", "content"]),
         outputSchema: { type: "object", required: ["taskId", "commit", "relativePath"] }
     },
     {
@@ -319,6 +320,7 @@ export function createBuiltinCapabilities(host, store, jobs, signal = () => unde
             if (name === "artifact.save")
                 return saveArtifactCapability(store.rootDirectory(), taskId, {
                     relativePath: params.relativePath, content: params.content,
+                    ...(params.encoding === undefined ? {} : { encoding: params.encoding }),
                     ...(params.message === undefined ? {} : { message: params.message }),
                     ...(params.expectedHead === undefined ? {} : { expectedHead: params.expectedHead })
                 });

package/dist/message/message.js

@@ -42,6 +42,9 @@ export function createTaskMessage(id, taskId, body, kind, author, now, context =
             : { inputControl: {
                     action: context.inputControl.action,
                     requestId: requireSafeIdentity(context.inputControl.requestId, "Message input requestId"),
+                    ...(context.inputControl.expectedSessionId === undefined ? {} : {
+                        expectedSessionId: requireText(context.inputControl.expectedSessionId, "Message Session")
+                    }),
                     ...(context.inputControl.expectedTarget === undefined
                         ? {} : { expectedTarget: requireText(context.inputControl.expectedTarget, "Message input expectedTarget") })
                 } }),
@@ -236,6 +239,8 @@ export function validateTaskMessage(message) {
             throw new Error(`Message input action is invalid: ${String(message.inputControl.action)}.`);
         }
         requireSafeIdentity(message.inputControl.requestId, "Message input requestId");
+        if (message.inputControl.expectedSessionId !== undefined)
+            requireText(message.inputControl.expectedSessionId, "Message Session");
         if (message.inputControl.expectedTarget !== undefined) {
             requireText(message.inputControl.expectedTarget, "Message input expectedTarget");
             if (message.inputControl.action !== "steer") {
@@ -317,7 +322,11 @@ export function validateTaskMessage(message) {
             throw new Error("A recipient requires an exact WorkItem or ReviewRound.");
         }
     }
-    if (message.continuation !== undefined && message.recipient?.ownerRunId === undefined) {
+    const selectedSessionNondelivery = message.inputControl?.action === "queue"
+        && message.inputControl.expectedSessionId !== undefined
+        && message.continuation?.runId === undefined
+        && message.continuation?.notDeliveredReason !== undefined;
+    if (message.continuation !== undefined && message.recipient?.ownerRunId === undefined && !selectedSessionNondelivery) {
         throw new Error("Message continuation requires an owner Assignment.");
     }
     if (message.continuation?.runId !== undefined) {
@@ -373,6 +382,9 @@ export function createGlobalRoleMessage(id, roleName, body, kind, author, now, c
             : { inputControl: {
                     action: context.inputControl.action,
                     requestId: requireSafeIdentity(context.inputControl.requestId, "Message input requestId"),
+                    ...(context.inputControl.expectedSessionId === undefined ? {} : {
+                        expectedSessionId: requireText(context.inputControl.expectedSessionId, "Message Session")
+                    }),
                     ...(context.inputControl.expectedTarget === undefined
                         ? {} : { expectedTarget: requireText(context.inputControl.expectedTarget, "Message input expectedTarget") })
                 } }),
@@ -404,6 +416,8 @@ export function validateGlobalRoleMessage(message) {
             throw new Error(`Message input action is invalid: ${String(message.inputControl.action)}.`);
         }
         requireSafeIdentity(message.inputControl.requestId, "Message input requestId");
+        if (message.inputControl.expectedSessionId !== undefined)
+            requireText(message.inputControl.expectedSessionId, "Message Session");
         if (message.inputControl.expectedTarget !== undefined) {
             requireText(message.inputControl.expectedTarget, "Message input expectedTarget");
             if (message.inputControl.action !== "steer") {

package/dist/output/rolePresentation.js

@@ -22,7 +22,10 @@ export function renderRoleLaunchComparison(role, effective) {
             permission(binding),
             current.defaultAccess
         ];
-    }), defaultTableWidth());
+    }), defaultTableWidth()) + "\n\nSkill package evidence:\n" + (effective.skillPackages === undefined
+        ? "  Legacy / externally recorded: complete package versions were not recorded."
+        : effective.skillPackages.map(skill => `  ${skill.id} @ ${skill.digest}\n    ${skill.source.kind}: ${skill.source.path}\n`
+            + `    ${skill.fileCount} files; ${skill.byteSize} bytes; inventory: ${skill.manifestPath}`).join("\n"));
 }
 export function activeRoleSummary(role) {
     const binding = role.agentBindings[role.activeAgentId];

package/dist/repository/executionLaneGitSnapshot.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { isDeepStrictEqual } from "node:util";
+import { supportedGit } from "./gitCompatibility.js";
 /**
  * Freeze the exact committed heads of a durable managed Lane workspace at the
  * synchronous runtime-terminalization boundary, before opening the result
@@ -67,7 +68,7 @@ export function snapshotExecutionLaneWorkspaceSync(store, workspace) {
 }
 function git(cwd, args) {
     try {
-        return execFileSync("git", args, {
+        return execFileSync(supportedGit().path, args, {
             cwd,
             encoding: "utf8",
             timeout: 5_000,

package/dist/repository/gitCompatibility.js

@@ -0,0 +1,62 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import { resolveExecutable } from "../external/pinnedCommandRunner.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";
+export function gitVersionSupport(output) {
+    const match = /^git version (\d+)\.(\d+)(?:\.(\d+))?(?:[.\s-].*)?$/u.exec(output.trim());
+    const version = match === null ? "unknown" : `${match[1]}.${match[2]}.${match[3] ?? "0"}`;
+    const supported = match !== null && (Number(match[1]) > 2
+        || (Number(match[1]) === 2 && Number(match[2]) >= 29));
+    return {
+        version, supported,
+        detail: `Git ${version}; requires >= ${MINIMUM_GIT_VERSION} (isolated fetch without writing FETCH_HEAD). `
+            + "Read-only version check; repository permissions, transport and server capabilities are not tested."
+    };
+}
+let cached;
+/** Pin the executable checked, reusing only an unchanged on-disk identity. */
+export function supportedGit() {
+    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.");
+    const path = realpathSync(selected);
+    const stat = statSync(path);
+    const identity = `${path}:${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+    if (cached?.identity === identity)
+        return cached;
+    const output = execFileSync(path, ["--version"], {
+        encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "pipe"]
+    });
+    const support = gitVersionSupport(output);
+    if (!support.supported) {
+        throw new Error(`${path}: ${support.detail} No Git operation was started by this call. `
+            + "Select a supported Git in PATH, run doctor, then retry; existing resources are retained.");
+    }
+    cached = { identity, path, version: support.version };
+    return cached;
+}
+/** Git paths are relative to the actual -C directory, not the Node process. */
+export function gitOutputLine(output) {
+    if (!output.endsWith("\n") || output.length === 1 || output.includes("\0")) {
+        throw new Error("Git returned an invalid path or line.");
+    }
+    // Remove exactly Git's record terminator, never spaces/tabs in a path.
+    return output.slice(0, -1);
+}
+/** rev-parse --verify accepts exactly one validated operand on old Git.
+ * Keep option-looking data out before removing the newer option terminator.
+ */
+export function compatibleGitArguments(args) {
+    const marker = args.indexOf("--end-of-options");
+    if (marker < 0)
+        return [...args];
+    const operand = args[marker + 1];
+    if (!args.includes("rev-parse") || !args.includes("--verify")
+        || marker !== args.length - 2 || operand === undefined
+        || operand.length === 0 || operand.startsWith("-") || /[\0\r\n]/u.test(operand)) {
+        throw new Error("Unsafe Git revision operand; no Git operation was started.");
+    }
+    return [...args.slice(0, marker), operand];
+}