@zq-silk/yui 0.15.9 → 0.15.11

package/dist/web/webTaskSurface.js

@@ -1,14 +1,53 @@
+import { recordTaskInterruptResult } from "../message/taskInterrupt.js";
+import { recordGlobalInterruptResult, recordGlobalSteerResult } from "../message/globalInterrupt.js";
+import { runGlobalRoleCommand } from "../commands/globalRoleCommands.js";
 import { readTaskContext, readTaskContextDelta, inspectTaskContext, withContextObservations } from "../context/taskContext.js";
 import { BUILTIN_CAPABILITIES } from "../kernel/builtinCapabilities.js";
 import { capabilitySchemaError } from "../kernel/capabilitySchema.js";
-import { updateTaskMetadataCommand, sendTaskMessageCommand } from "../commands/taskCommands.js";
+import { updateTaskMetadataCommand, sendTaskMessageCommand, runTaskCommand } from "../commands/taskCommands.js";
 import { webLocalMutation, WebRequestRejected } from "./webMutation.js";
 import { runTaskInputCommand } from "../commands/taskInputCommands.js";
+import { sendAgentHostSteerControl, sendAgentHostCancelControl, AGENT_HOST_CONTROL_PROTOCOL, foldSteerLiveReceipt, foldInterruptLiveReceipt } from "../runtime/agentHost.js";
+const DEFAULT_WEB_HOST_CONTROL = {
+    steer: sendAgentHostSteerControl,
+    cancel: sendAgentHostCancelControl
+};
+/** The store-only CLI argv for the shared application-layer primitive
+ * (decision-3 §7). The Web surface never re-implements the queue/steer/interrupt
+ * decisions; it drives the exact same command the CLI drives. */
+function controlArgv(taskId, input) {
+    if (input.action === "queue") {
+        return ["message", "queue", taskId, input.body, "--request-id", input.requestId,
+            ...(input.to === undefined ? [] : ["--to", input.to]),
+            ...(input.workItem === undefined ? [] : ["--work-item", input.workItem]),
+            ...(input.reviewRound === undefined ? [] : ["--review-round", input.reviewRound])];
+    }
+    if (input.action === "steer") {
+        return ["message", "steer", taskId, input.body, "--request-id", input.requestId,
+            "--expected-target", input.expectedTarget, "--to", input.to,
+            ...(input.workItem === undefined ? [] : ["--work-item", input.workItem]),
+            ...(input.reviewRound === undefined ? [] : ["--review-round", input.reviewRound])];
+    }
+    return ["role", "interrupt", taskId, input.role, "--expected-target", input.expectedTarget,
+        ...(input.thenMessage === undefined ? [] : ["--then-message", input.thenMessage]),
+        "--request-id", input.requestId];
+}
+/** A queue is delivered to the Leader mailbox only when it is unaddressed or
+ * addressed to the Leader; an addressed Worker/Reviewer queue goes to the Task
+ * mailbox. A steer/interrupt is a live control op, so it only reconciles the
+ * Task. This mirrors the mailbox the core command itself enqueues. */
+function controlNotifiesLeader(input) {
+    return input.action === "queue" && (input.to === undefined || input.to === "leader");
+}
+function controlTarget(taskId, input) {
+    const roleName = input.action === "interrupt" ? input.role : input.to ?? "leader";
+    return { scope: "task", taskId, roleName };
+}
 /** Installed only by the local-user Web composition root. HTTP authenticates
  * its token before using this port; input never supplies a caller or Role.
  * Managed capability RPC keeps its own Session authentication unchanged.
  */
-export function createWebTaskSurface(store, options = {}, observations = []) {
+export function createWebTaskSurface(store, options = {}, observations = [], hostControl = DEFAULT_WEB_HOST_CONTROL) {
     const environment = {};
     const commandOptions = { ...options, environment, runtime: undefined };
     // Notifications are after the outer transaction. Their failure must not be
@@ -22,10 +61,83 @@ export function createWebTaskSurface(store, options = {}, observations = []) {
             options.runtime?.notifyStateChanged(taskId);
     };
     return {
+        globalState: (roleName) => {
+            const role = store.getGlobalRole(roleName);
+            if (role === null)
+                throw new WebRequestRejected("Global Role not found.");
+            const sessions = store.getGlobalRoleSessionSet(roleName);
+            return {
+                roleName,
+                nativeSessionId: sessions?.sessions[sessions.activeAgentId]?.nativeSessionId,
+                turn: sessions?.providerBinding?.run ?? null,
+                authority: sessions?.providerBinding?.authority ?? null,
+                interrupts: sessions?.interrupts ?? {},
+                messages: store.listGlobalRoleMessages(roleName).map(message => ({
+                    id: message.id, body: message.body, inputControl: message.inputControl,
+                    control: message.control, delivery: message.delivery, notDelivered: message.notDelivered
+                }))
+            };
+        },
+        globalControl: async (roleName, input) => {
+            const argv = input.action === "interrupt"
+                ? ["interrupt", roleName, "--request-id", input.requestId, "--expected-target", input.expectedTarget,
+                    ...(input.thenMessage === undefined ? [] : ["--then-message", input.thenMessage])]
+                : ["message", input.action, roleName, input.body, "--request-id", input.requestId,
+                    ...(input.action === "steer" ? ["--expected-target", input.expectedTarget] : [])];
+            const result = webLocalMutation(store, tx => runGlobalRoleCommand(argv, tx, {
+                env: {}, yuiHome: options.yuiHome, jsonOutput: true
+            }));
+            if (typeof result === "string") {
+                if (input.action === "queue")
+                    void options.runtime?.notifyMailboxChanged?.({
+                        kind: "global-role-runtime", roleName
+                    });
+                return { action: input.action, ...JSON.parse(result) };
+            }
+            if (result.kind !== "input-steer" && result.kind !== "input-interrupt") {
+                throw new WebRequestRejected("Global input cannot perform a Session lifecycle operation.");
+            }
+            if (options.yuiHome === undefined)
+                throw new Error("Global control requires a configured Yui Home.");
+            if (result.kind === "input-steer") {
+                let control;
+                try {
+                    control = await hostControl.steer({
+                        home: options.yuiHome, scope: "global", roleName,
+                        control: { protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "steer-turn",
+                            nativeSessionId: result.target.nativeSessionId, nativeTurnId: result.target.nativeTurnId,
+                            authority: result.target.authority,
+                            run: { attemptId: result.receiptId, boundedText: result.text } }
+                    });
+                }
+                catch (error) {
+                    recordGlobalSteerResult(store, roleName, result.messageId, { state: "steer-unknown", outcome: "pending" });
+                    throw error;
+                }
+                const steer = foldSteerLiveReceipt(control);
+                recordGlobalSteerResult(store, roleName, result.messageId, steer);
+                return { action: "steer", roleName, messageId: result.messageId, steer };
+            }
+            let control;
+            try {
+                control = await hostControl.cancel({
+                    home: options.yuiHome, scope: "global", roleName,
+                    control: { protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "cancel", nativeOnly: true,
+                        nativeSessionId: result.target.nativeSessionId,
+                        authority: result.target.authority, attemptId: result.target.attemptId }
+                });
+            }
+            catch (error) {
+                recordGlobalInterruptResult(store, roleName, result.receiptId, { state: "interrupt-unknown", outcome: "cancel-requested" });
+                throw error;
+            }
+            const interrupt = foldInterruptLiveReceipt(control);
+            recordGlobalInterruptResult(store, roleName, result.receiptId, interrupt);
+            return { action: "interrupt", roleName, receiptId: result.receiptId, interrupt };
+        },
         message: (taskId, body, intent, requestId) => {
-            // With no explicit intent the Web surface submits `discuss` like every other
-            // client (§2.5), through the one shared service; the requestId is threaded as
-            // the submission key (§2.3) and the structured feedback is returned verbatim.
+            // Preserve the submission's intent and frozen receipt separately from
+            // queue/steer controls; an omitted intent still means discuss.
             const { message, task, queuedForLeader, feedback } = webLocalMutation(store, (tx) => sendTaskMessageCommand(tx, taskId, body, undefined, commandOptions, undefined, intent, requestId));
             notify(taskId, queuedForLeader);
             return { record: message, revision: message.createdAt,
@@ -34,6 +146,111 @@ export function createWebTaskSurface(store, options = {}, observations = []) {
                 ...(feedback === undefined ? {} : { submission: feedback }),
                 target: { scope: "task", taskId, roleName: "leader" } };
         },
+        /**
+         * The decision-3 three-action input-control path for the local-user Web
+         * surface. Its store-only phase is the identical shared application-layer
+         * primitive the CLI uses (`runTaskCommand`), run inside `webLocalMutation`
+         * so a rejected input is provably not-submitted. A ready steer/interrupt
+         * returns a live intent; the single Agent Host edge then runs OUTSIDE the
+         * transaction exactly as cli.ts performs it — never a fallback, retarget, or
+         * fourth action. A committed input whose live edge fails is delivery-unknown,
+         * not not-submitted: it throws a plain error so the receipt is "unknown" and
+         * the durable Message is retained (decision-3 §1/§3/§5, message-5 gap F).
+         */
+        control: async (taskId, input) => {
+            const execution = webLocalMutation(store, (tx) => runTaskCommand(controlArgv(taskId, input), tx, commandOptions));
+            if (execution.kind === "output") {
+                // A queue receipt, or a steer/interrupt that was saved-but-not-delivered
+                // or an idempotent replay: fully durable, no live edge, exact disposition.
+                notify(taskId, controlNotifiesLeader(input));
+                const data = execution.data;
+                const settlement = data.delivery ?? data.steer ?? data.interrupt;
+                return {
+                    action: input.action, disposition: settlement?.state ?? "saved",
+                    target: controlTarget(taskId, input),
+                    ...(data.message === undefined ? {} : { record: data.message, revision: data.message.createdAt }),
+                    ...(data.delivery === undefined ? {} : { delivery: data.delivery }),
+                    ...(data.steer === undefined ? {} : { steer: data.steer }),
+                    ...(data.interrupt === undefined ? {} : { interrupt: data.interrupt })
+                };
+            }
+            // A resolved live control op. Core has persisted the Message (steer) and
+            // recorded the one `pending` control attempt; both are already committed.
+            const home = options.yuiHome;
+            if (home === undefined) {
+                throw new Error("Live Agent Host control requires a configured Yui home.");
+            }
+            if (execution.kind === "input-steer") {
+                let control;
+                try {
+                    control = await hostControl.steer({
+                        home, scope: "task", taskId: execution.taskId, roleName: execution.roleName,
+                        control: {
+                            protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "steer-turn",
+                            nativeSessionId: execution.target.nativeSessionId,
+                            nativeTurnId: execution.target.nativeTurnId ?? execution.target.attemptId,
+                            authority: execution.target.authority,
+                            run: { attemptId: execution.receiptId, boundedText: execution.text }
+                        }
+                    });
+                }
+                catch (error) {
+                    throw new Error(`Steer message ${execution.messageId} is saved but the native steer did not `
+                        + `complete: ${error instanceof Error ? error.message : String(error)}. The Message is `
+                        + "retained and its outcome is recorded from the Host; whether the Provider accepted it may "
+                        + "be delivery-unknown. Re-read the Session before acting; do not reissue the same input "
+                        + "under a new requestId or a different action.");
+                }
+                notify(taskId);
+                // decision-3 §7 live acceptance: fold the actual Host outcome rather than
+                // presume success. `steered` is the only proven delivery; pending is
+                // delivery-unknown; rejected/unavailable did not deliver. No fallback.
+                const steer = foldSteerLiveReceipt(control);
+                return { action: "steer", disposition: steer.state,
+                    taskId, roleName: execution.roleName, messageId: execution.messageId,
+                    target: { scope: "task", taskId, roleName: execution.roleName },
+                    steer };
+            }
+            let control;
+            if (execution.kind !== "input-interrupt") {
+                // The three-action argv only ever yields output/input-steer/input-interrupt;
+                // any other intent means the shared command was mis-dispatched, not a
+                // control outcome to fold. Fail closed rather than guess.
+                throw new Error(`Unexpected control execution kind: ${execution.kind}.`);
+            }
+            try {
+                control = await hostControl.cancel({
+                    home, scope: "task", taskId: execution.taskId, roleName: execution.roleName,
+                    control: {
+                        protocol: AGENT_HOST_CONTROL_PROTOCOL, type: "cancel",
+                        nativeOnly: true,
+                        nativeSessionId: execution.target.nativeSessionId,
+                        // Native cancel names the exact original execution attempt it stops,
+                        // never the durable receiptId of this interrupt operation.
+                        attemptId: execution.target.attemptId,
+                        authority: execution.target.authority
+                    }
+                });
+            }
+            catch (error) {
+                recordTaskInterruptResult(store, execution.taskId, execution.receiptId, { state: "interrupt-unknown", outcome: "cancel-requested" });
+                throw new Error(`Interrupt ${execution.receiptId} of ${execution.taskId}/${execution.roleName} did not complete: `
+                    + `${error instanceof Error ? error.message : String(error)}. No process was killed; `
+                    + "re-read the Session before retrying.");
+            }
+            notify(taskId);
+            // The proof is `control.cancellation`, not the bare `cancel-requested`
+            // outcome: only a proven stop-request is `interrupted`. A then-handoff, if
+            // any, was already claimed durably by Core and is delivered once by the
+            // ordinary continuation path — never re-driven from this receipt.
+            const interrupt = foldInterruptLiveReceipt(control);
+            recordTaskInterruptResult(store, execution.taskId, execution.receiptId, interrupt);
+            return { action: "interrupt", disposition: interrupt.state,
+                taskId, roleName: execution.roleName,
+                target: { scope: "task", taskId, roleName: execution.roleName },
+                ...(execution.thenMessageId === undefined ? {} : { thenMessageId: execution.thenMessageId }),
+                interrupt };
+        },
         read: async (taskId) => withContextObservations(readTaskContext(store, taskId, environment), observations),
         delta: (taskId, input) => readTaskContextDelta(store, taskId, input, environment),
         inspect: (taskId, input) => inspectTaskContext(store, taskId, input, environment),

package/dist/workspace/workItemChangeSetManager.js

@@ -1,4 +1,5 @@
 import { isDeepStrictEqual } from "node:util";
+import { lstat } from "node:fs/promises";
 import { createWorkItemChangeSet } from "../integration/changeSet.js";
 import { createChangeSetManifest } from "../integration/changeSetManifest.js";
 import { deriveManifestTags } from "../integration/manifestTags.js";
@@ -60,11 +61,25 @@ export class WorkItemChangeSetManager {
         const git = new NodeGitWorkspace();
         const projects = [];
         for (const entry of writableEntries(workspace)) {
-            if (!await git.isClean(entry.path)) {
+            const path = await lstat(entry.path).catch(error => {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            });
+            if (path?.isSymbolicLink())
+                throw new Error(`WorkItem path is a symbolic link: ${entry.path}.`);
+            if (path !== null && !await git.isClean(entry.path)) {
                 throw new Error(`WorkItem Project workspace is not clean: ${item.id}/${entry.projectId}.`);
             }
-            const workspaceHeadCommit = (await git.inspect(entry.path, "HEAD")).baseCommit;
             const resultCommit = candidate?.gitSnapshot?.projects.find(({ projectId }) => projectId === entry.projectId)?.commit;
+            // Absence is a filesystem fact, not proof of integration or Git cleanup.
+            // Check any retained branch against the same frozen Candidate; the
+            // cleanup primitive separately removes its exact Git registration.
+            const repository = this.store.getTaskWorkspace(taskId)?.entries.find(e => e.projectId === entry.projectId);
+            const workspaceHeadCommit = path !== null ? (await git.inspect(entry.path, "HEAD")).baseCommit
+                : repository !== undefined && await git.refExists(repository.path, entry.branch)
+                    ? (await git.inspect(repository.path, entry.branch)).baseCommit
+                    : resultCommit;
             if (candidate?.workspace === undefined
                 || !isDeepStrictEqual(candidate.workspace, workspace)
                 || resultCommit === undefined
@@ -109,6 +124,7 @@ export class WorkItemChangeSetManager {
         }
         const unresolved = this.store.listIntegrationAttempts(task.id).find((attempt) => (attempt.status === "running"
             || attempt.status === "blocked"
+            || attempt.status === "conflicted"
             || attempt.status === "validating"));
         if (unresolved !== undefined) {
             throw new Error(`Task has an unresolved Integration Attempt: ${task.id}/${unresolved.id}.`);

package/docs/release-workflow.md

@@ -74,6 +74,45 @@ Candidate and Task-final ReviewRound records must all carry that one contract.
 Conflicting records fail closed; there is no rebind event, recovery command, or
 second contract state machine.
 
+## Persistent Agent Host compatibility
+
+A running Host keeps its original Endpoint implementation. It records exact
+Session/attempt/native-Turn facts in the existing durable Inbox before contacting
+the Controller; only the current Controller resolves Run ownership, validates
+authority/workspace/lifecycle/history, and commits the result. An Inbox file is
+not acceptance. Files are consumed only after commit, so downtime or a lost ACK
+does not replay user input or model work.
+
+Startup facts use the exact Run identity from the redeemed launch payload, not
+the long-lived Session environment. This preserves pre-adoption evidence even
+when the frozen Run workspace differs from the Role's default; later activity
+and terminal facts still resolve solely by their own native input identities.
+
+The supported Host boundary is control `yui-agent-host/v5`, event source
+`yui-agent-host-events/v1`, and Controller RPC version 4. Hosts advertising
+`storage=controller-owned` do not open the Home database, including for process
+custody, native account locations, or execution-environment checks. Home 22
+declares the additive Inbox source envelope; valid older Inbox v1 facts and
+domain history remain readable. Future changes must retain this wire boundary
+or reject incompatible live producers before changing storage. CLI wrapper
+refresh and a successful new `doctor` are not Host compatibility proofs.
+
+`upgrade`, the staged target's `update` preflight, and release activation inspect
+live Host capabilities independently. An old Host without this capability,
+including an idle Host or one whose response is unconfirmed, blocks adoption.
+Checks are repeated at the existing fenced/quiesced handover boundary before
+migration or promotion. No Host is killed, replaced, or reloaded by these checks.
+Let existing work settle and preserve original pending input/result evidence;
+then an authorized Operator can select a safe Session replacement/cleanup before
+retrying. Installing this change cannot repair already-loaded legacy Host code
+or collect a terminal that that code never durably emitted.
+
+`task role status`, `task role list`, and `task role session inspect` expose Host
+reporting alongside durable Run state. Pending native results or known reporting
+failures require attention; they do not mean the Provider failed, the Run ended,
+or the work was accepted. The Host's live diagnostics inspect only its own event
+file identities and never parse or quarantine another producer's newer payload.
+
 ## CLI and Controller release boundary
 
 The global `yui` command is the stable user and managed-Session interface. It

package/docs/release-workflow.zh-CN.md

@@ -59,6 +59,35 @@ Session 使用普通的 `yui` 命令，兼容性由协议和存储身份检查
 Task-final 的 ReviewRound 记录必须全部携带那唯一的合同。冲突的记录 fail closed；
 不存在重新绑定事件、恢复命令或第二套合同状态机。
 
+## 常驻 Agent Host 升级兼容
+
+存活 Host 保持原 Endpoint 实现，先把准确的 Session/attempt/nativeTurn 事实写入现有
+持久 Inbox，再联系 Controller。只有当前 Controller 解析 Run 归属、校验权限、工作区、
+生命周期与历史关联并提交结果。Inbox 文件不代表接受；提交后才确认消费，断线或丢失
+ACK 不会重放用户输入或模型工作。
+
+启动事实从已兑现的 launch payload 取得准确 Run 身份，不把 Run 固定到长期 Session
+环境。即使冻结的 Run 工作区不同于 Role 默认值，登记前的证据也能保留；后续活动和
+终态仍只按各自的原生输入身份解析归属。
+
+支持边界为控制协议 `yui-agent-host/v5`、事件来源协议 `yui-agent-host-events/v1`、
+Controller RPC 版本 4。声明 `storage=controller-owned` 的 Host 不打开 Home 数据库，
+包括进程归属、原生账号位置和执行环境校验。Home 22 声明 Inbox 的新增来源字段，
+不改写有效历史事实与业务记录。后续版本要么保留该线协议，要么在修改存储前拒绝不兼容
+的存活生产者。刷新 Session CLI wrapper 或新 `doctor` 成功都不能证明旧 Host 兼容。
+
+`upgrade`、`update` 的目标版本预检及 release activation 独立检查存活 Host。
+没有此能力的 legacy Host（包括 idle）以及兼容响应不确定的 Host 都阻止采用；
+在既有隔离/静默交接边界再次检查，先于迁移或发布切换。检查不会 kill、替换或 reload
+Host。先让原有工作结束并保留原始未决输入/结果证据，再由获授权的 Operator 在安全
+边界选择 Session 替换或清理，之后重试。安装新代码不能修改已加载的 legacy Host 内存，
+也不能回收它从未持久投递过的终态。
+
+`task role status`、`task role list` 和 `task role session inspect` 在持久 Run 状态旁
+显示 Host 上报观测。原生结果待落库或已知上报故障需要关注，但不代表 Provider 失败、
+Run 已结束或业务已验收。Host 诊断只检查自己已投递文件的身份是否存在，不解析或隔离
+其他生产者的新格式事件。
+
 ## CLI 与 Controller 发布边界
 
 全局 `yui` 命令是稳定的用户与受管 Session 接口。对普通命令，它不跟随

package/docs/sqlite-control-plane-design.md

@@ -69,10 +69,232 @@ Every persistent schema or payload change appends one immutable, contiguous
 storage migration. The CLI publishes both `storageVersion` and
 `minimumStorageVersion`; every valid Home in that inclusive range can upgrade
 directly to the current version without installing intermediate releases.
-The current source declares storage version **18**, with minimum supported
+The current source declares storage version **25**, with minimum supported
 migration version **1**, in `src/storage/storageVersions.ts`. Homes below that
 floor are not migration inputs and remain untouched.
 The target binary's `upgrade --update-preflight` and `--update-apply` result
 shapes and parent-owned handover-lock proof remain backward compatible with
 every updater released from storage version 1 onward, so an old source CLI can
 still drive a much newer target's complete migration chain.
+
+## Unified Home layout
+
+Every Yui self-managed directory lives under the single canonical `YUI_HOME`
+(default `~/.yui`; an explicit `YUI_HOME` is honoured verbatim). `YUI_HOME` is
+never inferred from the current working directory and never substituted with a
+username. `src/storage/homeLayout.ts` is the one authority that derives each
+managed root from Home:
+
+| Root | Path | Holds |
+|---|---|---|
+| Managed worktrees | `<home>/workspaces/tasks/<taskId>/<owner>/<projectDirectory>` | Actual Task/WorkItem/Review/Integration Git directories, addressed by the bound Project directory. Owners are `main`, `work-items/<id>`, `reviews/<id>`, `integrations/<id>` and `execution-lanes/<group>/<lane>`. |
+| Read-only context views | Within the same owner directory | Regenerable symlinks to read-only Project context only; writable entries are actual Git directories, not links. |
+| Global Role workspace | `<home>/workspaces/global` | Default cwd for Yui-auto-created Global Roles (the `yui setup` Operator/Leader and ad-hoc Global Roles added without an explicit `--workspace`). A plain cwd, not a managed Git workspace. |
+| Task provider runtimes | `<home>/runtime/task-runtimes` | Task provider data/cache/tmp; also the planning cwd at `…/planning/<taskId>`. |
+| Integration runtimes | `<home>/runtime/integration-runtimes` | The integration check's provider data/cache/tmp (a separate partition from Task runtimes). |
+| Update staging | `<home>/runtime/update-staging` | `yui update`'s side-by-side package install (an upgrade artifact). |
+| Release workflow scratch | `<home>/runtime/release-workflow` | The release workflow's smoke-install dir and verified publish-snapshot tarball (release artifacts). |
+| Storage backups | `<home>/backups` | Pre-upgrade DB backups (the fenced upgrade's rollback anchor). |
+
+Published migrations 1–23 remain unchanged, including Task artifacts in local
+Git (19), Integration continuation (20), force-archive evidence (21), and
+Controller-owned Host ingress (22), and unified message input control (23).
+The two offline layout steps are now 23→24 (`unify-home-layout`) and
+24→25 (`collapse-worktree-layout`). Version 24's
+`workspaces/worktree` directory is an intermediate layout, not a second live
+root at version 25. A single upgrade applies the full pending chain.
+
+Stop this Home's writers and take a backup before upgrading. The layout steps
+copy and verify the registered Git trees, repair only the copies' links, and
+preserve old sources for manual recovery. Version 25 replaces registered
+Task-view symlinks with real writable directories; unrelated Task scratch is
+retained. Read-only context remains a view and can be promoted to a writable
+worktree when WorkItem scope expands. Do not delete the old sources until the
+new layout is verified; a failed upgrade requires manual residue cleanup and
+backup recovery, not automatic resume.
+
+Both runtime partitions (`runtime/task-runtimes`, `runtime/integration-runtimes`)
+are the ONLY Home subtrees a provider runtime root is allowed to overlap; a
+runtime root overlapping any other part of Home (the database, `workspaces/`,
+`projects/`) is still rejected by `assertTaskRuntimeIsolationPreflight`, so
+unifying the root does not weaken control-data or cross-owner isolation.
+
+`defaultWorkspace` is a user-facing cwd for external Project input only; it is
+**not** a second authority for internal managed paths, and is intentionally not
+an input to `homeLayout.ts`. A Yui-auto-created Global Role that carries no
+user-chosen cwd no longer falls back to it (or to `process.cwd()`): `yui setup`'s
+built-in Operator/Leader and `yui role add` without `--workspace` now default to
+the Home-internal `managedGlobalRoleWorkspace(home)` (`<home>/workspaces/global`),
+and `setup` no longer fabricates an external Home-sibling `workspace/` — a
+`default-workspace` is persisted only if the user configured one. A user who
+*names* an external directory (explicit `--workspace`, or a configured
+`default-workspace`) keeps external-resource semantics; the outside-Home guard
+still applies to it. The "planning/global cwd" that criterion 1 places under Home
+is thus both the *disposable runtime cwd Yui materializes itself* — the Draft
+planning cwd (`planningRuntimeCwd`, under `runtime/task-runtimes/planning`) — and
+the auto-created Global Role cwd above; only an operator's *explicitly named*
+external directory stays outside by design.
+
+Only genuine short-path IPC socket ENDPOINTS remain outside Home, and only
+because a Unix-domain `sockaddr_un` path has a small fixed length budget that a
+deep Home path would exceed. Each is a single socket path, never a data/cache/tmp
+root:
+
+- the Controller socket (`/tmp/yui-<uid>/<homeId>.sock`),
+- the tmux server socket (`/tmp/tmux-<uid>` via the tmux namespace),
+- the Agent Host socket (`/tmp/yui-<uid>/agent-host/…sock`), and
+- the integration check's tmux socket dir (`/tmp/yi-<uid>-<digest>`), bound only
+  into `TMUX_TMPDIR`.
+
+The integration check's ordinary runtime state is **not** an exception: its
+provider data, cache, and temp roots live in the Home partition above
+(`runtime/integration-runtimes`); `TMPDIR`/`TMP`/`TEMP` point there, and only
+`TMUX_TMPDIR` is redirected to the short `/tmp` socket dir.
+
+## Migration 23 → 24: unify managed paths under Home
+
+Historically the managed worktrees lived under the out-of-Home
+`defaultWorkspace` (`<ws>/worktree`, `<ws>/tasks`) and the provider runtimes
+under a string-built Home sibling (`<home>.task-runtimes`). The one forward
+migration `unify-home-layout` (`src/storage/migrations/unifyHomeLayout.ts`)
+brings that content under Home and rewrites the persisted absolute pointers the
+runtime dereferences as live, without re-cloning Git content or renaming the
+path-independent Git refs. It runs as the migration's `migrateData` step inside
+the upgrade transaction, so schema and data advance atomically or roll back
+together.
+
+**Exactly one tree is physically relocated: the managed Git worktree tree.** It
+is the sole subtree that holds durable, non-regenerable content (committed **and**
+uncommitted work), so it alone is copied on disk. Everything else that "moves"
+moves only by pointer:
+
+- the per-Task symlink views (`<ws>/tasks`) are regenerable — the pointer is
+  rewritten and `ensureWorkspaceView` rebuilds the links at the next launch;
+- the provider runtimes (`<home>.task-runtimes`) are disposable — the pointer is
+  rewritten and the roots are recreated at the next launch.
+
+The worktree copy is **non-destructive and verified** (see *Recovery and
+rollback*): the source is copied (never renamed away), the replica's content
+digest is checked against the source, and only a verified replica is atomically
+published. The original worktree tree is **preserved** as the rollback anchor;
+removing it is a later, authorized, post-restart cleanup step, never part of this
+transaction.
+
+The pointer rewrite is **surgical, not a table sweep** — only records the runtime
+treats as live launch pointers are touched:
+
+- `managed_workspaces` — the authoritative registry (`path` column, payload
+  `root`, every `entries[].path`). Every surviving row is live (dispositioned
+  rows are deleted at cleanup).
+- active (`status='active'`) `turns` — **both** `run.effective.workspace` (the
+  actual OS launch cwd source) and the `run.workspace` mirror, rewritten together
+  because `validateRun` requires them to stay identical; a run's
+  `.result.systemEvidence.workspaceSnapshot` is frozen Git evidence and is left
+  byte-for-byte intact.
+- `role_session_sets` / `global_role_session_sets` — each live session's
+  `effective.workspace` in the `sessions` map; terminal sessions in `history` are
+  preserved.
+- `review_rounds` — the mirrored workspace (only while its `managed_workspaces`
+  owner row still exists) and each OPEN execution lane; an orphaned mirror or a
+  terminal lane is frozen evidence and is preserved.
+- `work_items` — each OPEN execution lane inside `executionGroups`; candidate
+  snapshots (`work_item_candidates`) are frozen and preserved.
+- `task_roles.workspace` — the live launch cwd, including a Draft's planning Role
+  under the old runtime sibling (never self-healed until activation).
+- `task_records.cwd` — self-heals on the next `prepareTaskWorkspace`, but is
+  rewritten defensively to close the stale-read window.
+
+Everything else is preserved on purpose: `context_snapshots`, terminal `turns`
+(with their system evidence), terminal sessions, `work_item_candidates`, terminal
+execution lanes, terminal `durable_jobs`, `events`, and reports are frozen
+history. `resource_registry` is re-discovered from disk; `projects.path` is an
+external, user-owned checkout.
+
+The migration is applied **offline** and is **fail-closed and pre-checkable**.
+It is run by the standalone `yui upgrade` boundary AFTER the operator has stopped
+this Home's Controller, Agent Host, and any execution/Job writers; it does not
+orchestrate that shutdown, coordinate an online write-stop, or migrate a live
+Session. It keeps only the minimal preconditions it can implement directly:
+
+- It **refuses** if a queued or running `durable_jobs` step is bound to a tree
+  about to relocate. A durable Job's runner is detached and could outlive an
+  incompletely stopped Controller, so moving that tree would risk an in-flight
+  silent move; this is the one residual runtime signal the offline migration
+  still guards. Let the Job drain or cancel it, then re-run the upgrade.
+  (`active_turns` is steady state, not an in-flight signal, and is deliberately
+  not consulted.)
+- It **refuses** if a relocation target already exists at all — it is either a
+  foreign directory or residue from a failed prior run, and the offline migration
+  never adopts a pre-existing target. Confirm the source is intact, then move or
+  remove the target and re-run the upgrade.
+- Every refusal is surfaced as a **collected, read-only pre-check**: `yui
+  upgrade --dry-run` and the updater's `--update-preflight` run the same plan and
+  the same blocking conditions execute would throw on, opening the DB read-only
+  and reporting each independent blocker as `{reason, detail}` (blocked outcome)
+  without mutating the Home — a genuine pre-check, not a best-effort guess.
+- A Home already in the unified layout (or a fresh Home with nothing to relocate)
+  is a **no-op**.
+
+### Recovery and rollback
+
+The migration keeps **no recovery manifest and no resumable state machine** — it
+is a one-time offline transform, not an interruptible online orchestration. The
+worktree relocation is **copy → digest-verify → atomic-publish → preserve-source**:
+
+1. the relocation target must not already exist; a pre-existing target is refused
+   up front (foreign directory or failed-run residue — never adopted);
+2. the source is copied into a same-filesystem staging dir (`<to>.incoming`),
+   never renamed away;
+3. a content-addressed inventory digest of the replica is compared to the source
+   — a mismatch deletes the staging copy and aborts (nothing published, source
+   intact);
+4. only a verified replica is `rename`d into the final target (atomic on one
+   filesystem);
+5. the original source tree is left in place as the rollback anchor.
+
+There is **no automatic idempotent recovery**. Because a pre-existing target is
+always refused, a run interrupted after a partial publish does not silently
+resume or adopt the partial tree on the next attempt: the operator inspects the
+preserved source, removes the incomplete target (and any `<to>.incoming`
+staging), and re-runs the upgrade from a clean state. The `--dry-run` /
+`--update-preflight` pre-check surfaces exactly this `target-conflict` before the
+apply transaction is entered, so the residue is reported, not discovered
+mid-migration.
+
+After the copy, the worktrees are reconnected. `git worktree repair` chases the
+absolute pointer files inside a worktree, so running it on a verbatim copy whose
+pointers still address the OLD source would rewrite the OLD source's `.git`
+files and corrupt the rollback anchor. The migration therefore **relinks first**:
+it deterministically repoints, in the NEW copy only, the two cross-reference
+pointer files (a linked worktree's `.git` stub and each
+`main/.git/worktrees/<name>/gitdir`) from OLD to NEW, and only THEN runs `git
+worktree repair` from each main clone at its new path as a belt-and-braces
+reconciliation now confined to the new tree. This keeps the preserved source a
+fully independent, working Git: its `.git` is byte-for-byte unchanged and it
+still resolves HEAD/index/status after the migration (verified empirically on a
+private disposable Home). **A repair failure is fatal** — it aborts the migration
+so the transaction rolls back rather than advancing the version over unrepaired
+worktrees.
+
+Because the data step runs inside the upgrade transaction, any throw rolls the
+schema back to its original version; the fenced upgrade orchestrator additionally takes a
+`database.backup()` and restores it on failure. Recovery from a failed run is
+**manual, not automatic**: because the source is never removed and the copy is
+digest-verified before publish, the preserved source is always intact, so the
+operator clears any partial target and re-runs the upgrade. No re-run can lose or
+corrupt the original content, but the tool does not itself resume an interrupted
+move set.
+
+**Old-source cleanup** is intentionally deferred and out of band: after a
+successful upgrade the old external `worktree`, `tasks`, and `<home>.task-runtimes`
+roots are left **in place** (not emptied) until an operator-authorized cleanup
+removes them. This keeps a full rollback anchor available across the first
+restart.
+
+**Rollback limits:** once the Controller restarts against the unified layout and
+begins writing new records under Home, restoring the pre-upgrade DB backup no
+longer matches the newly written on-disk state. Until that first post-upgrade
+write, the preserved old source plus the DB backup are a complete rollback pair;
+after it, the supported recovery is forward (the layout is already unified), not a
+downgrade to the split layout. Verify an upgrade only on a private, disposable
+Home before applying it to a shared environment.