@zq-silk/yui 0.6.2 → 0.6.4

package/dist/telemetry/sqliteTelemetryStore.js

@@ -163,34 +163,6 @@ export class SqliteTelemetryStore {
     revision() {
         return this.#applied;
     }
-    latestProgressEvents(taskId) {
-        const db = this.#ensureDb();
-        if (db === null)
-            return [];
-        const rows = db.prepare(`SELECT task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at FROM (
-         SELECT *, ROW_NUMBER() OVER (
-           PARTITION BY run_id
-           ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
-         ) AS rn FROM telemetry WHERE task_id = ?
-       ) WHERE rn = 1`).all(taskId);
-        return rows.map((row) => {
-            const entry = rowToEntry(row);
-            const payload = { ...entry.payload };
-            payload.runId = entry.runId;
-            payload.progressId = entry.progressId;
-            // The semantic progress event carries progressAt = observation time;
-            // mirror that so liveness folds see the same timestamp.
-            payload.progressAt = entry.receivedAt;
-            return {
-                schemaVersion: 2,
-                id: `telemetry-progress-${entry.runId}-${entry.progressId}`,
-                taskId: entry.taskId,
-                type: "runtime.provider-turn-progress",
-                payload,
-                createdAt: entry.receivedAt
-            };
-        });
-    }
     // -- retention -----------------------------------------------------------------
     pruneGeneration(taskId, roleName, runId, generation, keep = this.#terminalKeep) {
         const db = this.#ensureDb();

package/dist/telemetry/telemetryCompaction.js

@@ -15,6 +15,7 @@ import { DEFAULT_TERMINAL_KEEP } from "./telemetryConfig.js";
  * copy only after this module validates the result; a validation failure
  * throws and leaves the original history unchanged.
  */
+/** Historical pre-Driver event type accepted only by the offline migration. */
 export const PROGRESS_EVENT_TYPE = "runtime.provider-turn-progress";
 /**
  * Scan a store and build the compaction plan. Read-only: nothing is modified.

package/dist/telemetry/telemetryConfig.js

@@ -2,10 +2,9 @@
  * Issue 09 — telemetry retention & compaction configuration.
  *
  * Telemetry lives in the Home's authoritative `yui.db` (database-only
- * direction). Its activation is an explicit per-Home switch so the feature
- * can be rolled out (legacy → dual → bounded) and rolled back independently
- * of every other Issue. Retention defaults are the schema's own constants
- * (§4.4); the environment only overrides them.
+ * direction). Its activation is an explicit per-Home diagnostic switch and
+ * never changes canonical runtime-state persistence. Retention defaults are
+ * the schema's own constants (§4.4); the environment only overrides them.
  */
 import { TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "../storage/sqliteSchema.js";
 export const DEFAULT_TELEMETRY_MODE = "legacy";
@@ -23,7 +22,7 @@ const TELEMETRY_MODES = ["legacy", "dual", "bounded"];
 /**
  * Resolve `YUI_TELEMETRY_MODE` (default `legacy`). Only the three exact
  * values (case-insensitive) are accepted; anything else fails closed at
- * startup instead of silently changing progress routing.
+ * startup instead of silently changing diagnostic retention.
  */
 export function resolveTelemetryMode(env = process.env) {
     const raw = env.YUI_TELEMETRY_MODE?.trim().toLowerCase();

package/dist/tmux/tmuxManager.js

@@ -9,6 +9,9 @@ const DEFAULT_READINESS_POLL_MS = 50;
 const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
 const DEFAULT_HISTORY_LIMIT = 100_000;
 const PANE_STATE_MARKER = "__YUI_PANE_STATE__";
+const WRITABLE_CLIENT_SESSION_PREFIX = "yui-writer-";
+const HOST_WRITABLE_CLIENT_SESSION_PREFIX = `${WRITABLE_CLIENT_SESSION_PREFIX}host-`;
+const ROLE_WRITABLE_CLIENT_SESSION_PREFIX = `${WRITABLE_CLIENT_SESSION_PREFIX}role-`;
 export class TmuxReadinessTimeoutError extends Error {
     taskId;
     roleName;
@@ -72,12 +75,13 @@ export class TmuxManager {
     }
     enterRole(taskId, role, launch) {
         this.ensureRoleWindow(taskId, role, launch);
-        this.attachRole(taskId, role.name);
+        this.attachRole(taskId, role.name, "auto");
     }
     ensureRoleWindow(taskId, role, launch) {
         if (this.windowNames(taskId).includes(role.name)) {
             this.recordRoleTarget(taskId, role.name);
             this.configureServerHistory();
+            this.configureRoleWindowSizing(taskId, role.name);
             return false;
         }
         if (launch === undefined) {
@@ -114,6 +118,7 @@ export class TmuxManager {
                 ...launchCommand(launch)
             ]);
         }
+        this.configureRoleWindowSizing(taskId, role.name);
         return true;
     }
     async ensureRoleWindowAsync(taskId, role, launch) {
@@ -121,6 +126,7 @@ export class TmuxManager {
         if (snapshot.names.includes(role.name)) {
             this.recordRoleTarget(taskId, role.name);
             await this.configureServerHistoryAsync();
+            await this.configureRoleWindowSizingAsync(taskId, role.name);
             return false;
         }
         if (launch === undefined) {
@@ -156,9 +162,13 @@ export class TmuxManager {
                 ...launchCommand(launch)
             ]);
         }
+        await this.configureRoleWindowSizingAsync(taskId, role.name);
         return true;
     }
-    attachRole(taskId, roleName) {
+    attachRole(taskId, roleName, access, options = {}) {
+        if (access !== "auto" && access !== "read-only" && access !== "read-write") {
+            throw runtimeError("Tmux attach access must be auto, read-only, or read-write.");
+        }
         let historyNotice;
         if (this.#onWarning !== undefined) {
             const history = this.inspectRoleHistory(taskId, roleName);
@@ -167,18 +177,36 @@ export class TmuxManager {
                 this.#onWarning(historyNotice);
             }
         }
-        const readOnly = this.hasWritableClient(taskId);
-        const clientSession = this.createInteractiveClientSession(taskId, historyNotice);
+        let resolvedAccess = access === "read-only"
+            ? "read-only"
+            : "read-write";
+        // Automatic entry is used by global Roles and retains one writer for the
+        // whole tmux host. Explicit Task write access is scoped to the selected
+        // Role so a human in one pane cannot pause unrelated Role launches.
+        const writerRoleName = access === "read-write" ? roleName : undefined;
+        let clientSession = this.createInteractiveClientSession(taskId, historyNotice, resolvedAccess, writerRoleName);
         try {
+            if (resolvedAccess === "read-write"
+                && this.hasWritableClient(taskId, writerRoleName, clientSession)) {
+                if (access !== "auto") {
+                    throw runtimeError(`A writable tmux client is already attached to ${taskId}; use read-only access.`);
+                }
+                this.destroyInteractiveClientSession(clientSession);
+                resolvedAccess = "read-only";
+                clientSession = this.createInteractiveClientSession(taskId, historyNotice, resolvedAccess);
+            }
+            if (resolvedAccess === "read-write")
+                options.revalidateWritableAttach?.();
             handoffTerminal(this.#terminalInput, this.#closeInteractiveInput);
             this.run([
                 "attach-session",
-                ...(readOnly ? ["-r"] : []),
+                ...(resolvedAccess === "read-only" ? ["-r"] : []),
                 "-t", `${clientSession}:${safeValue(roleName, "Role name")}`
             ], {
                 inheritStdio: true,
                 environment: { TERM: this.#terminalType }
             });
+            return resolvedAccess;
         }
         finally {
             this.destroyInteractiveClientSession(clientSession);
@@ -188,8 +216,11 @@ export class TmuxManager {
      * A grouped session shares the Agent windows while keeping the selected
      * window and terminal options local to this one human client.
      */
-    createInteractiveClientSession(taskId, attachedNotice) {
-        const clientSession = `yui-client-${randomBytes(12).toString("hex")}`;
+    createInteractiveClientSession(taskId, attachedNotice, access = "read-only", writerRoleName) {
+        const prefix = access === "read-write"
+            ? writableClientSessionPrefix(writerRoleName)
+            : "yui-client-";
+        const clientSession = `${prefix}${randomBytes(12).toString("hex")}`;
         this.run([
             "new-session", "-d",
             "-t", this.sessionName(taskId),
@@ -243,8 +274,12 @@ export class TmuxManager {
             limited: actual < this.#historyLimit
         };
     }
-    /** Multiple viewers are safe, but only the first attached human may type. */
-    hasWritableClient(taskId) {
+    /** Multiple viewers are safe, but one pane may have only one writer. */
+    hasWritableClient(taskId, roleName, excludedLease) {
+        if (this.taskSessionGroupNames(taskId).some((sessionName) => (sessionName !== excludedLease
+            && writableLeaseMatchesRole(sessionName, roleName)))) {
+            return true;
+        }
         const formatSeparator = "\u001f";
         const encodedSeparator = "\\037";
         const taskSession = this.sessionName(taskId);
@@ -254,19 +289,29 @@ export class TmuxManager {
                 "-F",
                 `#{session_name}${formatSeparator}#{session_group}${formatSeparator}#{client_readonly}`
             ]);
-            return clients.split("\n").some((line) => {
-                if (line.length === 0)
-                    return false;
-                const separator = line.includes(encodedSeparator) ? encodedSeparator : formatSeparator;
-                const [sessionName, sessionGroup, readOnly, ...extra] = line.split(separator);
-                if (sessionName === undefined
-                    || sessionGroup === undefined
-                    || readOnly === undefined
-                    || extra.length > 0) {
-                    throw runtimeError("Tmux returned an invalid client state row.");
-                }
-                return (sessionName === taskSession || sessionGroup === taskSession) && readOnly === "0";
-            });
+            return writableClientRowsContainMatch(clients, taskSession, roleName, excludedLease, formatSeparator, encodedSeparator);
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return false;
+            throw error;
+        }
+    }
+    async hasWritableClientAsync(taskId, roleName, excludedLease) {
+        if ((await this.taskSessionGroupNamesAsync(taskId)).some((sessionName) => (sessionName !== excludedLease
+            && writableLeaseMatchesRole(sessionName, roleName)))) {
+            return true;
+        }
+        const formatSeparator = "\u001f";
+        const encodedSeparator = "\\037";
+        const taskSession = this.sessionName(taskId);
+        try {
+            const clients = await this.runAsync([
+                "list-clients",
+                "-F",
+                `#{session_name}${formatSeparator}#{session_group}${formatSeparator}#{client_readonly}`
+            ]);
+            return writableClientRowsContainMatch(clients, taskSession, roleName, excludedLease, formatSeparator, encodedSeparator);
         }
         catch (error) {
             if (isExplicitlyAbsentTmuxSession(error))
@@ -928,6 +973,28 @@ export class TmuxManager {
             "set-option", "-g", "history-limit", String(this.#historyLimit)
         ]);
     }
+    /**
+     * 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
+     * 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.
+     */
+    configureRoleWindowSizing(taskId, roleName) {
+        this.run([
+            "set-option", "-w",
+            "-t", `${this.sessionName(taskId)}:${safeValue(roleName, "Role name")}`,
+            "window-size", "largest"
+        ]);
+    }
+    async configureRoleWindowSizingAsync(taskId, roleName) {
+        await this.runAsync([
+            "set-option", "-w",
+            "-t", `${this.sessionName(taskId)}:${safeValue(roleName, "Role name")}`,
+            "window-size", "largest"
+        ]);
+    }
     /** Every operation is pinned to the server derived from this YUI_HOME. */
     run(args, options) {
         const bounded = options?.inheritStdio === true
@@ -990,6 +1057,53 @@ function parseTaskSessionGroupNames(output, taskSession, formatSeparator, encode
         return sessionName === taskSession || sessionGroup === taskSession ? [sessionName] : [];
     });
 }
+function writableClientSessionPrefix(roleName) {
+    if (roleName === undefined)
+        return HOST_WRITABLE_CLIENT_SESSION_PREFIX;
+    const digest = createHash("sha256")
+        .update(safeValue(roleName, "Role name"))
+        .digest("hex")
+        .slice(0, 24);
+    return `${ROLE_WRITABLE_CLIENT_SESSION_PREFIX}${digest}-`;
+}
+function writableLeaseMatchesRole(sessionName, roleName) {
+    if (!sessionName.startsWith(WRITABLE_CLIENT_SESSION_PREFIX))
+        return false;
+    if (roleName === undefined)
+        return true;
+    if (sessionName.startsWith(HOST_WRITABLE_CLIENT_SESSION_PREFIX))
+        return true;
+    if (sessionName.startsWith(ROLE_WRITABLE_CLIENT_SESSION_PREFIX)) {
+        return sessionName.startsWith(writableClientSessionPrefix(roleName));
+    }
+    // Conservative compatibility for writer leases created before Role-scoped
+    // lease names existed.
+    return true;
+}
+function writableClientRowsContainMatch(clients, taskSession, roleName, excludedLease, formatSeparator, encodedSeparator) {
+    return clients.split("\n").some((line) => {
+        if (line.length === 0)
+            return false;
+        const separator = line.includes(encodedSeparator) ? encodedSeparator : formatSeparator;
+        const [sessionName, sessionGroup, readOnly, ...extra] = line.split(separator);
+        if (sessionName === undefined
+            || sessionGroup === undefined
+            || readOnly === undefined
+            || extra.length > 0) {
+            throw runtimeError("Tmux returned an invalid client state row.");
+        }
+        if (sessionName === excludedLease
+            || (sessionName !== taskSession && sessionGroup !== taskSession)
+            || readOnly !== "0") {
+            return false;
+        }
+        // Current Yui clients publish a lease before attach. A direct or legacy
+        // writable tmux client has no Role identity, so conservatively fence every
+        // Role in that host.
+        return !sessionName.startsWith(WRITABLE_CLIENT_SESSION_PREFIX)
+            || writableLeaseMatchesRole(sessionName, roleName);
+    });
+}
 /** A small FIFO boundary for Controller scheduler passes. */
 export class TmuxDeliveryPump {
     tmux;

package/dist/web/assets/client/view.js

@@ -320,7 +320,7 @@ export function renderTaskDetail(detail, data, t, locale, actions) {
       const card = node("article", "record-card");
       card.append(
         node("strong", "", run.roleName + " · " + run.runId),
-        node("p", "record-copy", (run.kind || "execution-stalled") + " · " + (run.classification || "truly-stalled")),
+        node("p", "record-copy", (run.kind || "workflow-not-progressing") + " · " + (run.classification || "truly-stalled")),
         node("small", "", t("detail.lastProgress") + " · " + formatDateTime(run.progressAt, locale))
       );
       runtimeHealthBody.append(card);

package/dist/web/tmuxWebTerminal.js

@@ -14,24 +14,29 @@ export class TmuxWebTerminalService {
     }
     async open(request) {
         const hostId = request.scope === "task" ? request.taskId : "operator";
-        if (request.scope === "task") {
-            await this.options.prepareTaskRole({
-                taskId: request.taskId,
-                roleName: request.roleName
-            });
-        }
-        else {
+        if (request.scope === "global") {
             await this.options.prepareGlobalRole(request.roleName);
         }
         const roleHistory = this.options.tmux.inspectRoleHistory?.(hostId, request.roleName);
-        const readOnly = this.#writers.has(hostId)
-            || this.options.tmux.hasWritableClient(hostId);
-        if (!readOnly)
-            this.#writers.add(hostId);
+        let readOnly = request.scope === "task" || this.#writers.has(hostId);
         let clientSession;
         let process;
         try {
-            clientSession = this.options.tmux.createInteractiveClientSession(hostId);
+            if (!readOnly) {
+                // Publish the same host-scoped lease used by Terminal auto-attach
+                // before deciding that this Web client may write. This closes the
+                // cross-surface gap where neither client was visible to list-clients.
+                clientSession = this.options.tmux.createInteractiveClientSession(hostId, undefined, "read-write");
+                if (this.options.tmux.hasWritableClient(hostId, undefined, clientSession)) {
+                    this.options.tmux.destroyInteractiveClientSession(clientSession);
+                    clientSession = undefined;
+                    readOnly = true;
+                }
+                else {
+                    this.#writers.add(hostId);
+                }
+            }
+            clientSession ??= this.options.tmux.createInteractiveClientSession(hostId);
             process = this.#spawnPty(this.options.tmuxBin, [
                 "-L", yuiTmuxServerName(this.options.yuiHome),
                 "attach-session",

package/dist/web/webSnapshot.js

@@ -68,7 +68,7 @@ export function buildWebTaskDetail(store, taskId) {
             runId: run.id,
             roleName: run.roleName,
             progressAt: latestStallProgress(events, run.id),
-            kind: latestStallField(events, run.id, "kind") ?? "execution-stalled",
+            kind: latestStallField(events, run.id, "kind") ?? "workflow-not-progressing",
             classification: latestStallField(events, run.id, "classification") ?? "truly-stalled"
         }));
         const activeRuns = new Map(runs

package/dist/worktree/managedWorkspace.js

@@ -1,5 +1,19 @@
 import { resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+/**
+ * Launch-stable workspace identity. Audit timestamps describe persistence
+ * activity, not a change to the workspace a runtime is authorized to use.
+ */
+export function managedWorkspaceIdentity(workspace) {
+    return {
+        owner: workspace.owner,
+        root: workspace.root,
+        entries: workspace.entries
+    };
+}
+export function sameManagedWorkspaceIdentity(left, right) {
+    return isDeepStrictEqual(managedWorkspaceIdentity(left), managedWorkspaceIdentity(right));
+}
 /** Every active Task launch is fenced by this durable owner. */
 export function isTaskOwnedWorkspace(workspace, taskId, taskRoot, bindings) {
     if (workspace === null || workspace === undefined

package/i18n/README.zh-CN.md

@@ -431,16 +431,18 @@ Task 生命周期的交互选择只展示有效来源状态：activate 只展示
 
 ## Session 与 tmux
 
-所有长时间运行的交互式 Agent 进程都由 tmux 承载。执行 `operator enter`、`role enter` 或 `task enter` 前，Yui 会关闭 readline、退出 raw mode、暂停自身 stdin，再同步把终端交给 tmux。attach 会继承外层终端的真实能力并进入干净的 alternate screen；鼠标滚动只查看 Agent pane 的 100,000 行 tmux 历史，不再混入 attach 之前的 shell 或 IDE Terminal 历史。因此 Agent 原生的 `/model`、斜杠命令提示、全屏渲染和按键处理都可正常工作。
+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 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 本身支持的原生交互，但它不参与受管理会话的启动或投递。
 
 tmux 会在 pane 创建时固定其历史容量。配置该限制之前创建的 Role 会保留原容量；Yui 会在 Terminal attach 和 Web 中提示用户退出并重新进入一次，从而在保留 Agent 原生对话的同时创建具有 100,000 行历史的新 pane。
 
-同一个 Operator 或 Task tmux session 中，第一个 Terminal/Web 客户端可写，后续查看者自动只读，避免多个入口同时向同一个 Agent 输入。
+Global 交互入口在不存在 writer 时保持可写；已有 writer 时自动降级为只读。global Web 对每个 tmux session 只允许一个 writer；Task Web 始终只读。Task CLI 入口除非显式请求 `--read-write`，否则始终只读，避免观察动作改变 Agent 执行。
 
 ```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]
 ```
 
 每个 Role 可绑定多个 Agent，但任一时刻只有一个 active Agent，并为每个
@@ -454,7 +456,7 @@ binding 是预先保存、可随时切换的配置，而不是并行身份。Ope
 
 使用 `yui 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 在启动前分配。受管理的 Codex 启动使用 Codex 结构化 `notify` 回调，在 turn 完成后记录 thread ID，不再向模型对话注入 session-bind prompt。
+Claude 的 session ID 在启动前分配。每个受管理的 Task Claude Run 都使用新的有限生命周期进程；resume 会针对固定 native session 启动新进程，而不是复用交互式 pane。受管理的 Codex 启动使用 Codex 结构化 `notify` 回调，在 turn 完成后记录 thread ID，不再向模型对话注入 session-bind prompt。
 
 自动生命周期与投递判断只使用结构化 Hook payload、持久身份、tmux process
 state、receipt 与 pane fence。Yui 不会解析 prompt glyph、进度文本、trust dialog
@@ -532,8 +534,6 @@ Agent 环境变量绑定只保存进程环境变量名，不保存 secret 值；
 Yui 面向一台机器上的一个受信任本地用户。它的 Web/API 仅支持 loopback，不包含远程或多用户 Web、分布式协调、backup/import/export、trash/restore、derived index、recovery journal、runtime lease、inactivity TTL、cooldown 或 recurring schedule。
 
 持久化和调度细节见 [ARCHITECTURE.md](../ARCHITECTURE.md)。
-可复用的用户视角验收方案见
-[Operator 路由与长期任务端到端测试方案](../docs/testing/operator-routing-e2e-plan.md)。
 
 ## 本地开发
 
@@ -544,6 +544,11 @@ npm test
 npm run lint
 ```
 
+`npm test` 只保留秒级核心 smoke：CLI 启动、正常 SQLite Task、受支持迁移和内置
+Agent Driver。针对当前修改编写的 TDD、异常数据和故障复现仅作为开发期证据，需求完成后
+删除，不累积为常驻回归测试。具体约束见
+[验证策略](../docs/testing/verification-levels.md)。
+
 如需让用户终端使用当前 checkout，可逆地接管用户级 `yui` 命令：
 
 ```sh

package/package.json

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