@zq-silk/yui 2.21.0 → 2.23.0

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -43,7 +43,7 @@ import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { RUNTIME_CLEANUP_REQUIRED_REASON, RUNTIME_HOST_DETACH_REQUIRED_REASON, RUNTIME_LIFECYCLE_OWNER, hasRuntimeCleanupObligation, hasRuntimeLifecycleWork, isRuntimeCleanupReason, runtimeCleanupDisposition, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { classifyRuntimeProcessExit, validateRuntimeProcessExitObservation } from "../runtime/processExitObservation.js";
 import { providerContinuationKey } from "../runtime/providerContinuation.js";
-import { acceptProviderTurn, beginProviderTurn, cancelQuiescentProviderInput, clearProviderGoal, createProviderRuntimeBinding, currentProviderConversation, managedProviderTurnId, settleProviderTurn, settleProviderTurnSubmission, supersedeProviderConversation, transferProviderAuthority, updateProviderConversationRecoverability, updateProviderGoal } from "../runtime/providerRuntimeIdentity.js";
+import { acceptProviderTurn, beginProviderTurn, cancelQuiescentProviderInput, clearProviderGoal, createProviderRuntimeBinding, currentProviderConversation, managedProviderTurnId, providerTurnIsActive, settleProviderTurn, settleProviderTurnSubmission, supersedeProviderConversation, transferProviderAuthority, updateProviderConversationRecoverability, updateProviderGoal } from "../runtime/providerRuntimeIdentity.js";
 import { projectProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
 import { RUNTIME_OBSERVATION_TASK_EVENT, createRuntimeObservation, isRuntimeUsageEvidence, runtimeObservationFenceMatches, runtimeObservationFromTaskEvent, runtimeObservationRunFenceMatches, runtimeObservationTaskEventPayload } from "../runtime/runtimeObservation.js";
 import { recordLeaderFailure } from "../scheduler/leaderFailure.js";
@@ -106,11 +106,24 @@ export class FileSchedulerStoreAdapter {
         return errors;
     }
     observeAgentHostObservation(event, now = new Date()) {
+        let preparation;
+        if (isRunTerminalObservation(event.observation)) {
+            preparation = {};
+            try {
+                preparation = this.prepareRuntimeTerminalObservation(resolveAgentHostObservation(this.store, event), now);
+            }
+            catch (error) {
+                if (!(error instanceof AgentHostObservationDeferred || error instanceof RuntimeHookRunFenceError))
+                    throw error;
+                // Re-resolve under the committing fence below; preparation grants no
+                // authority and must not settle a deferred/obsolete Host envelope.
+            }
+        }
         // Match canonical ingress: archive and Host fact settlement share the
         // same write boundary, including the original transport envelope.
-        return this.store.transaction(() => this.foldAgentHostObservation(event, now));
+        return this.store.transaction(() => this.foldAgentHostObservation(event, now, preparation));
     }
-    foldAgentHostObservation(event, now) {
+    foldAgentHostObservation(event, now, preparation) {
         const raw = createRuntimeObservation(event.observation);
         const task = raw.fence.taskId === undefined ? null : this.store.getTask(raw.fence.taskId);
         if (raw.fence.taskId !== undefined && task === null)
@@ -154,7 +167,7 @@ export class FileSchedulerStoreAdapter {
             // Rejection is durable diagnostic evidence, never business acceptance.
             return this.recordObsoleteCanonicalObservation(event.observation, error.message, now);
         }
-        return this.observeRuntimeObservation(input, now);
+        return this.foldRuntimeObservation(input, now, preparation);
     }
     /**
      * Sole provider-independent ingress for structured runtime state. Driver
@@ -163,12 +176,30 @@ export class FileSchedulerStoreAdapter {
      * transitions, and retains the canonical observation for status projection.
      */
     observeRuntimeObservation(raw, now = new Date()) {
+        const preparation = this.prepareRuntimeTerminalObservation(raw, now);
         // Archive and observation settlement share the same write boundary.
         // An ingress read outside this transaction must never authorize clearing
         // a claim after another CLI has committed archive.
-        return this.store.transaction(() => this.foldRuntimeObservation(raw, now));
+        return this.store.transaction(() => this.foldRuntimeObservation(raw, now, preparation));
     }
-    foldRuntimeObservation(raw, now) {
+    prepareRuntimeTerminalObservation(raw, now) {
+        const input = createRuntimeObservation(raw);
+        if (!isRunTerminalObservation(input))
+            return undefined;
+        if (input.fence.taskId === undefined || Date.parse(input.receivedAt) > now.getTime())
+            return {};
+        const adapterId = this.adapterForRuntimeObservation(input);
+        if (adapterId === null)
+            return {};
+        return this.prepareRuntimeTerminal({
+            taskId: input.fence.taskId, roleName: input.fence.roleName,
+            agentId: input.fence.agentId, adapterId, conversationId: input.fence.conversationId,
+            nativeSessionId: input.fence.nativeSessionId, nativeTurnId: input.fence.nativeTurnId,
+            attemptId: input.fence.receiptId, runId: input.fence.runId
+        }, input.kind === "turn.completed" && input.payload.resultTransportDiagnostic === undefined
+            && transportAgentResult(input.payload.output).status === "completed");
+    }
+    foldRuntimeObservation(raw, now, preparation) {
         const input = createRuntimeObservation(raw);
         const taskId = input.fence.taskId;
         if (taskId === undefined)
@@ -263,13 +294,13 @@ export class FileSchedulerStoreAdapter {
                 outcome = this.observeRuntimePromptAccepted(input, adapterId, now);
                 break;
             case "turn.completed":
-                outcome = this.foldProviderTurnBoundary(input, adapterId, "completed", now);
+                outcome = this.foldProviderTurnBoundary(input, adapterId, "completed", now, preparation);
                 break;
             case "turn.failed": {
                 // A Provider Turn is an activation boundary, not a Task outcome.
                 // Keep the AgentRun and Session identity available for Agent-directed
                 // restore + submit, even when a provider marks its AgentRun terminal.
-                outcome = this.foldProviderTurnBoundary(input, adapterId, "failed", now);
+                outcome = this.foldProviderTurnBoundary(input, adapterId, "failed", now, preparation);
                 break;
             }
             case "operation.started":
@@ -286,7 +317,7 @@ export class FileSchedulerStoreAdapter {
                 outcome = this.validateCanonicalRunObservation(input, now);
                 break;
             case "turn.cancelled": {
-                outcome = this.foldProviderTurnBoundary(input, adapterId, "cancelled", now);
+                outcome = this.foldProviderTurnBoundary(input, adapterId, "cancelled", now, preparation);
                 break;
             }
             case "conversation.observed":
@@ -617,7 +648,7 @@ export class FileSchedulerStoreAdapter {
             return "applied";
         });
     }
-    foldProviderTurnBoundary(input, adapterId, providerStatus, now) {
+    foldProviderTurnBoundary(input, adapterId, providerStatus, now, preparation) {
         const outcome = providerStatus === "completed"
             ? input.payload.resultTransportDiagnostic === undefined
                 ? transportAgentResult(input.payload.output)
@@ -656,7 +687,7 @@ export class FileSchedulerStoreAdapter {
         const classification = this.classifyRuntimeRunTerminal(completed);
         if (classification !== "apply")
             return classification;
-        const result = this.observeRuntimeRunTerminal(completed, now);
+        const result = this.foldRuntimeRunTerminal(completed, now, preparation ?? {});
         return result.disposition === "obsolete" ? "obsolete" : "applied";
     }
     validateCanonicalSessionObservation(input, now) {
@@ -1692,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;
@@ -1774,8 +1807,7 @@ export class FileSchedulerStoreAdapter {
     listDormantRuntimeOwners() {
         return this.listRuntimeSessionCandidates().flatMap((candidate) => {
             if (hasRuntimeLifecycleWork(this.store.getWorkMailbox(runtimeLifecycleTarget(candidate.owner)))
-                || (candidate.owner.scope === "task"
-                    && this.store.getActiveRun(candidate.owner.taskId, candidate.owner.roleName) !== null)) {
+                || runtimeOwnerHasActiveWork(this.store, candidate.owner)) {
                 return [];
             }
             return [{
@@ -2282,17 +2314,24 @@ export class FileSchedulerStoreAdapter {
     classifyRuntimeRunTerminal(input) {
         return resolveTerminalExecution(this.store, input) === null ? "obsolete" : "apply";
     }
+    prepareRuntimeTerminal(input, completed) {
+        const run = resolveTerminalExecution(this.store, input)?.run;
+        const workspace = run?.status === "active"
+            && run.executionGroupId !== undefined
+            && run.executionLaneId !== undefined
+            && run.workspace !== undefined
+            && completed
+            ? this.#observeRead("git-workspace-snapshot", run.taskId, () => this.snapshotExecutionLaneWorkspace(this.store, run.workspace))
+            : undefined;
+        return { run, workspace };
+    }
     observeRuntimeRunTerminal(input, now = new Date()) {
+        return this.foldRuntimeRunTerminal(input, now, this.prepareRuntimeTerminal(input, input.outcome.status === "completed"));
+    }
+    foldRuntimeRunTerminal(input, now, preparation) {
         // Resource inspection is bounded but external to SQLite. Revalidate the
         // immutable AgentRun workspace after acquiring the write transaction.
-        const preparedRun = resolveTerminalExecution(this.store, input)?.run;
-        const workspace = preparedRun?.status === "active"
-            && preparedRun.executionGroupId !== undefined
-            && preparedRun.executionLaneId !== undefined
-            && preparedRun.workspace !== undefined
-            && input.outcome.status === "completed"
-            ? this.#observeRead("git-workspace-snapshot", preparedRun.taskId, () => this.snapshotExecutionLaneWorkspace(this.store, preparedRun.workspace))
-            : undefined;
+        const { run: preparedRun, workspace } = preparation;
         return this.store.transaction((store) => {
             const task = store.getTask(input.taskId);
             if (task === null)
@@ -2304,7 +2343,8 @@ export class FileSchedulerStoreAdapter {
             if (resolved === null)
                 throw new Error("Runtime terminal has no exact execution binding.");
             const { run: observedRun, current: recordedProviderTurn, attemptId } = resolved;
-            if (!isDeepStrictEqual(preparedRun?.workspace, observedRun?.workspace)) {
+            if (preparedRun?.id !== observedRun?.id
+                || !isDeepStrictEqual(preparedRun?.workspace, observedRun?.workspace)) {
                 throw new Error("Runtime terminal workspace changed during result preparation.");
             }
             if (workspace !== undefined && observedRun?.workspace !== undefined
@@ -3132,8 +3172,7 @@ function sameRuntimeOwner(left, right) {
 }
 function dormantRuntimeCandidateIsCurrent(store, candidate, allowActiveRun = false) {
     const { owner } = candidate;
-    if (!allowActiveRun && owner.scope === "task"
-        && store.getActiveRun(owner.taskId, owner.roleName) !== null) {
+    if (!allowActiveRun && runtimeOwnerHasActiveWork(store, owner)) {
         return false;
     }
     const sessions = runtimeOwnerSessionSet(store, owner);
@@ -3143,6 +3182,17 @@ function dormantRuntimeCandidateIsCurrent(store, candidate, allowActiveRun = fal
     return active !== undefined && active.agentId === candidate.agentId && active.adapterId === candidate.adapterId
         && active.nativeSessionId === candidate.nativeSessionId && (allowActiveRun || active.updatedAt === candidate.sessionUpdatedAt);
 }
+function runtimeOwnerHasActiveWork(store, owner) {
+    if (owner.scope === "task")
+        return store.getActiveRun(owner.taskId, owner.roleName) !== null;
+    // Global Turns do not have Task AgentRun records. Use their existing native
+    // delivery binding, including submitting and uncertain acceptance.
+    const sessions = store.getGlobalRoleSessionSet(owner.roleName);
+    const binding = sessions?.providerBinding;
+    return binding != null && (providerTurnIsActive(binding.run)
+        || currentProviderConversation(binding).conversationId
+            !== sessions?.sessions[sessions.activeAgentId]?.nativeSessionId);
+}
 function endRuntimeOwnerSession(store, owner, now) {
     if (owner.scope === "task") {
         const sessions = store.getTaskRoleSessionSet(owner.taskId, owner.roleName);

package/dist/controller/hostLifecycle.js

@@ -0,0 +1,153 @@
+import { createRuntimeBinding } from "../runtime/runtimeBinding.js";
+import { normalizeRuntimeOwner } from "../runtime/runtimeOwner.js";
+import { RuntimeHostContentionError } from "../runtime/ports.js";
+const states = ["unavailable", "stopped", "starting", "running", "stopping"];
+export const CONTROLLER_HOST_TRANSITIONS = {
+    launch: { from: ["unavailable", "stopped", "running"], to: "starting" },
+    launched: { from: ["starting"], to: "running" },
+    stop: { from: states, to: "stopping" },
+    "exit-sent": { from: ["stopping"], to: "stopping" },
+    stopped: { from: ["stopping"], to: "stopped" },
+    failed: { from: ["starting", "stopping"], to: "unavailable" },
+    observed: { from: states, to: (current, observed) => current === "stopping" && (observed.state === "running" || observed.state === "starting")
+            ? "stopping" : observed.state }
+};
+/** All physical effects still require their existing durable caller authority.
+ * This process-local FSM gates competing effects at the shared Host port.
+ * Recovery observes current custody; it never invents a launch or replays one.
+ * Observation revisions reject late reads, not external process identities:
+ * exact OS/native identities remain owned by SessionOwner/Host fences. */
+export function createControllerHostLifecycle(raw, hooks = {}) {
+    const entries = new Map();
+    let nextOperation = 0;
+    const entryFor = (input) => {
+        const owner = normalizeRuntimeOwner(input);
+        const key = JSON.stringify(owner);
+        let entry = entries.get(key);
+        if (!entry) {
+            entry = { owner: Object.freeze(owner), state: "unavailable", revision: 0 };
+            entries.set(key, entry);
+        }
+        return entry;
+    };
+    const send = (entry, event, observed, binding) => {
+        const rule = CONTROLLER_HOST_TRANSITIONS[event];
+        if (!rule.from.includes(entry.state))
+            throw new RuntimeHostContentionError("previous-process", `Host lifecycle cannot ${event} from ${entry.state}.`);
+        const to = typeof rule.to === "function" ? rule.to(entry.state, observed) : rule.to;
+        const nativeSessionId = to === "stopped" ? undefined
+            : binding?.nativeSessionId ?? observed?.nativeSessionId ?? entry.nativeSessionId;
+        const bindingId = to === "stopped" ? undefined
+            : observed?.nativeSessionId && observed.nativeSessionId !== entry.nativeSessionId
+                ? undefined : binding?.id ?? entry.bindingId;
+        if (event === "observed" && to === entry.state && nativeSessionId === entry.nativeSessionId)
+            return;
+        const transition = Object.freeze({ owner: entry.owner, from: entry.state, to, event,
+            revision: entry.revision + 1, operationId: entry.operationId, nativeSessionId, bindingId });
+        hooks.before?.notify(transition);
+        entry.state = to;
+        entry.revision = transition.revision;
+        entry.nativeSessionId = nativeSessionId;
+        entry.bindingId = bindingId;
+        hooks.after?.notify(transition);
+    };
+    const observe = (entry, revision, inspection) => {
+        if (entry.revision === revision && entry.operationId === undefined)
+            send(entry, "observed", inspection);
+        return inspection;
+    };
+    const effect = async (owner, event, run) => {
+        const entry = entryFor(owner);
+        if (entry.operationId !== undefined)
+            throw new RuntimeHostContentionError("previous-process", `Host lifecycle already has an in-flight operation for ${owner.roleName}.`);
+        // Check state before reserving the operation; a rejected edge owns nothing.
+        if (!CONTROLLER_HOST_TRANSITIONS[event].from.includes(entry.state))
+            throw new RuntimeHostContentionError("previous-process", `Host lifecycle cannot ${event} from ${entry.state}.`);
+        entry.operationId = ++nextOperation;
+        send(entry, event);
+        try {
+            return await run(entry);
+        }
+        catch (error) {
+            send(entry, "failed");
+            throw error;
+        }
+        finally {
+            entry.operationId = undefined;
+        }
+    };
+    const inspectOwner = async (owner) => {
+        const entry = entryFor(owner), revision = entry.revision;
+        return observe(entry, revision, await raw.inspectOwner(owner));
+    };
+    const launch = async (request, before) => {
+        await inspectOwner(request.owner);
+        return effect(request.owner, "launch", async (entry) => {
+            const binding = createRuntimeBinding(request.mode === "new"
+                ? await raw.start(request, before) : await raw.restore(request, before));
+            if (JSON.stringify(normalizeRuntimeOwner(binding.owner)) !== JSON.stringify(entry.owner)
+                || binding.agentId !== request.agentId || binding.adapterId !== request.adapterId
+                || request.mode === "resume" && binding.nativeSessionId !== request.nativeSessionId) {
+                throw new Error("Host lifecycle launch handshake has mismatched owner/native identity.");
+            }
+            send(entry, "launched", undefined, binding);
+            return binding;
+        });
+    };
+    const port = {
+        start: launch, restore: launch, inspectOwner,
+        inspect: async (binding) => {
+            const entry = entryFor(binding.owner), revision = entry.revision;
+            const inspection = await raw.inspect(binding);
+            if (entry.bindingId && entry.bindingId !== binding.id
+                || entry.nativeSessionId && binding.nativeSessionId !== entry.nativeSessionId)
+                return inspection;
+            return observe(entry, revision, inspection);
+        },
+        ...(raw.inspectOwners === undefined ? {} : {
+            inspectOwners: async (owners) => {
+                const revisions = new Map(owners.map(owner => {
+                    const entry = entryFor(owner);
+                    return [entry, entry.revision];
+                }));
+                const results = await raw.inspectOwners(owners);
+                for (const { owner, inspection } of results) {
+                    const entry = entryFor(owner), revision = revisions.get(entry);
+                    if (revision !== undefined)
+                        observe(entry, revision, inspection);
+                }
+                return results;
+            }
+        }),
+        stop: async (binding) => {
+            const current = entryFor(binding.owner);
+            if (current.nativeSessionId && binding.nativeSessionId !== current.nativeSessionId
+                || current.bindingId && binding.id !== current.bindingId) {
+                throw new Error("Host lifecycle stop carries a stale binding identity.");
+            }
+            return effect(binding.owner, "stop", async (entry) => {
+                await raw.stop(binding);
+                const observed = await raw.inspect(binding);
+                if (observed.state !== "stopped")
+                    throw new Error("Host lifecycle stop has no physical exit proof.");
+                send(entry, "stopped");
+            });
+        },
+        stopOwner: owner => effect(owner, "stop", async (entry) => {
+            const stopped = await (hooks.stopOwner ? hooks.stopOwner(owner) : raw.stopOwner(owner));
+            send(entry, stopped ? "stopped" : "failed");
+            return stopped;
+        })
+    };
+    return {
+        port,
+        snapshot: (owner) => Object.freeze({ ...entryFor(owner) }),
+        // Graceful exit acknowledgement is not exit proof. A later physical
+        // observation moves stopping -> stopped; no timer or automatic replay.
+        requestExit: (owner, run) => effect(owner, "stop", async (entry) => {
+            const result = await run();
+            send(entry, "exit-sent");
+            return result;
+        })
+    };
+}

package/dist/controller/hostLifecycleChecks.js

@@ -0,0 +1,27 @@
+import { createNonBlockingChecks } from "../runtime/lifecycleChecks.js";
+/** Checks produce a recommendation; only the separately fenced coordinator
+ * can admit/execute it. Hints contain no target identity or restart authority. */
+export function createHostLifecycleChecks(coordinator, onError = () => { }) {
+    const checks = createNonBlockingChecks([{
+            id: "host-version",
+            run: async (_hint, signal) => {
+                const observations = await coordinator.status();
+                if (signal.aborted)
+                    return;
+                const recommended = coordinator.hasPending() || observations.some(entry => entry.status === "waiting" || entry.status === "unknown" || entry.status === "failed");
+                if (!recommended)
+                    return;
+                // This await belongs exclusively to this optional check lane. Neither
+                // Host transitions nor Controller event folding wait for this operation.
+                const results = await coordinator.request();
+                for (const entry of results) {
+                    if (entry.status === "failed" || entry.status === "unknown") {
+                        onError(new Error(`Host upgrade ${entry.owner.roleName}/${entry.nativeSessionId}: ${entry.detail}`));
+                    }
+                }
+            }
+        }], onError);
+    const close = checks.close;
+    checks.close = () => { close(); coordinator.stop(); };
+    return checks;
+}