@zq-silk/yui 0.13.4 → 0.13.5

package/dist/storage/sqliteStore.js

@@ -773,7 +773,7 @@ export class SqliteTaskStore {
                 if (found === undefined)
                     throw new StorageRecordError(`Task Project not found: ${binding.projectId}`);
             }
-            const isActive = task.status === "active" ? 1 : 0;
+            const isActive = task.status === "active" && task.executionGate.state === "enabled" ? 1 : 0;
             // The catalog projection is inserted first because task_records FKs it.
             this.#db.prepare(`INSERT INTO tasks_catalog (task_id, status, lifecycle, is_active, created_at, updated_at)
          VALUES (?, ?, ?, ?, ?, ?)
@@ -807,6 +807,7 @@ export class SqliteTaskStore {
             task: {
                 id: task.id,
                 status: task.status,
+                executionGate: task.executionGate,
                 projectBindings: task.projectBindings,
                 type: task.type
             },
@@ -835,7 +836,6 @@ export class SqliteTaskStore {
         return {
             ...base,
             agentRuns: operationalTaskRecords(this.listAgentRuns(taskId), this.listEvents(taskId), "agent-run"),
-            roleSessionSets: this.listRoleSessionSets(taskId),
             managedWorkspaces: this.#sortById(this.#listPayload("managed_workspaces", "task_id = ?", [taskId]), (workspace) => managedWorkspaceKey(workspace.owner)),
             durableJobs: this.#sortById(this.#listPayload("durable_jobs", "task_id = ?", [taskId]), (job) => job.id),
             integrationQueueEntries: this.#sortById(this.#listPayload("integration_queue", "task_id = ?", [taskId]), (entry) => entry.id),
@@ -1754,6 +1754,10 @@ export class SqliteTaskStore {
             return;
         }
         this.transaction((store) => {
+            const task = store.getTask(run.taskId);
+            if (task === null || task.status !== "active" || task.executionGate.state !== "enabled") {
+                throw new StorageRecordError(`Task execution is not enabled: ${run.taskId}.`);
+            }
             this.#assertActiveRunForWrite(run);
             const current = store.getActiveAgentRun(run.taskId, run.roleName);
             if (current !== null && current.id !== run.id) {
@@ -1796,6 +1800,10 @@ export class SqliteTaskStore {
             throw new StorageRecordError(`Active execution-lane run requires group and lane ids: ${run.id}`);
         }
         this.transaction((store) => {
+            const task = store.getTask(run.taskId);
+            if (task === null || task.status !== "active" || task.executionGate.state !== "enabled") {
+                throw new StorageRecordError(`Task execution is not enabled: ${run.taskId}.`);
+            }
             const key = executionLaneActiveRunKey(run.executionGroupId, run.executionLaneId);
             this.#assertActiveRunForWrite(run, {
                 executionGroupId: run.executionGroupId,

package/dist/storage/taskStore.js

@@ -61,7 +61,7 @@ export const CURRENT_PROJECT_SCHEMA_VERSION = 5;
 export const CURRENT_AGENT_PROFILE_SCHEMA_VERSION = 2;
 export const CURRENT_GLOBAL_ROLE_SCHEMA_VERSION = 3;
 export const CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION = 3;
-export const CURRENT_TASK_SCHEMA_VERSION = 5;
+export const CURRENT_TASK_SCHEMA_VERSION = 6;
 export const CURRENT_TASK_BRIEF_SCHEMA_VERSION = 2;
 export const CURRENT_CONTEXT_SNAPSHOT_SCHEMA_VERSION = 1;
 export const CURRENT_TASK_ROLE_SCHEMA_VERSION = 3;
@@ -431,7 +431,7 @@ export class FileTaskStore {
         // The file rollback backend has no catalog index, so it filters the loaded
         // aggregate. Layout-7 Controller hot paths use SQLite's bounded selector.
         return this.listTasks()
-            .filter((task) => task.status === "active")
+            .filter((task) => task.status === "active" && task.executionGate.state === "enabled")
             .map((task) => task.id);
     }
     getStateRevision() { return this.#state().revision; }
@@ -446,6 +446,7 @@ export class FileTaskStore {
             task: {
                 id: aggregate.task.id,
                 status: aggregate.task.status,
+                executionGate: aggregate.task.executionGate,
                 projectBindings: aggregate.task.projectBindings,
                 type: aggregate.task.type
             },
@@ -485,7 +486,6 @@ export class FileTaskStore {
         return {
             ...base,
             agentRuns: operationalTaskRecords(this.listAgentRuns(taskId), values(aggregate.events, "id"), "agent-run"),
-            roleSessionSets: this.listRoleSessionSets(taskId),
             managedWorkspaces: values(aggregate.managedWorkspaces, (workspace) => managedWorkspaceKey(workspace.owner)),
             durableJobs: values(aggregate.durableJobs, "id"),
             integrationQueueEntries: values(aggregate.integrationQueue, "id"),
@@ -1116,6 +1116,10 @@ export class FileTaskStore {
         if (run.status !== "active")
             throw new StorageRecordError(`Active Agent run must have active status: ${run.id}`);
         this.transaction((store) => {
+            const task = store.getTask(run.taskId);
+            if (task === null || task.status !== "active" || task.executionGate.state !== "enabled") {
+                throw new StorageRecordError(`Task execution is not enabled: ${run.taskId}.`);
+            }
             const current = store.getActiveAgentRun(run.taskId, run.roleName);
             if (current !== null && current.id !== run.id) {
                 throw new StorageRecordError(`Role already has an active Agent run: ${run.taskId}/${run.roleName}`);
@@ -1177,6 +1181,10 @@ export class FileTaskStore {
             throw new StorageRecordError(`Lane active Agent run requires execution lineage: ${run.id}`);
         }
         this.transaction((store) => {
+            const task = store.getTask(run.taskId);
+            if (task === null || task.status !== "active" || task.executionGate.state !== "enabled") {
+                throw new StorageRecordError(`Task execution is not enabled: ${run.taskId}.`);
+            }
             const key = executionLaneActiveRunKey(run.executionGroupId, run.executionLaneId);
             const current = store.getActiveExecutionLaneRun(run.taskId, run.executionGroupId, run.executionLaneId);
             if (current !== null && current.id !== run.id) {

package/dist/task/completionReadiness.js

@@ -5,7 +5,6 @@ import { isSemanticReviewRound } from "../review/reviewOutcomeClassifier.js";
 import { reviewFindingLedgerWriteFailedFromEvents } from "../review/reviewFindingLedger.js";
 import { resolveRecordedTaskFinalReviewContract } from "../review/taskFinalReviewContractRebind.js";
 import { sameTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
-import { blockingProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
 const ACTIVE_JOB_STATUSES = new Set([
     "queued",
     "running",
@@ -160,19 +159,6 @@ export function projectCompletionReadiness(facts, options = {}) {
             fix: `settle integration queue entry ${entry.id} (continue or supersede)`
         });
     }
-    // Provider continuations that may still write the Workspace.
-    for (const continuation of blockingProviderContinuations(facts.events)) {
-        if (!providerContinuationBlocksCompletion(continuation, facts))
-            continue;
-        const identity = continuation.identity;
-        blockers.push({
-            code: "blocking-provider-continuation",
-            ref: ref("provider-continuation", identity.continuationId),
-            reason: `Provider continuation ${identity.continuationId} (run ${continuation.runId}) `
-                + "may still write the Workspace or has an identity conflict.",
-            fix: `wait for or recover the Provider turn on run ${continuation.runId}`
-        });
-    }
     // Terminal child workspaces are cleanup advisories: Task completion is the
     // semantic delivery boundary, while archive remains the fail-closed resource
     // reclamation boundary. Missing/non-terminal ownership stays conservative.
@@ -183,18 +169,6 @@ export function projectCompletionReadiness(facts, options = {}) {
         if (disposition?.kind === "advisory")
             advisories.push(disposition.value);
     }
-    // Active non-Leader Runs must finish.  The Leader's own Run is terminalized
-    // by the completion transaction itself, so it is not a readiness blocker.
-    for (const run of facts.activeRuns) {
-        if (run.roleName === "leader")
-            continue;
-        blockers.push({
-            code: "active-run",
-            ref: ref("agent-run", run.id),
-            reason: `Role ${run.roleName} has an active Run ${run.id}.`,
-            fix: `wait for Run ${run.id} to yield or fail`
-        });
-    }
     // Review finding ledger gate (enforce mode only).
     // The transactional completion path runs this gate after final-review
     // preparation: a pending/running Task-final Review is expected to resolve
@@ -248,47 +222,6 @@ export function projectCompletionReadiness(facts, options = {}) {
         advisories: sortedAdvisories
     };
 }
-/**
- * A terminal Run releases only its completion blocker, never its immutable
- * continuation audit. Missing or inconsistent ownership remains ambiguous and
- * therefore fail-closed. A live exact native Session can still deliver or
- * write for a terminal Run, so it retains the blocker until that Session is
- * stopped, broken, or replaced by another Conversation identity.
- */
-function providerContinuationBlocksCompletion(continuation, facts) {
-    if (continuation.identityConflict)
-        return true;
-    const ownerRun = facts.agentRuns.find(({ id }) => id === continuation.runId);
-    if (ownerRun === undefined
-        || ownerRun.taskId !== continuation.taskId
-        || ownerRun.roleName !== continuation.roleName
-        || ownerRun.effective.agentId !== continuation.identity.accountScope) {
-        return true;
-    }
-    if (ownerRun.status !== "failed" && ownerRun.status !== "yielded")
-        return true;
-    const sessions = facts.roleSessionSets.find(({ owner }) => (owner.taskId === continuation.taskId && owner.roleName === continuation.roleName));
-    const session = sessions?.sessions[continuation.identity.accountScope];
-    if (session !== undefined
-        && session.status !== "stopped"
-        && session.status !== "broken"
-        && session.nativeSessionId === continuation.identity.conversationId) {
-        return true;
-    }
-    const binding = sessions?.providerBinding;
-    if (binding === undefined || binding === null
-        || binding.providerNamespace !== continuation.identity.providerNamespace
-        || binding.accountScope !== continuation.identity.accountScope) {
-        return false;
-    }
-    const conversationIsCurrent = binding.conversations.some((conversation) => (conversation.conversationId === continuation.identity.conversationId
-        && conversation.epoch === binding.currentConversationEpoch
-        && conversation.status === "current"));
-    const activationIsLive = binding.activations.some((activation) => (activation.activationId === continuation.identity.activationId
-        && activation.conversationId === continuation.identity.conversationId
-        && activation.status === "active"));
-    return conversationIsCurrent && activationIsLive;
-}
 function workspaceCompletionDisposition(facts, taskId, workspace) {
     const owner = workspace.owner;
     switch (owner.type) {

package/dist/task/nextAction.js

@@ -22,6 +22,17 @@ export function projectNextAction(facts) {
             ]
         });
     }
+    if (task.status === "active" && task.executionGate.state === "stopped") {
+        return buildAction(facts, {
+            kind: "start-task-execution",
+            reason: `Task ${task.id} execution is stopped; durable progress is preserved.`,
+            refs: [ref("task", task.id)],
+            preconditions: [
+                { fact: "Task execution is stopped", satisfied: true, ref: ref("task", task.id) }
+            ],
+            recommendedCommand: `yui task execution start ${task.id}`
+        });
+    }
     const openInput = facts.openInputRequests[0];
     if (openInput !== undefined) {
         return buildAction(facts, {
@@ -597,42 +608,15 @@ function buildExecutionLaneRecoveryAction(facts, lane) {
         ref("execution-lane", lane.laneId),
         ref("agent-run", lane.runId)
     ];
-    if (lane.recovery === "retry-new-agent-run") {
-        return buildAction(facts, {
-            kind: "recover-execution-lane",
-            reason: `Execution Lane ${lane.laneId} is durably failed; retry only exact Run ${lane.runId} and retain sibling results.`,
-            refs,
-            preconditions: [
-                { fact: "Execution Lane is failed and unresolved", satisfied: true, ref: refs[1] },
-                { fact: "Exact failed AgentRun is retained", satisfied: true, ref: refs[2] }
-            ],
-            recommendedCommand: `yui task run retry ${facts.task.id}/${lane.runId}`
-        });
-    }
-    const action = lane.recovery === "diagnose" ? "diagnose" : "terminate";
-    const recovery = facts.runRecoveries?.find(({ runId }) => runId === lane.runId);
-    const plan = recovery?.actions.find((candidate) => candidate.action === action);
     return buildAction(facts, {
-        kind: "recover-execution-lane",
-        reason: lane.recovery === "diagnose"
-            ? `Execution Lane ${lane.laneId} needs bounded diagnostics for exact Run ${lane.runId}.`
-            : `Execution Lane ${lane.laneId} has confirmed death evidence; terminate exact Run ${lane.runId}.`,
+        kind: "retry-execution-lane",
+        reason: `Execution Lane ${lane.laneId} is durably failed; retry only exact Run ${lane.runId} and retain sibling results.`,
         refs,
         preconditions: [
-            { fact: `Lane recovery is ${lane.recovery}`, satisfied: true, ref: refs[1] },
-            {
-                fact: `Exact Run exposes a current ${action} recovery plan`,
-                satisfied: plan !== undefined,
-                ref: refs[2]
-            }
+            { fact: "Execution Lane is failed and unresolved", satisfied: true, ref: refs[1] },
+            { fact: "Exact failed AgentRun is retained", satisfied: true, ref: refs[2] }
         ],
-        ...(plan === undefined ? {} : { recommendedCommand: plan.command }),
-        ...(plan !== undefined && recovery?.judgmentRequired === undefined
-            ? {}
-            : {
-                judgmentRequired: recovery?.judgmentRequired
-                    ?? `Inspect yui task run show ${facts.task.id}/${lane.runId}; its exact recovery fence is unavailable.`
-            })
+        recommendedCommand: `yui task run retry ${facts.task.id}/${lane.runId}`
     });
 }
 function exhaustedExplorationReason(item, executionGroups) {

package/dist/task/task.js

@@ -2,11 +2,12 @@ import { validateTaskWorkspaceIdentity } from "../repository/taskWorkspaceIdenti
 export function createTask(id, title, now, metadata = {}) {
     const timestamp = now.toISOString();
     return {
-        schemaVersion: 5,
+        schemaVersion: 6,
         id: requireSafeIdentity(id, "Task id"),
         title: requireText(title, "Task title"),
         ...cloneMetadata(metadata),
         status: "draft",
+        executionGate: { state: "enabled" },
         createdAt: timestamp,
         updatedAt: timestamp
     };
@@ -169,9 +170,38 @@ export function updateTaskWorkspace(task, cwd, now) {
 export function isTaskArchived(task) {
     return task.status === "archived";
 }
+export function isTaskExecutionEnabled(task) {
+    return task.executionGate.state === "enabled";
+}
+export function stopTaskExecution(task, now) {
+    validateTask(task);
+    if (task.status !== "active") {
+        throw new Error(`Only an active Task can be stopped: ${task.id}.`);
+    }
+    if (task.executionGate.state === "stopped")
+        return task;
+    return validateTask({
+        ...task,
+        executionGate: { state: "stopped" },
+        updatedAt: now.toISOString()
+    });
+}
+export function startTaskExecution(task, now) {
+    validateTask(task);
+    if (task.status !== "active") {
+        throw new Error(`Only an active Task can be started: ${task.id}.`);
+    }
+    if (task.executionGate.state === "enabled")
+        return task;
+    return validateTask({
+        ...task,
+        executionGate: { state: "enabled" },
+        updatedAt: now.toISOString()
+    });
+}
 export function validateTask(task) {
-    if (task.schemaVersion !== 5)
-        throw new Error("Task must use schemaVersion 5.");
+    if (task.schemaVersion !== 6)
+        throw new Error("Task must use schemaVersion 6.");
     requireSafeIdentity(task.id, "Task id");
     requireText(task.title, "Task title");
     if (task.type !== undefined)
@@ -179,6 +209,11 @@ export function validateTask(task) {
     if (!["draft", "active", "completed", "retired", "archived"].includes(task.status)) {
         throw new Error(`Task status is invalid: ${String(task.status)}.`);
     }
+    if (task.executionGate === null
+        || typeof task.executionGate !== "object"
+        || !["enabled", "stopped"].includes(task.executionGate.state)) {
+        throw new Error(`Task execution state is invalid: ${String(task.executionGate?.state)}.`);
+    }
     requireTimestamp(task.createdAt, "Task createdAt");
     requireTimestamp(task.updatedAt, "Task updatedAt");
     if (Date.parse(task.updatedAt) < Date.parse(task.createdAt)) {

package/dist/web/assets/client/i18n.js

@@ -86,8 +86,6 @@ const messages = {
     "detail.focus": "Current focus",
     "detail.runtimeHealth": "Runtime health",
     "detail.lastProgress": "Last semantic progress",
-    "detail.recoveryFence": "Canonical recovery fence (Yui durable)",
-    "detail.recoveryProviderObserved": "Provider observation (evidence only)",
     "input.freeText": "Type your answer",
     "input.answered": "Input answered.",
     "input.new": "A new input needs your attention.",
@@ -424,8 +422,6 @@ const messages = {
     "detail.focus": "当前重点",
     "detail.runtimeHealth": "运行健康",
     "detail.lastProgress": "最近语义进展",
-    "detail.recoveryFence": "规范恢复 fence（Yui 持久）",
-    "detail.recoveryProviderObserved": "Provider 观测（仅证据）",
     "input.freeText": "输入回答",
     "input.answered": "输入已回答。",
     "input.new": "有新的输入请求需要处理。",

package/dist/web/assets/client/view.js

@@ -345,24 +345,6 @@ export function renderTaskDetail(detail, data, t, locale, actions) {
         node("p", "record-copy", (run.kind || "workflow-not-progressing") + " · " + (run.classification || "truly-stalled")),
         node("small", "", t("detail.lastProgress") + " · " + formatDateTime(run.progressAt, locale))
       );
-      // Issue 08: the same canonical recovery projection as the CLI. The
-      // durable fence and the Provider observation stay clearly separated;
-      // the exact recovery actions live in "yui task run show".
-      if (run.recovery) {
-        if (run.recovery.canonicalProgressAt) {
-          card.append(node("small", "",
-            t("detail.recoveryFence") + " · " + formatDateTime(run.recovery.canonicalProgressAt, locale)));
-        }
-        if (run.recovery.provider && run.recovery.provider.observedAt) {
-          card.append(node("small", "",
-            t("detail.recoveryProviderObserved") + " · " + run.recovery.provider.observationKind
-            + " " + formatDateTime(run.recovery.provider.observedAt, locale)));
-        }
-        if (run.recovery.recoverable) {
-          card.append(node("small", "record-copy",
-            "yui task run show " + task.id + "/" + run.runId));
-        }
-      }
       runtimeHealthBody.append(card);
     });
     scaffold.append(anchorSection(

package/dist/web/webSnapshot.js

@@ -2,7 +2,6 @@ import { isRoleRunStalled, latestRunDurableProgressAt } from "../scheduler/roleR
 import { buildTaskExecutionProjection } from "../scheduler/taskExecutionProjection.js";
 import { summarizeExecutionGroup } from "../execution/executionGroup.js";
 import { currentWorkItemExecutionGroup } from "../workItem/workItem.js";
-import { projectRunRecovery, readRunRecoveryFacts } from "../run/recoveryProjection.js";
 import { classifyRuntimeHealth, projectRuntimeTaskEvents } from "../runtime/runtimeProjection.js";
 import { builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
@@ -73,18 +72,13 @@ export function buildWebTaskDetail(store, taskId, now = new Date()) {
         const events = reader.listEvents?.(taskId) ?? [];
         const needsAttentionRuns = runs
             .filter((run) => run.status === "active" && isRoleRunStalled(events, run.id))
-            .map((run) => {
-            const facts = readRunRecoveryFacts(reader, taskId, run.id);
-            return {
-                runId: run.id,
-                roleName: run.roleName,
-                progressAt: latestStallProgress(events, run.id),
-                kind: latestStallField(events, run.id, "kind") ?? "workflow-not-progressing",
-                classification: latestStallField(events, run.id, "classification") ?? "truly-stalled",
-                // Issue 08: the same canonical recovery projection the CLI exposes.
-                ...(facts === null ? {} : { recovery: projectRunRecovery(facts) })
-            };
-        });
+            .map((run) => ({
+            runId: run.id,
+            roleName: run.roleName,
+            progressAt: latestStallProgress(events, run.id),
+            kind: latestStallField(events, run.id, "kind") ?? "workflow-not-progressing",
+            classification: latestStallField(events, run.id, "classification") ?? "truly-stalled"
+        }));
         const activeRuns = new Map(runs
             .filter((run) => run.status === "active")
             .map((run) => [run.roleName, run]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.13.4",
+  "version": "0.13.5",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,

package/dist/run/recoveryProjection.js

@@ -1,252 +0,0 @@
-import { createHash } from "node:crypto";
-import { latestRunDurableProgressAt } from "../scheduler/roleRunStall.js";
-import { actionableExecutionLaneRecoveries } from "../execution/executionHealth.js";
-import { runOwnsBlockingProviderContinuation } from "../runtime/runtimeContinuationProjection.js";
-import { runHasActiveRuntimeOperations } from "../runtime/runtimeObservation.js";
-export const RUN_RECOVERY_ACTIONS = [
-    "diagnose",
-    "retry",
-    "terminate"
-];
-/**
- * Reads every durable record the recovery projection needs. Returns null
- * only when the Run itself is absent.
- */
-export function readRunRecoveryFacts(store, taskId, runId) {
-    const run = store.getAgentRun(taskId, runId);
-    if (run === null || run.taskId !== taskId)
-        return null;
-    const task = store.getTask(taskId);
-    const sessionSet = store.getTaskRoleSessionSet(taskId, run.roleName);
-    const events = store.listEvents(taskId);
-    const roleMailbox = store.getWorkMailbox?.({
-        kind: "role",
-        taskId,
-        roleName: run.roleName
-    }) ?? null;
-    const progress = latestRunDurableProgressAt(store, taskId, run.roleName, runId);
-    return {
-        run,
-        task: task === null ? null : { id: task.id, status: task.status },
-        sessionSet,
-        inputDeliveryUnsettled: roleMailbox?.inputDelivery != null,
-        blockingProviderContinuation: runOwnsBlockingProviderContinuation(events, {
-            taskId,
-            roleName: run.roleName,
-            runId: run.id,
-            agentId: run.effective.agentId
-        }),
-        activeRuntimeOperation: runHasActiveRuntimeOperations(events, {
-            taskId,
-            roleName: run.roleName,
-            runId: run.id,
-            agentId: run.effective.agentId
-        }),
-        progress,
-        latestProviderObservation: latestRunProviderObservation(events, runId)
-    };
-}
-/**
- * Resolve the exact live-Run recovery plans referenced by Lane health. Failed
- * terminal Lanes use `task run retry` directly and therefore need no live-Run
- * recovery projection here.
- */
-export function projectExecutionLaneRunRecoveries(store, taskId, groups) {
-    const runIds = new Set(actionableExecutionLaneRecoveries(groups).flatMap((lane) => (lane.runId === undefined || lane.recovery === "retry-new-agent-run"
-        ? []
-        : [lane.runId])));
-    return [...runIds].flatMap((runId) => {
-        const facts = readRunRecoveryFacts(store, taskId, runId);
-        return facts === null ? [] : [projectRunRecovery(facts)];
-    });
-}
-/**
- * Latest Provider observation for a Run. Provider timestamps are evidence:
- * they explain why a stale fence was supplied but never authorize recovery.
- */
-function latestRunProviderObservation(events, runId) {
-    let latest = null;
-    for (const event of events) {
-        if (event.type !== "runtime.observation")
-            continue;
-        if (event.payload.runId !== runId)
-            continue;
-        const kind = typeof event.payload.kind === "string" ? event.payload.kind : "unknown";
-        const receivedAt = typeof event.payload.receivedAt === "string"
-            && Number.isFinite(Date.parse(event.payload.receivedAt))
-            ? event.payload.receivedAt
-            : event.createdAt;
-        const at = Date.parse(receivedAt);
-        if (latest === null || at > latest.at) {
-            latest = { kind, receivedAt, at };
-        }
-    }
-    return latest === null ? null : { kind: latest.kind, receivedAt: latest.receivedAt };
-}
-export function projectRunRecovery(facts) {
-    const { run, task, sessionSet, progress } = facts;
-    const session = activeSession(facts);
-    const canonicalProgressAt = progress?.progressAt ?? null;
-    const accepted = run.deliveredAt !== undefined;
-    const acceptanceOptions = accepted
-        ? ["accepted", "ambiguous"]
-        : ["rejected", "ambiguous"];
-    const blocked = recoveryBlocker(facts, session, canonicalProgressAt);
-    const sessionTerminal = session?.status === "stopped" || session?.status === "broken";
-    const providerTerminal = sessionSet?.providerBinding?.turn?.status === "failed"
-        || sessionSet?.providerBinding?.turn?.status === "cancelled"
-        || sessionSet?.providerBinding?.turn?.status === "rejected";
-    const supportedActions = RUN_RECOVERY_ACTIONS.filter((action) => ((action !== "retry" || !sessionTerminal)
-        && (action !== "terminate" || sessionTerminal || providerTerminal)));
-    const actions = blocked === null
-        ? supportedActions.map((action) => buildActionPlan(facts, action, session, canonicalProgressAt))
-        : [];
-    const judgmentRequired = blocked === null && actions.some((plan) => plan.argv.includes(PROVIDER_ACCEPTANCE_PLACEHOLDER))
-        ? "Provider acceptance is not durably determined for every action; pass --provider-acceptance explicitly."
-        : undefined;
-    return {
-        taskId: run.taskId,
-        runId: run.id,
-        roleName: run.roleName,
-        runStatus: run.status,
-        recoverable: blocked === null,
-        canonicalProgressAt,
-        ...(progress?.evidence === undefined ? {} : { canonicalProgressEvidence: progress.evidence }),
-        provider: {
-            acceptedAt: run.deliveredAt ?? null,
-            observedAt: facts.latestProviderObservation?.receivedAt ?? null,
-            observationKind: facts.latestProviderObservation?.kind ?? null
-        },
-        providerAcceptance: {
-            accepted,
-            options: acceptanceOptions
-        },
-        session: session === null ? null : {
-            status: session.status,
-            ...(session.nativeSessionId === undefined ? {} : { nativeSessionId: session.nativeSessionId }),
-            ...(session.launchId === undefined ? {} : { launchId: session.launchId })
-        },
-        actions,
-        ...(judgmentRequired === undefined ? {} : { judgmentRequired }),
-        ...(blocked === null ? {} : { reason: blocked })
-    };
-}
-const PROVIDER_ACCEPTANCE_PLACEHOLDER = "<accepted|rejected|ambiguous>";
-function activeSession(facts) {
-    const sessions = facts.sessionSet;
-    if (sessions === null)
-        return null;
-    const session = sessions.sessions[sessions.activeAgentId];
-    if (session === undefined)
-        return null;
-    if (session.agentId !== facts.run.effective.agentId)
-        return null;
-    if (session.adapterId !== facts.run.effective.adapterId)
-        return null;
-    return session;
-}
-/**
- * Mirrors the fail-closed checks of `recoverExactAgentRun` that are visible
- * from durable records. A non-null result means recovery cannot currently be
- * applied; the canonical fence is still projected for diagnosis.
- */
-function recoveryBlocker(facts, session, canonicalProgressAt) {
-    const { run, task } = facts;
-    if (task === null)
-        return "task-missing";
-    if (task.status !== "active")
-        return "task-terminal";
-    if (run.status !== "active")
-        return "run-terminal";
-    if (canonicalProgressAt === null)
-        return "progress-unavailable";
-    if (session === null)
-        return "session-missing";
-    if (facts.inputDeliveryUnsettled)
-        return "provider-input-delivery-unsettled";
-    if (facts.blockingProviderContinuation)
-        return "provider-continuation-writer-owned";
-    if (facts.activeRuntimeOperation)
-        return "provider-operation-active";
-    const binding = facts.sessionSet?.providerBinding;
-    if (run.deliveredAt !== undefined
-        && (binding === null || binding?.turn === null))
-        return "provider-turn-state-missing";
-    if (binding !== null && binding !== undefined) {
-        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 buildActionPlan(facts, action, session, canonicalProgressAt) {
-    const { run } = facts;
-    const acceptance = actionAcceptance(facts, action);
-    const argv = [
-        "task",
-        "run",
-        "recover",
-        `${run.taskId}/${run.id}`,
-        "--action",
-        action,
-        "--expected-progress-at",
-        canonicalProgressAt,
-        "--provider-acceptance",
-        acceptance,
-        "--reason",
-        "<text>",
-        "--agent-id",
-        run.effective.agentId,
-        "--adapter-id",
-        run.effective.adapterId,
-        ...(session.nativeSessionId === undefined
-            ? []
-            : ["--native-session-id", session.nativeSessionId]),
-        ...(session.launchId === undefined
-            ? []
-            : ["--launch-id", session.launchId])
-    ];
-    const command = `yui ${argv
-        .map((part) => (part === "<text>" ? '"<text>"' : part))
-        .join(" ")}`;
-    const fingerprintSource = [
-        run.id,
-        action,
-        canonicalProgressAt,
-        run.effective.agentId,
-        run.effective.adapterId,
-        session.nativeSessionId ?? "",
-        session.launchId ?? ""
-    ].join("|");
-    return {
-        action,
-        reason: ACTION_REASONS[action],
-        expectedProgressAt: canonicalProgressAt,
-        agentId: run.effective.agentId,
-        adapterId: run.effective.adapterId,
-        ...(session.nativeSessionId === undefined
-            ? {}
-            : { nativeSessionId: session.nativeSessionId }),
-        ...(session.launchId === undefined ? {} : { launchId: session.launchId }),
-        command,
-        argv,
-        fingerprint: createHash("sha256").update(fingerprintSource).digest("hex")
-    };
-}
-/**
- * The acceptance value for the copy-paste command. When exactly one value is
- * durably valid it is filled in (the durable record, not a guess); otherwise
- * the Leader must choose and the command carries an explicit placeholder.
- */
-function actionAcceptance(facts, action) {
-    if (action === "diagnose")
-        return PROVIDER_ACCEPTANCE_PLACEHOLDER;
-    return facts.run.deliveredAt === undefined ? "rejected" : "accepted";
-}
-const ACTION_REASONS = {
-    diagnose: "Collect bounded diagnostics before any state-changing recovery.",
-    retry: "Request another provider turn on the same native Session when the failure is transient.",
-    terminate: "Fail the Run explicitly when recovery is not viable."
-};