@zq-silk/yui 2.22.0 → 2.25.0

package/dist/runtime/providerRetry.js

@@ -164,16 +164,16 @@ export function completeProviderRetry(binding, turn) {
 export function providerRetryAttemptId(retry) {
     return `provider-retry:${retry.chainId}/${retry.transportSequence + 1}`;
 }
-export function providerRetryPrompt(retry, original) {
+/** Recovery guidance only. User input is delivered separately, once. */
+export function providerRetryContext(retry) {
     if (retry.failedNativeTurnId === undefined)
-        return original;
+        return undefined;
     return [
         "Yui infrastructure recovery, not new user authorization.",
         `Continue the existing input after failed attempt ${retry.failureAttemptId}`,
         `(native Turn ${retry.failedNativeTurnId}; failure ${retry.failureRef}).`,
         "Read current authorized context and the original input. Inspect existing work and receipts first;",
-        "continue only unfinished work. Preserve local changes and do not repeat confirmed side effects.",
-        original
+        "continue only unfinished work. Preserve local changes and do not repeat confirmed side effects."
     ].join("\n");
 }
 /** The same presentation is consumed by explicit detail reads and Web. */

package/dist/runtime/structuredProviderHost.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { createNativeTitleSync } from "./nativeTitleSync.js";
 import { Duplex } from "node:stream";
 import { nativeExecutable } from "./nativeExecutable.js";
 import { startMissingCodexSharedDaemon } from "./codexSharedDaemon.js";
@@ -15,6 +16,7 @@ import { JsonLineChannel, PROVIDER_MESSAGE_MAX_BYTES, terminateProcessGroup } fr
 import { PROVIDER_ACCEPT_TIMEOUT_MS } from "./runtimeDeadlines.js";
 import { foldPublicReply } from "./publicReply.js";
 import { createCodexNativeAccess } from "./codexNativeAccess.js";
+import { isNativeContextRecovery } from "./contextRecovery.js";
 const CODEX_PROXY_HANDSHAKE_TIMEOUT_MS = 10_000;
 /**
  * These Session implementations do not expose run-configuration observations.
@@ -396,7 +398,22 @@ class CodexStructuredProviderSession {
     onActivity;
     mirror;
     nativeAccountHome;
+    contextEpoch = 0;
+    async checkQuiescent() {
+        const snapshot = await this.runtime.readConversation(this.conversationId, { includeTurns: false });
+        if (snapshot.threadId !== this.conversationId || snapshot.status !== "idle"
+            || snapshot.activeTurnId !== undefined)
+            return false;
+        const backgrounds = await this.nativeAccess.read("thread/backgroundTerminals/list", {
+            threadId: this.conversationId, limit: 1
+        });
+        if (!Array.isArray(backgrounds.data) || !("nextCursor" in backgrounds)) {
+            throw new Error("Native background execution response is invalid.");
+        }
+        return backgrounds.data.length === 0 && backgrounds.nextCursor === null;
+    }
     appliedGeneratedTitle;
+    #titleSync;
     nativeAccess;
     #turnAttempts = new Map();
     adapterId = "codex";
@@ -456,16 +473,6 @@ class CodexStructuredProviderSession {
                 throw error;
             }
         }
-        if (control.sessionTitle !== undefined) {
-            // The native title mutation can persist without replying and stall later
-            // Goal/Turn requests, even through a separate metadata connection. Keep
-            // Yui's launch title, but do not put that optional mutation on a managed
-            // Session's execution path. Reconnect must not replay it either.
-            // This is an intentional omission, not a failed delivery or unavailable
-            // observer. Keep it in the Host log without waking an Agent to recover
-            // an operation that was never attempted.
-            mirror("stderr", "Native title synchronization was not submitted; Yui retains its Session title without blocking native Goal/Turn control.\n");
-        }
         const ownedTurn = control.kind === "restore" ? control.ownedTurn : undefined;
         // Keep notifications buffered during paginated recovery. Otherwise a live
         // terminal can be emitted before open returns and then returned again as a
@@ -521,6 +528,15 @@ class CodexStructuredProviderSession {
             }
         }
         const goal = await runtime.readGoal(conversationId);
+        session.#titleSync = createNativeTitleSync(payload, conversationId, session.nativeAccountHome, result => {
+            if (result.status === "confirmed")
+                session.appliedGeneratedTitle = result.title;
+            mirror("stderr", `Native title: ${JSON.stringify(result)}\n`);
+        });
+        void exit.then(() => session.#titleSync?.close());
+        // Fresh Threads may not be persisted until their first accepted input.
+        if (control.mode === "resume")
+            session.#titleSync.notify();
         return Object.freeze({
             session,
             ...(recoveredTerminal === undefined ? {} : { recoveredTerminal }),
@@ -530,6 +546,8 @@ class CodexStructuredProviderSession {
     #observeMessage(message, emit) {
         const method = typeof message.method === "string" ? message.method : "";
         const params = object(message.params) ?? {};
+        if (isNativeContextRecovery("codex", this.conversationId, message))
+            this.contextEpoch += 1;
         const threadId = optionalId(params.threadId);
         if (emit)
             this.publicReply = foldPublicReply(this.publicReply, this.conversationId, method, params);
@@ -539,6 +557,13 @@ class CodexStructuredProviderSession {
             }
             return undefined;
         }
+        if (method === "thread/name/updated") {
+            this.#titleSync?.close();
+            if (params.threadName !== this.appliedGeneratedTitle)
+                this.appliedGeneratedTitle = undefined;
+        }
+        if (method === "turn/started")
+            this.#titleSync?.notify();
         let goal;
         try {
             goal = codexGoalNotification({ method, params });
@@ -663,6 +688,7 @@ class CodexStructuredProviderSession {
                 conversationId: this.conversationId,
                 attemptId: turn.attemptId,
                 text: turn.boundedText,
+                ...(turn.additionalContext === undefined ? {} : { additionalContext: turn.additionalContext }),
                 expectedNoActiveTurn: true,
                 ...(turn.requireQuiescent ? { requireQuiescent: true } : {}),
                 ...(turn.expectedFailedNativeTurnId === undefined ? {} : {
@@ -682,6 +708,7 @@ class CodexStructuredProviderSession {
             this.#clientOwnedTurnId = acceptance.turnId;
             this.#clientOwnedAttemptId = turn.attemptId;
             this.#turnAttempts.set(acceptance.turnId, turn.attemptId);
+            this.#titleSync?.notify();
             return Object.freeze({
                 attemptId: turn.attemptId,
                 conversationId: this.conversationId,
@@ -712,6 +739,7 @@ class CodexStructuredProviderSession {
             conversationId: this.conversationId,
             expectedTurnId: nativeTurnId,
             text: turn.boundedText,
+            ...(turn.additionalContext === undefined ? {} : { additionalContext: turn.additionalContext }),
             clientUserMessageId: turn.attemptId
         });
         if (acceptance.status === "unknown") {
@@ -776,6 +804,7 @@ class CodexStructuredProviderSession {
         return result === "interrupted" ? "requested" : result;
     }
     terminate(signal) {
+        this.#titleSync?.close();
         terminateProcessGroup(this.child, signal);
     }
 }
@@ -787,6 +816,7 @@ class ClaudeStructuredProviderSession {
     channel;
     onGoal;
     mirror;
+    contextEpoch = 0;
     adapterId = "claude";
     get ownedProcessId() { return this.child.pid; }
     #activeAttemptId;
@@ -903,6 +933,8 @@ class ClaudeStructuredProviderSession {
         terminateProcessGroup(this.child, signal);
     }
     #receive(message, onTerminal, onAccepted, onActivity) {
+        if (isNativeContextRecovery("claude", this.conversationId, message))
+            this.contextEpoch += 1;
         const goal = claudeActiveGoal(message, this.conversationId);
         if (goal !== undefined) {
             const key = JSON.stringify(goal === null ? null : {

package/dist/storage/sqliteSchema.js

@@ -295,6 +295,36 @@ const MINOR_UPGRADES = Object.freeze([{
         targetChecksum: CURRENT_SCHEMA_CHECKSUM,
         // Optional workspace-write permission fields; preserve all existing payloads.
         sql: ""
+    }, {
+        fromVersion: "1.26",
+        toVersion: "1.27",
+        name: "host-upgrade-lifecycle-signals",
+        introducedIn: "next",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // New versioned signal sources in the existing role-runtime mailbox. No
+        // historical requests are inferred and existing records remain unchanged.
+        sql: ""
+    }, {
+        fromVersion: "1.27",
+        toVersion: "1.28",
+        name: "native-title-effect-receipts",
+        introducedIn: "next",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // Additive exact-identity intent/confirmation files under runtime/native-titles.
+        // Never invent native ownership or replay history during migration.
+        sql: ""
+    }, {
+        fromVersion: "1.28",
+        toVersion: "1.29",
+        name: "git-command-budgets",
+        introducedIn: "2.24.0",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // Optional local/remote Git budgets in config. Absence uses runtime defaults;
+        // preserve every existing payload byte rather than persisting defaults.
+        sql: ""
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)

package/dist/storage/storageVersions.js

@@ -1,4 +1,4 @@
-export const CURRENT_STORAGE_VERSION = "1.26";
+export const CURRENT_STORAGE_VERSION = "1.29";
 export const MIN_SUPPORTED_STORAGE_VERSION = "1.0";
 export const STORAGE_FORMAT = "yui-home";
 export function isStorageVersion(value) {

package/dist/storage/taskStore.js

@@ -4,7 +4,7 @@ import { validateModelConnection } from "../models/modelManagementConfig.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { resolveTimeZone } from "../config/timeZone.js";
-import { reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveResourcesGcAutoQuarantine, resolveResourcesGcMode, resolveResourcesQuarantineTtlHours, resolveRuntimeHealth, resolveTelemetryEnabled, resolveTelemetryRunCap, resolveTelemetryTerminalKeep, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
+import { reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveGitLocalTimeoutSeconds, resolveGitRemoteInactivityTimeoutSeconds, resolveGitRemoteTimeoutSeconds, resolveResourcesGcAutoQuarantine, resolveResourcesGcMode, resolveResourcesQuarantineTtlHours, resolveRuntimeHealth, resolveTelemetryEnabled, resolveTelemetryRunCap, resolveTelemetryTerminalKeep, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
 import { validateCapabilityGrant } from "../grant/capabilityGrant.js";
 import { validateReleaseWorkflow } from "../release/releaseWorkflow.js";
 import { validateReviewConfig } from "../review/reviewConfig.js";
@@ -131,6 +131,9 @@ export function validateYuiConfig(config) {
             "controllerTaskConcurrency",
             "agentLaunchInactivityTimeoutSeconds",
             "deliveryTimeoutSeconds",
+            "gitLocalTimeoutSeconds",
+            "gitRemoteInactivityTimeoutSeconds",
+            "gitRemoteTimeoutSeconds",
             "resourcesQuarantineTtlHours",
             "tmuxBin",
             "tmuxHistoryLimit",
@@ -159,6 +162,9 @@ export function validateYuiConfig(config) {
         resolveControllerTaskConcurrency(config.controllerTaskConcurrency);
         resolveAgentLaunchInactivityTimeoutSeconds(config.agentLaunchInactivityTimeoutSeconds);
         resolveDeliveryTimeoutSeconds(config.deliveryTimeoutSeconds);
+        resolveGitLocalTimeoutSeconds(config.gitLocalTimeoutSeconds);
+        resolveGitRemoteInactivityTimeoutSeconds(config.gitRemoteInactivityTimeoutSeconds);
+        resolveGitRemoteTimeoutSeconds(config.gitRemoteTimeoutSeconds);
         resolveTmuxBin(config.tmuxBin);
         resolveTmuxHistoryLimit(config.tmuxHistoryLimit);
         resolveTelemetryEnabled(config.telemetryEnabled);

package/dist/web/webConversation.js

@@ -227,7 +227,7 @@ export function createWebConversationSurface(store, surface, plan, readPage = re
             if (["completed", "cancelled", "retired", "archived"].includes(task.status)) {
                 throw new WebRequestRejected("Terminal Task materials are read-only.");
             }
-            return saveTextMaterial(store.rootDirectory(), owner.taskId, id, input);
+            return saveTextMaterial(store.rootDirectory(), owner.taskId, id, input, () => store.getConfig());
         },
         state(owner, offset = 0) {
             const set = sessions(owner);
@@ -296,7 +296,7 @@ export function createWebConversationSurface(store, surface, plan, readPage = re
                 if (owner.scope !== "task" || input.action === "interrupt")
                     throw new WebRequestRejected("Materials require Task text input.");
                 try {
-                    body = await materialInputBody(store.rootDirectory(), owner.taskId, required(body), input.materials);
+                    body = await materialInputBody(store.rootDirectory(), owner.taskId, required(body), input.materials, () => store.getConfig());
                 }
                 catch (error) {
                     throw new WebRequestRejected(error instanceof Error ? error.message : "Invalid material.");

package/dist/web/webMaterials.js

@@ -16,24 +16,24 @@ const TEXT_EXTENSIONS = new Set([
 const TEXT_NAMES = new Set(["readme", "license", "dockerfile", "makefile"]);
 export const MAX_MATERIAL_BYTES = 256 * 1024;
 const PAGE_CHARACTERS = 12000;
-async function fixedImage(home, taskId, input) {
+async function fixedImage(home, taskId, input, getConfig) {
     if (input.taskId !== taskId)
         throw new WebRequestRejected("Materials must belong to the same Task.");
     const ref = validateGitArtifactRef(input);
     if (ref.relativePath.length > 512)
         throw new WebRequestRejected("Image path is too long.");
-    const file = await resolveGitArtifact(home, ref);
+    const file = await resolveGitArtifact(home, ref, getConfig);
     const metadata = rasterMetadata(file.bytes);
     return { ...ref, digest: file.digest, kind: "image", byteSize: file.bytes.length,
         ...metadata, base64: file.bytes.toString("base64") };
 }
 /** One selected immutable file, never a workspace path or a remote URL.
  * Markdown is bounded and whole so fences/tables are not split by pagination. */
-export async function readArtifactPreview(home, taskId, ref, offset = 0) {
+export async function readArtifactPreview(home, taskId, ref, offset = 0, getConfig) {
     if (ref.taskId !== taskId)
         throw new WebRequestRejected("Materials must belong to the same Task.");
     const valid = validateGitArtifactRef(ref);
-    const file = await resolveGitArtifact(home, valid);
+    const file = await resolveGitArtifact(home, valid, getConfig);
     return { ...valid, ...previewArtifactContent(file, offset) };
 }
 /** Shared data-only preview for Task and Job evidence; no path lookup or authority. */
@@ -81,12 +81,12 @@ function decodeText(bytes) {
     }
     return text;
 }
-async function fixedText(home, taskId, input) {
+async function fixedText(home, taskId, input, getConfig) {
     if (input.taskId !== taskId)
         throw new WebRequestRejected("Materials must belong to the same Task.");
     const ref = validateGitArtifactRef(input);
     textPath(ref.relativePath);
-    const file = await resolveGitArtifact(home, ref);
+    const file = await resolveGitArtifact(home, ref, getConfig);
     return { ref: { ...ref, digest: file.digest }, text: decodeText(file.bytes), bytes: file.bytes.length };
 }
 function page(text, offset = 0) {
@@ -100,26 +100,26 @@ function page(text, offset = 0) {
     return { content: text.slice(offset, end), offset, totalCharacters: text.length,
         nextOffset: end < text.length ? end : null };
 }
-export async function readTextArtifactPage(home, taskId, ref, offset = 0) {
-    const file = await fixedText(home, taskId, ref);
+export async function readTextArtifactPage(home, taskId, ref, offset = 0, getConfig) {
+    const file = await fixedText(home, taskId, ref, getConfig);
     return { ...file.ref, byteSize: file.bytes, ...page(file.text, offset) };
 }
-export async function compareTextArtifacts(home, taskId, before, after, offset = 0) {
-    const left = await fixedText(home, taskId, before);
-    const right = await fixedText(home, taskId, after);
+export async function compareTextArtifacts(home, taskId, before, after, offset = 0, getConfig) {
+    const left = await fixedText(home, taskId, before, getConfig);
+    const right = await fixedText(home, taskId, after, getConfig);
     // Blob identities avoid interpreting user paths as options or reading the
     // working tree. Neither external diff drivers nor text converters can run.
-    const repo = openTaskArtifactRepository(home, taskId);
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     const diff = await managedGit(repo.repoPath, [
         "diff", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=3",
         `${left.ref.commit}:${left.ref.relativePath}`, `${right.ref.commit}:${right.ref.relativePath}`, "--"
-    ], { maxBuffer: 20 * 1024 * 1024, timeoutMs: 5000 });
+    ], { maxBuffer: 20 * 1024 * 1024, getConfig });
     return { taskId, before: left.ref, after: right.ref, ...page(diff, offset) };
 }
 /** Saves DATA only. Sending it is a separate explicit conversation action.
  * The normal artifact repository and commit message retain origin; no second
  * storage/receipt schema is introduced. Unknown saves are inspected, not replayed. */
-export async function saveTextMaterial(home, taskId, sessionId, input) {
+export async function saveTextMaterial(home, taskId, sessionId, input, getConfig) {
     if (!/^[A-Za-z0-9_-]{1,128}$/u.test(input.requestId)
         || typeof input.name !== "string" || input.name.includes("/") || input.name.includes("\\")
         || typeof input.content !== "string")
@@ -130,7 +130,7 @@ export async function saveTextMaterial(home, taskId, sessionId, input) {
         throw new WebRequestRejected(`Material exceeds ${MAX_MATERIAL_BYTES} UTF-8 bytes or has invalid text.`);
     }
     decodeText(bytes);
-    const repo = openTaskArtifactRepository(home, taskId);
+    const repo = openTaskArtifactRepository(home, taskId, getConfig);
     await repo.ensure();
     const head = (await repo.head());
     if ((await repo.list(head)).some(entry => entry.relativePath === relativePath)) {
@@ -141,22 +141,22 @@ export async function saveTextMaterial(home, taskId, sessionId, input) {
         return { taskId, relativePath, commit: head, digest: existing.digest };
     }
     return saveArtifactFile(home, taskId, { relativePath, bytes, expectedHead: head,
-        message: `Text material from Leader Session ${sessionId}; request ${input.requestId}` });
+        message: `Text material from Leader Session ${sessionId}; request ${input.requestId}` }, getConfig);
 }
 /** Existing durable Message body carries self-contained frozen references.
  * Contents are deliberately absent: reading material cannot elevate it to an
  * instruction, execute it, or broaden the receiving Agent's Task authority. */
-export async function materialInputBody(home, taskId, body, refs) {
+export async function materialInputBody(home, taskId, body, refs, getConfig) {
     if (!Array.isArray(refs) || refs.length > 8)
         throw new WebRequestRejected("Select at most eight material references.");
     const verified = [];
     for (const ref of refs) {
         if (isRasterArtifact(ref.relativePath)) {
-            const image = await fixedImage(home, taskId, ref);
+            const image = await fixedImage(home, taskId, ref, getConfig);
             verified.push({ taskId, commit: image.commit, relativePath: image.relativePath, digest: image.digest });
         }
         else
-            verified.push((await fixedText(home, taskId, ref)).ref);
+            verified.push((await fixedText(home, taskId, ref, getConfig)).ref);
     }
     if (!verified.length)
         return body;

package/dist/web/webTaskSurface.js

@@ -136,7 +136,7 @@ export function createWebTaskSurface(store, options = {}, observations = [], hos
         artifacts: async (taskId, selectedCommit, offset = 0) => {
             if (store.getTask(taskId) === null)
                 throw new WebRequestRejected("Task not found.");
-            const repo = openTaskArtifactRepository(store.rootDirectory(), taskId);
+            const repo = openTaskArtifactRepository(store.rootDirectory(), taskId, () => store.getConfig());
             if (selectedCommit !== undefined && !repo.exists())
                 throw new WebRequestRejected("Artifact revision unavailable.");
             const commit = selectedCommit ?? await repo.head();
@@ -151,12 +151,12 @@ export function createWebTaskSurface(store, options = {}, observations = [], hos
                 throw new WebRequestRejected("Task not found.");
             // The browser always names a fixed revision. Never substitute HEAD after
             // a missing object, and never execute/render artifact HTML as an app.
-            return readArtifactPreview(store.rootDirectory(), taskId, { taskId, relativePath, commit }, offset);
+            return readArtifactPreview(store.rootDirectory(), taskId, { taskId, relativePath, commit }, offset, () => store.getConfig());
         },
         artifactDiff: async (taskId, relativePath, commit, beforeCommit, offset = 0) => {
             if (store.getTask(taskId) === null)
                 throw new WebRequestRejected("Task not found.");
-            return compareTextArtifacts(store.rootDirectory(), taskId, { taskId, relativePath, commit: beforeCommit }, { taskId, relativePath, commit }, offset);
+            return compareTextArtifacts(store.rootDirectory(), taskId, { taskId, relativePath, commit: beforeCommit }, { taskId, relativePath, commit }, offset, () => store.getConfig());
         },
         globalState: (roleName) => {
             const role = store.getGlobalRole(roleName);

package/dist/workspace/workItemChangeSetManager.js

@@ -26,7 +26,7 @@ export class WorkItemChangeSetManager {
         const context = requireCapturableContext(this.store, taskId, workItemId, options.taskFinalReviewContract);
         const entries = capturableEntries(context);
         if (context.source === "task-main") {
-            const git = new NodeGitWorkspace();
+            const git = new NodeGitWorkspace(() => this.store.getConfig());
             for (const { entry, expectedHead } of entries) {
                 if (!await git.isClean(entry.path)) {
                     throw new Error(`Exact direct Candidate Task main must be clean: ${context.workItemId}/${entry.projectId}.`);
@@ -64,7 +64,7 @@ export class WorkItemChangeSetManager {
         const workspace = this.store.getWorkItemWorkspace(item.taskId, item.id);
         if (workspace === null)
             return { proof: null, checks: [] };
-        const git = new NodeGitWorkspace();
+        const git = new NodeGitWorkspace(() => this.store.getConfig());
         const projects = [];
         const checks = [];
         const sources = [`work-item:${taskId}/${workItemId}`,
@@ -189,7 +189,7 @@ export class WorkItemChangeSetManager {
         if (unresolved !== undefined) {
             throw new Error(`Task has an unresolved Integration Attempt: ${task.id}/${unresolved.id}.`);
         }
-        const git = new NodeGitWorkspace();
+        const git = new NodeGitWorkspace(() => this.store.getConfig());
         const remoteHeads = new Map();
         const findPublishedCommit = async (entry, headCommit) => {
             const project = this.store.getProject(entry.projectId);

package/docs/managed-turn-and-session-runtime.md

@@ -2,6 +2,99 @@
 
 # Session, AgentRun and notifications
 
+## Two lifecycle layers and nonblocking checks
+
+Controller custody of a Host and the Host's native Session lifecycle have
+separate event/guard/transition tables. Neither is an upgrade workflow.
+
+| Layer | Events and transitions | Authority and correlation |
+| --- | --- | --- |
+| Controller → Host | Fresh physical observations recover `unavailable`/`stopped`/`starting`/`running`. Authorized launch enters `starting`; matching launch handshake enters `running`. Stop or graceful-exit request enters `stopping`; sending exit does not prove `stopped`. Physical absence confirms `stopped`; unknown effects enter `unavailable`. | Owner, local operation/revision, returned binding and native Session ID. Durable Role/Task intent, launch reservations and exact process custody remain authoritative. |
+| Host → native Session | Launch, attachment, input acceptance, native activity, terminal, persistence, disconnect and exit drive the native states described below. | Native Session, proxy process, attempt and Turn identity; existing writer/resource fences still authorize effects. |
+
+The Controller wraps the shared Host port for launch/restore, observation and
+stop, including graceful-upgrade exit. A competing physical operation is
+rejected before its side effect, not queued or replayed by this FSM. Late
+reads and old bindings cannot overwrite newer custody; identical observations
+produce no hook feedback loop. A Controller restart reconstructs by observation,
+never by replaying the process-local state. Native completion/attachment exit
+does not prove Host process exit. Legal same-conversation resume correlates the
+layers without sharing their state enums or inventing another durable authority.
+
+Host-side native Session lifecycle state is owned by an explicit transition table, not
+by version detection. Launch/submit enters `starting`; attachment facts select
+`idle`, `busy`, `ready` (owned input), or `delivery-unknown`; acceptance enters
+`ready`; native execution enters `busy`; terminal handling enters `settling`;
+persisted settlement returns to observed `idle`/`busy`. Disconnect enters
+`starting`, classified failures retain their failure outcome, and exit enters
+`exited`. Only an explicit launch can leave `exited`. Native-TUI attachment
+readiness has its own event: `ready` there is not proof of native quiescence.
+Illegal edges do not mutate state; stale process, attempt and terminal-Turn
+facts are ignored. Exact writer/resource guards remain at command admission.
+This process-local reducer reconstructs from existing launch and native facts;
+it adds no persisted Session authority or upgrade workflow state machine.
+
+Optional before/after observations are immutable, deferred and independently
+coalesced (at most one running and one latest pending observation per check).
+“Before” describes the transition's source, not an awaited precondition.
+A slow or failing check cannot veto a transition or hold event folding/input
+delivery; checks must yield for I/O and honour cancellation before effects.
+They may recommend work to the separate fenced upgrade coordinator.
+Controller Host-state hooks suggest version reconciliation. Host Session-state
+hooks asynchronously observe current Skill metadata on attachment/settlement,
+without reading Skill bodies, committing a notice or assuming model memory.
+The exact per-input integrity check remains an ingress safeguard: invalid
+Skills can reject that input, but an optional check cannot stall lifecycle.
+Only accepted input advances the existing notice baseline; unchanged input
+is passed through without any extra content.
+
+Controller startup, Host connection/exit observations, Host state-change
+signals and event persistence trigger version checks without an explicit
+`update` request. Existing periodic reconciliation covers missed hints,
+including providers without reliable background-execution-end events and
+graceful exits that cannot emit a post-exit hint. Checks
+compare actual loaded Host/Endpoint implementations with this Controller's
+loaded target, never npm `latest`. Incomplete readiness on matching versions
+is not an upgrade reason. Checks stop on shutdown; already-admitted work
+retains the existing durable mailbox. A request pinned to a different target
+stays waiting for explicit recovery, not silent retargeting. An explicitly
+stopped Session is never restarted by a check.
+
+## Host upgrade and context checks
+
+`update` reports package installation, verified Controller startup and each
+Host separately. `update --hosts-status` reads current per-Host evidence without
+installing, starting or advancing a switch. Supported controlled Codex Hosts fence new input immediately,
+wait for the current native Turn and event persistence, inspect native background
+execution, and release their owned Endpoint before exiting gracefully. The
+existing role-runtime mailbox retains the exact generation, native Session,
+configuration digest and drain receipt across Controller restarts. A successor
+uses the recorded effective configuration and resumes that same conversation;
+only its loaded Host/Endpoint and control/event handshake confirm success.
+Queued Messages remain original and accepted/unknown inputs are never replayed.
+
+Paused Roles stay paused. Older Hosts, native-TUI-only attachments and Endpoints
+without a quiescence capability are retained with an unsupported diagnosis; no
+unsupported drain command is sent. A busy/unknown native execution has no
+bounded upgrade-completion promise. An uncertain launch is not automatically
+repeated; a later exact successful handshake can settle the retained request.
+This fence covers Host-controlled ingress, not arbitrary external native clients;
+it never terminates a shared daemon or native conversation.
+
+Host Skill checks still run before every input. Unchanged inputs are passed
+through exactly, with no notice, marker, separator or extra native input part.
+The attachment's loading guidance explains this managed-input contract; no
+notice is not a reason to repeat the check. Unmediated clients or uncertain
+current input routing retain the explicit Manifest check fallback; reusing a
+conversation alone does not establish Host mediation. Cold attachment,
+affected Skill changes and observed native compaction supply loading guidance;
+compaction invalidates the next input's metadata baseline. Without a reliable
+native event, the Agent must still recover any missing instructions using the
+Manifest. Neither a version nor an accepted notice proves model memory.
+Routine checks and empty inboxes are not user-facing progress.
+
+## Session stop and runtime observations
+
 Global Session stop/replacement uses the same exact native-execution quiescence
 boundary as Task Sessions. A departed Host or archived Session alone is not
 proof that an accepted input ended: its retained Provider binding is inspected
@@ -31,7 +124,9 @@ Samples use a process-monotonic clock and hashed target/request labels, with
 at most 16 recent and 16 active samples plus the slowest completed sample.
 In-flight request count is not queue depth; total client-to-route wait is not
 measured by the server alone. These observations neither identify an old incident
-retroactively nor establish quiescence; restarting a Controller does not refresh live Hosts.
+retroactively nor establish quiescence. A Controller restart does not itself
+prove Host replacement; asynchronous lifecycle checks still require a safe
+drain and the successor's actual handshake.
 
 `observations.commands.routes.transport` correlates socket accept-to-route,
 complete-frame receive-to-route and route-to-local-flush stages by the same

package/docs/managed-turn-and-session-runtime.zh-CN.md

@@ -2,6 +2,74 @@
 
 # Session、AgentRun 与通知
 
+## 两层生命周期与非阻塞检查
+
+Controller 对 Host 的管理状态、Host 对原生 Session 的生命周期分别拥有自己的
+事件、guard 和转换表，都不是升级流程状态机。
+
+| 层级 | 事件与转换 | 权限及关联 |
+| --- | --- | --- |
+| Controller → Host | 新鲜物理观测恢复 `unavailable`／`stopped`／`starting`／`running`；合法 launch 进入 `starting`，匹配启动握手进入 `running`。停止或优雅退出请求进入 `stopping`，发送退出不证明 `stopped`；物理不存在才确认 `stopped`，未知效果进入 `unavailable`。 | owner、本地操作／观测 revision、返回 binding 和原生 Session ID；持久 Role／Task 意图、启动 reservation 和精确进程权属仍是权威。 |
+| Host → 原生 Session | launch、附件、输入接受、原生活动、终态、持久化、断连和退出驱动下述原生状态。 | 原生 Session、proxy 进程、attempt 和 Turn 身份；原有 writer／资源栅栏继续授权副作用。 |
+
+Controller 在共享 Host port 处统一管理启动／恢复、观测与停止（含安全升级的优雅退出）。
+冲突物理操作在副作用前拒绝，不由状态机另建队列或重放。迟到读取和旧 binding 不能覆盖
+新管理状态；相同观测不重复触发检查反馈循环。Controller 重启后从观测重建，
+不重放进程内状态。原生轮次完成或附件退出不能证明 Host 进程已退出；
+合法恢复通过同一原生对话关联两层，不共用状态枚举或新增持久权威。
+
+Host 内的原生 Session 生命周期由明确的转换表管理，不由版本检查管理。
+launch／submit 进入 `starting`；附件事实选择 `idle`、`busy`、
+`ready`（持有输入）或 `delivery-unknown`；接受输入进入 `ready`；
+原生执行进入 `busy`；终态处理进入 `settling`；持久化结清后回到观测到的
+`idle`／`busy`。断连进入 `starting`，分类失败保留对应失败状态，退出进入
+`exited`，只有显式 launch 可离开它。原生 TUI 附件就绪有独立事件，
+其 `ready` 不证明原生执行静止。非法边不改变状态；过期的进程、attempt、
+终态 Turn 事实被忽略。精确 writer／资源 guard 仍在命令准入处执行。
+状态机仅在进程内从现有 launch 和原生事实恢复，不新增持久 Session 权威或升级流程状态机。
+
+可组合的前／后检查接收不可变观测，各自异步执行并合并重复提示
+（每项最多一个执行中和一个最新待处理观测）。“前”表示转换来源，不是等待完成的前置条件。
+慢检查或失败不能否决转换、阻塞事件折叠或输入投递；检查回调必须异步等待 I/O，
+并在请求副作用前响应取消。它们只能向独立的、受精确栅栏保护的升级协调器提出请求。
+Controller 的 Host 状态 hook 提议版本对账；Host 的 Session 状态 hook 在附件和结清时
+异步观测当前 Skill 元数据，不读正文、不提交通知基线、不假定模型记忆。
+逐输入完整性核验仍是投递安全门：无效 Skill 可以拒绝该次输入，但可选检查不能卡住生命周期。
+仍只有被接受的输入推进通知基线，未变化输入原样通过，不额外注入内容。
+
+Controller 启动、Host 连接／退出观测、Host 状态变化 signal 和事件持久化均可触发版本检查，
+不依赖显式 `update`。现有周期对账覆盖丢失提示、无法可靠提供后台执行结束事件的提供方，
+以及无法在退出后发出提示的优雅退出。
+比较对象是实际加载的 Host／Endpoint 实现与当前 Controller 已加载的目标，不查询 npm `latest`。
+版本匹配但就绪证据未齐不是升级理由。关闭时停止检查，已准入工作仍保留现有持久 mailbox；
+请求固定的目标与当前 Controller 不同时保持等待，交由显式恢复，不静默改目标。
+检查不会复活明确停止的 Session。
+
+## Host 升级与上下文检查
+
+`update` 分别报告程序安装、Controller 启动核验及逐 Host 的状态。
+`update --hosts-status` 只读查询逐 Host 证据，不安装、启动或推进切换。支持此能力的
+受控 Codex Host 先关闭新输入准入，等待当前原生轮次和事件持久化、核验后台执行，
+释放自己持有的 Endpoint 后优雅退出。现有 role-runtime mailbox 保存精确实现代际、
+native Session、配置摘要和排空回执，Controller 重启后仍可继续。
+后继使用原 effective 配置接回同一对话；实际加载的 Host/Endpoint、控制与事件能力
+握手通过后才确认成功。队列中的 Message 原文不变，不重放 accepted 或 unknown 输入。
+
+暂停角色保持暂停。旧 Host、仅有原生 TUI 的附件及不能证明静止的 Endpoint
+保留并报告不支持，不反复发送不支持的排空命令。忙碌或未知执行不承诺限时升级。
+启动结果未知不自动重放；后续精确成功握手可结清原请求。
+准入栅栏覆盖 Host 控制的入口，不控制任意外部原生客户端，也不会终止共享 daemon 或原生对话。
+
+Host 仍逐输入机械检查 Skills。未变化时原文原样通过，不添加检查通知、隐藏标记、
+分隔换行或原生输入片段。附件加载指引说明这一托管输入约定，不因没有通知而重复检查。
+绕过 Host 的客户端或当前输入路由不明时仍通过 Manifest 显式检查；复用同一对话
+本身不证明当前输入受 Host 托管。首次附件、局部 Skill 变化、已观测到的原生压缩
+提供相应加载指引；压缩使下一次输入的元数据基线失效。
+提供方无法可靠暴露事件时，Agent 仍须通过 Manifest 恢复缺失指令。
+版本和已接受的通知都不能证明模型记忆；例行检查、角色版本和空 inbox 不作为用户进度播报。
+
+## 会话停止与运行时观测
+
 局部停止等待自身的持久清理义务完成，不等待整个 Home 的 `scheduler.scan`
 循环排空。signal 只请求调度；完成仍以现有物理停止证明及清理事务为准。
 超时保留义务并阻止替换；选择失败和新会话启动未确认分别报告，不允许重放未知效果。
@@ -16,7 +84,8 @@ interrupt-owned 输入仍保留原处理路径。
 目标／请求标签仅保存哈希；每组最多保留 16 个近期样本、16 个活动样本及最慢完成样本。
 in-flight 请求数不是排队数，服务端不能独自测量客户端到路由的完整等待。
 观测不能反推旧事故的唯一根因，
-也不构成静止证明；重启 Controller 不会刷新存活 Host。
+也不构成静止证明；Controller 重启本身不证明 Host 已替换，
+异步生命周期检查仍须经过安全排空和后继实际握手。
 
 `observations.commands.routes.transport` 使用与 route service time 相同的请求哈希，
 分别关联 socket accept→route、完整帧 receive→route、route→本地 flush。

package/docs/project-refresh.md

@@ -80,7 +80,8 @@ upstream is left untouched and carries no such promise.
 
 ## Scope of adoption
 
-This operation adds no persistent Yui schema or migration. Installing code
-that implements it does not itself refresh a real Project. A normal authorized
+Refresh bookkeeping adds no persistent Yui schema. The shared remote Git
+budget settings require storage 1.29; see [configuration](roles-and-configuration.md#git-operation-budgets).
+Installing this code does not itself refresh a real Project. A normal authorized
 refresh applies the behavior; Task completion, integration, publication and
 archive remain separate operations.

package/docs/project-refresh.zh-CN.md

@@ -63,5 +63,6 @@ upstream 保持原样，不作这一承诺。
 
 ## 采用边界
 
-本操作不新增 Yui 持久 schema 或迁移。安装实现代码不等于刷新真实 Project；
+refresh 记账不新增 Yui 持久 schema；共享远程 Git 预算配置要求存储 1.29，
+见[配置说明](roles-and-configuration.zh-CN.md#git-操作预算)。安装实现代码不等于刷新真实 Project；
 正常获授权的 refresh 才应用此行为。Task 完成、集成、发布和归档仍是独立操作。