@zq-silk/yui 0.6.2 → 0.6.3

package/ARCHITECTURE.md

@@ -201,10 +201,34 @@ context.
 
 ## Runtime ownership
 
-tmux owns native Agent terminals. The Controller owns mailbox delivery,
-wakeups, Role liveness, reconciliation, and read-only Web observation. Operator
-and Leader Sessions are fixed Task/global Roles; Task Worker Sessions are
-selected through Role Agent bindings.
+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.
 
 Role desired revisions and Run/Session effective snapshots keep configuration
 history explicit. Resume compares the complete effective snapshot and

package/README.md

@@ -618,28 +618,48 @@ Task lifecycle completion/selection only suggests valid source states: Draft for
 
 ## Sessions and tmux
 
-tmux owns every long-lived interactive Agent process. Before `operator enter`,
-`role enter`, or `task enter` attaches, 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 the shell or IDE terminal history that preceded the attach. Native Agent
-features such as `/model`, slash-command suggestions, full-screen rendering,
-and key handling remain available.
+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.
 
-The first terminal attached to one Operator or Task tmux session is writable.
-Additional Terminal or Web viewers attach read-only, preventing two surfaces
-from typing into the same Agent at once.
+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.
 
 ```sh
 yui role enter <global-role>
-yui task enter <task-id> [role]
-yui task role enter <task-id> <role>
+yui task enter <task-id> [role] [--read-only | --read-write]
+yui task role enter <task-id> <role> [--read-only | --read-write]
 ```
 
 Each Role, including a Task-bound Worker instance, can bind multiple configured Agents, has one active Agent, and keeps
@@ -663,17 +683,31 @@ snapshot instead of applying desired drift as a hot change.
 
 Use `yui 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. Managed Codex launches use Codex's structured `notify` callback; after a completed turn, the callback records the native thread ID without injecting a session-binding prompt into the model conversation.
+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.
 
 Automated lifecycle and delivery decisions use structured Hook payloads,
-persisted identities, tmux process state, receipts, and pane fences. Yui never
+persisted identities, usage snapshots, tmux process state, receipts, and pane
+fences. Yui never
 parses prompt glyphs, progress text, trust dialogs, or other Agent terminal
 output to infer readiness or success. `captureRole()` remains an explicit
 human-facing transcript read and has no lifecycle authority.
 
+The [Agent Runtime Driver architecture](docs/agent-runtime-drivers.md) keeps
+native Codex/Claude event names at the edge. Core consumes exact-fenced
+Session, Turn, operation, waiting, host, and activity observations. A positive
+token delta is evidence of recent runtime activity; an unchanged counter is
+not. A live tmux pane proves only that the host exists. Runtime activity and
+durable workflow progress use independent clocks, so token/tool/resource
+movement cannot conceal a workflow that is not advancing.
+
 Stable Role context is also launch metadata, never a bootstrap turn. Yui passes Role policy and `systemPrompt` through the Agent's native system/developer-instruction channel. Task execution Runs receive the generic Leader or Worker Skill, while review Runs receive the generic Reviewer Skill based on durable Run purpose rather than a configured Role name. 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.
 
-Native Codex developer instructions carry compact absolute references only for Yui-owned Role Skills, which Codex reads on demand. Because `developer_instructions` is one scalar setting, Yui inspects every supported Linux Codex layer—`/etc/codex/config.toml`, the user config, the selected `$CODEX_HOME/<name>.config.toml`, project configs, and `/etc/codex/managed_config.toml`—and refuses to replace a value found in any of them. Managed Codex sessions also require exclusive ownership of the structured `notify` callback that records native Turn completion; Yui refuses launch when any inspected layer already defines `notify`, so neither callback can silently replace the other. `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. An adapter without a native instruction channel must reject this context rather than silently converting it into a first user prompt.
+Native Codex developer instructions carry compact absolute references only for Yui-owned Role Skills, which Codex reads on demand. Because `developer_instructions` is one scalar setting, Yui inspects every supported Linux Codex layer—`/etc/codex/config.toml`, the user config, the selected `$CODEX_HOME/<name>.config.toml`, project configs, and `/etc/codex/managed_config.toml`—and refuses to replace a value found in any of them. Codex sessions opened without a managed Run use Yui's structured `notify` callback for session presentation and therefore require exclusive ownership of that setting. Managed Runs instead use invocation-local Agent Driver Hooks as their sole lifecycle authority. `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. An adapter without a native instruction channel must reject this context rather than silently converting it into a first user prompt.
 
 ## Controller and failure handling
 
@@ -703,7 +737,7 @@ hiding the resources that remain. Use `--all` to include discovered Yui homes.
 
 `controller restart` replaces the Controller process and its scheduler/socket services with the currently installed Yui version. It does not stop or restart managed tmux/Agent sessions.
 
-Its recovery reconciliation runs every 120 seconds by default. Normal durable state changes enqueue a Task, Role, or Operator key and return immediately; keys received in the same fixed 100 ms window trigger one non-overlapping targeted pass. Operator presentation has an independent lane, so a blocked Task workspace operation cannot delay a user question. Periodic Git/worktree work is limited to Tasks with durable Task-mailbox work, while active Role liveness uses one tmux inventory. A Codex turn-complete Hook writes directly to storage without starting or waiting for the Controller, then gives a legal yield/input/completion two seconds to win before closing a forgotten Run. Durable mailboxes freeze the current batch while new signals merge into the next batch. Task-orchestration failures retain the exact Controller-owned processing batch for two bounded fast retries and later periodic recovery; a successful retry completes that batch before newer pending work is claimed. Recommended InputRequest and pending Turn deadlines share one nearest-deadline selector and therefore do not wait for the recovery interval. Explicit `task reconcile` still requests an immediate recovery pass. The retained loop is:
+Its recovery reconciliation runs every 120 seconds by default. Normal durable state changes enqueue a Task, Role, or Operator key and return immediately; keys received in the same fixed 100 ms window trigger one non-overlapping targeted pass. Operator presentation has an independent lane, so a blocked Task workspace operation cannot delay a user question. Periodic Git/worktree work is limited to Tasks with durable Task-mailbox work, while active Role liveness uses one tmux inventory. Agent Driver Hooks write exact-fenced observations to the durable runtime inbox without starting or waiting for the Controller. A terminal Turn observation gives a legal yield/input/completion two seconds to win before a forgotten Run fails its workflow contract. Durable mailboxes freeze the current batch while new signals merge into the next batch. Task-orchestration failures retain the exact Controller-owned processing batch for two bounded fast retries and later periodic recovery; a successful retry completes that batch before newer pending work is claimed. Recommended InputRequest and pending Turn deadlines share one nearest-deadline selector and therefore do not wait for the recovery interval. Explicit `task reconcile` still requests an immediate recovery pass. The retained loop is:
 
 1. dispatch pending Leader wakes whose Task workspaces are already ready;
 2. prepare active Project Task main worktrees with durable orchestration work;
@@ -711,7 +745,7 @@ Its recovery reconciliation runs every 120 seconds by default. Normal durable st
 4. resolve due Turn completions and reconcile Role liveness;
 5. dispatch Leader work created or unblocked by the later recovery phases.
 
-Automated input is sent only through tmux. Each pass performs one non-blocking process-state readiness check; a busy startup is retried through a small bounded mailbox timer, while later busy sessions are normally woken by Codex turn-complete events. A pane-local receipt prevents the same Run from being typed twice after a Controller retry.
+Automated input is sent only through tmux. Each pass performs one non-blocking process-state readiness check; a busy startup is retried through a small bounded mailbox timer, while later busy sessions are woken by canonical Agent Driver terminal observations. A pane-local receipt prevents the same Run from being typed twice after a Controller retry.
 
 If a Role process exits before yielding, the Controller fails that Run and running WorkItem and queues the Leader. Recovery failures are exposed through the small compatibility Jobs view:
 
@@ -854,14 +888,18 @@ The reusable, user-driven acceptance plan is documented in
 
 ```sh
 npm ci
-npm run build
-npm test
-npm run lint
+npm run test:core
 ```
 
-`npm test` (and `make test` / `make check`) runs the full **deterministic** test
-suite: it never launches a real model and never touches the global `yui`
-binary, a shared `YUI_HOME`, or a running production Session. It stays
+`npm run test:core` builds once and runs the same small, explicit core matrix as
+CI. During development, add the smallest affected test files for the behavior
+being changed.
+
+`npm test` (and `make test` / `make check`) remains the full **deterministic**
+diagnostic suite. Run it on demand for unusually cross-cutting changes or
+regression investigation; it is not a routine merge requirement. It never
+launches a real model or touches the global `yui` binary, a shared `YUI_HOME`,
+or a running production Session. It stays
 deterministic even when launched from inside a managed Yui Session, because it
 preloads `test/helpers/scrubSessionEnv.js` to strip every Yui-owned managed
 runtime value from the test process, including shared `YUI_HOME`, exact Leader

package/dist/agent/argumentPolicy.js

@@ -16,7 +16,7 @@ const OWNED_ARGUMENTS_BY_ADAPTER = {
         "--allow-dangerously-skip-permissions", "--no-session-persistence", "--from-pr",
         "--fallback-model", "--tools", "--system-prompt", "--system-prompt-file",
         "--append-system-prompt", "--append-system-prompt-file", "--plugin-dir",
-        "--name", "-n"
+        "--name", "-n", "--output-format", "--input-format"
     ]
 };
 export function ownedArgumentsForAdapter(adapterId) {

package/dist/agent/managedRuntimeEnvironment.js

@@ -14,6 +14,7 @@ export const YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES = Object.freeze([
     "YUI_ROLE",
     "YUI_AGENT_ID",
     "YUI_ADAPTER_ID",
+    "YUI_DRIVER_ID",
     "YUI_WORKSPACE",
     "YUI_RUN_ID",
     "YUI_LAUNCH_ID",

package/dist/cli/commandCatalog.js

@@ -421,7 +421,12 @@ const taskChildren = [
                 usage: "yui task role reset <task> <role> --reason <text>",
                 options: ["--reason"]
             },
-            { name: "enter", summary: "Enter a Task Role's native session.", usage: "yui task role enter <task> <role>" }
+            {
+                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"]
+            }
         ]
     },
     {
@@ -777,7 +782,12 @@ const taskChildren = [
             { name: "show", summary: "Show one ChangeSet.", usage: "yui task change-set show <task>/<change-set>" }
         ]
     },
-    { name: "enter", summary: "Enter a Task Role, defaulting to Leader.", usage: "yui task enter <task> [role]" }
+    {
+        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",
@@ -1153,7 +1163,7 @@ export const ROOT_COMMAND = buildNode({
             name: "internal",
             summary: "Internal Yui callbacks.",
             hidden: true,
-            sections: [{ id: "callbacks", title: "Callbacks", entries: ["session-notify", "claude-hook", "codex-hook"] }],
+            sections: [{ id: "callbacks", title: "Callbacks", entries: ["session-notify", "runtime-hook", "managed-claude-run"] }],
             children: [
                 {
                     name: "session-notify",
@@ -1161,14 +1171,14 @@ export const ROOT_COMMAND = buildNode({
                     usage: "yui internal session-notify <payload>"
                 },
                 {
-                    name: "claude-hook",
-                    summary: "Record a managed Claude StopFailure event from stdin.",
-                    usage: "yui internal claude-hook"
+                    name: "runtime-hook",
+                    summary: "Record a managed Agent Driver observation from stdin.",
+                    usage: "yui internal runtime-hook"
                 },
                 {
-                    name: "codex-hook",
-                    summary: "Record managed Codex provider lifecycle evidence from stdin.",
-                    usage: "yui internal codex-hook"
+                    name: "managed-claude-run",
+                    summary: "Run one managed Claude turn over the stream-json protocol.",
+                    usage: "yui internal managed-claude-run -- <command> [args...]"
                 }
             ]
         }

package/dist/cli/interactionPolicy.js

@@ -371,7 +371,8 @@ export const INTERACTION_POLICIES = Object.freeze([
                 dependsOn: 3,
                 actionTarget: true
             }
-        ]
+        ],
+        trailingOptions: { "--read-only": "flag", "--read-write": "flag" }
     },
     {
         commandPath: ["task", "work", "create"],
@@ -534,7 +535,8 @@ export const INTERACTION_POLICIES = Object.freeze([
     })),
     {
         commandPath: ["task", "enter"],
-        selectors: [{ argumentIndex: 2, entity: "task", provider: "tasks", actionTarget: true }]
+        selectors: [{ argumentIndex: 2, entity: "task", provider: "tasks", actionTarget: true }],
+        trailingOptions: { "--read-only": "flag", "--read-write": "flag" }
     },
     {
         commandPath: ["jobs", "retry"],

package/dist/cli.js

@@ -32,7 +32,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, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, validateTaskArchiveRequest } from "./commands/taskCommands.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 { taskActor } from "./commands/taskActor.js";
 import { runTaskIntegrationCommand } from "./commands/taskIntegrationCommands.js";
 import { runTaskChangeSetCommand } from "./commands/taskChangeSetCommands.js";
@@ -53,11 +53,11 @@ import { cleanControllerResource } from "./controller/resourceCleanupLinux.js";
 import { scanControllerResourceInventory } from "./controller/resourceInventoryLinux.js";
 import { runSessionNotifyCommand } from "./controller/sessionNotify.js";
 import { openSchedulerTelemetry } from "./telemetry/telemetryWiring.js";
-import { runClaudeLifecycleHookCommand } from "./controller/claudeLifecycleHook.js";
-import { runCodexLifecycleHookCommand } from "./controller/codexLifecycleHook.js";
+import { runRuntimeObservationHookCommand } from "./controller/runtimeObservationHook.js";
 import { buildDoctorReport, renderDoctor, runDoctorCommand } from "./doctor/doctor.js";
 import { agentNotFound, CliError, usageError } from "./errors/cliError.js";
 import { FileRoleLaunchPlanner } from "./executor/fileRoleLaunchPlanner.js";
+import { runManagedClaudeProcess } from "./executor/managedClaudeRunner.js";
 import { TaskWorkspaceCoordinator, WorkspaceCleanupBlockedError } from "./repository/taskWorkspaceCoordinator.js";
 import { FileTaskWorkspacePreparer, ReviewRoundWorkspaceEvidenceError } from "./repository/taskWorkspacePreparer.js";
 import { inspectStorageSchema } from "./storage/storageSchema.js";
@@ -75,6 +75,7 @@ import { TmuxWebTerminalService } from "./web/tmuxWebTerminal.js";
 import { listOperatorSessions, operatorSessionRef } from "./operator/operatorSessionHistory.js";
 import { YUI_VERSION, yuiVersionIdentity } from "./version.js";
 import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactControlPlanePreflight, assertExactTaskRuntimeEnvironment, assertExactTaskRuntimeState, exactControlPlaneDigest, extractExactControlArgument, parseExactControlPlaneDescriptor } from "./runtime/exactControlPlane.js";
+import { builtinAgentDriverRegistry } from "./runtime/builtinAgentDrivers.js";
 import { createTaskFinalReviewContract, extractTaskFinalReviewRequest } from "./review/taskFinalReviewContract.js";
 import { currentWorkItemExecutionGroup, workItemExecutionGroupById } from "./workItem/workItem.js";
 const VERSION = YUI_VERSION;
@@ -228,12 +229,38 @@ export async function main() {
             await runSessionNotifyCommand(args[2], process.env);
             return;
         }
-        if (args[1] === "claude-hook" && args.length === 2) {
-            await runClaudeLifecycleHookCommand(readFileSync(0, "utf8"), process.env);
+        if (args[1] === "runtime-hook" && args.length === 2) {
+            await runRuntimeObservationHookCommand(readFileSync(0, "utf8"), process.env);
             return;
         }
-        if (args[1] === "codex-hook" && args.length === 2) {
-            await runCodexLifecycleHookCommand(readFileSync(0, "utf8"), process.env);
+        if (args[1] === "managed-claude-run"
+            && args[2] === "--"
+            && args.length >= 4
+            && verifiedStore !== undefined) {
+            const taskId = process.env.YUI_TASK_ID;
+            const runId = process.env.YUI_RUN_ID;
+            const agentId = process.env.YUI_AGENT_ID;
+            if (taskId === undefined || runId === undefined || agentId === undefined) {
+                throw new Error("Managed Claude run identity is incomplete.");
+            }
+            const run = verifiedStore.getActiveAgentRun(taskId, process.env.YUI_ROLE ?? "");
+            if (run === null || run.id !== runId || run.effective.agentId !== agentId
+                || run.effective.adapterId !== "claude") {
+                throw new Error("Managed Claude run is not the exact active generation.");
+            }
+            const configured = verifiedStore.getConfiguredAgent(agentId);
+            if (configured === null || configured.adapterId !== "claude" || args[3] !== configured.command) {
+                throw new Error("Managed Claude command does not match the active Agent.");
+            }
+            if (!configured.baseArgs.every((value, index) => args[index + 4] === value)) {
+                throw new Error("Managed Claude arguments do not start with the configured base arguments.");
+            }
+            process.exitCode = await runManagedClaudeProcess({
+                command: configured.command,
+                args: args.slice(4),
+                prompt: run.input,
+                environment: process.env
+            });
             return;
         }
         throw usageError("Internal lifecycle callback usage is invalid.");
@@ -450,7 +477,6 @@ export async function main() {
             yuiHome: home,
             tmuxBin: process.env.YUI_TMUX_BIN ?? "tmux",
             tmux,
-            prepareTaskRole: (input) => runtime.prepareTaskRoleEnter(input),
             prepareGlobalRole: (roleName) => runtime.prepareGlobalRoleEnter(roleName),
             environment: process.env,
             onError: (error) => {
@@ -562,7 +588,7 @@ export async function main() {
         }
         await ensureFileTaskController(home, { environment: process.env });
         await runtime.prepareGlobalRoleEnter(result.role.name);
-        tmux.attachRole("operator", result.role.name);
+        tmux.attachRole("operator", result.role.name, "auto");
         return;
     }
     if (resolved[0] === "operator") {
@@ -571,7 +597,7 @@ export async function main() {
                 throw usageError("Operator enter usage: yui operator enter.");
             await ensureFileTaskController(home, { environment: process.env });
             await runtime.prepareGlobalRoleEnter("operator");
-            tmux.attachRole("operator", "operator");
+            tmux.attachRole("operator", "operator", "auto");
             return;
         }
         const result = runOperatorCommand(resolved.slice(1), store, { runtime, environment: process.env });
@@ -628,16 +654,6 @@ export async function main() {
             emit(result.output, false, result.data);
             return;
         }
-        const enteringTask = (resolved[1] === "enter")
-            || (resolved[1] === "role" && resolved[2] === "enter");
-        if (enteringTask) {
-            await ensureFileTaskController(home, { environment: process.env });
-            const taskId = resolved[1] === "enter" ? resolved[2] : resolved[3];
-            const task = taskId === undefined ? null : store.getTask(taskId);
-            if (task?.status === "active") {
-                await workspacePreparer.prepareTaskWorkspace(task.id);
-            }
-        }
         if (resolved[1] === "work" && resolved[2] === "isolate") {
             const workItemId = resolved[3];
             if (workItemId === undefined || resolved.length !== 4) {
@@ -1044,13 +1060,33 @@ export async function main() {
                     : { command: result.data, ...reviewData });
                 return;
             }
-            await runtime.prepareTaskRoleEnter({
-                taskId: result.taskId,
-                roleName: result.roleName
-            });
             if (result.output !== undefined)
                 emit(result.output);
-            tmux.attachRole(result.taskId, result.roleName);
+            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")
+                                });
+                            }
+                        }
+                        : {})
+                });
+            }
+            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.
+                    runtime.notifyMailboxChanged({
+                        kind: "role",
+                        taskId: result.taskId,
+                        roleName: result.roleName
+                    });
+                }
+            }
             return;
         }
         catch (error) {
@@ -1138,12 +1174,21 @@ async function preflightManagedTaskControlPlane() {
         checkController: !internalCallback
     });
     const runtime = assertExactTaskRuntimeEnvironment(serializedRuntime, process.env, digest, control.yuiHome);
-    const preallocatedClaudeCallback = args.length === 2
-        && args[0] === "internal"
-        && args[1] === "claude-hook";
+    const runtimeDriverCallback = args[0] === "internal"
+        && (args[1] === "runtime-hook" || args[1] === "managed-claude-run")
+        && process.env.YUI_DRIVER_ID !== undefined
+        ? builtinAgentDriverRegistry().require(process.env.YUI_DRIVER_ID)
+        : undefined;
+    const preallocatedDriverCallback = runtimeDriverCallback
+        ?.capabilities.observation.sessionBootstrap === "preallocated";
     const verifiedStore = openCompatibleFileTaskStore(control.yuiHome);
-    assertExactTaskRuntimeState(runtime, verifiedStore, preallocatedClaudeCallback
-        ? { preallocatedNativeSessionReservation: { yuiHome: control.yuiHome } }
+    assertExactTaskRuntimeState(runtime, verifiedStore, preallocatedDriverCallback
+        ? {
+            preallocatedDriverSessionReservation: {
+                yuiHome: control.yuiHome,
+                adapterId: runtimeDriverCallback.adapterId
+            }
+        }
         : {});
     const request = taskFinalReviewInvocation.request;
     if (request === undefined)
@@ -1634,7 +1679,7 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
         && control.targetAgentId === active?.agentId
         && active !== undefined
         && operatorSessionRef(active) === control.ref) {
-        tmux.attachRole("operator", "operator");
+        tmux.attachRole("operator", "operator", "auto");
         return;
     }
     const handle = terminalIo();
@@ -1686,7 +1731,7 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
     }
     applyOperatorSessionControl(control, store);
     await runtime.prepareGlobalRoleEnter(role.name);
-    tmux.attachRole("operator", role.name);
+    tmux.attachRole("operator", role.name, "auto");
 }
 function adapterLabel(adapterId) {
     return adapterId === "codex"

package/dist/commands/taskCommands.js

@@ -13,7 +13,7 @@ import { createTaskMessage, taskMessageAuthorLabel } from "../message/message.js
 import { cancelInputRequest } from "../input/inputRequest.js";
 import { recoverExactAgentRun, terminalizeExactTaskRun, validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
 import { resetTaskRoleSessionGeneration } from "../lifecycle/taskRoleSessionReset.js";
-import { copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole, updateRoleStatus } from "../role/role.js";
+import { activeRoleAgentBinding, copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole, updateRoleStatus } from "../role/role.js";
 import { createAgentRun } from "../run/agentRun.js";
 import { matchYieldReceipt } from "../run/yieldReceipt.js";
 import { providerRetryConfig } from "../run/providerRetryConfig.js";
@@ -1268,7 +1268,7 @@ function listTaskRoles(args, store, options) {
     exactPositionals(args, 1, "Task role list usage: yui task role list <task>.");
     const task = requireTask(store, args[0]);
     const roles = store.listRoles(task.id);
-    const statuses = inspectTaskRoleRuntimeStatuses(task.id, roles, store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? []);
+    const statuses = inspectTaskRoleRuntimeStatuses(task.id, roles, store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? [], options.now?.() ?? new Date());
     if (statuses.length === 0)
         return output("No roles assigned.\n", { roles: statuses });
     return output(`${renderTable(`Task roles: ${task.id}`, [
@@ -1293,7 +1293,7 @@ function taskRoleStatus(args, store, options) {
     exactPositionals(args, 2, "Task role status usage: yui task role status <task> <role>.");
     const task = requireTask(store, args[0]);
     const role = requireRole(store, task.id, args[1]);
-    const [status] = inspectTaskRoleRuntimeStatuses(task.id, [role], store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? []);
+    const [status] = inspectTaskRoleRuntimeStatuses(task.id, [role], store, options.runtime?.inspectTaskRolePanes?.(task.id) ?? [], options.now?.() ?? new Date());
     if (status === undefined)
         throw roleNotFound(role.name);
     return output(renderTaskRoleRuntimeStatus(status), { role: status });
@@ -1475,25 +1475,60 @@ function unbindTaskRole(args, store, options) {
     });
     return `Unbound Agent ${args[2]} from ${result.taskId}/${result.name}\n`;
 }
-function enterTaskRole(args, store, options) {
-    exactPositionals(args, 2, "Task role enter usage: yui task role enter <task> <role>.");
-    const task = requireTask(store, args[0]);
+function enterTaskRole(args, store, _options) {
+    const usage = "Task role enter usage: yui task role enter <task> <role> "
+        + "[--read-only | --read-write].";
+    const parsed = parseTail(args, new Set(), usage, new Set(["--read-only", "--read-write"]));
+    exactPositionals(parsed.positionals, 2, usage);
+    if (parsed.options.has("--read-only") && parsed.options.has("--read-write")) {
+        throw usageError("--read-only and --read-write are mutually exclusive.", usage);
+    }
+    const task = requireTask(store, parsed.positionals[0]);
     if (task.status !== "active") {
         throw usageError(inactiveTaskMessage(task, "entering a role session"));
     }
-    const role = requireRole(store, task.id, args[1]);
+    const role = requireRole(store, task.id, parsed.positionals[1]);
+    const access = parsed.options.has("--read-write") ? "read-write" : "read-only";
+    if (access === "read-write") {
+        assertTaskRoleWritableAttachAvailable(store, task.id, role.name);
+    }
     return {
         kind: "enter",
         taskId: task.id,
         roleName: role.name,
-        output: `Prepared role ${role.name} for ${task.id}\n`
+        access,
+        output: `Attaching to ${role.name} for ${task.id} (${access})\n`
     };
 }
+/** Re-run after the tmux writer lease exists to close attach/launch races. */
+export function assertTaskRoleWritableAttachAvailable(store, taskId, roleName, options = {}) {
+    const role = requireRole(store, taskId, roleName);
+    if (store.getActiveAgentRun(taskId, roleName) !== null) {
+        throw usageError(`Role has an active managed Run; writable attach is unavailable: ${taskId}/${roleName}.`);
+    }
+    const session = store.getRoleSession(taskId, roleName);
+    if (activeRoleAgentBinding(role).adapterId === "claude"
+        && ((session !== null
+            && session.status !== "stopped"
+            && session.status !== "broken")
+            || options.isManagedProcessRunning?.() === true)) {
+        throw usageError(`A managed Claude process is still running; writable attach is unavailable: ${taskId}/${roleName}.`);
+    }
+}
 function enterTaskRoleAlias(args, store, options) {
-    if (args.length < 1 || args.length > 2 || args.some((value) => value.trim().length === 0)) {
-        throw usageError("Task enter usage: yui task enter <task> [role].");
+    const usage = "Task enter usage: yui task enter <task> [role] "
+        + "[--read-only | --read-write].";
+    const parsed = parseTail(args, new Set(), usage, new Set(["--read-only", "--read-write"]));
+    if (parsed.positionals.length < 1 || parsed.positionals.length > 2
+        || parsed.positionals.some((value) => value.trim().length === 0)) {
+        throw usageError(usage);
     }
-    return enterTaskRole([args[0], args[1] ?? LEADER_ROLE], store, options);
+    return enterTaskRole([
+        parsed.positionals[0],
+        parsed.positionals[1] ?? LEADER_ROLE,
+        ...(parsed.options.has("--read-only") ? ["--read-only"] : []),
+        ...(parsed.options.has("--read-write") ? ["--read-write"] : [])
+    ], store, options);
 }
 function taskWorkCommand(args, store, options) {
     const [command, ...rest] = args;

package/dist/commands/taskContextCommand.js

@@ -303,7 +303,7 @@ function latestStallKind(events, runId) {
     const event = [...events]
         .filter((candidate) => candidate.type === "run.stalled" && candidate.payload.runId === runId)
         .sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))[0];
-    return event?.payload.kind ?? "execution-stalled";
+    return event?.payload.kind ?? "workflow-not-progressing";
 }
 function renderWorkItemReviews(rounds) {
     const latest = rounds.at(-1);