@zq-silk/yui 0.13.4 → 0.13.5

package/README.md

@@ -549,18 +549,18 @@ yui operator new
 yui operator enter
 ```
 
-When a Task Role's current Provider Conversation cannot continue, request a
-bounded switch with an audited reason:
+If current execution cannot be settled normally, fence the Task and restart
+from its durable progress:
 
 ```sh
-yui task role session switch <task-id> <role> --reason "<why this conversation cannot continue>"
+yui task execution stop <task-id> --force --reason "<why execution must be fenced>"
+yui task execution start <task-id>
 ```
 
-The command records intent only. It does not fail active work, stop a live
-runtime, or forget the current Conversation. Once the Role has ready work and
-the current writer/Turn is settled, Yui creates and binds the replacement; a
-failure before that bind leaves the old Conversation authoritative. Existing
-messages, reviews, and delivery history remain durable.
+`stop` terminates disposable Runs and Sessions while preserving WorkItems,
+repository changes, Messages, reviews, and other Task progress. `start` admits
+one new Leader attempt from those durable records; it does not recover an old
+Agent conversation.
 
 Without `--task`, `operator submit` creates a new Draft. Drafts accept planning changes but must be activated before Agent execution.
 Operator resolves every request against the Project catalog and existing Task

package/dist/cli/commandCatalog.js

@@ -282,6 +282,24 @@ const taskChildren = [
         }
     },
     { name: "activate", summary: "Activate a Draft Task.", usage: "yui task activate <id>" },
+    {
+        name: "execution",
+        summary: "Fence or resume all execution for a Task.",
+        sections: [{ id: "manage", title: "Commands", entries: ["stop", "start"] }],
+        children: [
+            {
+                name: "stop",
+                summary: "Stop all Task execution while preserving durable progress.",
+                usage: "yui task execution stop <task> --force --reason <text>",
+                options: ["--force", "--reason"]
+            },
+            {
+                name: "start",
+                summary: "Resume the Leader from durable Task progress.",
+                usage: "yui task execution start <task>"
+            }
+        ]
+    },
     {
         name: "complete",
         summary: "Complete an active Task and stop automatic wakeups.",
@@ -540,7 +558,7 @@ const taskChildren = [
         name: "role",
         summary: "Manage Roles within a Task.",
         sections: [{ id: "manage", title: "Commands", entries: [
-                    "add", "list", "status", "show", "update", "remove", "bind", "unbind", "session",
+                    "add", "list", "status", "show", "update", "remove", "bind", "unbind",
                     "view", "takeover", "release"
                 ] }],
         children: [
@@ -569,17 +587,6 @@ const taskChildren = [
             { name: "remove", summary: "Remove a Task Role.", usage: "yui task role remove <task> <role>" },
             { name: "bind", summary: "Bind and activate an Agent for a Task Role.", usage: "yui task role bind <task> <role> <agent-id>" },
             { name: "unbind", summary: "Unbind a dormant Agent from a Task Role.", usage: "yui task role unbind <task> <role> <agent-id>" },
-            {
-                name: "session",
-                summary: "Manage the Provider Conversation bound to a Task Role.",
-                sections: [{ id: "manage", title: "Commands", entries: ["switch"] }],
-                children: [{
-                        name: "switch",
-                        summary: "Request a fresh Conversation after the current one reaches a safe boundary.",
-                        usage: "yui task role session switch <task> <role> --reason <text>",
-                        options: ["--reason"]
-                    }]
-            },
             {
                 name: "view",
                 summary: "Attach read-only to an independent Provider presentation surface.",
@@ -720,12 +727,12 @@ const taskChildren = [
     {
         name: "run",
         summary: "Inspect and control Task Role Agent Runs.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint", "retire"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "yield", "context", "checkpoint", "retire"] }],
         children: [
             { name: "list", summary: "List Runs for a work item.", usage: "yui task run list <task>/<work>" },
             {
                 name: "show",
-                summary: "Show one Run with its canonical recovery fence and exact recovery actions.",
+                summary: "Show one Run and its retained audit evidence.",
                 usage: "yui task run show <task>/<run> [--json]"
             },
             {
@@ -738,12 +745,6 @@ const taskChildren = [
                 summary: "Close an obsolete stranded final Review Run without requesting a retry Round.",
                 usage: "yui task run settle <task>/<run>"
             },
-            {
-                name: "recover",
-                summary: "Record one exact Leader-controlled Run recovery decision.",
-                usage: "yui task run recover <task>/<run> --action <diagnose|retry|terminate> (--expected-progress-at <timestamp>|--from-next-action <fingerprint>) --provider-acceptance <accepted|rejected|ambiguous> --reason <text>",
-                options: ["--action", "--expected-progress-at", "--progress-at", "--from-next-action", "--provider-acceptance", "--reason", "--role", "--agent-id", "--adapter-id", "--native-session-id", "--launch-id"]
-            },
             {
                 name: "yield",
                 summary: "Complete an active Run and wake the Leader.",
@@ -1432,7 +1433,7 @@ export const ROOT_COMMAND = buildNode({
             name: "task",
             summary: "Manage Tasks, WorkItems, Agent Runs, and integration.",
             sections: [
-                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "next-action", "archive", "rebuild", "history", "replace", "reconcile", "upstream"] },
+                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "execution", "complete", "reopen", "retire", "list", "show", "context", "next-action", "archive", "rebuild", "history", "replace", "reconcile", "upstream"] },
                 { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "overlap", "change-set"] },
                 { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event", "continuation", "wake"] }
             ],

package/dist/cli/interactionPolicy.js

@@ -346,20 +346,6 @@ export const INTERACTION_POLICIES = Object.freeze([
             { argumentIndex: 5, entity: "agent", provider: "configured-agents", actionTarget: false }
         ]
     })),
-    {
-        commandPath: ["task", "role", "session", "switch"],
-        selectors: [
-            { argumentIndex: 4, entity: "task", provider: "tasks", actionTarget: true, statuses: ["active"] },
-            {
-                argumentIndex: 5,
-                entity: "task-role",
-                provider: "task-roles",
-                dependsOn: 4,
-                actionTarget: true
-            }
-        ],
-        trailingOptions: { "--reason": "value" }
-    },
     ...["view", "takeover", "release"].map((command) => ({
         commandPath: ["task", "role", command],
         selectors: [

package/dist/cli.js

@@ -39,6 +39,7 @@ import { runProjectCommand } from "./commands/projectCommands.js";
 import { runProfileCommand } from "./commands/profileCommands.js";
 import { dispatchPreparedReviewRound, failPendingReviewRound, preserveReviewRoundWorkspace, parseTaskCompletionRequest, parseTaskFinalReviewContractRebindRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, resolvedExecutionStageRetryGroup, validateTaskArchiveRequest } from "./commands/taskCommands.js";
 import { taskActor } from "./commands/taskActor.js";
+import { parseTaskExecutionStartRequest, parseTaskExecutionStopRequest, finalizeStoppedTaskExecution, startTaskExecutionCommand, stopTaskExecutionCommand } from "./commands/taskExecutionCommands.js";
 import { isCurrentGlobalOperator } from "./commands/taskInputCommands.js";
 import { runTaskIntegrationCommand } from "./commands/taskIntegrationCommands.js";
 import { runTaskChangeSetCommand } from "./commands/taskChangeSetCommands.js";
@@ -808,6 +809,47 @@ export async function main() {
         return;
     }
     if (resolved[0] === "task") {
+        if (resolved[1] === "execution") {
+            if (resolved[2] === "stop") {
+                const request = parseTaskExecutionStopRequest(resolved.slice(3));
+                const result = stopTaskExecutionCommand(request, store, { environment: process.env });
+                try {
+                    await ensureFileTaskController(home, { environment: process.env });
+                    await runtime.stopTaskDurableJobs(result.taskId);
+                    await runtime.stopTaskRoleSessions(result.taskId, result.roleNames);
+                    await runtime.assertTaskPhysicalResourcesReleased(result.taskId);
+                    finalizeStoppedTaskExecution(result.taskId, store);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw runtimeError(`Task execution is stopped and durable progress is preserved, but physical runtime cleanup failed: ${message}`);
+                }
+                emit(result.output, false, result);
+                return;
+            }
+            if (resolved[2] === "start") {
+                const taskId = parseTaskExecutionStartRequest(resolved.slice(3));
+                const task = store.getTask(taskId);
+                if (task === null)
+                    throw usageError(`Task not found: ${taskId}.`);
+                // Reject managed Task callers before inspecting or starting runtime resources.
+                if (taskActor(process.env, taskId) === "leader") {
+                    throw usageError("Task execution stop/start requires the global Operator or a human user.");
+                }
+                if (task.executionGate.state === "stopped") {
+                    await runtime.assertTaskPhysicalResourcesReleased(taskId);
+                }
+                await ensureFileTaskController(home, { environment: process.env });
+                const result = startTaskExecutionCommand(taskId, store, { environment: process.env });
+                // Idempotent start is also a reliable kick: if an earlier caller
+                // committed the gate but lost its Controller acknowledgement, retrying
+                // start re-signals the same durable wake without creating another one.
+                await runtime.notifyMailboxChanged?.({ kind: "role", taskId, roleName: "leader" });
+                emit(result.output, false, result);
+                return;
+            }
+            throw usageError("Task execution usage: yui task execution <stop|start> ...");
+        }
         if (resolved[1] === "integration") {
             const result = await runTaskIntegrationCommand(resolved.slice(2), store, home, {
                 environment: process.env,

package/dist/commands/executionAuditCommands.js

@@ -139,7 +139,7 @@ export function renderExecutionAudit(report, width = defaultTableWidth()) {
     }
     if (report.sessions.status === "ok" && report.sessions.data !== undefined) {
         const sessions = report.sessions.data;
-        lines.push("", `Sessions: ${sessions.generations} generations · ${sessions.broken} broken · ${sessions.stopped} stopped · ${sessions.other} other`, `Resets: ${sessions.resets} · Conversation switches ${sessions.conversationSwitches}`
+        lines.push("", `Sessions: ${sessions.generations} generations · ${sessions.broken} broken · ${sessions.stopped} stopped · ${sessions.other} other`, `Resets: ${sessions.resets} · Historical conversation switches ${sessions.conversationSwitches}`
             + ` · lifecycle events ${sessions.lifecycleEvents} · stop failures ${sessions.stopFailures}`, `Terminal by Run relation: ${sessions.terminalByRunRelation.postRunYielded} post-run-yielded`
             + ` · ${sessions.terminalByRunRelation.runFailed} run-failed`
             + ` · ${sessions.terminalByRunRelation.activeRun} active-run`