@zq-silk/yui 0.8.1 → 0.8.2

package/ARCHITECTURE.md

@@ -201,34 +201,33 @@ context.
 
 ## Runtime ownership
 
-tmux owns Agent process lifetimes and observable output. The Controller owns
-mailbox delivery, wakeups, Role liveness, and reconciliation. Task attachment
-surfaces only attach to an existing pane and cannot create, resume, wake, or
-deliver to a managed runtime. Global interactive entry remains an explicit
-session-lifecycle operation.
-
-Task observation is read-only by default. Explicit write access publishes a
-Role-scoped tmux lease before revalidating durable Run state. The managed host
-also checks that lease before planning or process creation, so either the Run
-claim or the writer lease wins and they never share a pane. Writer contention
-is transient backpressure rather than a delivery failure: it does not consume
-bounded delivery retries, and lease release signals only existing durable work.
-Global interactive entry uses the same mechanism at tmux-host scope and
-automatically falls back to read-only when another writer already exists.
-
-Managed Task Claude execution is process-per-Run: the exact Run input is a
-stream-json stdin frame submitted at process launch, while native session IDs
-carry conversation continuity across processes. The lifecycle binding records
-the exact Run submitted at launch. A Controller restart may recover only the
-same reserved launch/Run as uncertain until its Provider Hook arrives; a newly
-reserved Run cannot reuse an older live Role pane, so its provisional launch
-is released, the old owner is fenced through the durable cleanup lane, and the
-same Run is retried only after cleanup; pending cleanup prevents a successor
-generation from starting early.
-Terminal key injection is therefore an interactive compatibility mechanism,
-not a managed Claude delivery protocol. Operator and Leader Sessions remain
-fixed Task/global Roles; Task Worker Sessions are selected through Role Agent
-bindings.
+tmux owns the persistent Agent Host lifetime and observable output. The
+Controller owns mailbox delivery, wakeups, Role liveness, recovery decisions,
+and a durable single-writer authority epoch. The Agent Host owns one structured
+Provider child process and mirrors its output to the pane. Managed prompts are
+never terminal bytes: both Controller and human takeover input become fenced
+Provider-native Turn requests.
+
+Run, Conversation, Activation, and Turn identities are independent. A
+Conversation can span Runs and Provider processes; one Activation identifies
+one live process; one Turn identifies one pre-recorded input attempt. A live
+Activation is retained when a later Run reuses the Conversation. Process exit
+ends that Activation, and a resumed process receives a new Activation and a
+higher authority epoch.
+
+Task observation uses `task role view`. Explicit takeover requires a live
+managed Run, atomically transfers authority to a human holder, synchronizes the
+same fence to the Host, and only then exposes the PTY input gateway. Detach
+releases authority; `task role release` is an idempotent repair path even after
+the Run has ended. Global interactive entry remains a native session-lifecycle
+operation outside this managed Provider contract.
+
+Codex uses a persistent App Server JSON-RPC transport. 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 maps an uncertain write to `delivery-unknown` without automatic
+resubmission. Conversation replacement requires exact missing evidence and no
+unsettled input, Turn, Activation, or writer authority.
 
 Role desired revisions and Run/Session effective snapshots keep configuration
 history explicit. Resume compares the complete effective snapshot and

package/README.md

@@ -659,55 +659,46 @@ yui task complete <task-id> --summary-file delivery.txt --refresh-remote
 yui task reopen <task-id>
 ```
 
-Completed Tasks reject messages, dispatch, enter, retry, and late yields until explicitly reopened, while retaining Task main for inspection or integration. Every isolated WorkItem worktree must be explicitly cleaned as integrated or abandoned before archive; that cleanup also removes its managed branch. Archive requires `--integrated` or `--abandon` to state the Task main outcome and is allowed only after Task main is clean. It removes managed worktrees but retains Task and WorkItem records. The Task main branch is retained as a recovery artifact instead of being silently deleted.
+Completed Tasks reject messages, dispatch, Provider authority changes, retry, and late yields until explicitly reopened, while retaining Task main for inspection or integration. Every isolated WorkItem worktree must be explicitly cleaned as integrated or abandoned before archive; that cleanup also removes its managed branch. Archive requires `--integrated` or `--abandon` to state the Task main outcome and is allowed only after Task main is clean. It removes managed worktrees but retains Task and WorkItem records. The Task main branch is retained as a recovery artifact instead of being silently deleted.
 Task lifecycle completion/selection only suggests valid source states: Draft for activate, active for complete, and completed for reopen.
 
 ## Sessions and tmux
 
-tmux owns Agent process lifetimes and their observable output. Global Operator
-and global Role sessions remain native interactive CLIs. A managed Task Claude
-Run instead starts one finite Claude process with `--print`, stream-json input
-and stream-json output. Yui writes the exact Run prompt as one newline-delimited
-JSON user frame on stdin, drains output concurrently, and carries native
-continuity with Claude's session ID. Startup and delivery therefore never
-depend on a TUI composer, readiness glyph, paste delay, or a synthetic Enter
-key. Codex keeps its adapter-native launch-prompt and structured callback path.
-
-`task enter` and `task role enter` are pure attachments to an existing Task
-Role pane. They do not start the Controller, prepare a workspace, create or
-resume an Agent, wake a Role, or deliver input. Task attachments default to
-`--read-only`; `--read-write` is explicit and is rejected while that Role owns
-an active managed Run, a managed Claude process is still exiting, or another
-writer owns the same pane. A read-write attach first publishes a Role-scoped
-tmux writer lease and then revalidates durable Run state, closing the race with
-Controller launch. While the lease exists, managed delivery for that Role is
-paused without consuming its bounded delivery retries; detach releases the
-lease and signals only already-durable Role work for reconsideration. Other
-Roles in the same Task continue independently. Before any attach Yui closes
-readline, leaves raw mode, pauses its stdin, and synchronously hands the terminal
-to tmux. The attach uses the real outer terminal capabilities and a clean alternate
-screen; mouse scrolling stays in the Agent pane's
-100,000-line tmux history instead of mixing with earlier shell or IDE terminal
-history. A read-write attachment exposes whatever native interaction the
-existing pane supports, but it is never part of managed startup or delivery.
-
-tmux fixes a pane's history capacity when that pane is created. Roles created
-before this limit was configured keep their earlier capacity; Yui warns on
-Terminal attach and in Web so the user can exit and re-enter that Role once to
-create a 100,000-line pane while retaining the native Agent conversation.
-
-Global interactive entry remains writable when no writer exists and
-automatically downgrades to read-only when another writer is present; global
-Web keeps one writer per tmux session. Task Web is always read-only. Task CLI
-entry is read-only unless `--read-write` is requested, preventing observation
-from changing Agent execution.
+Managed Task Agents use the [hybrid Provider runtime](docs/provider-runtime.md).
+The Controller and Agent Host send Provider-native structured requests; tmux
+and PTY keep the Host alive, show output, and provide an explicit human input
+gateway. Managed prompts are never delivered as terminal bytes.
+
+Codex uses a persistent App Server JSON-RPC process. Claude Code uses a
+persistent stream-json process with exact user-message replay acknowledgement.
+Both follow the same Conversation, Activation, Turn, and authority-epoch
+contract. A timeout or uncertain write becomes `delivery-unknown` and is never
+automatically retried.
+
+Task Role observation and takeover are explicit:
+
+```sh
+yui task role view <task-id> <role>
+yui task role takeover <task-id> <role>
+yui task role release <task-id> <role>
+```
+
+`view` is read-only. `takeover` transfers the durable writer authority to the
+human before enabling the Host PTY gateway and requires a live managed Run;
+detach returns it to the Controller. `release` remains available without a live
+Run and idempotently repairs a stranded or partially synchronized takeover.
+Authority cannot transfer while a Provider Turn or input delivery is unsettled.
+
+Global Operator and global Role sessions remain native interactive CLIs:
 
 ```sh
 yui session enter <global-role>
-yui task enter <task-id> [role] [--read-only | --read-write]
-yui task role enter <task-id> <role> [--read-only | --read-write]
 ```
 
+tmux fixes a pane's history capacity when that pane is created. Existing panes
+retain their configured capacity; managed runtime output remains observable in
+the Agent Host pane without becoming lifecycle or acknowledgement evidence.
+
 Each Role, including a Task-bound Worker instance, can bind multiple configured Agents, has one active Agent, and keeps
 a separate native session per Agent binding. Operator narrows this to at most
 one Agent per adapter—for example, one Codex and one Claude—so its bindings are
@@ -729,12 +720,10 @@ snapshot instead of applying desired drift as a hot change.
 
 Use `yui config role unbind <global-role> <agent-id>` or `yui task role unbind <task-id> <role> <agent-id>` to retire a dormant binding. The active binding and any non-stopped native session are rejected; a stopped session record is removed atomically with the binding.
 
-Claude session IDs are preallocated at launch. Every managed Task Claude Run
-uses a new finite process; resume starts a new process against the fixed native
-session instead of reusing an interactive pane. Codex discovers its native
-thread identity from structured lifecycle events. Managed Task Runs use one
-Agent Driver Hook ingress for both CLIs. Global interactive Codex sessions may
-still use its structured `notify` callback for conversation presentation.
+Claude session IDs are preallocated at launch. Codex discovers its native
+thread identity from App Server responses. Managed Task Runs use structured
+Provider observations for both CLIs. Global interactive Codex sessions may
+still use its `notify` callback for conversation presentation.
 
 Automated lifecycle and delivery decisions use structured Hook payloads,
 persisted identities, usage snapshots, tmux process state, receipts, and pane

package/dist/cli/commandCatalog.js

@@ -513,7 +513,8 @@ const taskChildren = [
         name: "role",
         summary: "Manage Roles within a Task.",
         sections: [{ id: "manage", title: "Commands", entries: [
-                    "add", "list", "status", "show", "update", "remove", "bind", "unbind", "reset", "enter"
+                    "add", "list", "status", "show", "update", "remove", "bind", "unbind", "reset",
+                    "view", "takeover", "release"
                 ] }],
         children: [
             {
@@ -548,10 +549,19 @@ const taskChildren = [
                 options: ["--reason"]
             },
             {
-                name: "enter",
-                summary: "Attach to an existing Task Role session without starting it.",
-                usage: "yui task role enter <task> <role> [--read-only | --read-write]",
-                options: ["--read-only", "--read-write"]
+                name: "view",
+                summary: "Attach read-only to a managed Provider presentation surface.",
+                usage: "yui task role view <task> <role>"
+            },
+            {
+                name: "takeover",
+                summary: "Acquire Provider writer authority and enter the PTY input gateway.",
+                usage: "yui task role takeover <task> <role>"
+            },
+            {
+                name: "release",
+                summary: "Return stranded human Provider authority to the Controller.",
+                usage: "yui task role release <task> <role>"
             }
         ]
     },
@@ -675,7 +685,7 @@ const taskChildren = [
     {
         name: "run",
         summary: "Inspect and control Task Role Agent Runs.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "checkpoint"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint"] }],
         children: [
             { name: "list", summary: "List Runs for a work item.", usage: "yui task run list <task>/<work>" },
             {
@@ -706,6 +716,28 @@ const taskChildren = [
                 options: ["--summary", "--summary-file"],
                 fileOptions: ["--summary-file"]
             },
+            {
+                name: "context",
+                summary: "Load the exact authorized Run context.",
+                usage: "yui task run context <task>/<run> [--json]",
+                executable: true,
+                hidden: true,
+                sections: [{ id: "load", title: "Commands", entries: ["expand", "delta"] }],
+                children: [
+                    {
+                        name: "expand",
+                        summary: "Expand one authorized Run context reference.",
+                        usage: "yui task run context expand <task>/<run> <ref-id> [--mode full]",
+                        options: ["--mode"]
+                    },
+                    {
+                        name: "delta",
+                        summary: "Load authorized Run context changes after a cursor.",
+                        usage: "yui task run context delta <task>/<run> --after <cursor>",
+                        options: ["--after"]
+                    }
+                ]
+            },
             {
                 name: "checkpoint",
                 summary: "Record durable progress for a long-running Agent Run.",
@@ -940,12 +972,6 @@ const taskChildren = [
             { name: "show", summary: "Show one ChangeSet.", usage: "yui task change-set show <task>/<change-set>" }
         ]
     },
-    {
-        name: "enter",
-        summary: "Attach to an existing Task Role, defaulting to Leader and read-only.",
-        usage: "yui task enter <task> [role] [--read-only | --read-write]",
-        options: ["--read-only", "--read-write"]
-    }
 ];
 export const ROOT_COMMAND = buildNode({
     name: "yui",
@@ -1319,7 +1345,7 @@ export const ROOT_COMMAND = buildNode({
             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"] },
-                { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "enter", "overlap", "change-set"] },
+                { 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"] }
             ],
             children: taskChildren
@@ -1359,8 +1385,17 @@ export const ROOT_COMMAND = buildNode({
             name: "internal",
             summary: "Internal Yui callbacks.",
             hidden: true,
-            sections: [{ id: "callbacks", title: "Callbacks", entries: ["session-notify", "runtime-hook"] }],
+            sections: [{
+                    id: "callbacks",
+                    title: "Callbacks",
+                    entries: ["session-notify", "runtime-hook", "agent-host"]
+                }],
             children: [
+                {
+                    name: "agent-host",
+                    summary: "Run the persistent structured Provider host.",
+                    usage: "yui internal agent-host <launch-id> <ticket>"
+                },
                 {
                     name: "session-notify",
                     summary: "Record a structured native session notification.",

package/dist/cli/interactionPolicy.js

@@ -361,8 +361,8 @@ export const INTERACTION_POLICIES = Object.freeze([
         trailingOptions: { "--reason": "value" },
         confirmation: { action: "Reset Task Role Session", targetArgumentIndex: 4 }
     },
-    {
-        commandPath: ["task", "role", "enter"],
+    ...["view", "takeover", "release"].map((command) => ({
+        commandPath: ["task", "role", command],
         selectors: [
             { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true },
             {
@@ -372,9 +372,8 @@ export const INTERACTION_POLICIES = Object.freeze([
                 dependsOn: 3,
                 actionTarget: true
             }
-        ],
-        trailingOptions: { "--read-only": "flag", "--read-write": "flag" }
-    },
+        ]
+    })),
     {
         commandPath: ["task", "work", "create"],
         selectors: [
@@ -534,11 +533,6 @@ export const INTERACTION_POLICIES = Object.freeze([
                 ? { trailingOptions: { "--reason": "value" } }
                 : {})
     })),
-    {
-        commandPath: ["task", "enter"],
-        selectors: [{ argumentIndex: 2, entity: "task", provider: "tasks", actionTarget: true }],
-        trailingOptions: { "--read-only": "flag", "--read-write": "flag" }
-    },
     {
         commandPath: ["jobs", "retry"],
         selectors: [{ argumentIndex: 2, entity: "job", provider: "jobs", actionTarget: true }]

package/dist/cli/invocationRouter.js

@@ -32,7 +32,8 @@ function resolveExecutionPath(args) {
         const child = findChild(node, args[index] ?? "");
         const internalExecutable = child !== undefined && ((node === ROOT_COMMAND && child.name === "internal")
             || (node.path.join(" ") === "yui config completion" && child.name === "candidates")
-            || (node.path.join(" ") === "yui task run" && child.name === "checkpoint")
+            || (node.path.join(" ") === "yui task run"
+                && (child.name === "checkpoint" || child.name === "context"))
             || (node.path.join(" ") === "yui controller"
                 && (child.name === "identity" || child.name === "live-identity")));
         if (child === undefined || (child.hidden && !internalExecutable)) {

package/dist/cli.js

@@ -36,7 +36,7 @@ import { runResourcesCommand } from "./commands/resourcesCommands.js";
 import { applyOperatorSessionControl, runOperatorCommand } from "./commands/operatorCommands.js";
 import { runProjectCommand } from "./commands/projectCommands.js";
 import { runProfileCommand } from "./commands/profileCommands.js";
-import { dispatchPreparedReviewRound, failPendingReviewRound, assertTaskRoleWritableAttachAvailable, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, validateTaskArchiveRequest } from "./commands/taskCommands.js";
+import { dispatchPreparedReviewRound, failPendingReviewRound, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, validateTaskArchiveRequest } from "./commands/taskCommands.js";
 import { taskActor } from "./commands/taskActor.js";
 import { runTaskIntegrationCommand } from "./commands/taskIntegrationCommands.js";
 import { runTaskChangeSetCommand } from "./commands/taskChangeSetCommands.js";
@@ -61,9 +61,9 @@ import { runSessionNotifyCommand } from "./controller/sessionNotify.js";
 import { openSchedulerTelemetry } from "./telemetry/telemetryWiring.js";
 import { runRuntimeObservationHookCommand } from "./controller/runtimeObservationHook.js";
 import { buildDoctorReport, renderDoctor, runDoctorCommand } from "./doctor/doctor.js";
-import { agentNotFound, CliError, usageError } from "./errors/cliError.js";
+import { agentNotFound, CliError, runtimeError, usageError } from "./errors/cliError.js";
 import { FileRoleLaunchPlanner } from "./executor/fileRoleLaunchPlanner.js";
-import { runAgentHost } from "./runtime/agentHost.js";
+import { AGENT_HOST_CONTROL_PROTOCOL, runAgentHost, sendAgentHostAuthorityControl } from "./runtime/agentHost.js";
 import { TaskWorkspaceCoordinator, WorkspaceCleanupBlockedError } from "./repository/taskWorkspaceCoordinator.js";
 import { FileTaskWorkspacePreparer, ReviewRoundWorkspaceEvidenceError } from "./repository/taskWorkspacePreparer.js";
 import { inspectStorageSchema } from "./storage/storageSchema.js";
@@ -1148,30 +1148,82 @@ export async function main() {
                     : { command: result.data, ...reviewData });
                 return;
             }
-            if (result.output !== undefined)
-                emit(result.output);
-            try {
-                tmux.attachRole(result.taskId, result.roleName, result.access, {
-                    ...(result.access === "read-write"
-                        ? {
-                            revalidateWritableAttach: () => {
-                                assertTaskRoleWritableAttachAvailable(store, result.taskId, result.roleName, {
-                                    isManagedProcessRunning: () => (tmux.probeRoleStatus(result.taskId, result.roleName) === "running")
-                                });
-                            }
+            if (jsonOutput) {
+                throw usageError("Task Role view/takeover requires an interactive terminal.");
+            }
+            if (result.kind === "view") {
+                if (result.output !== undefined)
+                    emit(result.output);
+                tmux.attachRole(result.taskId, result.roleName, "read-only");
+                return;
+            }
+            const syncAuthority = async (authorityResult) => {
+                let control;
+                try {
+                    control = await sendAgentHostAuthorityControl({
+                        home,
+                        scope: "task",
+                        taskId: authorityResult.taskId,
+                        roleName: authorityResult.roleName,
+                        control: {
+                            protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                            type: "set-authority",
+                            nativeSessionId: authorityResult.nativeSessionId,
+                            authority: authorityResult.authority
                         }
-                        : {})
+                    });
+                }
+                catch (error) {
+                    throw runtimeError(`Agent Host authority synchronization failed at epoch ${authorityResult.authority.epoch}: `
+                        + `${error instanceof Error ? error.message : String(error)}. `
+                        + `Durable authority is ${authorityResult.authority.owner}-owned; retry `
+                        + `'yui task role release ${authorityResult.taskId} ${authorityResult.roleName}' `
+                        + "to reconcile the Host.");
+                }
+                if (control.outcome !== "accepted"
+                    || control.snapshot.nativeSessionId !== authorityResult.nativeSessionId
+                    || control.snapshot.authorityEpoch !== authorityResult.authority.epoch
+                    || control.snapshot.authorityOwner !== authorityResult.authority.owner
+                    || control.snapshot.authorityHolderId !== authorityResult.authority.holderId) {
+                    throw runtimeError(`Agent Host did not accept Provider authority epoch ${authorityResult.authority.epoch}: `
+                        + (control.snapshot.detail ?? control.outcome)
+                        + `. Durable authority is ${authorityResult.authority.owner}-owned; `
+                        + "retry 'yui task role release "
+                        + `${authorityResult.taskId} ${authorityResult.roleName}' to reconcile the Host.`);
+                }
+                return control;
+            };
+            await syncAuthority(result);
+            emit(result.output);
+            if (result.action === "release") {
+                runtime.notifyMailboxChanged({
+                    kind: "role",
+                    taskId: result.taskId,
+                    roleName: result.roleName
                 });
+                return;
+            }
+            process.stdout.write("Provider input is now routed through the Agent Host PTY gateway. "
+                + "Use tmux detach (Ctrl-b d) to return authority to the Controller.\n");
+            try {
+                tmux.attachRole(result.taskId, result.roleName, "read-write");
             }
             finally {
-                if (result.access === "read-write") {
-                    // A Run claimed while the writer lease was visible is intentionally
-                    // paused. Releasing the lease only signals that existing durable
-                    // work may be reconsidered; it never creates or wakes a Run.
+                const currentTask = store.getTask(result.taskId);
+                // Completing or retiring the Task from inside the takeover Turn owns
+                // Provider shutdown and clears the live binding. Do not turn that
+                // successful terminal transition into a failing best-effort release.
+                if (currentTask?.status === "active") {
+                    const released = runTaskCommand(["role", "release", result.taskId, result.roleName], store, { runtime, environment: process.env, yuiHome: home });
+                    if (released.kind !== "authority" || released.action !== "release") {
+                        throw runtimeError("Provider authority release returned an invalid result.");
+                    }
+                    await syncAuthority(released);
+                    emit(released.output);
                     runtime.notifyMailboxChanged({
                         kind: "role",
-                        taskId: result.taskId,
-                        roleName: result.roleName
+                        taskId: released.taskId,
+                        roleName: released.roleName
                     });
                 }
             }