@zq-silk/yui 0.13.4 → 0.13.6

package/ARCHITECTURE.md

@@ -254,21 +254,21 @@ Yui's current attachment, not exclusive ownership of the Provider thread. One
 Turn identifies one provider-native execution. Yui's authority epoch fences
 only Yui's own submissions and retries.
 
-Codex Task threads can be opened and used directly in Desktop as ordinary
-sessions; no Yui takeover is required. If a direct user Turn is active, Yui
-keeps its pending Run/message and retries after that Turn settles. The explicit
-tmux takeover gateway remains for providers whose managed conversation is
-attached to an independent process. Global interactive entry remains a native
-session-lifecycle operation outside the Task delivery contract.
-
-Codex uses `app-server proxy` to create or resume a normal thread on the shared
-App Server daemon. Role model, effort, permission, workspace, and shell settings are passed at
+Codex Task threads remain ordinary native sessions and can be inspected in
+Desktop. While their managed Role runtime is live, writes go through Yui's
+view/takeover boundary; stop Task execution before resuming the thread from a
+different client. If Yui observes a pre-existing active Turn during resume, it
+keeps its pending Run/message until that Turn settles. Global interactive entry
+remains a native session-lifecycle operation outside the Task delivery contract.
+
+Codex uses a Yui-owned direct `app-server` child to create or resume a normal
+thread. The process loads the selected native config profile; Role model,
+effort, permission, workspace, and shell settings are passed at
 `thread/start`/`thread/resume`, while the ordinary Task message points to the
 Session Manifest and matching Role Skill. Yui does not write either to global
-Codex config and may only ensure that the daemon is running; it never restarts
-or stops it for a thread error. A Codex native config profile is rejected for
-Managed Codex because the protocol cannot isolate it to one thread; a Yui Agent
-Profile supplies the per-Role behavior, Skills, model, and effort instead.
+Codex config. The Agent Host owns the Provider process group, so Task execution
+stop can end the complete runtime and start can rebuild it without depending on
+the shared Codex daemon.
 Claude uses a persistent stream-json
 transport with exact user-message replay acknowledgement. In both cases, Yui
 records Turn intent before writing, accepts only exact Provider evidence, and

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
@@ -875,13 +875,13 @@ Provider conversations remain ordinary user conversations. Yui adds the Role
 Skill and Session Manifest pointer, then sends Task work through provider-native
 structured requests. Managed prompts are never delivered as terminal bytes.
 
-Codex uses `app-server proxy` to create or resume a normal thread on the shared
-App Server daemon. The thread is visible and directly usable in Desktop; Yui
-does not require takeover or install global Hook/config state. It may
-idempotently start an absent daemon, but never restarts or stops it for a thread
-error. When a user Turn is active, Yui keeps pending Task work and retries
-later. If Yui's proxy disconnects, the Host reattaches without ending the
-logical Activation and reconciles the exact owned Turn from native history.
+Codex uses a direct, Yui-owned `app-server` child to create or resume a normal
+thread. The thread remains visible in Codex, while Yui's view/takeover boundary
+is the supported way to interact with a live managed Role. Task execution stop
+terminates the Agent Host and its Provider process group; start creates a fresh
+owned runtime without depending on the shared Codex daemon. If the child
+disconnects, the Host may start a bounded replacement process and reconcile the
+exact owned Turn from native history.
 Claude Code keeps its independent stream-json process with exact
 user-message replay acknowledgement. A timeout or uncertain write becomes
 `delivery-unknown` and is never automatically retried.
@@ -894,10 +894,9 @@ yui task role takeover <task-id> <role>
 yui task role release <task-id> <role>
 ```
 
-For Codex, open the Role's ordinary thread in Desktop for direct interaction;
-these commands are not required. `view`/`takeover`/`release` remain the explicit
-PTY gateway for providers whose managed conversation uses an independent
-process.
+For a live managed Role, including Codex, these commands are the supported
+human-control boundary. Its ordinary native thread remains inspectable in
+Codex; stop Task execution before resuming it from a different client.
 
 Global Operator and global Role sessions remain native interactive CLIs:
 
@@ -962,7 +961,7 @@ movement cannot conceal a workflow that is not advancing.
 
 Stable Role context never creates a separate bootstrap Turn. Task execution Runs use the generic Leader or Worker Skill, while review Runs use the generic Reviewer Skill based on durable Run purpose rather than a configured Role name. The provider either carries the Skill through a safe additive native context channel or points to it from the ordinary Task delivery. These Yui-owned Role Skills define portable orchestration only. Project Skills remain ordinary versioned files in the Project and are discovered, selected, and loaded by the Agent through its native project mechanism; Yui does not scan, parse, copy, or inject them.
 
-Managed Codex keeps the user's native developer instructions unchanged. The ordinary Task message includes a compact absolute Session Manifest pointer, and the manifest identifies the matching Yui-owned Role Skill for Codex to read on demand. Model, effort, permission, workspace, and shell settings selected for the Role are supplied as thread-scoped `thread/start` or `thread/resume` configuration through the shared App Server daemon. A Codex native config profile cannot be isolated to one shared-daemon thread, so Managed Codex rejects that setting and directs callers to a Yui Agent Profile; ordinary non-Yui and interactive Codex sessions remain unaffected. Unrelated Codex threads keep their existing user, profile, project, and system configuration and the underlying config file is never mutated. App Server notifications are the managed thread's lifecycle authority; Yui installs no managed Codex Hook and does not claim `notify`. Interactive Codex Sessions may still use Yui's structured `notify` callback, and Doctor reports any effective configuration conflict. `skills.config` is not misused because it only enables or disables already-discovered Skills. Claude receives the same Yui-owned Role Skill content from a private `0600` managed context file rather than a large or sensitive argv value; retries and resumes reuse the purpose-specific Role path. Non-Operator global Roles stay neutral and receive no Task orchestration Skill. Operator therefore opens at an empty native composer, so the user's text remains its first user message. Leader wakeups and Worker or Reviewer Run assignments remain real mailbox-delivered work messages.
+Managed Codex keeps the user's native developer instructions unchanged. The ordinary Task message includes a compact absolute Session Manifest pointer, and the manifest identifies the matching Yui-owned Role Skill for Codex to read on demand. Its Yui-owned App Server process loads any selected Codex native config profile; model, effort, permission, workspace, and shell settings are supplied to `thread/start` or `thread/resume`, and the underlying Codex config file is never mutated. App Server notifications are the managed thread's lifecycle authority; Yui installs no managed Codex Hook and does not claim `notify`. Interactive Codex Sessions may still use Yui's structured `notify` callback, and Doctor reports any effective configuration conflict. `skills.config` is not misused because it only enables or disables already-discovered Skills. Claude receives the same Yui-owned Role Skill content from a private `0600` managed context file rather than a large or sensitive argv value; retries and resumes reuse the purpose-specific Role path. Non-Operator global Roles stay neutral and receive no Task orchestration Skill. Operator therefore opens at an empty native composer, so the user's text remains its first user message. Leader wakeups and Worker or Reviewer Run assignments remain real mailbox-delivered work messages.
 
 ## Controller and failure handling
 

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`