@zq-silk/yui 0.11.3 → 0.12.1

package/dist/interaction/operatorPresentation.js

@@ -1,96 +1,40 @@
-import { formatTimestamp } from "../output/timePresentation.js";
-import { formatInputRequestReceiptId, formatTaskRecordReference } from "../task/taskRecordReference.js";
-export function createInputRequestOperatorPresentation(request, context) {
-    const policy = request.policy;
-    const recommendation = policy.kind === "recommended"
-        ? request.choices.find(({ key }) => key === policy.recommendedChoiceKey)
-        : undefined;
-    if (policy.kind === "recommended" && recommendation === undefined) {
-        throw new Error(`Input request ${request.id} recommendation ${policy.recommendedChoiceKey} is missing.`);
-    }
-    return {
-        category: "attention",
-        taskId: request.taskId,
-        receiptId: formatInputRequestReceiptId(request.taskId, request.id),
-        source: { kind: "input-request", taskId: request.taskId, localId: request.id },
-        text: [
-            "A Task Leader is waiting for a boundary decision. Inspect it before involving the user.",
-            "Present it only when it is a user-owned choice, authorization, credential, unavailable external fact, or irreversible operation.",
-            `If it is an implementation, scheduling, review, or recoverable runtime choice, do not present it to the user; return it to the Leader with: yui task input cancel ${request.taskId} ${request.id} --reason \"Operator returned: not a user-owned boundary\"`,
-            "For a user-owned boundary, do not answer it yourself; do not answer or choose on the user's behalf; relay the user's exact response only.",
-            `Task: ${request.taskId}`,
-            `Input: ${request.id}`,
-            `Question: ${request.question}`,
-            ...(request.choices.length === 0
-                ? ["Answer type: free text"]
-                : ["Choices:", ...request.choices.map(({ key, label }) => `  ${key}: ${label}`)]),
-            ...(policy.kind === "required"
-                ? ["Decision policy: this requires the user's response; there is no automatic fallback."]
-                : [
-                    `Agent recommendation: ${recommendation.key}: ${recommendation.label}`,
-                    `Automatic fallback after: ${formatTimestamp(policy.timeoutAt, context.timeZone)}`
-                ]),
-            `Inspect: yui task input show ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")}`,
-            request.choices.length === 0
-                ? `After the user replies: yui task input answer ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")} --text "<answer>"`
-                : `After the user chooses: yui task input answer ${formatTaskRecordReference(request.taskId, request.id, "inputRequest")} --choice <key>`
-        ].join("\n")
-    };
-}
-export function createLeaderRecoveryOperatorPresentation(notification) {
+/**
+ * One mailbox batch becomes one short synthetic user message. The durable
+ * records remain the context authority; this wake text carries only stable
+ * identities and exact CLI reads, never copied Task or Provider narrative.
+ */
+export function createOperatorBatchPresentation(batchId, items) {
+    if (items.length === 0)
+        throw new Error("Operator presentation requires at least one item.");
     return {
-        category: "attention",
-        taskId: notification.taskId,
-        receiptId: `leader-recovery:${notification.taskId}:${notification.createdAt}`,
-        source: { kind: "leader-recovery", id: notification.taskId },
+        receiptId: `operator-batch:${batchId}`,
         text: [
-            "A Task cannot recover its Leader automatically and needs user attention.",
-            `Task: ${notification.taskId}`,
-            `Failure: ${notification.message}`,
-            `Inspect: yui task show ${notification.taskId}`,
-            "Recovery status: yui jobs list",
-            `Retry after inspection: yui jobs retry leader-recovery:${notification.taskId}`
+            "[Yui updates]",
+            "Yui recorded the following durable updates. Inspect the referenced records and present only information that changes the user's understanding, authorization, or next action.",
+            ...items.flatMap(renderItem)
         ].join("\n")
     };
 }
-export function createLeaderStallOperatorPresentation(notification) {
-    return {
-        category: "attention",
-        taskId: notification.taskId,
-        receiptId: `leader-stall:${notification.taskId}:${notification.runId}:${notification.progressAt}`,
-        source: {
-            kind: "leader-stall",
-            id: `${notification.runId}:${notification.progressAt}`
-        },
-        text: [
-            "A Task Leader is truly stalled and needs user attention.",
-            `Task: ${notification.taskId}`,
-            `Leader Run: ${notification.runId}`,
-            `lastProgressAt: ${notification.progressAt}`,
-            "Classification: truly-stalled",
-            `Evidence: ${notification.evidenceKey}`,
-            "Controller preserved the exact Run/Session fence and performed no automatic Enter, reset, retry, kill, or Session replacement.",
-            `Inspect: yui task context ${notification.taskId}`,
-            "Choose the supported continuation, reset, retry, Agent change, or user-input action only after inspection."
-        ].join("\n")
-    };
+function renderItem(item) {
+    if (item.kind === "input-request") {
+        const { request } = item;
+        return [
+            `- User input requested: ${request.taskId}/${request.id}`,
+            `  Inspect: yui task input show ${request.taskId}/${request.id}`
+        ];
+    }
+    const { event } = item;
+    return [
+        `- ${eventLabel(event)}: ${event.taskId}/${event.id}`,
+        `  Inspect: yui task event show ${event.taskId} ${event.id}`
+    ];
 }
-export function createTaskTerminalOperatorPresentation(notification) {
-    const action = notification.status === "completed" ? "completed" : "retired";
-    const actor = notification.by === "leader"
-        ? "its Leader"
-        : notification.by === "operator"
-            ? "the Operator"
-            : "the user";
-    return {
-        category: "information",
-        taskId: notification.taskId,
-        receiptId: `task-terminal:${notification.taskId}:${notification.status}:${notification.createdAt}`,
-        source: { kind: "task-terminal", id: notification.taskId },
-        text: [
-            `Task ${notification.taskId} was ${action} by ${actor}.`,
-            `Summary: ${notification.summary}`,
-            `Inspect: yui task show ${notification.taskId}`
-        ].join("\n")
-    };
+function eventLabel(event) {
+    switch (event.type) {
+        case "task.completed": return "Task completed";
+        case "task.retired": return "Task retired";
+        case "leader.attention-required": return "Task Leader needs attention";
+        case "run.stalled": return "Task Leader stalled";
+        default: return `Task event ${event.type}`;
+    }
 }

package/dist/lifecycle/exactRunTerminalization.js

@@ -12,7 +12,8 @@ import { createYieldReceipt } from "../run/yieldReceipt.js";
 import { recordExecutionLaneResult } from "../execution/executionGroup.js";
 import { isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { runOwnsBlockingProviderContinuation } from "../runtime/runtimeContinuationProjection.js";
-import { clearMatchingLeaderStallAttention, latestRunDurableProgressAt, RUN_RECOVERY_APPLIED_EVENT, RUN_RECOVERY_REQUESTED_EVENT } from "../scheduler/roleRunStall.js";
+import { runHasActiveRuntimeOperations } from "../runtime/runtimeObservation.js";
+import { latestRunDurableProgressAt, RUN_RECOVERY_APPLIED_EVENT, RUN_RECOVERY_REQUESTED_EVENT } from "../scheduler/roleRunStall.js";
 import { markTaskWakeConsumed } from "../scheduler/taskWake.js";
 import { workItemExecutionGroupById, workItemOwnsUnresolvedExecutionLane, updateWorkItemExecutionGroup, updateWorkItemStatus } from "../workItem/workItem.js";
 /**
@@ -352,7 +353,7 @@ export function terminalizeExactTaskRun(store, input, now) {
 /**
  * Leader-controlled recovery boundary for one active AgentRun. This primitive
  * validates every durable fence in one transaction and records only a
- * structured request for retry/session replacement. It never writes terminal
+ * structured request for same-Run diagnosis/retry. It never writes terminal
  * bytes, retries a provider input, kills a host, or silently rebinds a native
  * generation. Explicit termination is the sole action that changes Run state.
  */
@@ -420,6 +421,35 @@ function recoverExactAgentRunInTransaction(store, input) {
     if (!matchesRecoverySessionFence(store, input)) {
         return stateChanged("session-or-launch-fence-mismatch");
     }
+    const recoveryBlocker = exactRecoveryExecutionBlocker(store, current);
+    if (recoveryBlocker !== null) {
+        return {
+            disposition: "blocked",
+            action: input.action,
+            run: current,
+            progressAt: progress.progressAt,
+            reason: recoveryBlocker
+        };
+    }
+    if (input.action === "terminate") {
+        const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
+        const session = sessions?.sessions[input.agentId];
+        const providerTurn = sessions?.providerBinding?.turn;
+        const exactTerminalEvidence = session?.status === "stopped"
+            || session?.status === "broken"
+            || providerTurn?.status === "failed"
+            || providerTurn?.status === "cancelled"
+            || providerTurn?.status === "rejected";
+        if (!exactTerminalEvidence) {
+            return {
+                disposition: "blocked",
+                action: input.action,
+                run: current,
+                progressAt: progress.progressAt,
+                reason: "runtime-not-terminal"
+            };
+        }
+    }
     if (input.providerAcceptance === "ambiguous"
         && input.action !== "diagnose") {
         return {
@@ -496,7 +526,6 @@ function recoverExactAgentRunInTransaction(store, input) {
         }
     }
     store.saveEvent(input.taskId, createTaskEvent(store.nextEventId(input.taskId), input.taskId, RUN_RECOVERY_APPLIED_EVENT, { ...eventPayload, status: "terminated" }, input.now));
-    clearMatchingLeaderStallAttention(store, input.taskId, input.runId);
     if (input.roleName !== "leader") {
         enqueueWork(store, { kind: "role", taskId: input.taskId, roleName: "leader" }, "run-recovery-terminated", input.now, [{ type: "run", taskId: input.taskId, id: input.runId }]);
     }
@@ -507,6 +536,42 @@ function recoverExactAgentRunInTransaction(store, input) {
         progressAt: progress.progressAt
     };
 }
+function exactRecoveryExecutionBlocker(store, run) {
+    const sessions = store.getTaskRoleSessionSet(run.taskId, run.roleName);
+    const binding = sessions?.providerBinding;
+    const mailbox = store.getWorkMailbox({
+        kind: "role",
+        taskId: run.taskId,
+        roleName: run.roleName
+    });
+    if (mailbox?.inputDelivery != null)
+        return "provider-input-delivery-unsettled";
+    if (runOwnsBlockingProviderContinuation(store.listEvents(run.taskId), {
+        taskId: run.taskId,
+        roleName: run.roleName,
+        runId: run.id,
+        agentId: run.effective.agentId
+    }))
+        return "provider-continuation-writer-owned";
+    if (runHasActiveRuntimeOperations(store.listEvents(run.taskId), {
+        taskId: run.taskId,
+        roleName: run.roleName,
+        runId: run.id,
+        agentId: run.effective.agentId
+    }))
+        return "provider-operation-active";
+    if (run.deliveredAt !== undefined
+        && (binding === null || binding?.turn === null))
+        return "provider-turn-state-missing";
+    if (binding === null || binding === undefined)
+        return null;
+    if (["submitting", "accepted", "running", "delivery-unknown"].includes(binding.turn?.status ?? ""))
+        return "provider-turn-unsettled";
+    if (binding.authority.owner === "human" || binding.authority.owner === "unknown") {
+        return "provider-writer-authority-unavailable";
+    }
+    return null;
+}
 function matchesRecoverySessionFence(store, input) {
     const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
     // Recovery must never proceed without a durable Session fence.  A missing
@@ -521,8 +586,7 @@ function matchesRecoverySessionFence(store, input) {
         return false;
     if (session.agentId !== input.agentId || session.adapterId !== input.adapterId)
         return false;
-    // A dead Session is precisely when replace-session/terminate recovery is
-    // needed. Preserve its exact identity as the CAS fence; only same-Session
+    // Preserve a dead Session's exact identity as the CAS fence; only same-Session
     // retry is invalid once the native process is stopped or broken.
     if ((session.status === "stopped" || session.status === "broken")
         && input.action === "retry")

package/dist/observability/executionAudit.js

@@ -363,6 +363,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
             let stopped = 0;
             let other = 0;
             let resets = 0;
+            let conversationSwitches = 0;
             let lifecycleEvents = 0;
             let stopFailures = 0;
             const terminalByRunRelation = {
@@ -393,6 +394,9 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                         continue;
                     if (event.type === "runtime.role-session-reset")
                         resets += 1;
+                    else if (event.type === "runtime.conversation-switch-resolved"
+                        && event.payload.status === "applied")
+                        conversationSwitches += 1;
                     else if (runtimeObservationFromTaskEvent(event)?.kind.startsWith("session.")) {
                         lifecycleEvents += 1;
                     }
@@ -406,6 +410,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                 stopped,
                 other,
                 resets,
+                conversationSwitches,
                 lifecycleEvents,
                 stopFailures,
                 terminalByRunRelation

package/dist/observability/orchestrationMetrics.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import { classifyReviewRoundOutcome } from "../review/reviewOutcomeClassifier.js";
 import { projectFirstProgressAdvisory } from "../runtime/firstProgressAdvisory.js";
 /** One Task's orchestration cost and advisory projection, with no writes. */
@@ -129,10 +130,14 @@ function projectAdvisories(facts, classifications, fullRounds, repeatedIdentitie
     const recent = semanticFull.slice(-3);
     const recentIds = new Set(recent.map(({ id }) => id));
     const newFinding = facts.reviewFindings.some(({ firstReviewRoundId }) => recentIds.has(firstReviewRoundId));
-    if (semanticFull.length > 2 && !newFinding) {
+    const sameCandidate = recent.length === 3
+        && recent.every((round) => isDeepStrictEqual(round.taskCandidate, recent[0].taskCandidate));
+    const sameReviewer = recent.length === 3
+        && recent.every((round) => round.reviewerRoleName === recent[0].reviewerRoleName);
+    if (sameCandidate && sameReviewer && !newFinding) {
         result.push({
-            code: "review-budget-exhausted",
-            reason: `${semanticFull.length} full semantic Reviews ran and the latest three produced no new finding; stop repeating full rounds without a changed head or new risk.`,
+            code: "repeated-full-review",
+            reason: `The same Reviewer completed three full semantic Reviews of the same frozen candidate without a new finding; this is a cost advisory, not a Review limit.`,
             refs: recent.map(({ id }) => `review-round:${id}`)
         });
     }

package/dist/profile/agentProfile.js

@@ -75,7 +75,7 @@ export function builtinAgentProfileInputs() {
         {
             id: "reviewer",
             description: "Review one candidate against the user's core outcome, supported behavior, and direct evidence.",
-            instructions: "Start from user intent and acceptance criteria. Inspect the complete relevant change and report only reachable, material, actionable problems with direct evidence. Separate defects from verification gaps, and prefer the smallest sufficient correction. Follow the bound Project's Policy and Knowledge for build, test, migration, release, and review expectations; do not import rules from another Project or Task. For normal software delivery, review the frozen Task result as one final ReviewRound rather than inventing a per-WorkItem protocol unless the Project Policy explicitly requires one. A Task-final Round has no synthetic WorkItem anchor, and a compatible Reviewer Session may continue across changed-head Rounds without reusing an earlier verdict. Do not turn speculative or extreme edge cases into new state, retries, fallbacks, or protocol. In a ReviewRound-owned workspace you may edit source or tests, run local checks, and optionally commit diagnostic evidence. Never push, integrate, mutate Task state, touch another workspace or stable checkout, or write the real Yui control-plane home. Report complete findings, checks actually run, uncertainty, and bounded next actions through the exact Review yield; Yui preserves the full free-form report. Expose evidence and options to the Leader, who decides.",
+            instructions: "Start from user intent and acceptance criteria. Inspect the complete relevant change and report only reachable, material, actionable problems with direct evidence. Separate defects from verification gaps, and prefer the smallest sufficient correction. Follow the bound Project's Policy and Knowledge for build, test, migration, release, and review expectations; do not import rules from another Project or Task. For normal software delivery, review the frozen Task result as one final ReviewRound rather than inventing a per-WorkItem protocol unless the Project Policy explicitly requires one. A Task-final Round has no synthetic WorkItem anchor, and the Reviewer Session and physical workspace continue across changed-head Rounds without reusing an earlier verdict. The current Run's frozen candidate remains the only scope even if Task main advances. For Delta Recheck, return equivalent-and-accepted, finding, or requires-full-review with explicit reasoning; never create the next Round. Do not turn speculative or extreme edge cases into new state, retries, fallbacks, or protocol. In the Review workspace you may edit source or tests, run local checks, and optionally commit diagnostic evidence. Never push, integrate, mutate Task state, touch another workspace or stable checkout, or write the real Yui control-plane home. Report complete findings, checks actually run, uncertainty, and bounded next actions through the exact Review yield; Yui preserves the full free-form report. Expose evidence and options to the Leader, who decides.",
             defaultAccess: "write"
         }
     ];

package/dist/release/cliHomeReleaseFence.js

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { UNSUPPORTED, collectRuntimeBuildIdentity, createProductionRuntimeIdentityPorts } from "../observability/runtimeIdentity.js";
+import { readCompatibleHomeIdentity } from "../storage/compatibleTaskStore.js";
+import { detectRunningRelease, readActiveReleasePointer, releaseDirectoryName } from "./runtimeRelease.js";
+/**
+ * Prevent a checkout or otherwise unverified CLI from entering a Home that is
+ * already owned by an immutable active release. This fence runs before any
+ * TaskStore is opened, so even schema discovery cannot advance SQLite state.
+ * Published global packages remain the stable ordinary CLI boundary; an exact
+ * installed release may also run when it is active or is the explicit handover
+ * target.
+ */
+export function assertCliHomeReleaseFence(input) {
+    const active = readActiveReleasePointer(input.home);
+    if (active === null)
+        return "unregistered-home";
+    const running = detectRunningRelease(input.entryPath);
+    if (running !== null) {
+        if (matchesActiveRelease(running.manifest, active))
+            return "active-release";
+        if (isExplicitActivation(input.args, running.manifest))
+            return "release-activation";
+        throw fenceError(input, active, "installed-release", running.manifest);
+    }
+    const build = collectRuntimeBuildIdentity(createProductionRuntimeIdentityPorts(input.packageRoot, input.entryPath));
+    const distribution = readPackageDistribution(input.packageRoot);
+    if (distribution === "published" && build.sourceCommit === UNSUPPORTED) {
+        return "published-package";
+    }
+    const source = distribution === "checkout" || build.sourceCommit !== UNSUPPORTED
+        ? "checkout-local"
+        : "unverified-local";
+    throw fenceError(input, active, source, undefined, build);
+}
+/** Render bounded, non-secret identity evidence for a migration diagnosis. */
+export function describeCliHomeInvocation(input) {
+    const running = detectRunningRelease(input.entryPath);
+    const collected = collectRuntimeBuildIdentity(createProductionRuntimeIdentityPorts(input.packageRoot, input.entryPath));
+    const distribution = readPackageDistribution(input.packageRoot);
+    const source = running !== null
+        ? "installed-release"
+        : distribution === "published" && collected.sourceCommit === UNSUPPORTED
+            ? "published-package"
+            : distribution === "checkout" || collected.sourceCommit !== UNSUPPORTED
+                ? "checkout-local"
+                : "unverified-local";
+    let homeId = "unknown";
+    try {
+        homeId = readCompatibleHomeIdentity(input.home).homeId;
+    }
+    catch {
+        // The primary migration error remains authoritative when identity is unreadable.
+    }
+    let activeRelease = "none";
+    let activeBuild = "none";
+    try {
+        const active = readActiveReleasePointer(input.home);
+        if (active !== null) {
+            activeRelease = active.releaseId;
+            activeBuild = active.buildId;
+        }
+    }
+    catch {
+        activeRelease = "unreadable";
+        activeBuild = "unreadable";
+    }
+    const version = running?.manifest.version ?? collected.packageVersion;
+    const buildId = running?.manifest.buildId
+        ?? (source === "checkout-local" ? "checkout" : source);
+    const sourceCommit = running?.manifest.sourceCommit ?? (collected.sourceCommit === UNSUPPORTED ? "unknown" : collected.sourceCommit);
+    return [
+        `CLI: version=${diagnostic(version)} build=${diagnostic(buildId)} sourceCommit=${diagnostic(sourceCommit)}`,
+        `Home: homeId=${diagnostic(homeId)} activeRelease=${diagnostic(activeRelease)} activeBuild=${diagnostic(activeBuild)}`,
+        `Invocation: source=${source}`
+    ].join("\n");
+}
+function matchesActiveRelease(manifest, active) {
+    return active.releaseId === releaseDirectoryName(manifest)
+        && active.version === manifest.version
+        && active.buildId === manifest.buildId
+        && active.packageDigest === manifest.packageDigest;
+}
+function isExplicitActivation(args, manifest) {
+    if (args.length !== 3 || args[0] !== "release" || args[1] !== "activate")
+        return false;
+    return args[2] === releaseDirectoryName(manifest) || args[2] === manifest.buildId;
+}
+function readPackageDistribution(packageRoot) {
+    try {
+        const value = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        if (value.private === true)
+            return "checkout";
+        if (value.private === false)
+            return "published";
+    }
+    catch {
+        // A missing or damaged package identity is not publication evidence.
+    }
+    return "unknown";
+}
+function fenceError(input, active, source, release, collected = collectRuntimeBuildIdentity(createProductionRuntimeIdentityPorts(input.packageRoot, input.entryPath))) {
+    let homeId = "unknown";
+    try {
+        homeId = readCompatibleHomeIdentity(input.home).homeId;
+    }
+    catch {
+        // The release fence must still diagnose and reject an unreadable Home.
+    }
+    const version = release?.version ?? collected.packageVersion;
+    const buildId = release?.buildId ?? (source === "checkout-local" ? "checkout" : "unknown");
+    const sourceCommit = release?.sourceCommit ?? (collected.sourceCommit === UNSUPPORTED ? "unknown" : collected.sourceCommit);
+    return new Error([
+        `Refusing ${source} CLI access to a Home owned by another active release.`,
+        `CLI: version=${diagnostic(version)} build=${diagnostic(buildId)} sourceCommit=${diagnostic(sourceCommit)}`,
+        `Home: homeId=${diagnostic(homeId)} activeRelease=${diagnostic(active.releaseId)} activeBuild=${diagnostic(active.buildId)}`,
+        `Invocation: source=${source}`,
+        "Use the published global yui for this Home, or run make install-local without overriding its isolated YUI_HOME."
+    ].join("\n"));
+}
+function diagnostic(value) {
+    return value.replace(/[^A-Za-z0-9._:+/@-]/gu, "?").slice(0, 160);
+}

package/dist/release/runtimeRelease.js

@@ -267,6 +267,26 @@ export function isHandoverLockHeld(home) {
         return !isEnoent(error);
     }
 }
+/**
+ * True when a live handover is owned by a process other than `allowedOwnerPid`.
+ *
+ * Foreground maintenance commands acquire the lock and still need to call the
+ * Controller they are draining, while every unrelated CLI/managed Session must
+ * wait rather than starting a second Controller during the replacement window.
+ * An unreadable lock remains a foreign live lock so callers fail closed.
+ */
+export function isForeignHandoverLockHeld(home, allowedOwnerPid = process.pid) {
+    const lockPath = join(resolve(home), "runtime", "handover.lock");
+    try {
+        const owner = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (!isHandoverLockLive(owner))
+            return false;
+        return owner.pid !== allowedOwnerPid;
+    }
+    catch (error) {
+        return !isEnoent(error);
+    }
+}
 export function acquireHandoverLock(home) {
     const lockPath = join(resolve(home), "runtime", "handover.lock");
     mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });