@zq-silk/yui 2.3.0 → 2.5.0

package/dist/executor/fileRoleLaunchPlanner.js

@@ -9,7 +9,7 @@ import { assertExecutionEnvironmentCurrent } from "../runtime/executionEnvironme
 import { configuredAgentToDefinition, resolveAgentEnvironment } from "../agent/agent.js";
 import { NATIVE_AGENT_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, operationalAgentEnvironment, selectEnvironment } from "../agent/launchEnvironment.js";
 import { compileRoleSessionContext, roleSessionKind } from "../context/roleSessionContext.js";
-import { materializeSessionBootstrap } from "../context/sessionBootstrapManifest.js";
+import { materializeSessionBootstrap, sessionContextInstructions } from "../context/sessionBootstrapManifest.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 import { activeRoleAgentBinding } from "../role/role.js";
 import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
@@ -70,11 +70,13 @@ export class FileRoleLaunchPlanner {
     }
     /** Recovery addresses the recorded Agent/Session, independent of delivery
      * admission, a missing worktree, or the old Endpoint code generation. */
-    planNativeControl(owner) {
+    planNativeControl(owner, nativeSessionId) {
         const set = owner.scope === "task"
             ? this.store.getTaskRoleSessionSet(owner.taskId, owner.roleName)
             : this.store.getGlobalRoleSessionSet(owner.roleName);
-        const session = roleSessionControlTarget(set);
+        const session = nativeSessionId === undefined ? roleSessionControlTarget(set)
+            : [...Object.values(set?.sessions ?? {}), ...Object.values(set?.history ?? {})]
+                .find(entry => entry.nativeSessionId === nativeSessionId);
         if (session?.adapterId !== "codex")
             throw new Error("Native metadata control requires a recorded Codex Session.");
         const configured = this.store.getConfiguredAgent(session.agentId);
@@ -229,7 +231,7 @@ export class FileRoleLaunchPlanner {
             throw new Error("Global Role has an unmanaged live Session. Stop that exact Session before opening controlled input; it will not be silently replaced.");
         }
         const resolvedEffective = activeLiveRoleAgentSession(sessionSet)?.effective
-            ?? resolveEffectiveLaunch({ role, purpose: "execution" });
+            ?? resolveEffectiveLaunch({ store: this.store, role, purpose: "execution" });
         if (input.effective !== undefined
             && !isDeepStrictEqual(resolvedEffective, input.effective)) {
             throw new Error(`Global Role launch effective snapshot changed: ${role.name}.`);
@@ -335,7 +337,12 @@ export class FileRoleLaunchPlanner {
         Object.assign(launchEnvironment, runtimeIsolation === undefined
             ? {}
             : taskRuntimeIsolationEnvironment(runtimeIsolation));
-        const baseSessionContext = compileRoleSessionContext(this.home, launchRole, owner, sessionPolicy);
+        const skillPackages = input.mode === "resume"
+            ? existingSession?.effective.skillPackages : effective.skillPackages;
+        if (skillPackages === undefined) {
+            throw new Error("This launch has no frozen Skill package evidence (pre-1.5 or externally recorded Session). Create a new Session from current Role configuration; historical Skill versions cannot be reconstructed.");
+        }
+        const baseSessionContext = compileRoleSessionContext(this.home, launchRole, owner, { ...sessionPolicy, skillPackages });
         const bootstrap = materializeSessionBootstrap({
             yuiHome: this.home,
             role: launchRole,
@@ -351,7 +358,7 @@ export class FileRoleLaunchPlanner {
         }
         const sessionContext = {
             ...baseSessionContext,
-            developerInstructions: `Read and follow the exact Yui Session Manifest at ${bootstrap.manifestPath}.`,
+            developerInstructions: sessionContextInstructions(bootstrap.manifestPath, bootstrap.manifest.digest),
             managedContextFile: bootstrap.manifestPath,
             sessionManifestPath: bootstrap.manifestPath,
             sessionManifestDigest: bootstrap.manifest.digest
@@ -686,7 +693,7 @@ function resolveTaskRoleEffectiveLaunch(store, role, purpose = "execution") {
     if (purpose === "planning") {
         // Planning has no WorkItem assignment and no managed workspace, so it
         // resolves the Role's own configured workspace with no writable Project.
-        return resolveEffectiveLaunch({ role, purpose: "planning" });
+        return resolveEffectiveLaunch({ store, role, purpose: "planning" });
     }
     const item = store.listWorkItems(role.taskId).find((candidate) => (candidate.assignee === role.name
         && !["accepted", "retired"].includes(candidate.status))) ?? null;
@@ -696,6 +703,7 @@ function resolveTaskRoleEffectiveLaunch(store, role, purpose = "execution") {
         ?? store.getTaskWorkspace(role.taskId)
         ?? undefined;
     return resolveEffectiveLaunch({
+        store,
         role,
         purpose: "execution",
         ...(workspace === undefined ? {} : { workspace }),

package/dist/integration/gitIntegrationService.js

@@ -5,6 +5,8 @@ import { promisify } from "node:util";
 import { selectEnvironment } from "../agent/launchEnvironment.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";
@@ -1047,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
@@ -1182,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/interaction/notificationPresentation.js

@@ -0,0 +1,85 @@
+import { parseWakeReason } from "../scheduler/wakeReason.js";
+/** Optional producer-authored presentation, stored in the original text, not a
+ * parsed business outcome or a second fact store. Reject oversized summaries
+ * whole: clipping could remove a failure/authority qualifier. */
+export function authoredNotificationSummary(text) {
+    const line = text?.trimStart().split(/\r?\n/u, 1)[0];
+    if (!line?.startsWith("Yui-Summary: "))
+        return undefined;
+    const summary = line.slice("Yui-Summary: ".length).trim();
+    return summary.length > 0 && Buffer.byteLength(summary) <= 512
+        && !/[\u0000-\u001f\u007f]/u.test(summary) ? summary : undefined;
+}
+export function taskMessagePresentation(message, getRun) {
+    const run = message.resultRef?.type === "agent-run-result"
+        ? getRun(message.taskId, message.resultRef.runId) : null;
+    const summary = authoredNotificationSummary(run?.result?.output ?? message.body);
+    const fact = run !== null
+        ? `${run.purpose === "review" ? "Review" : "Execution"} result returned (${run.status}); disposition pending`
+        : message.kind === "role-result" ? "Role result returned; disposition pending"
+            : message.kind === "user" || message.kind === "operator" ? "Additional input received"
+                : "System message received";
+    return {
+        fact,
+        ...(summary === undefined ? {} : {
+            summary, summarySource: run?.result?.output === undefined ? "message-body" : "agent-run-result"
+        })
+    };
+}
+export function wakeChangeLabels(reasons) {
+    return [...new Set(reasons.map(tag => {
+            const { kind } = parseWakeReason(tag);
+            switch (kind) {
+                case "operator-input":
+                case "user-message":
+                case "interrupt-then": return "Additional input received";
+                case "execution-started": return "Task execution enabled";
+                case "task-created": return "Task created";
+                case "task-reopened": return "Task reopened; check for scoped follow-up";
+                case "role-result": return "Role result returned; disposition pending";
+                case "review-failed": return "Review execution failed; inspect original failure";
+                case "agent-error":
+                case "leader-turn-failed":
+                case "role-turn-failed": return "Execution failure needs attention";
+                case "job-finished": return "Job ended; inspect outcome";
+                case "input-timeout": return "Input deadline reached; inspect recorded decision";
+                case "notification-retry": return "Notification retry after recorded correction";
+                default: return Buffer.byteLength(kind) <= 120 && !/[\u0000-\u001f\u007f]/u.test(kind)
+                    ? `Recorded update: ${kind}` : "Other recorded update; inspect wake";
+            }
+        }))];
+}
+export function wakeMessages(wake, messages) {
+    const ids = new Set(wake.refs?.filter(ref => ref.type === "message" && ref.taskId === wake.taskId).map(ref => ref.id));
+    const from = Date.parse(wake.fromCursor), to = Date.parse(wake.toCursor);
+    return messages.filter(message => ids.has(message.id)
+        || Date.parse(message.createdAt) > from && Date.parse(message.createdAt) <= to);
+}
+export function taskNotificationPresentation(wake, store) {
+    const messages = wakeMessages(wake, store.listMessages(wake.taskId));
+    const labels = wakeChangeLabels(wake.reasons);
+    return [
+        `Yui Task notification: task=${wake.taskId} wake=${wake.id}.`,
+        `Changes: ${labels.slice(0, 4).join("; ")}${labels.length > 4 ? "; more in wake" : ""}.`,
+        ...messages.slice(0, 4).map(message => {
+            const item = taskMessagePresentation(message, (task, run) => store.getRun(task, run));
+            return `- ${message.id} [${message.author.type}${message.author.type === "role" ? `:${message.author.roleName}` : ""}]: ${item.fact}.`
+                + (item.summary === undefined ? "" : ` Author summary (${item.summarySource}): ${JSON.stringify(item.summary)}`);
+        }),
+        ...(messages.length > 4 ? [`${messages.length - 4} more messages in the fixed wake.`] : []),
+        `Refresh: yui task context ${wake.taskId} --json`,
+        `Read inputs/results: yui task wake show ${wake.taskId} ${wake.id} --json`,
+        "Apply yui-leader (from the current Manifest); read relevant originals in full and advance authorized work."
+    ].join("\n");
+}
+export function globalMessagePresentation(roleName, messageId, message) {
+    const summary = authoredNotificationSummary(message?.body);
+    return [
+        `Yui Global Message: role=${roleName} message=${messageId}.`,
+        `Changes: ${message?.author.type ?? "Recorded"} input received.`,
+        ...(summary === undefined ? [] : [`Author summary (message-body): ${JSON.stringify(summary)}`]),
+        "Refresh Session Context using the current Manifest's loadCommand.",
+        `Read original: yui role message show ${roleName} ${messageId} --json`,
+        `Apply ${roleName === "operator" ? "yui-operator" : "yui-runtime"} from the current Manifest within existing authority.`
+    ].join("\n");
+}

package/dist/interaction/operatorPresentation.js

@@ -10,8 +10,7 @@ export function createOperatorBatchPresentation(batchId, items) {
         receiptId: `operator-batch:${batchId}`,
         text: [
             "[Yui updates]",
-            "Yui recorded the following durable updates. Inspect the referenced records and present only information that changes the user's understanding, authorization, or next action.",
-            "This notification is not a new execution assignment or authorization to replay prior operations.",
+            "Apply yui-operator from the current Manifest: inspect these originals and present material changes or decisions.",
             ...items.flatMap(renderItem)
         ].join("\n")
     };

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/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];
+}