@zq-silk/yui 2.22.0 → 2.25.0

package/dist/commands/projectCommands.js

@@ -109,7 +109,7 @@ async function diagnoseProject(args, store, options) {
             data: { project, diagnosis: "no-remote" }
         };
     }
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         requireUnchangedMaintenanceProject(store, project, "diagnose");
@@ -153,7 +153,7 @@ async function discoverProjects(args, store, options) {
     const workspace = store.getConfig().defaultWorkspace;
     if (workspace === undefined)
         throw usageError("No default workspace is configured; run yui setup.");
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const entries = await readdir(workspace, { withFileTypes: true });
     const discovered = [];
     for (const entry of entries) {
@@ -195,7 +195,7 @@ function renderDiscoveredProjects(projects) {
 async function cloneProject(args, store, options) {
     const usage = "Project clone usage: yui project clone <name> <remote> [--alias <name> ...] [--stable <ref>] [--development <ref>] [--external].";
     const parsed = parseCloneArguments(args, usage);
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const name = validateProjectName(parsed.name);
     const stableRef = parsed.stable ?? "HEAD";
     const developmentRef = parsed.development ?? stableRef;
@@ -282,7 +282,7 @@ async function migrateProject(args, store, options) {
     if (project.remoteUrl === undefined) {
         throw usageError(`Project migrate requires a remote URL: ${project.id}.`);
     }
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const destination = managedProjectPath(store.rootDirectory(), project.id);
     // Migration rewrites the Project's Git repository: hold the per-Project
     // maintenance fence so no rebuild/archive/cleanup (or a second migrate)
@@ -444,7 +444,7 @@ async function addProject(args, store, options) {
     const usage = "Project add usage: yui project add <name> <path> [--alias <name> ...] [--remote <url>] [--stable <ref>] [--development <ref>].";
     const parsed = parseAddArguments(args, usage);
     assertOutsideManagedWorktrees(parsed.path, store.rootDirectory());
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const head = await git.inspect(parsed.path, "HEAD");
     assertOutsideManagedWorktrees(head.root, store.rootDirectory());
     if (!await git.isClean(head.root)) {
@@ -483,7 +483,7 @@ async function updateProject(args, store, options) {
             : { developmentBranch: parsed.development })
     };
     assertProjectAvailable(store, updateProjectMetadata(current, patch, now), current.id);
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     if (parsed.stable !== undefined) {
         const head = await git.inspect(current.path, "HEAD");
         if (!await git.isClean(head.root)) {
@@ -568,7 +568,7 @@ async function resetProject(args, store, options) {
     if (project.stableBranch !== project.developmentBranch) {
         throw usageError(`Project reset requires matching stable and development branches: ${project.id}.`);
     }
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         // Re-read under the fence so a concurrent catalog change can never drive
@@ -693,7 +693,7 @@ async function replaceProject(args, store, options) {
         throw usageError(`Project replace discards the current checkout and re-clones from ${project.remoteUrl}. `
             + "Re-run with --discard-local to acknowledge that the checkout and any uncommitted state will be discarded.");
     }
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         const current = requireProject(store, project.id);
@@ -909,7 +909,7 @@ async function deleteProjectCommand(args, store, options) {
         // Heal a crashed earlier attempt before the prechecks turn.
         await healCheckoutSwap({ currentPath: project.path, backupPath: tombstone });
         if (existsSync(project.path)) {
-            const git = options.git ?? new NodeGitWorkspace();
+            const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
             const worktrees = await git.listWorktrees(project.path);
             const linked = worktrees.filter((path) => path !== project.path);
             if (linked.length > 0) {

package/dist/commands/taskCompletionGate.js

@@ -27,7 +27,7 @@ export async function verifyTaskCompletionPublishedTree(taskId, publicationId, s
         throw usageError(`Publication ${publication.id} must record exact local and remote commits.`);
     }
     const workspace = requireTaskWorkspace(store, task);
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const actualHeads = new Map();
     for (const taskBinding of task.projectBindings) {
         const entry = workspaceProjectEntry(workspace, taskBinding.projectId);

package/dist/commands/taskIntegrationCommands.js

@@ -123,7 +123,7 @@ async function start(args, store, home, now, options) {
         throw usageError(`Task main worktree is not ready; reconcile the Task first: ${task.id}.`);
     }
     taskIntegrationTargetCheckout(store, options.environment, task.id, project.id, targetRef);
-    const expectedHead = (await new NodeGitWorkspace().inspect(mainEntry.path, targetRef)).baseCommit;
+    const expectedHead = (await new NodeGitWorkspace(() => store.getConfig()).inspect(mainEntry.path, targetRef)).baseCommit;
     const snapshotEntry = candidate.workspace.entries.find(({ projectId }) => projectId === project.id);
     const resultCommit = candidate.gitSnapshot.projects.find(({ projectId }) => projectId === project.id)?.commit;
     if (snapshotEntry === undefined || resultCommit === undefined) {

package/dist/commands/taskPublicationAdoptCommand.js

@@ -74,7 +74,7 @@ export async function runTaskPublicationAdoptCommand(args, store, options = {})
         return { task, publication, completion, acceptedCommit, workspace, entry, integration, actor };
     };
     const facts = store.transaction(read);
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const localCommit = facts.publication.localCommit;
     const [acceptedTree, candidateTree, diff] = await Promise.all([
         git.resolveTree(facts.entry.path, facts.acceptedCommit),

package/dist/commands/taskRoleRuntimeStatus.js

@@ -19,6 +19,10 @@ export function taskRoleHostDiagnostic(host) {
     const delivery = snapshot.eventDelivery;
     return [
         `Provider Host=${snapshot.state}`,
+        `loaded Host=${snapshot.hostImplementation?.generation ?? "unreported"}`,
+        `loaded Endpoint=${snapshot.endpointImplementation?.generation ?? "unreported"}`,
+        snapshot.hostUpgrade === undefined ? undefined
+            : `Host upgrade=${snapshot.hostUpgrade.state} (${snapshot.hostUpgrade.requestId})${snapshot.hostUpgrade.detail ? `: ${snapshot.hostUpgrade.detail}` : ""}`,
         `terminal reconciliation=${snapshot.controlCapabilities?.includes("reconcile-turn") ? "supported" : "unreported/unsupported"}`,
         delivery === undefined ? "event delivery=unreported" :
             `pending facts=${delivery.pending}; native terminals awaiting acknowledgement=${delivery.pendingTerminals}`,

package/dist/commands/taskUpstreamCommands.js

@@ -48,7 +48,7 @@ async function integrateUpstream(args, store, home, options) {
         throw usageError(`Task must be active to integrate upstream: ${taskId}/${task.status}.`);
     }
     taskLocalActor(store, options.environment, task.id);
-    const git = options.git ?? new NodeGitWorkspace();
+    const git = options.git ?? new NodeGitWorkspace(() => store.getConfig());
     const now = options.now ?? (() => new Date());
     await new FileTaskWorkspacePreparer(home, store, git, now)
         .prepareTaskWorkspace(task.id);

package/dist/config/configCatalog.js

@@ -20,6 +20,9 @@ export const CONFIG_DEFINITIONS = Object.freeze([
     { key: "resources-quarantine-ttl-hours", domain: "resources", property: "resourcesQuarantineTtlHours", label: "Resource quarantine TTL", summary: "Default observation window before purge, 1-720 hours (default: 24).", takesEffect: "The next resource GC command without an explicit TTL override." },
     { key: "tmux-bin", domain: "tools", property: "tmuxBin", label: "Tmux bin", summary: "Command or path to the tmux binary (default: tmux).", takesEffect: "The next CLI-owned tmux invocation; restart the Controller for Controller-owned launches." },
     { key: "tmux-history-limit", domain: "tools", property: "tmuxHistoryLimit", label: "Tmux history limit", summary: "History lines retained for newly created tmux sessions, 1000-1000000 (default: 100000).", takesEffect: "New tmux sessions; existing sessions report drift until recreated." },
+    { key: "git-local-timeout-seconds", domain: "tools", property: "gitLocalTimeoutSeconds", label: "Git local total timeout", summary: "Total elapsed-time limit for each local Git command, 1-86400 seconds (default: 30). Independent of remote transport budgets.", takesEffect: "The next local Git command, including Controller-owned commands; in-flight commands keep their budgets." },
+    { key: "git-remote-inactivity-timeout-seconds", domain: "tools", property: "gitRemoteInactivityTimeoutSeconds", label: "Git remote inactivity timeout", summary: "Maximum silence on stdout/stderr for clone, remote fetch and ls-remote, 1-86400 seconds (default: 120). Local Git uses its separate configurable total budget.", takesEffect: "The next remote Git command, including Controller-owned commands; in-flight commands keep their budgets." },
+    { key: "git-remote-timeout-seconds", domain: "tools", property: "gitRemoteTimeoutSeconds", label: "Git remote total timeout", summary: "Total elapsed-time limit for each clone, remote fetch or ls-remote, 1-86400 seconds (default: 1800), even while progress continues.", takesEffect: "The next remote Git command, including Controller-owned commands; in-flight commands keep their budgets." },
     { key: "telemetry-enabled", domain: "tools", property: "telemetryEnabled", label: "Diagnostic telemetry", summary: "Enable the optional SQLite diagnostic telemetry projection (default: false); requires a SQLite Home.", takesEffect: "Standalone telemetry commands immediately; scheduler writes after Controller restart." },
     { key: "telemetry-terminal-keep", domain: "tools", property: "telemetryTerminalKeep", label: "Telemetry terminal keep", summary: "Positive-integer rows retained per terminal AgentRun (default: 200).", takesEffect: "Explicit retention immediately; automatic retention after the Controller restarts." },
     { key: "telemetry-run-cap", domain: "tools", property: "telemetryRunCap", label: "Telemetry AgentRun cap", summary: `Positive-integer maximum rows retained per AgentRun, at most ${MAX_RUN_CAP} (default: 50000).`, takesEffect: "Explicit retention immediately; automatic write-time capping after the Controller restarts." }

package/dist/config/gitConfig.js

@@ -0,0 +1,20 @@
+export const DEFAULT_GIT_LOCAL_TIMEOUT_SECONDS = 30;
+export const DEFAULT_GIT_REMOTE_INACTIVITY_TIMEOUT_SECONDS = 120;
+export const DEFAULT_GIT_REMOTE_TIMEOUT_SECONDS = 1_800;
+export function resolveGitLocalTimeoutSeconds(value) {
+    return timeoutSeconds(value, DEFAULT_GIT_LOCAL_TIMEOUT_SECONDS, "gitLocalTimeoutSeconds");
+}
+export function resolveGitRemoteInactivityTimeoutSeconds(value) {
+    return timeoutSeconds(value, DEFAULT_GIT_REMOTE_INACTIVITY_TIMEOUT_SECONDS, "gitRemoteInactivityTimeoutSeconds");
+}
+export function resolveGitRemoteTimeoutSeconds(value) {
+    return timeoutSeconds(value, DEFAULT_GIT_REMOTE_TIMEOUT_SECONDS, "gitRemoteTimeoutSeconds");
+}
+function timeoutSeconds(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 86_400) {
+        throw new TypeError(`${label} must be an integer from 1 to 86400.`);
+    }
+    return value;
+}

package/dist/config/yuiConfig.js

@@ -91,6 +91,7 @@ export const MAX_CONTROLLER_TASK_CONCURRENCY = 32;
 export const DEFAULT_AGENT_LAUNCH_INACTIVITY_TIMEOUT_SECONDS = 300;
 export const DEFAULT_DELIVERY_TIMEOUT_SECONDS = 120;
 export const DEFAULT_TMUX_HISTORY_LIMIT = 100_000;
+export { DEFAULT_GIT_LOCAL_TIMEOUT_SECONDS, DEFAULT_GIT_REMOTE_INACTIVITY_TIMEOUT_SECONDS, DEFAULT_GIT_REMOTE_TIMEOUT_SECONDS, resolveGitLocalTimeoutSeconds, resolveGitRemoteInactivityTimeoutSeconds, resolveGitRemoteTimeoutSeconds } from "./gitConfig.js";
 export function resolveRuntimeHealth(configured) {
     if (configured === undefined || configured === null)
         return DEFAULT_RUNTIME_HEALTH_POLICY;

package/dist/context/currentSkills.js

@@ -1,4 +1,5 @@
 import { accessSync, constants, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { access, lstat, readFile, realpath } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 export const BUILTIN_YUI_SKILLS = new Set([
@@ -41,9 +42,39 @@ export function checkCurrentSkills(home, ids) {
         }
     });
 }
+/** Advisory lifecycle observation uses asynchronous filesystem I/O; it neither
+ * blocks a state transition nor substitutes for the exact per-input check. */
+export async function checkCurrentSkillsAsync(home, ids, signal) {
+    const skills = [];
+    for (const id of new Set(ids)) {
+        signal.throwIfAborted();
+        const path = currentSkillPath(home, id);
+        const versionPath = join(path, "VERSION");
+        try {
+            for (const file of [join(path, "SKILL.md"), versionPath]) {
+                if (await realpath(file) !== resolve(file) || !(await lstat(file)).isFile()) {
+                    throw new Error(`Skill files must be regular files without symlinks: ${file}.`);
+                }
+                await access(file, constants.R_OK);
+            }
+            if ((await lstat(versionPath)).size > 128)
+                throw new Error("VERSION exceeds 128 bytes.");
+            const version = (await readFile(versionPath, { encoding: "utf8", signal })).trim();
+            if (!/^[1-9][0-9]{0,8}$/u.test(version))
+                throw new Error("VERSION must contain a positive internal integer.");
+            skills.push({ id, path, version, versionPath });
+        }
+        catch (error) {
+            throw new Error(`Current Skill ${id} is missing, unreadable or invalid at ${path}. `
+                + `${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    return skills;
+}
 export const SKILL_CHECK_COMMAND = "yui session skills --json";
 export const SKILL_REUSE_RULE = "The managed Host checks current Skill versions/availability before each input; "
-    + "do not repeat an explicit Host check. Without that notice, check through the Manifest's command. "
+    + "unchanged inputs carry no notice or marker, and do not require a duplicate check. "
+    + "For unmediated clients or uncertain current input routing, check through the Manifest's command; conversation reuse alone does not establish Host mediation. Keep routine checks internal, not user-facing progress. "
     + "Reuse unchanged full instructions in context; messages alone require no reload. "
     + "Read affected entries/references fully on change or localized loss. On first entry, recovery or lost context, "
     + "rebuild the current working set from applicable Skill entry points and action-relevant references, not all past procedures. "

package/dist/context/sessionBootstrapManifest.js

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
 import { chmodSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { validateSkillPackageRef } from "./skillPackage.js";
-import { checkCurrentSkills, SKILL_CHECK_COMMAND, SKILL_REUSE_RULE } from "./currentSkills.js";
+import { checkCurrentSkills, checkCurrentSkillsAsync, SKILL_CHECK_COMMAND, SKILL_REUSE_RULE } from "./currentSkills.js";
 import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 /** Portable read pointers accompany every managed input, including the first
@@ -22,11 +23,11 @@ export function withSessionContextPointer(text, environment) {
  * Unmediated/native clients retain the explicit diagnostic fallback. */
 export function sessionContextInstructions(manifestPath, digest) {
     return `Yui Session Manifest: ${manifestPath}${digest === undefined ? "" : ` (digest ${digest})`}. `
-        + "For inputs carrying the Yui Host Skill-check notice, engineering has checked current versions; do not repeat that check. "
-        + `Otherwise run its contextProtocol.skillCheckCommand (fallback: ${SKILL_CHECK_COMMAND}). `
+        + "The managed Host checks Skills internally and injects guidance only when loading is needed; absence of a notice does not require another check. "
+        + `For unmediated clients or uncertain current input routing, run its contextProtocol.skillCheckCommand (fallback: ${SKILL_CHECK_COMMAND}); conversation reuse alone does not establish Host mediation. `
         + "On first entry or lost instructions, read the current applicable Skill entry points, then only references needed for the current action. "
         + "On change reload affected instructions. Compaction does not require restoring every previously used procedure. "
-        + "Preserve the Manifest Role profile; metadata never proves loading or memory.";
+        + "Preserve the Manifest Role profile; metadata never proves loading or memory. Keep routine role, version and empty-inbox checks internal.";
 }
 /** The caller must already pass the ordinary managed Session/CLI/Home checks.
  * Old manifests remain immutable audit records, while this read resolves their
@@ -40,6 +41,15 @@ export function checkSessionSkills(home, manifestPath) {
         historicalPackagesAreAuditOnly: true
     };
 }
+export async function checkSessionSkillsAsync(home, manifestPath, signal) {
+    const manifest = validateSessionBootstrapManifest(JSON.parse(await readFile(resolve(manifestPath), { encoding: "utf8", signal })));
+    return {
+        skills: await checkCurrentSkillsAsync(home, manifest.skills.map(skill => skill.id), signal),
+        roleProfileRef: manifest.roleProfileRef,
+        rule: SKILL_REUSE_RULE,
+        historicalPackagesAreAuditOnly: true
+    };
+}
 /** Read back one immutable Session Manifest and verify its content digest. */
 export function readSessionBootstrapManifest(path) {
     const source = resolve(path);
@@ -50,6 +60,9 @@ export function readSessionBootstrapManifest(path) {
     catch (error) {
         throw new Error(`Session Manifest is unreadable: ${source}.`, { cause: error });
     }
+    return validateSessionBootstrapManifest(parsed);
+}
+function validateSessionBootstrapManifest(parsed) {
     if (parsed === null || typeof parsed !== "object") {
         throw new Error("Session Manifest is invalid.");
     }

package/dist/context/sessionSkillNotice.js

@@ -1,4 +1,26 @@
-import { checkSessionSkills } from "./sessionBootstrapManifest.js";
+import { checkSessionSkills, checkSessionSkillsAsync } from "./sessionBootstrapManifest.js";
+/** Early advisory checks do not commit notices or assert model memory. The
+ * next input still validates its exact metadata and emits only its own delta.
+ * Invalid metadata may reject that input, never a Session state transition. */
+export function createSessionSkillLifecycleCheck(home, environment) {
+    return {
+        id: "session-skills",
+        run: async (transition, signal) => {
+            if (!["connected", "interactive-connected", "settled"].includes(transition.event.type))
+                return;
+            const manifest = environment().YUI_SESSION_MANIFEST;
+            if (!manifest || signal.aborted)
+                return;
+            try {
+                await checkSessionSkillsAsync(home, manifest, signal);
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    throw error;
+            }
+        }
+    };
+}
 /** Host-local last accepted metadata, never a model loading/memory receipt.
  * A new Host/attachment starts cold. No durable schema or input replay is added. */
 export function createSessionSkillNotice(home) {
@@ -10,9 +32,7 @@ export function createSessionSkillNotice(home) {
         prepare(text, environment, sessionKey, options = {}) {
             const manifest = environment.YUI_SESSION_MANIFEST;
             if (manifest === undefined)
-                return { text, commit() { } };
-            if (options.recovery)
-                invalidate();
+                return { text, inputText: text, commit() { } };
             let current;
             try {
                 current = checkSessionSkills(home, manifest);
@@ -21,7 +41,7 @@ export function createSessionSkillNotice(home) {
                 invalidate();
                 throw error; // Do not submit business input with an invalid current installation.
             }
-            const key = JSON.stringify([sessionKey, manifest, current.roleProfileRef]);
+            const key = JSON.stringify([sessionKey, manifest, current.roleProfileRef, options.contextEpoch]);
             const skills = new Map(current.skills.map(skill => [skill.id, JSON.stringify({
                     id: skill.id, path: skill.path, version: skill.version
                 })]));
@@ -30,17 +50,18 @@ export function createSessionSkillNotice(home) {
                 .map(([, value]) => value);
             const removed = !cold && [...previous.skills.keys()].some(id => !skills.has(id));
             // Every input is checked, but only a lifecycle/metadata event needs an
-            // instruction-loading notice. This marker distinguishes Host-mediated
-            // input from an unmediated client without restating the operating manual.
-            const lines = ["Yui Host checked current Skills; no Agent check needed."];
+            // instruction-loading notice. Unchanged input is passed through exactly.
+            const lines = [];
             if (cold || changed.length > 0 || removed) {
-                lines.push(`Yui Session Manifest: ${manifest}`, cold
-                    ? `First input or recovered attachment: read the exact Role profile at ${current.roleProfileRef.path} and the full current listed Skill entry points. Follow references only for the action you are taking, not to restore every previously used procedure. A Task role-profile projection is not this profile.`
-                    : "Skill metadata changed: load affected entries and applicable references; retain other complete instructions.", `Current Skill pointers: [${(removed ? [...skills.values()] : changed).join(",")}]`, "Metadata is not a loading receipt. Read each required file through EOF; if output is truncated, finish the missing ranges. Recover missing instructions for the current task, not the whole manual.");
+                lines.push(`Yui Session Manifest: ${manifest}`, "Host-managed Skill checks are active; unchanged input has no notice. Detached/unmediated clients must use the Manifest check fallback.", cold
+                    ? `Read the exact Role profile at ${current.roleProfileRef.path} (not a Task projection) and all current Skill entry points below. Follow references only for the current action.`
+                    : "Skill metadata changed: load affected entries and applicable references; retain other complete instructions.", `Current Skill pointers: [${(removed ? [...skills.values()] : changed).join(",")}]`, "Read required files through EOF. Metadata is not loaded instructions. Keep routine checks internal.");
             }
             const preparedGeneration = generation;
             return {
-                text: `${lines.join("\n")}\n\n${text}`,
+                text: lines.length === 0 ? text : `${lines.join("\n")}\n\n${text}`,
+                inputText: text,
+                ...(lines.length === 0 ? {} : { context: lines.join("\n") }),
                 commit() {
                     if (generation !== preparedGeneration)
                         return;

package/dist/controlPlaneCli.js

@@ -1111,7 +1111,7 @@ export async function main() {
                 if (action === "list") {
                     if (resolved.length !== 4)
                         throw usageError(usage);
-                    data = await listArtifactsCapability(home, taskId);
+                    data = await listArtifactsCapability(home, taskId, () => store.getConfig());
                 }
                 else if (action === "read") {
                     const relativePath = resolved[4];
@@ -1120,7 +1120,7 @@ export async function main() {
                         throw usageError(usage);
                     data = await readArtifactCapability(home, taskId, {
                         relativePath, ...(commit === undefined ? {} : { commit })
-                    });
+                    }, () => store.getConfig());
                 }
                 else {
                     // save: a delivery-authoritative action; a managed Task caller must be the current Leader.
@@ -1156,7 +1156,7 @@ export async function main() {
                         relativePath, content, ...(encoding === undefined ? {} : { encoding }),
                         ...(message === undefined ? {} : { message }),
                         ...(expectedHead === undefined ? {} : { expectedHead })
-                    });
+                    }, () => store.getConfig());
                 }
                 emit(JSON.stringify(data, null, 2), false, data);
                 return;
@@ -2515,7 +2515,7 @@ async function deltaRecheckPreflightForTaskCommand(args, store, actualTaskReview
         repositoryPaths,
         previousRound: previous,
         candidate: actualTaskReviewCandidate,
-        git: new NodeGitWorkspace()
+        git: new NodeGitWorkspace(() => store.getConfig())
     });
     if (assessment.kind === "ineligible") {
         throw usageError(`Delta-recheck is technically unavailable: ${assessment.reason}`);

package/dist/controller/clientRuntime.js

@@ -59,21 +59,31 @@ export async function assertFileTaskControllerStorageCompatible(home, options =
 export async function ensureFileTaskController(home, options = {}) {
     const call = options.call ?? callController;
     await waitForForeignHandover(home, options);
-    try {
-        const status = await call(home, "controller.status", {});
-        assertCompatibleControllerStatus(status, options.expectedIdentity);
-        return status;
-    }
-    catch (error) {
-        if (!isUnavailable(error))
-            throw error;
+    const timeoutMs = positive(options.startupTimeoutMs, STARTUP_TIMEOUT_MS, "startupTimeoutMs");
+    const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
+    const probeDeadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const status = await call(home, "controller.status", {});
+            assertCompatibleControllerStatus(status, options.expectedIdentity);
+            return status;
+        }
+        catch (error) {
+            if (isUnavailable(error))
+                break;
+            // A closing endpoint may reset a read even after its owner exited.
+            // Retry only this observation: ambiguity never authorizes a spawn.
+            if (!(error instanceof ControllerClientError)
+                || error.code !== "CONTROLLER_DELIVERY_UNKNOWN"
+                || Date.now() >= probeDeadline)
+                throw error;
+        }
+        await delay(pollMs);
     }
     // A handover may have started after the first lock check and before the
     // failed discovery/socket call. Re-check before spawning so a managed
     // Session can never resurrect the old Controller during an update.
     await waitForForeignHandover(home, options);
-    const timeoutMs = positive(options.startupTimeoutMs, STARTUP_TIMEOUT_MS, "startupTimeoutMs");
-    const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
     const spawnController = options.spawnController ?? spawnDetachedFileTaskController;
     // A readiness timeout is not exit evidence. Reuse the observable startup
     // process for this exact Home rather than multiplying unready Controllers.
@@ -213,17 +223,26 @@ async function waitForControllerProcessExit(controller, options) {
     const timeoutMs = positive(options.shutdownTimeoutMs, CONTROLLER_SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs");
     const pollMs = positive(options.pollIntervalMs, POLL_INTERVAL_MS, "pollIntervalMs");
     const deadline = Date.now() + timeoutMs;
-    // This check is tri-state: unreadable OS identity throws rather than
-    // collapsing an unknown/live process into the absence of a Controller match.
-    while (processGenerationIsLive(controller.pid, controller.processStartIdentity)) {
-        if (process.platform === "linux") {
-            const observed = readLinuxProcessIdentity(controller.pid);
-            // Preserve the existing physical-stop boundary: an exact zombie has
-            // exited, even if its parent has not reaped the process table entry.
-            if (observed?.startIdentity === controller.processStartIdentity && observed.state === "Z")
+    for (;;) {
+        let observationError;
+        try {
+            if (!processGenerationIsLive(controller.pid, controller.processStartIdentity))
                 return;
+            if (process.platform === "linux") {
+                const observed = readLinuxProcessIdentity(controller.pid);
+                // An exact zombie has exited even before its parent reaps it.
+                if (observed?.startIdentity === controller.processStartIdentity && observed.state === "Z")
+                    return;
+            }
+        }
+        catch (error) {
+            // OS identity can disappear before kill(pid, 0) reports absence.
+            // Keep observing within the existing stop budget, never infer exit.
+            observationError = error;
         }
         if (Date.now() >= deadline) {
+            if (observationError !== undefined)
+                throw observationError;
             throw new ControllerClientError("CONTROLLER_TIMEOUT", `Controller process ${controller.pid} did not exit within ${timeoutMs} ms.`);
         }
         await delay(pollMs);

package/dist/controller/controller.js

@@ -14,7 +14,7 @@ import { KeyedWorkQueue } from "../coordination/keyedWorkQueue.js";
 import { MailboxScheduler } from "../coordination/mailboxScheduler.js";
 import { nearestDeadlineBatch } from "../coordination/deadlineScheduler.js";
 import { mailboxHasWork, nextPendingBatch } from "../coordination/workMailbox.js";
-import { hasRuntimeCleanupObligation } from "../runtime/lifecycleReservation.js";
+import { hasRuntimeCleanupObligation, runtimeCleanupDisposition } from "../runtime/lifecycleReservation.js";
 import { formatTaskRecordReference } from "../task/taskRecordReference.js";
 import { parseDurableJobAcknowledgeParams, parseDurableJobCancelParams, parseDurableJobRefParams, parseDurableJobStartParams } from "./jobControl.js";
 const DEFAULT_RECONCILIATION_INTERVAL_MS = reconciliationIntervalMilliseconds();
@@ -211,6 +211,12 @@ async function processSelectedRoleRuntimeCleanups(store, delivery, lifecycleHost
         const owner = runtimeOwner(target);
         const batchId = runtimeLifecycleBatchIdentity(target, mailbox);
         if (hasRuntimeCleanupObligation(mailbox)) {
+            // Upgrade is a graceful, exact-identity operation, never the destructive
+            // cleanup path. Its coordinator owns drain/restore; retain backpressure.
+            if (runtimeCleanupDisposition(mailbox) === "upgrade-host") {
+                markFailedRuntimeTarget(failedRoles, target);
+                continue;
+            }
             try {
                 if (lifecycleHost === undefined) {
                     throw new Error("Role runtime cleanup host is unavailable.");
@@ -698,6 +704,7 @@ export class FileTaskController {
     #providerRetry;
     #continuationReconciler;
     #hostTerminalRecovery;
+    #lifecycleChecks;
     #persistenceMetrics;
     #diagnosticMetrics;
     #current;
@@ -754,6 +761,7 @@ export class FileTaskController {
         this.#schedules = options.schedules;
         this.#continuationReconciler = options.continuationReconciler;
         this.#hostTerminalRecovery = options.hostTerminalRecovery;
+        this.#lifecycleChecks = options.lifecycleChecks;
         this.#globalInputDelivery = options.globalInputDelivery;
         this.#messageHealth = options.messageHealth;
         this.#providerRetry = options.providerRetry;
@@ -842,6 +850,7 @@ export class FileTaskController {
             return;
         if (this.#stopped)
             throw new Error("Controller runtime is stopped.");
+        this.#lifecycleChecks?.notify("startup");
         this.#requestBackgroundPump();
         this.#requestRuntimeObservation();
         // Arm the Operator lane once for work that was already pending when the
@@ -862,6 +871,7 @@ export class FileTaskController {
     }
     stop() {
         this.#stopped = true;
+        this.#lifecycleChecks?.close();
         this.#workspaceWaitAbort.abort(new Error("Controller stopped while waiting for Project maintenance."));
         this.#signalScheduler.stop();
         this.#operatorSignalScheduler.stop();
@@ -905,6 +915,7 @@ export class FileTaskController {
         if (this.#stopped)
             throw new Error("Controller runtime is stopped.");
         parseMailboxKey(key);
+        this.#lifecycleChecks?.notify("signal");
         if (key === "operator") {
             // Main lane owns durable Hook folding; the Operator lane is the sole
             // consumer of the Operator delivery mailbox.
@@ -1017,6 +1028,8 @@ export class FileTaskController {
                         }
                     }
                     const firstRuntimeDrain = await this.#phases.observe("runtime-drain", "home", () => this.#drainRuntimeEvents());
+                    if (scope.kind === "full")
+                        this.#lifecycleChecks?.notify("periodic");
                     if (scope.kind === "full" && this.#hostTerminalRecovery !== undefined) {
                         await this.#observeMaintenance("Host terminal recovery", this.#hostTerminalRecovery);
                     }
@@ -1258,6 +1271,8 @@ export class FileTaskController {
             ? await processor.drainAsync(this.#now())
             : processor.drain(this.#now());
         this.#lastRuntimeDrain = result;
+        if (result.acknowledgedEventIds.length > 0)
+            this.#lifecycleChecks?.notify("events-persisted");
         this.#runtimeDrainPasses += 1;
         const metrics = result.metrics ?? ZERO_DRAIN_METRICS;
         this.#runtimeListedEvents += metrics.listedEventCount;

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -1723,6 +1723,8 @@ export class FileSchedulerStoreAdapter {
             const disposition = runtimeCleanupDisposition(mailbox);
             if (mailbox === null || disposition === null)
                 return false;
+            if (disposition === "upgrade-host")
+                return false;
             if (mailbox.processing !== null) {
                 if (disposition !== "replace-session" && !mailbox.processing.batch.reasons.every(isRuntimeCleanupReason)) {
                     return false;