@zq-silk/yui 0.8.1 → 0.8.2

package/dist/scheduler/leaderWakeupProcessor.js

@@ -67,6 +67,7 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
         let effectiveSession = existingSession;
         let claimed = false;
         let deliveryAttempted = false;
+        let providerSubmissionBegun = false;
         let run = null;
         let prepared;
         let preStartFencePersisted = false;
@@ -183,13 +184,14 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                     preStartFencePersisted = true;
                 }
             });
-            // A managed host may already have submitted the exact Run prompt as
-            // part of process launch. Once preparation returns that transport
+            // A managed Host may have submitted the exact Run Turn after its
+            // two-phase launch handshake. Once preparation returns that transport
             // fact, any
             // later readiness or aggregate-write failure is delivery uncertainty,
             // not a launch failure: preserve the Run and its reservation for the
             // matching provider Hook instead of terminalizing it.
-            deliveryAttempted = prepared.inputSubmittedAtLaunch === true;
+            deliveryAttempted = prepared.turnAcceptedDuringLaunch === true
+                || prepared.turnDeliveryUnknownDuringLaunch === true;
             // Persist the exact preparation fence before waiting on provider
             // readiness. A pre-input lifecycle Hook may fire during that wait; it
             // must be able to resolve this Run/Session/launch generation from durable
@@ -211,7 +213,8 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
             }
             const ready = await delivery.waitUntilReady(prepared);
             deliveryAttempted = deliveryAttempted
-                || ready.prepared.inputSubmittedAtLaunch === true;
+                || ready.prepared.turnAcceptedDuringLaunch === true
+                || ready.prepared.turnDeliveryUnknownDuringLaunch === true;
             const latestTask = store.getTask(task.id);
             if (latestTask === null || latestTask.status !== "active") {
                 delivery.forgetPrepared?.({
@@ -236,12 +239,54 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                     : { launchId: ready.prepared.launchId }),
                 now
             });
-            if (ready.prepared.inputSubmittedAtLaunch === true) {
-                // A fresh Codex command may carry the exact first prompt in its launch
-                // argv. That is transport evidence only: the matching Provider Hook
-                // still owns Run acceptance. Persist the push fence without writing a
-                // second terminal prompt, then leave the reservation for the async
-                // SessionStart/UserPromptSubmit fold.
+            if (ready.prepared.turnRejectedDuringLaunch === true) {
+                delivery.forgetPrepared?.({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    ...(ready.prepared.launchId === undefined
+                        ? {}
+                        : { launchId: ready.prepared.launchId })
+                });
+                results.push({
+                    taskId: task.id,
+                    runId: run.id,
+                    status: "skipped",
+                    reason: "not-ready"
+                });
+                continue;
+            }
+            if (ready.prepared.turnDeliveryUnknownDuringLaunch === true) {
+                store.saveRoleRunDelivery({
+                    task,
+                    role,
+                    run,
+                    session: effectiveSession,
+                    ...(ready.prepared.launchId === undefined
+                        ? {}
+                        : { launchId: ready.prepared.launchId }),
+                    now
+                });
+                delivery.forgetPrepared?.({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    ...(ready.prepared.launchId === undefined
+                        ? {}
+                        : { launchId: ready.prepared.launchId })
+                });
+                results.push({
+                    taskId: task.id,
+                    runId: run.id,
+                    status: "skipped",
+                    reason: "delivery-uncertain"
+                });
+                continue;
+            }
+            if (ready.prepared.turnAcceptedDuringLaunch === true) {
+                // The Agent Host submitted the exact first Turn through structured
+                // Provider control. Persist the transport fence without a second write;
+                // the matching structured acknowledgement owns Run acceptance.
                 store.saveRoleRunDelivery({
                     task,
                     role,
@@ -263,13 +308,41 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                 results.push({ taskId: task.id, runId: run.id, status: "dispatched" });
                 continue;
             }
+            const receiptId = formatAgentRunReceiptId(task.id, run.id);
+            if (effectiveSession === null || effectiveSession.launchId === undefined
+                || !hasNativeSession(effectiveSession)
+                || store.beginRoleRunProviderTurn?.({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    agentId: run.effective.agentId,
+                    launchId: effectiveSession.launchId,
+                    nativeSessionId: effectiveSession.nativeSessionId,
+                    attemptId: receiptId,
+                    now
+                }) !== true) {
+                throw new Error("Provider Turn intent could not be durably fenced before delivery.");
+            }
+            providerSubmissionBegun = true;
             deliveryAttempted = true;
             const outcome = await delivery.sendOnce({
                 delivery: ready,
-                receiptId: formatAgentRunReceiptId(task.id, run.id),
+                receiptId,
                 text: serializeRunBootstrapEnvelope(run.bootstrapEnvelope)
             });
             if (outcome === "busy" || outcome === "unavailable") {
+                store.resolveRoleRunProviderSubmission?.({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    attemptId: receiptId,
+                    status: "rejected",
+                    reason: outcome === "busy"
+                        ? "Agent Host was busy before Provider mutation."
+                        : "Agent Host was unavailable before Provider mutation.",
+                    now
+                });
+                providerSubmissionBegun = false;
                 results.push({
                     taskId: task.id,
                     runId: run.id,
@@ -278,6 +351,49 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                 });
                 continue;
             }
+            if (outcome === "rejected") {
+                store.resolveRoleRunProviderSubmission?.({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    attemptId: receiptId,
+                    status: "rejected",
+                    reason: "Provider returned an exact negative acknowledgement.",
+                    now
+                });
+                providerSubmissionBegun = false;
+                results.push({ taskId: task.id, runId: run.id, status: "skipped", reason: "not-ready" });
+                continue;
+            }
+            if (outcome === "delivery-unknown") {
+                store.resolveRoleRunProviderSubmission?.({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    attemptId: receiptId,
+                    status: "delivery-unknown",
+                    reason: "Provider Turn delivery is ambiguous; automatic retry is fenced.",
+                    now
+                });
+                providerSubmissionBegun = false;
+                store.saveRoleRunDelivery({
+                    task,
+                    role,
+                    run,
+                    session: effectiveSession,
+                    ...(ready.prepared.launchId === undefined
+                        ? {}
+                        : { launchId: ready.prepared.launchId }),
+                    now
+                });
+                results.push({
+                    taskId: task.id,
+                    runId: run.id,
+                    status: "skipped",
+                    reason: "delivery-uncertain"
+                });
+                continue;
+            }
             store.saveRoleRunDelivery({
                 task,
                 role,
@@ -293,6 +409,17 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
             const message = `Leader dispatch failed: ${detail}`;
+            if (providerSubmissionBegun && run !== null) {
+                store.resolveRoleRunProviderSubmission?.({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    attemptId: formatAgentRunReceiptId(task.id, run.id),
+                    status: "delivery-unknown",
+                    reason: detail,
+                    now
+                });
+            }
             if (claimed && run !== null) {
                 // Scheduler single-flight backpressure: the Role runtime lifecycle
                 // lane was busy when the launch was reserved. The claimed Run stays
@@ -314,11 +441,9 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                     });
                     continue;
                 }
-                // A finite managed provider from the preceding Run may still be
-                // exiting after its durable yield. Keep this newly-claimed Run as the
-                // sole owner of the Role mailbox; active-Run delivery will retry it
-                // after the old host disappears. This is runtime backpressure, not a
-                // Leader failure and not grounds for allocating another Run.
+                // A managed Provider lifecycle operation may still be settling. Keep
+                // this newly-claimed Run as the sole mailbox owner; active-Run delivery
+                // retries after the lifecycle lane clears.
                 if (error instanceof RuntimeLaunchError && error.retryable) {
                     results.push({
                         taskId: task.id,

package/dist/storage/migration/productionRegistry.js

@@ -79,6 +79,8 @@ const WORK_MAILBOX_FROM_VERSION = 1;
 const WORK_MAILBOX_TO_VERSION = 2;
 const TASK_ROLE_SESSION_SET_FROM_VERSION = 4;
 const TASK_ROLE_SESSION_SET_TO_VERSION = 5;
+const STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION = 5;
+const STRUCTURED_PROVIDER_SESSION_SET_TO_VERSION = 6;
 const PUBLICATION_REFERENCE_FROM_VERSION = 0;
 const PUBLICATION_REFERENCE_TO_VERSION = 1;
 const CONFIG_FROM_VERSION = 1;
@@ -161,6 +163,7 @@ export function createProductionStorageRegistry() {
         .registerOfflineMigration(releaseWorkflowIntroductionStep())
         .registerOfflineMigration(workMailboxV2Step())
         .registerOfflineMigration(taskRoleSessionSetV5Step())
+        .registerOfflineMigration(structuredProviderSessionSetV6Step())
         .registerOfflineMigration(publicationReferenceIntroductionStep());
     assertRegistryCoversBaselineToCurrent(registry);
     return registry;
@@ -2225,6 +2228,114 @@ function taskRoleSessionSetV5Step() {
         declaredEffects: []
     };
 }
+/**
+ * v6 is a deliberate runtime cutover, not an emulation layer. Existing Task,
+ * Run, Conversation, and Session identities remain as audit evidence, while
+ * every pre-v6 managed process is terminalized locally. A new Agent Host must
+ * establish structured Provider evidence before any further write.
+ */
+function structuredProviderSessionSetV6Step() {
+    return {
+        axis: "record",
+        recordKind: "taskRoleSessionSet",
+        fromVersion: STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION,
+        toVersion: STRUCTURED_PROVIDER_SESSION_SET_TO_VERSION,
+        preconditions: requireTaskRoleSessionSetV5Family,
+        transform: migrateTaskRoleSessionSetV5ToV6,
+        declaredEffects: []
+    };
+}
+function requireTaskRoleSessionSetV5Family(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.taskRoleSessionSet !== STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION) {
+        throw new Error(`Record taskRoleSessionSet migration requires manifest version ${STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawAggregate] of Object.entries(tasks)) {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const sets = asObject(aggregate.roleSessionSets, `Task Role session sets ${taskId}`);
+        for (const [roleName, rawSet] of Object.entries(sets)) {
+            const set = asObject(rawSet, `Task Role session set ${taskId}/${roleName}`);
+            if (set.schemaVersion !== STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION) {
+                throw new Error(`Task Role session set ${taskId}/${roleName} must use schemaVersion ${STRUCTURED_PROVIDER_SESSION_SET_FROM_VERSION}.`);
+            }
+        }
+    }
+}
+function migrateTaskRoleSessionSetV5ToV6(snapshot) {
+    requireTaskRoleSessionSetV5Family(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...versions,
+            taskRoleSessionSet: STRUCTURED_PROVIDER_SESSION_SET_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawAggregate] of Object.entries(tasks)) {
+        const aggregate = asObject(rawAggregate, `Task aggregate ${taskId}`);
+        const rawSets = asObject(aggregate.roleSessionSets, `Task Role session sets ${taskId}`);
+        const nextSets = {};
+        for (const [roleName, rawSet] of Object.entries(rawSets)) {
+            const set = asObject(rawSet, `Task Role session set ${taskId}/${roleName}`);
+            const invalidatedAt = String(set.updatedAt);
+            const sessions = asObject(set.sessions, `Task Role sessions ${taskId}/${roleName}`);
+            const nextSessions = Object.fromEntries(Object.entries(sessions).map(([agentId, rawSession]) => {
+                const session = asObject(rawSession, `Task Role Session ${taskId}/${roleName}/${agentId}`);
+                return [agentId, session.status === "stopped" || session.status === "broken"
+                        ? session
+                        : { ...session, status: "broken", updatedAt: invalidatedAt }];
+            }));
+            nextSets[roleName] = {
+                ...set,
+                schemaVersion: STRUCTURED_PROVIDER_SESSION_SET_TO_VERSION,
+                sessions: nextSessions,
+                providerBinding: set.providerBinding === null
+                    ? null
+                    : invalidateLegacyProviderBinding(asObject(set.providerBinding, `Provider Binding ${taskId}/${roleName}`), invalidatedAt)
+            };
+        }
+        nextTasks[taskId] = { ...aggregate, roleSessionSets: nextSets };
+    }
+    return { schemaManifest, state: { ...snapshot.state, tasks: nextTasks } };
+}
+function invalidateLegacyProviderBinding(binding, invalidatedAt) {
+    if (binding.schemaVersion !== 1) {
+        throw new Error("Pre-v6 Provider Runtime Binding must use schemaVersion 1.");
+    }
+    const activations = Array.isArray(binding.activations) ? binding.activations : [];
+    return {
+        ...binding,
+        schemaVersion: 2,
+        conversations: (Array.isArray(binding.conversations) ? binding.conversations : []).map((rawConversation) => {
+            const conversation = asObject(rawConversation, "Provider Conversation");
+            return conversation.status === "current"
+                ? { ...conversation, recoverability: "unknown" }
+                : conversation;
+        }),
+        activations: activations.map((rawActivation) => {
+            const activation = asObject(rawActivation, "Provider Activation");
+            const { writerLease: _removed, ...withoutLease } = activation;
+            void _removed;
+            return activation.status === "active"
+                ? {
+                    ...withoutLease,
+                    status: "failed",
+                    endedAt: invalidatedAt,
+                    terminalReason: "legacy-managed-runtime-invalidated"
+                }
+                : withoutLease;
+        }),
+        authority: { epoch: 1, owner: "none", changedAt: invalidatedAt },
+        turn: null
+    };
+}
 function requireTaskRoleSessionSetV4Family(snapshot) {
     const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
     if (versions.taskRoleSessionSet !== TASK_ROLE_SESSION_SET_FROM_VERSION) {

package/dist/storage/taskStore.js

@@ -117,7 +117,7 @@ export const CURRENT_STORED_TASK_SCHEMA_VERSION = 17;
  * Keep these named at the storage boundary so the upgrade record-axis map can
  * assert it is classifying the same bytes the store reads and writes.
  */
-export const CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION = 5;
+export const CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION = 6;
 /**
  * v7 combines optional Issue 04 retry/receipt fields and Issue 05 Leader
  * actionability fields. All are optional, so the v6→v7 migration is a

package/dist/tmux/tmuxManager.js

@@ -1025,7 +1025,7 @@ export class TmuxManager {
     /**
      * Pin the Role window to the largest attached client. The tmux default
      * `window-size latest` lets a later-attaching smaller client (e.g. the Web
-     * terminal or a second `task enter` from a smaller pane) shrink the shared
+     * terminal or a second Role viewer from a smaller pane) shrink the shared
      * Role window, leaving the primary viewer with a TUI pinned to the top of a
      * large terminal and no scrollback. `largest` keeps the window at the
      * biggest attached client so a compact viewer cannot compress it.

package/i18n/README.zh-CN.md

@@ -435,20 +435,23 @@ Task 生命周期的交互选择只展示有效来源状态：activate 只展示
 
 ## Session 与 tmux
 
-tmux 负责 Agent 进程生命周期及其可观察输出。Global Operator 与 global Role 仍使用原生交互式 CLI；受管理的 Task Claude Run 则为每个 Run 启动一个有限生命周期进程，使用 `--print`、stream-json 输入和 stream-json 输出。Yui 通过 stdin 写入一条以换行结尾的精确 Run JSON user frame，并发排空 stdout/stderr，并通过 Claude session ID 保持原生上下文连续性。因此启动和投递不再依赖 TUI composer、ready 字符、粘贴延迟或模拟 Enter 键；Codex 保留其 adapter 原生的启动 prompt 与结构化 callback 路径。
+受管理的 Task Agent 统一使用混合 Provider Runtime：Controller 与 Agent Host 通过 Provider 原生结构化协议提交和确认输入；tmux/PTY 只负责保持 Host 存活、展示输出，以及在显式人工接管后提供输入网关。受管理输入绝不会作为终端按键、粘贴文本或启动 argv 发送。Codex 使用持久 App Server JSON-RPC 进程；Claude 使用持久 stream-json 进程，并以精确回放的 user message 作为接收确认。
 
-`task enter` 与 `task role enter` 只是附着到已存在的 Task Role pane：不会启动 Controller、准备 workspace、创建或恢复 Agent、唤醒 Role，也不会投递输入。Task attach 默认为 `--read-only`；只有显式指定 `--read-write` 才可交互，并且 Role 存在 active managed Run、受管理的 Claude 进程仍在退出，或同一 pane 已有 writer 时会被拒绝。读写 attach 会先发布 Role 级 tmux writer lease，再复核持久化 Run 状态，从而闭合与 Controller 启动之间的竞态。lease 存续期间只暂停该 Role 的受管理投递且不消耗有界投递重试；detach 会释放 lease，并且只通知已经存在的持久化 Role 工作重新评估，同一 Task 的其他 Role 不受影响。attach 前，Yui 会关闭 readline、退出 raw mode、暂停自身 stdin，再同步把终端交给 tmux。attach 会继承外层终端的真实能力并进入干净的 alternate screen；鼠标滚动只查看 Agent pane 的 100,000 行 tmux 历史，不再混入此前的 shell 或 IDE Terminal 历史。读写 attach 可以使用现有 pane 本身支持的原生交互，但它不参与受管理会话的启动或投递。
+Run、Conversation、Activation 与 Turn 是四个独立身份。Conversation 可以跨多个 Run 和进程；Activation 只代表一次 Provider 进程存活期；Turn 在写入前先持久化。写入超时或结果不明确会进入 `delivery-unknown`，不会自动重发。Provider 进程退出后结束当前 Activation；恢复同一 Conversation 会创建新 Activation 并推进 authority epoch。
 
-tmux 会在 pane 创建时固定其历史容量。配置该限制之前创建的 Role 会保留原容量；Yui 会在 Terminal attach 和 Web 中提示用户退出并重新进入一次，从而在保留 Agent 原生对话的同时创建具有 100,000 行历史的新 pane。
-
-Global 交互入口在不存在 writer 时保持可写；已有 writer 时自动降级为只读。global Web 对每个 tmux session 只允许一个 writer；Task Web 始终只读。Task CLI 入口除非显式请求 `--read-write`，否则始终只读，避免观察动作改变 Agent 执行。
+Task Role 使用以下显式入口：
 
 ```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]
+yui task role view <task-id> <role>
+yui task role takeover <task-id> <role>
+yui task role release <task-id> <role>
 ```
 
+`view` 始终只读。`takeover` 要求存在 active managed Run 且没有未决 Turn；它先以持久 CAS 把唯一 writer authority 转给人工 holder，再把相同 epoch 同步给 Agent Host，最后开放 PTY 输入网关。人工输入仍由 Host 转换为结构化 Provider Turn，而不是直接注入 Provider 终端。detach 会自动归还 authority；`release` 即使没有 active Run 也可执行，用于幂等修复中断或未完全同步的接管。Global Operator 与 global Role 继续使用原生交互式 CLI，不属于受管理 Task Provider 协议。
+
+tmux 会在 pane 创建时固定其历史容量。配置该限制之前创建的 Role 会保留原容量；Yui 会在 Terminal attach 和 Web 中提示用户退出并重新进入一次，从而创建具有 100,000 行历史的新 pane。
+
 每个 Role 可绑定多个 Agent，但任一时刻只有一个 active Agent，并为每个
 Agent binding 独立保存 native session。Operator 进一步限制为同一种
 adapter 最多绑定一个，例如可同时绑定一个 Codex 和一个 Claude；这些
@@ -460,7 +463,7 @@ binding 是预先保存、可随时切换的配置，而不是并行身份。Ope
 
 使用 `yui config role unbind <global-role> <agent-id>` 或 `yui task role unbind <task-id> <role> <agent-id>` 可移除休眠 binding。active binding 或任何未 stopped 的 native session 都会被拒绝；stopped session 记录会和 binding 在同一事务中删除。
 
-Claude 的 session ID 在启动前分配。每个受管理的 Task Claude Run 都使用新的有限生命周期进程；resume 会针对固定 native session 启动新进程，而不是复用交互式 pane。受管理的 Codex 启动使用 Codex 结构化 `notify` 回调，在 turn 完成后记录 thread ID，不再向模型对话注入 session-bind prompt。
+Claude 的 session ID 在启动前分配，并由持久 stream-json Provider 进程承载多个 Turn；Codex 使用持久 App Server thread。两者都复用同一套 Conversation、Activation、Turn 与 authority fence，不再向模型对话注入 session-bind prompt。
 
 自动生命周期与投递判断只使用结构化 Hook payload、持久身份、tmux process
 state、receipt 与 pane fence。Yui 不会解析 prompt glyph、进度文本、trust dialog

package/package.json

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