@zq-silk/yui 2.22.0 → 2.25.0

package/README.md

@@ -5,7 +5,7 @@
 [![Core CI](https://github.com/zhangqian-silk/yui/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/zhangqian-silk/yui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 ![Node](https://img.shields.io/badge/node-20%20%7C%2022%20%7C%2024-brightgreen.svg)
-![Platform](https://img.shields.io/badge/platform-Linux%20x64%20%28glibc%29%20%7C%20macOS%20x64%2Farm64-blue.svg)
+![Platform](https://img.shields.io/badge/platform-Linux%20x64%20%28glibc%29%20%7C%20macOS%20arm64-blue.svg)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
 
 Give your Agents work to carry forward, not just another chat to answer.
@@ -46,15 +46,20 @@ For the self-built coding Agent (without a Controller or Yui Home), see
 [`yui agent`](docs/native-agent.md). Its explicit configuration and product state
 are separate from the orchestration setup below.
 
-You need Linux x64 (glibc) or macOS (x64 or Apple Silicon), Git 2.29.0 or newer, tmux, and
+You need Linux x64 (glibc) or macOS Apple Silicon with native arm64 Node.js, Git 2.29.0 or newer, tmux, and
 Node.js `^20.17.0`, `^22.9.0`, `^24.0.0` or `^26.0.0`. On macOS install tmux with
 `brew install tmux`. For the simplest setup, have Codex CLI or Claude Code CLI
 installed and ready to use with your own account. Yui coordinates those
 Agents; it does not supply model access.
 
-The npm package includes prebuilt Yui helpers for Linux x64, Mac Intel and
-Apple Silicon. The same package is tested on all three platforms before
+The npm package includes prebuilt Yui helpers for Linux x64 and macOS
+Apple Silicon. The same package is tested on both platforms before
 publication; Yui selects only the helper for the running platform.
+Starting with 2.25.0, macOS Intel and x64 Node.js under Rosetta are unsupported.
+Intel Mac users must stay on 2.23.0; Apple Silicon users must switch to native
+arm64 Node.js. npm's OS/CPU fields cannot express these platform pairs, so npm
+installation may succeed on an unsupported combination, but Yui rejects it
+before loading either CLI product or opening the Home. No install scripts are added.
 
 For Claude, Yui passes through your authentication environment and native
 configuration directory; Claude selects the API key or login method using its

package/dist/artifacts/artifactCapability.js

@@ -32,13 +32,13 @@ function requireTextContent(content) {
  * `artifact.save`: write `content` to `relativePath` in the Task's local repo,
  * commit exactly that path, and return the resulting commit-pinned reference.
  */
-export async function saveArtifactCapability(home, taskId, input) {
+export async function saveArtifactCapability(home, taskId, input, getConfig) {
     const bytes = artifactInputBytes(input);
     return saveArtifactFile(home, taskId, {
         relativePath: input.relativePath, bytes,
         ...(input.message === undefined ? {} : { message: input.message }),
         ...(input.expectedHead === undefined ? {} : { expectedHead: input.expectedHead })
-    });
+    }, getConfig);
 }
 /** Shared bounded text/static-image input; never executes HTML or scripts. */
 export function artifactInputBytes(input) {
@@ -66,8 +66,8 @@ export function artifactInputBytes(input) {
  * frozen evidence. Images return explicit base64 and bounded raster metadata;
  * text returns UTF-8. Both carry the resolved commit and exact digest.
  */
-export async function readArtifactCapability(home, taskId, input) {
-    const repo = openTaskArtifactRepository(home, taskId);
+export async function readArtifactCapability(home, taskId, input, getConfig) {
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     if (!repo.exists())
         throw new Error(`Artifact repository is unavailable for ${taskId}.`);
     const safeRelative = safeRelativeArtifactPath(input.relativePath);
@@ -101,8 +101,8 @@ export function presentArtifactContent(content) {
  * `artifact.list`: tracked artifacts at HEAD (empty when the Task has no repo
  * yet). This is an ordinary current read; it does not freeze anything.
  */
-export async function listArtifactsCapability(home, taskId) {
-    const repo = openTaskArtifactRepository(home, taskId);
+export async function listArtifactsCapability(home, taskId, getConfig) {
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     if (!repo.exists())
         return [];
     return repo.list();

package/dist/artifacts/gitArtifactRef.js

@@ -67,9 +67,9 @@ export function parseGitArtifactRef(value, taskId) {
  * though for a correctly pinned commit this can only happen if the recorded
  * digest was wrong, since the commit freezes the bytes.
  */
-export async function resolveGitArtifact(home, ref) {
+export async function resolveGitArtifact(home, ref, getConfig) {
     const valid = validateGitArtifactRef(ref);
-    const repo = openTaskArtifactRepository(home, valid.taskId);
+    const repo = openTaskArtifactRepository(home, valid.taskId, getConfig);
     if (!repo.exists()) {
         throw new Error(`Artifact repository is unavailable for ${valid.taskId}.`);
     }
@@ -88,8 +88,8 @@ export async function resolveGitArtifact(home, ref) {
  * for the resulting state. The returned reference is self-certifying, so a
  * caller can record it directly as frozen evidence.
  */
-export async function saveArtifactFile(home, taskId, input) {
-    const repo = openTaskArtifactRepository(home, taskId);
+export async function saveArtifactFile(home, taskId, input, getConfig) {
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     const relativePath = safeRelativeArtifactPath(input.relativePath);
     const result = await repo.save({
         files: [{ relativePath, bytes: input.bytes }],
@@ -105,15 +105,15 @@ export async function saveArtifactFile(home, taskId, input) {
         digest: content.digest
     });
 }
-export async function readCurrentArtifact(home, taskId, relativePath) {
-    const repo = openTaskArtifactRepository(home, taskId);
+export async function readCurrentArtifact(home, taskId, relativePath, getConfig) {
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     if (!repo.exists())
         throw new Error(`Artifact repository is unavailable for ${taskId}.`);
     return repo.read(safeRelativeArtifactPath(relativePath));
 }
 /** Ordinary listing: tracked artifacts at HEAD (ASYNC, not frozen). Empty when no repo yet. */
-export async function listCurrentArtifacts(home, taskId) {
-    const repo = openTaskArtifactRepository(home, taskId);
+export async function listCurrentArtifacts(home, taskId, getConfig) {
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     if (!repo.exists())
         return [];
     return repo.list();
@@ -123,8 +123,8 @@ export async function listCurrentArtifacts(home, taskId) {
  * references (ASYNC). Used at Candidate submission / completion time to capture
  * exactly what exists now. Fails if any path is not tracked at HEAD.
  */
-export async function pinCurrentArtifacts(home, taskId, relativePaths) {
-    const repo = openTaskArtifactRepository(home, taskId);
+export async function pinCurrentArtifacts(home, taskId, relativePaths, getConfig) {
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     if (!repo.exists())
         throw new Error(`Artifact repository is unavailable for ${taskId}.`);
     const head = await repo.head();

package/dist/artifacts/jobArtifact.js

@@ -57,7 +57,7 @@ export function jobArtifactOwner(run) {
 }
 /** Each Run has a distinct working tree and commit fence even for identical paths.
  * The retained storage is unrelated to execution workspaces/logs/checkpoints. */
-export function openJobArtifactRepository(home, owner, sourceRun) {
+export function openJobArtifactRepository(home, owner, sourceRun, getConfig) {
     validateScope(owner.scope);
     validateScope(sourceRun.scope);
     if (!isDeepStrictEqual(owner.scope, sourceRun.scope))
@@ -65,13 +65,13 @@ export function openJobArtifactRepository(home, owner, sourceRun) {
     const scopePath = owner.scope.kind === "global" ? ["global"] : ["task", owner.scope.taskId];
     const path = join(home, "job-artifacts", ...scopePath, identity(owner.jobId), identity(sourceRun.runId));
     const lockKey = `job-${createHash("sha256").update(JSON.stringify([jobScopeKey(owner.scope), owner.jobId, sourceRun.runId])).digest("hex")}`;
-    return openVersionedArtifactRepository(home, lockKey, path);
+    return openVersionedArtifactRepository(home, lockKey, path, getConfig);
 }
-export async function readJobArtifactReference(home, ref) {
+export async function readJobArtifactReference(home, ref, getConfig) {
     validateJobArtifactReference(ref);
     const repo = ref.owner.kind === "task"
-        ? openTaskArtifactRepository(home, ref.owner.taskId)
-        : openJobArtifactRepository(home, ref.owner, ref.sourceRun);
+        ? openTaskArtifactRepository(home, ref.owner.taskId, getConfig)
+        : openJobArtifactRepository(home, ref.owner, ref.sourceRun, getConfig);
     const content = await repo.read(ref.relativePath, ref.version);
     if (content.digest !== ref.digest)
         throw new Error("Artifact digest mismatch; preserved evidence was not replaced.");

package/dist/artifacts/managedGit.js

@@ -1,7 +1,6 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { supportedGit } from "../repository/gitCompatibility.js";
-const executeFile = promisify(execFile);
+import { executeGitCommand, GitCommandError, LOCAL_GIT_TIMEOUT_MS } from "../repository/gitCommand.js";
+import { resolveGitLocalTimeoutSeconds } from "../config/gitConfig.js";
 /**
  * Hardened, isolated Git runner for per-Task artifact repositories.
  *
@@ -65,7 +64,9 @@ export class ManagedGitError extends Error {
     stderr;
     args;
     constructor(args, stderr, cause) {
-        super(stderr.length === 0 ? "Managed git command failed." : `Managed git command failed: ${stderr}`, { cause });
+        super(cause instanceof Error
+            ? cause.message.replace(/^Git command/u, "Managed git command")
+            : stderr.length === 0 ? "Managed git command failed." : `Managed git command failed: ${stderr}`, { cause });
         this.name = "ManagedGitError";
         this.stderr = stderr;
         this.args = args;
@@ -124,14 +125,14 @@ function assertSafeArguments(args) {
  */
 async function spawnManagedGit(repoPath, args, options) {
     assertSafeArguments(args);
-    const program = supportedGit();
+    const timeoutMs = options?.timeoutMs ?? (options?.getConfig === undefined
+        ? LOCAL_GIT_TIMEOUT_MS : resolveGitLocalTimeoutSeconds(options.getConfig().gitLocalTimeoutSeconds) * 1_000);
+    const program = supportedGit(timeoutMs);
     try {
-        const result = await executeFile(program.path, [...HARDENING_FLAGS, "-C", repoPath, ...args], {
-            encoding: "buffer",
-            env: managedGitEnvironment(),
+        const result = await executeGitCommand(program.path, [...HARDENING_FLAGS, "-C", repoPath, ...args], {
+            environment: managedGitEnvironment(),
             maxBuffer: options?.maxBuffer ?? 16 * 1024 * 1024,
-            timeout: options?.timeoutMs ?? 30_000,
-            windowsHide: true
+            budget: { totalMs: timeoutMs }
         });
         return { stdout: result.stdout, stderr: result.stderr };
     }
@@ -160,14 +161,16 @@ export async function managedGitBuffer(repoPath, args, options) {
     const { stdout } = await spawnManagedGit(repoPath, args, options);
     return stdout;
 }
-/** Run a managed Git command purely for its exit status; never throws on non-zero. */
+/** Return false for a completed non-zero exit, but preserve timeouts/process failures. */
 export async function managedGitSucceeds(repoPath, args, options) {
     try {
         await spawnManagedGit(repoPath, args, options);
         return true;
     }
     catch (error) {
-        if (error instanceof ManagedGitError)
+        if (error instanceof ManagedGitError && error.cause instanceof GitCommandError
+            && error.cause.timeoutKind === undefined && error.cause.signal === null
+            && typeof error.cause.code === "number")
             return false;
         throw error;
     }

package/dist/artifacts/taskArtifactRepository.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { supportedGit } from "../repository/gitCompatibility.js";
+import { resolveGitLocalTimeoutSeconds } from "../config/gitConfig.js";
 import { acquireArtifactCommitLock } from "./artifactCommitLock.js";
 import { resolveContainedArtifactPath, safeRelativeArtifactPath, taskArtifactRepoPath } from "./artifactPaths.js";
 import { ManagedGitError, externalProgramConfigViolations, managedGit, managedGitBuffer, managedGitSucceeds, requireCommitId } from "./managedGit.js";
@@ -88,14 +89,14 @@ export class ArtifactHeadConflictError extends Error {
  * (e.g. `store.rootDirectory()`), so ownership is derived from the Task, never
  * from ambient state.
  */
-export function openTaskArtifactRepository(home, taskId) {
+export function openTaskArtifactRepository(home, taskId, getConfig) {
     const repoPath = taskArtifactRepoPath(home, taskId);
-    const repo = openVersionedArtifactRepository(home, taskId, repoPath);
+    const repo = openVersionedArtifactRepository(home, taskId, repoPath, getConfig);
     return { ...repo, taskId, save: async (input) => ({ ...await repo.save(input), taskId }) };
 }
 /** Shared local-only storage. Callers derive paths from validated owning identities,
  * never from a user-supplied filesystem location. Task layout/commits stay intact. */
-export function openVersionedArtifactRepository(home, key, repoPath) {
+export function openVersionedArtifactRepository(home, key, repoPath, getConfig) {
     const taskId = key; // Existing error fields retain their public spelling.
     const checkBoundary = async () => {
         await resolveContainedArtifactPath(home, `${relative(home, repoPath).split("\\").join("/")}/boundary-check`);
@@ -115,21 +116,21 @@ export function openVersionedArtifactRepository(home, key, repoPath) {
         await checkBoundary();
         if (!exists())
             return null;
-        return currentHead(repoPath);
+        return currentHead(repoPath, getConfig);
     };
     const ensureUnlocked = async () => {
         await checkBoundary();
-        supportedGit();
+        supportedGit(resolveGitLocalTimeoutSeconds(getConfig?.().gitLocalTimeoutSeconds) * 1_000);
         if (exists()) {
-            await assertNoRemote(taskId, repoPath);
+            await assertNoRemote(taskId, repoPath, getConfig);
             return;
         }
         await mkdir(repoPath, { recursive: true, mode: 0o700 });
-        await managedGit(repoPath, ["init", "-b", ARTIFACT_BRANCH]);
+        await managedGit(repoPath, ["init", "-b", ARTIFACT_BRANCH], { getConfig });
         // An empty root commit guarantees HEAD exists, so scoped per-path commits
         // and expected-HEAD checks work uniformly from the very first save.
-        await managedGit(repoPath, ["commit", "--allow-empty", "-m", "init artifact repo"]);
-        await assertNoRemote(taskId, repoPath);
+        await managedGit(repoPath, ["commit", "--allow-empty", "-m", "init artifact repo"], { getConfig });
+        await assertNoRemote(taskId, repoPath, getConfig);
     };
     const ensure = async () => {
         const release = await acquireArtifactCommitLock(home, key);
@@ -169,10 +170,10 @@ export function openVersionedArtifactRepository(home, key, repoPath) {
         const release = await acquireArtifactCommitLock(home, key);
         try {
             await ensureUnlocked();
-            await assertNoRemote(taskId, repoPath);
+            await assertNoRemote(taskId, repoPath, getConfig);
             // Expected-HEAD check under the lock: a conflict stops without writing.
             if (input.expectedHead !== undefined) {
-                const actual = await currentHead(repoPath);
+                const actual = await currentHead(repoPath, getConfig);
                 if (actual !== input.expectedHead) {
                     throw new ArtifactHeadConflictError(taskId, input.expectedHead, actual);
                 }
@@ -186,17 +187,17 @@ export function openVersionedArtifactRepository(home, key, repoPath) {
             }
             const pathspecs = prepared.map((file) => file.relativePath);
             // Stage exactly the saved paths so new files become known to Git...
-            await managedGit(repoPath, ["add", "--", ...pathspecs]);
+            await managedGit(repoPath, ["add", "--", ...pathspecs], { getConfig });
             // ...but if nothing actually changed, do not create an empty commit.
             const noChanges = await managedGitSucceeds(repoPath, [
                 "diff", "--cached", "--quiet", "--", ...pathspecs
-            ]);
+            ], { getConfig });
             if (noChanges) {
-                return { commit: await currentHead(repoPath), savedPaths: pathspecs };
+                return { commit: await currentHead(repoPath, getConfig), savedPaths: pathspecs };
             }
             // `--only <paths>` records exactly these paths; any other WIP stays WIP.
-            await managedGit(repoPath, ["commit", "--only", "-m", message, "--", ...pathspecs]);
-            return { commit: await currentHead(repoPath), savedPaths: pathspecs };
+            await managedGit(repoPath, ["commit", "--only", "-m", message, "--", ...pathspecs], { getConfig });
+            return { commit: await currentHead(repoPath, getConfig), savedPaths: pathspecs };
         }
         finally {
             release();
@@ -208,30 +209,31 @@ export function openVersionedArtifactRepository(home, key, repoPath) {
         // A pinned commit reads frozen evidence; otherwise read the current HEAD.
         // Both resolve `<commit>:<path>`, an OBJECT spec (never the working tree, so
         // a read never follows a symlink or sees unrelated WIP).
-        const pinned = await artifactCommit(repoPath, commit);
+        const pinned = await artifactCommit(repoPath, commit, getConfig);
         const objectSpec = `${pinned}:${safeRelative}`;
         // `<commit>:<path>` for a DIRECTORY resolves to a tree, and `git show` would
         // print a tree listing rather than fail — silently returning directory
         // metadata as if it were file bytes. Verify the object is a blob first, so a
         // read only ever yields real file content.
-        const objectType = (await managedGit(repoPath, ["cat-file", "-t", objectSpec]).catch((error) => {
+        const objectType = (await managedGit(repoPath, ["cat-file", "-t", objectSpec], { getConfig }).catch((error) => {
             if (error instanceof ManagedGitError) {
-                throw new Error(`Artifact ${safeRelative} is unavailable at ${pinned}.`, { cause: error });
+                throw new Error(`Artifact ${safeRelative} is unavailable at ${pinned}: ${error.message}`, { cause: error });
             }
             throw error;
         })).trim();
         if (objectType !== "blob") {
             throw new Error(`Artifact ${safeRelative} at ${pinned} is not a file (${objectType}).`);
         }
-        const size = Number((await managedGit(repoPath, ["cat-file", "-s", objectSpec])).trim());
+        const size = Number((await managedGit(repoPath, ["cat-file", "-s", objectSpec], { getConfig })).trim());
         if (!Number.isSafeInteger(size) || size > MAX_ARTIFACT_BYTES) {
             throw new Error(`Artifact ${safeRelative} exceeds the ${MAX_ARTIFACT_BYTES}-byte limit.`);
         }
         const bytes = await managedGitBuffer(repoPath, ["cat-file", "blob", objectSpec], {
+            getConfig,
             maxBuffer: MAX_ARTIFACT_BYTES + 4096
         }).catch((error) => {
             if (error instanceof ManagedGitError) {
-                throw new Error(`Artifact ${safeRelative} is unavailable at ${pinned}.`, { cause: error });
+                throw new Error(`Artifact ${safeRelative} is unavailable at ${pinned}: ${error.message}`, { cause: error });
             }
             throw error;
         });
@@ -246,10 +248,10 @@ export function openVersionedArtifactRepository(home, key, repoPath) {
         await checkBoundary();
         if (!exists())
             return [];
-        const pinned = await artifactCommit(repoPath, commit);
+        const pinned = await artifactCommit(repoPath, commit, getConfig);
         const output = await managedGit(repoPath, [
             "ls-tree", "-r", "-z", "--long", "--full-tree", pinned
-        ]);
+        ], { getConfig });
         const entries = [];
         for (const record of output.split("\0").filter(Boolean)) {
             // Format: "<mode> <type> <object> <size>\t<path>"
@@ -271,7 +273,7 @@ export function openVersionedArtifactRepository(home, key, repoPath) {
             return [];
         const output = await managedGit(repoPath, [
             "status", "--porcelain=v1", "--untracked-files=all", "-z"
-        ]);
+        ], { getConfig });
         // Porcelain v1 -z records: "XY <path>\0" (rename adds a second \0 field).
         const changes = [];
         for (const record of output.split("\0").filter(Boolean)) {
@@ -283,16 +285,16 @@ export function openVersionedArtifactRepository(home, key, repoPath) {
     };
     return { repoPath, ensure, exists, head, save, read, list, workingChanges };
 }
-async function currentHead(repoPath) {
-    return requireCommitId(await managedGit(repoPath, ["rev-parse", "HEAD^{commit}"]));
+async function currentHead(repoPath, getConfig) {
+    return requireCommitId(await managedGit(repoPath, ["rev-parse", "HEAD^{commit}"], { getConfig }));
 }
-async function artifactCommit(repoPath, value) {
+async function artifactCommit(repoPath, value, getConfig) {
     if (value === undefined)
-        return currentHead(repoPath);
+        return currentHead(repoPath, getConfig);
     const commit = requireCommitId(value);
-    const type = await managedGit(repoPath, ["cat-file", "-t", commit]).catch(error => {
+    const type = await managedGit(repoPath, ["cat-file", "-t", commit], { getConfig }).catch(error => {
         if (error instanceof ManagedGitError)
-            throw new Error(`Artifact commit ${commit} is unavailable.`, { cause: error });
+            throw new Error(`Artifact commit ${commit} is unavailable: ${error.message}`, { cause: error });
         throw error;
     });
     if (type.trim() !== "commit") {
@@ -306,8 +308,8 @@ async function artifactCommit(repoPath, value) {
  * program on add/diff/commit. Both are external violations — we report and stop,
  * never silently remove them.
  */
-async function assertNoRemote(taskId, repoPath) {
-    const output = await managedGit(repoPath, ["remote"]);
+async function assertNoRemote(taskId, repoPath, getConfig) {
+    const output = await managedGit(repoPath, ["remote"], { getConfig });
     const remotes = output.split("\n").map((line) => line.trim()).filter(Boolean);
     if (remotes.length > 0) {
         throw new ArtifactRemoteViolationError(taskId, remotes);
@@ -315,7 +317,7 @@ async function assertNoRemote(taskId, repoPath) {
     // A repo's own `.git/config` is read even with global/system config disabled,
     // so a committed `.gitattributes` filter paired with a repo-local
     // `filter.<n>.clean = <cmd>` would run `<cmd>` on `git add`. Detect and stop.
-    const configListZ = await managedGit(repoPath, ["config", "--local", "--list", "-z"]);
+    const configListZ = await managedGit(repoPath, ["config", "--local", "--list", "-z"], { getConfig });
     const violations = externalProgramConfigViolations(configListZ);
     if (violations.length > 0) {
         throw new ArtifactManagedConfigViolationError(taskId, violations);

package/dist/cli/commandCatalog.js

@@ -1289,8 +1289,8 @@ export const ROOT_COMMAND = buildNode({
         {
             name: "update", discovery: { surface: "public", audiences: ["public", "operator"] },
             summary: "Install the latest or an exact published Yui version after storage preflight.",
-            usage: "yui update [--version <exact-version>]",
-            options: ["--version"]
+            usage: "yui update [--version <exact-version>] | --hosts-status",
+            options: ["--version", "--hosts-status"]
         },
         {
             name: "upgrade", discovery: { surface: "public", audiences: ["public", "operator"] },

package/dist/cli/updateCommand.js

@@ -14,9 +14,16 @@ import { usageError } from "../errors/cliError.js";
  * Returns a process exit code: 0 on success or already-current, 5 on abort.
  */
 export function runUpdateCommand(args = [], environment = process.env, spawn, write = (text) => process.stdout.write(text), ports) {
-    const version = parseUpdateVersion(args);
+    const statusOnly = args.length === 1 && args[0] === "--hosts-status";
+    const version = statusOnly ? undefined : parseUpdateVersion(args);
     const home = resolveYuiHome(environment);
     const resolvedPorts = ports ?? createUpdatePorts(environment, spawn);
+    if (statusOnly) {
+        if (!resolvedPorts.hostStatus)
+            throw usageError("Host status inspection is unavailable.");
+        write(`${renderHosts(resolvedPorts.hostStatus(home)).join("\n")}\n`);
+        return 0;
+    }
     const result = runUpdate(resolvedPorts, { home, version });
     write(`${renderUpdateResult(result)}\n`);
     if (result.outcome === "aborted")
@@ -29,7 +36,12 @@ function parseUpdateVersion(args) {
     if (args.length === 2 && args[0] === "--version" && isConcreteVersion(args[1])) {
         return args[1].trim();
     }
-    throw usageError("Update usage: yui update [--version <exact-version>]");
+    throw usageError("Update usage: yui update [--version <exact-version>] | --hosts-status");
+}
+function renderHosts(hosts) {
+    return hosts.length === 0 ? ["Hosts: no recorded active Sessions."] : hosts.map(host => `Host ${host.owner.scope === "task" ? `${host.owner.taskId}/` : "global/"}${host.owner.roleName} `
+        + `(${host.nativeSessionId}): ${host.status}; loaded Host=${host.hostImplementation?.generation ?? "unreported"}; `
+        + `loaded Endpoint=${host.endpointImplementation?.generation ?? "unreported"}${host.detail ? ` — ${host.detail}` : ""}`);
 }
 /** Render an {@link UpdateResult} as concise, CLI-style text. */
 export function renderUpdateResult(result) {
@@ -66,7 +78,12 @@ export function renderUpdateResult(result) {
     return [
         rendered,
         ...(result.outcome === "updated" ? [
-            "Runtime: existing Hosts are retained, not upgraded in place. Host control capabilities and event delivery are checked separately; accepted input is never replayed."
+            result.controllerStarted ? "Controller: target startup verified." : "Controller: not started by this update.",
+            "Hosts: graceful switching is separate from installation; accepted input is never replayed.",
+            ...(result.hosts === undefined ? ["Hosts: not confirmed; existing Hosts may still run older code."]
+                : renderHosts(result.hosts)),
+            "Inspect later without reinstalling: yui update --hosts-status",
+            ...(result.hostUpgradeError === undefined ? [] : [result.hostUpgradeError])
         ] : []),
         ...(result.controllerReconciliation === undefined ? [] : [
             `Controller reconciliation: ${JSON.stringify(result.controllerReconciliation)}`

package/dist/cli/updateOrchestrator.js

@@ -250,9 +250,22 @@ function activateAndVerify(ports, staged, home, lifecycle, preflight) {
                 : restoreControllerOrReport(ports, home, lifecycle, failure);
         }
     }
+    let hosts;
+    let hostUpgradeError;
+    if (lifecycle.ensureRunning && ports.upgradeHosts) {
+        try {
+            hosts = ports.upgradeHosts(home);
+        }
+        catch (error) {
+            hostUpgradeError = `Host upgrade request outcome is unknown: ${messageOf(error)}. Inspect existing requests; do not replay inputs.`;
+        }
+    }
     return {
         outcome: "updated",
         version: staged.version,
+        ...(lifecycle.ensureRunning ? { controllerStarted: true } : {}),
+        ...(hosts === undefined ? {} : { hosts }),
+        ...(hostUpgradeError === undefined ? {} : { hostUpgradeError }),
         ...(migration?.backupPath === undefined ? {} : { backupPath: migration.backupPath })
     };
 }

package/dist/cli/updatePorts.js

@@ -236,9 +236,36 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
         },
         restoreController(home, identity) {
             restoreControllerIdentity(home, identity, environment, spawn);
+        },
+        upgradeHosts(home) {
+            if (!verifiedActivatedBinary)
+                throw new Error("Host upgrade requires the verified activated binary.");
+            const root = dirname(dirname(activatedControllerEntrypoint(verifiedActivatedBinary)));
+            return requestHosts(root, home, "runtime.upgrade-hosts", environment, spawn);
+        },
+        hostStatus(home) {
+            return requestHosts(fileURLToPath(new URL("../", import.meta.url)), home, "runtime.host-upgrade-status", environment, spawn);
         }
     };
 }
+function requestHosts(root, home, method, environment, spawn) {
+    const helper = [
+        "const [root, home] = process.argv.slice(1);",
+        "(async () => {",
+        " const { pathToFileURL } = await import('node:url');",
+        " const { callController } = await import(pathToFileURL(root + '/core/controllerClient.js').href);",
+        " const { AGENT_HOST_IMPLEMENTATION } = await import(pathToFileURL(root + '/runtime/agentHostImplementation.js').href);",
+        ` const data = await callController(home, ${JSON.stringify(method)}, { generation: AGENT_HOST_IMPLEMENTATION.generation });`,
+        " process.stdout.write(JSON.stringify({ok: true, data}));",
+        "})().catch(error => { process.stderr.write(String(error)); process.exitCode = 5; });"
+    ].join(" ");
+    const result = spawn(process.execPath, ["-e", helper, root, home], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+    const data = parseSuccessEnvelopeData(result);
+    if (result.error || result.status !== 0 || !Array.isArray(data?.hosts)) {
+        throw new Error(`Host request was not confirmed: ${result.stderr.toString("utf8")}`);
+    }
+    return data.hosts;
+}
 const UPDATE_CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
 const UPDATE_CLIENT_RUNTIME_PATH = fileURLToPath(new URL("../controller/clientRuntime.js", import.meta.url));
 const UPDATE_INVENTORY_PATH = fileURLToPath(new URL("../controller/resourceInventoryLinux.js", import.meta.url));

package/dist/cli.js

@@ -1,11 +1,19 @@
 #!/usr/bin/env node
+import { unsupportedPlatformMessage } from "./runtime/platform.js";
 // No static control-plane imports: the product never resolves/initializes Yui Home.
 const arguments_ = process.argv.slice(2);
 let commandOffset = 0;
 while (arguments_[commandOffset] === '--json')
     commandOffset++;
 const commandArguments = arguments_.slice(commandOffset);
-if (commandArguments[0] === 'agent' || (commandArguments[0] === 'help' && commandArguments[1] === 'agent')) {
+const platformFailure = unsupportedPlatformMessage();
+if (platformFailure !== undefined) {
+    process.stderr.write(`${arguments_.includes("--json")
+        ? JSON.stringify({ ok: false, code: "unsupported_platform", message: platformFailure })
+        : platformFailure}\n`);
+    process.exitCode = 1;
+}
+else if (commandArguments[0] === 'agent' || (commandArguments[0] === 'help' && commandArguments[1] === 'agent')) {
     let outputFailed = false;
     // Cover early help/config writes as well as execution UI disconnection.
     process.stdout.on('error', () => { outputFailed = true; process.exitCode = 1; });
@@ -31,4 +39,3 @@ if (commandArguments[0] === 'agent' || (commandArguments[0] === 'help' && comman
 else {
     await import('./controlPlaneCli.js');
 }
-export {};

package/dist/commands/configCommands.js

@@ -2,7 +2,7 @@ import { mkdirSync, realpathSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { CONFIG_DEFINITIONS, CONFIG_KEYS, configDefinition, configDefinitionsForDomain } from "../config/configCatalog.js";
 import { resolveTimeZone } from "../config/timeZone.js";
-import { DEFAULT_AGENT_LAUNCH_INACTIVITY_TIMEOUT_SECONDS, DEFAULT_CONTROLLER_TASK_CONCURRENCY, DEFAULT_DELIVERY_TIMEOUT_SECONDS, DEFAULT_RECONCILIATION_INTERVAL_SECONDS, DEFAULT_RESOURCES_GC_MODE, DEFAULT_RESOURCES_QUARANTINE_TTL_HOURS, DEFAULT_TMUX_HISTORY_LIMIT, reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveResourcesGcAutoQuarantine, resolveResourcesGcMode, resolveResourcesQuarantineTtlHours, resolveRuntimeHealth, resolveTelemetryEnabled, resolveTelemetryRunCap, resolveTelemetryTerminalKeep, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
+import { DEFAULT_AGENT_LAUNCH_INACTIVITY_TIMEOUT_SECONDS, DEFAULT_CONTROLLER_TASK_CONCURRENCY, DEFAULT_DELIVERY_TIMEOUT_SECONDS, DEFAULT_RECONCILIATION_INTERVAL_SECONDS, DEFAULT_RESOURCES_GC_MODE, DEFAULT_RESOURCES_QUARANTINE_TTL_HOURS, DEFAULT_TMUX_HISTORY_LIMIT, reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveGitLocalTimeoutSeconds, resolveGitRemoteInactivityTimeoutSeconds, resolveGitRemoteTimeoutSeconds, resolveResourcesGcAutoQuarantine, resolveResourcesGcMode, resolveResourcesQuarantineTtlHours, resolveRuntimeHealth, resolveTelemetryEnabled, resolveTelemetryRunCap, resolveTelemetryTerminalKeep, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
 import { usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { REVIEW_TRIGGERS } from "../review/reviewConfig.js";
@@ -75,6 +75,9 @@ export function effectiveConfigData(config, domain) {
         controllerTaskConcurrency: resolveControllerTaskConcurrency(config.controllerTaskConcurrency),
         agentLaunchInactivityTimeoutSeconds: resolveAgentLaunchInactivityTimeoutSeconds(config.agentLaunchInactivityTimeoutSeconds),
         deliveryTimeoutSeconds: resolveDeliveryTimeoutSeconds(config.deliveryTimeoutSeconds),
+        gitLocalTimeoutSeconds: resolveGitLocalTimeoutSeconds(config.gitLocalTimeoutSeconds),
+        gitRemoteInactivityTimeoutSeconds: resolveGitRemoteInactivityTimeoutSeconds(config.gitRemoteInactivityTimeoutSeconds),
+        gitRemoteTimeoutSeconds: resolveGitRemoteTimeoutSeconds(config.gitRemoteTimeoutSeconds),
         tmuxBin: resolveTmuxBin(config.tmuxBin),
         tmuxHistoryLimit: resolveTmuxHistoryLimit(config.tmuxHistoryLimit),
         telemetryEnabled: resolveTelemetryEnabled(config.telemetryEnabled),
@@ -393,6 +396,66 @@ const CONFIG_KEY_HANDLERS = [
             return `Delivery timeout reset to ${DEFAULT_DELIVERY_TIMEOUT_SECONDS} seconds\n`;
         }
     },
+    {
+        key: "git-local-timeout-seconds",
+        showLabel: "Git local total timeout",
+        showValue: (config) => `${resolveGitLocalTimeoutSeconds(config.gitLocalTimeoutSeconds)} seconds`,
+        set(args, store) {
+            const usage = "Tools config set usage: yui config tools set git-local-timeout-seconds <1-86400>.";
+            if (args.length !== 1)
+                throw usageError(usage);
+            const gitLocalTimeoutSeconds = validatedConfigValue(() => resolveGitLocalTimeoutSeconds(Number(args[0])), usage);
+            saveConfigKey(store, (config) => ({ ...config, gitLocalTimeoutSeconds }));
+            return `Git local total timeout set to ${gitLocalTimeoutSeconds} seconds\n`;
+        },
+        clear(store) {
+            saveConfigKey(store, (config) => {
+                const { gitLocalTimeoutSeconds: _removed, ...rest } = config;
+                return rest;
+            });
+            return "Git local total timeout reset to default\n";
+        }
+    },
+    {
+        key: "git-remote-inactivity-timeout-seconds",
+        showLabel: "Git remote inactivity timeout",
+        showValue: (config) => `${resolveGitRemoteInactivityTimeoutSeconds(config.gitRemoteInactivityTimeoutSeconds)} seconds`,
+        set(args, store) {
+            const usage = "Tools config set usage: yui config tools set git-remote-inactivity-timeout-seconds <1-86400>.";
+            if (args.length !== 1)
+                throw usageError(usage);
+            const gitRemoteInactivityTimeoutSeconds = validatedConfigValue(() => resolveGitRemoteInactivityTimeoutSeconds(Number(args[0])), usage);
+            saveConfigKey(store, (config) => ({ ...config, gitRemoteInactivityTimeoutSeconds }));
+            return `Git remote inactivity timeout set to ${gitRemoteInactivityTimeoutSeconds} seconds\n`;
+        },
+        clear(store) {
+            saveConfigKey(store, (config) => {
+                const { gitRemoteInactivityTimeoutSeconds: _removed, ...rest } = config;
+                return rest;
+            });
+            return "Git remote inactivity timeout reset to default\n";
+        }
+    },
+    {
+        key: "git-remote-timeout-seconds",
+        showLabel: "Git remote total timeout",
+        showValue: (config) => `${resolveGitRemoteTimeoutSeconds(config.gitRemoteTimeoutSeconds)} seconds`,
+        set(args, store) {
+            const usage = "Tools config set usage: yui config tools set git-remote-timeout-seconds <1-86400>.";
+            if (args.length !== 1)
+                throw usageError(usage);
+            const gitRemoteTimeoutSeconds = validatedConfigValue(() => resolveGitRemoteTimeoutSeconds(Number(args[0])), usage);
+            saveConfigKey(store, (config) => ({ ...config, gitRemoteTimeoutSeconds }));
+            return `Git remote total timeout set to ${gitRemoteTimeoutSeconds} seconds\n`;
+        },
+        clear(store) {
+            saveConfigKey(store, (config) => {
+                const { gitRemoteTimeoutSeconds: _removed, ...rest } = config;
+                return rest;
+            });
+            return "Git remote total timeout reset to default\n";
+        }
+    },
     {
         key: "tmux-bin",
         showLabel: "Tmux bin",