@zq-silk/yui 0.15.9 → 0.15.12

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/cleanupInspection.js

@@ -0,0 +1,63 @@
+import { isAbsolute, join, relative } from "node:path";
+export class CleanupInspectionError extends Error {
+    checks;
+    constructor(checks) {
+        super(checks.map(renderCleanupCheck).join("\n"));
+        this.checks = checks;
+        this.name = "CleanupInspectionError";
+    }
+}
+export function renderCleanupCheck(check) {
+    return `[${check.reason}] ${check.resource}: ${check.detail}`
+        + ` Expected=${JSON.stringify(check.expected)}; observed=${JSON.stringify(check.observed)}.`
+        + (check.actions.length === 0 ? "" : ` Inspect/resolve: ${check.actions.join("; ")}.`);
+}
+/** Do not forward arbitrary Git stderr, native arguments, or foreign paths. */
+export function cleanupCheckFromError(error, resource, sources, actions) {
+    if (error instanceof CleanupInspectionError) {
+        return error.checks.map(check => ({ ...check, resource, sources, actions }));
+    }
+    let cause = error;
+    let errorCode;
+    for (let depth = 0; depth < 4 && cause instanceof Error; depth += 1) {
+        const code = cause.code;
+        if ((typeof code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(code))
+            || (typeof code === "number" && Number.isSafeInteger(code))) {
+            errorCode = code;
+            break;
+        }
+        cause = cause.cause;
+    }
+    return [{ resource, reason: "inspection-unavailable", status: "unknown",
+            detail: "The resource could not be inspected; no safe cleanup conclusion is available.",
+            expected: "readable owned resource", observed: errorCode === undefined ? "unavailable" : { errorCode }, sources, actions }];
+}
+export function cleanupFailure(reason, detail, expected, observed, status = "blocked") {
+    throw new CleanupInspectionError([{ resource: "git-workspace", reason, status,
+            detail, expected, observed, sources: [], actions: [] }]);
+}
+/** Describe exact differences without disclosing paths outside this Task.
+ * Legacy locations are displayed only for this Task's exact branch identity;
+ * displaying a historical location is not accepting it as migration proof.
+ */
+export function workspacePathValue(workspace, path) {
+    const inside = (root) => {
+        const value = relative(root, path);
+        return value !== ".." && !value.startsWith("../") && !isAbsolute(value) ? value || "." : undefined;
+    };
+    const marker = `/workspaces/tasks/${workspace.owner.taskId}/`;
+    const index = workspace.root.lastIndexOf(marker);
+    if (index >= 0) {
+        const home = workspace.root.slice(0, index);
+        const taskPath = inside(join(home, "workspaces", "tasks", workspace.owner.taskId));
+        if (taskPath !== undefined)
+            return `<task>/${taskPath}`;
+        const legacyPath = inside(join(home, "workspaces", "worktree"));
+        const parts = legacyPath?.split("/");
+        const taskSegment = workspace.entries.find(e => e.access === "write")?.branch.split("/")[1];
+        if (parts?.length === 3 && parts[1] === taskSegment)
+            return `<legacy-worktree>/${legacyPath}`;
+    }
+    const local = inside(workspace.root);
+    return local === undefined ? "[outside authorized Task paths]" : `<owner>/${local}`;
+}

package/dist/workspace/workItemChangeSetManager.js

@@ -1,4 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
+import { lstat, realpath } from "node:fs/promises";
+import { join } from "node:path";
 import { createWorkItemChangeSet } from "../integration/changeSet.js";
 import { createChangeSetManifest } from "../integration/changeSetManifest.js";
 import { deriveManifestTags } from "../integration/manifestTags.js";
@@ -7,6 +9,7 @@ import { sameTaskFinalReviewContract } from "../review/taskFinalReviewContract.j
 import { governingWorkItemCandidate } from "../workItem/workItem.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { captureManagedGitChanges } from "./gitChangeSetCapture.js";
+import { CleanupInspectionError, cleanupCheckFromError, workspacePathValue } from "./cleanupInspection.js";
 const CAPTURABLE_WORK_ITEM_STATUSES = new Set([
     "open",
     "accepted",
@@ -44,6 +47,12 @@ export class WorkItemChangeSetManager {
         return captured;
     }
     async assertIntegrated(taskId, workItemId, candidateId) {
+        const inspection = await this.inspectIntegrated(taskId, workItemId, candidateId);
+        if (inspection.checks.length > 0)
+            throw new CleanupInspectionError(inspection.checks);
+        return inspection.proof;
+    }
+    async inspectIntegrated(taskId, workItemId, candidateId) {
         const item = this.store.getWorkItem(taskId, workItemId);
         if (item === null)
             throw new Error(`Work item not found: ${taskId}/${workItemId}.`);
@@ -53,48 +62,114 @@ export class WorkItemChangeSetManager {
             throw new Error(`Candidate not found: ${taskId}/${workItemId}/${candidateId}.`);
         }
         const workspace = this.store.getWorkItemWorkspace(item.taskId, item.id);
-        if (workspace === null
-            || workspace.owner.type !== "work-item"
-            || workspace.owner.workItemId !== item.id)
-            return null;
+        if (workspace === null)
+            return { proof: null, checks: [] };
         const git = new NodeGitWorkspace();
         const projects = [];
-        for (const entry of writableEntries(workspace)) {
-            if (!await git.isClean(entry.path)) {
-                throw new Error(`WorkItem Project workspace is not clean: ${item.id}/${entry.projectId}.`);
+        const checks = [];
+        const sources = [`work-item:${taskId}/${workItemId}`,
+            `candidate:${taskId}/${workItemId}/${candidate?.id ?? "missing"}`, managedWorkspaceKey(workspace.owner)];
+        const actions = [`yui task work show ${taskId}/${workItemId}`, `yui task integration list ${taskId}`];
+        const add = (resource, reason, detail, expected, observed) => {
+            checks.push({ resource, reason, detail, expected, observed, status: "blocked", sources, actions });
+        };
+        const resource = `work-item:${taskId}/${workItemId}`;
+        if (workspace.owner.type !== "work-item" || workspace.owner.taskId !== taskId || workspace.owner.workItemId !== item.id) {
+            add(resource, "workspace-identity-mismatch", "Managed workspace is not owned by this WorkItem.", { type: "work-item", taskId, workItemId }, "different owner");
+            return { proof: null, checks };
+        }
+        if (candidate?.workspace === undefined) {
+            add(resource, "candidate-workspace-missing", "The governing Candidate has no frozen workspace.", "frozen WorkItem workspace", null);
+        }
+        else if (!isDeepStrictEqual(candidate.workspace, workspace)) {
+            const frozen = candidate.workspace;
+            if (!isDeepStrictEqual(frozen.owner, workspace.owner)) {
+                add(resource, "workspace-identity-mismatch", "Frozen and current workspace owners differ.", frozen.owner, workspace.owner);
+            }
+            // Paths remain frozen evidence. A path-shaped difference alone is NOT a
+            // receipt proving that migration moved this exact Candidate safely.
+            if (frozen.root !== workspace.root) {
+                add(resource, "workspace-path-mismatch", "Workspace roots differ; relocation is not proven.", workspacePathValue(workspace, frozen.root), workspacePathValue(workspace, workspace.root));
             }
-            const workspaceHeadCommit = (await git.inspect(entry.path, "HEAD")).baseCommit;
+            if (!isDeepStrictEqual(frozen.entries.map(e => e.projectId), workspace.entries.map(e => e.projectId))) {
+                add(resource, "workspace-identity-mismatch", "Frozen and current Project scope/order differ.", frozen.entries.map(e => e.projectId), workspace.entries.map(e => e.projectId));
+            }
+            for (const entry of workspace.entries) {
+                const previous = frozen.entries.find(e => e.projectId === entry.projectId);
+                if (previous === undefined)
+                    continue;
+                const entryResource = `${resource}/${entry.projectId}`;
+                if (previous.path !== entry.path) {
+                    add(entryResource, "workspace-path-mismatch", "Frozen and current Project paths differ; no relocation receipt is available. Historical evidence is unchanged.", workspacePathValue(workspace, previous.path), workspacePathValue(workspace, entry.path));
+                }
+                for (const key of ["directory", "access", "branch", "baseRef", "baseCommit"]) {
+                    if (previous[key] !== entry[key])
+                        add(entryResource, "workspace-identity-mismatch", `Frozen and current ${key} differ.`, { [key]: previous[key] }, { [key]: entry[key] });
+                }
+            }
+            for (const key of ["schemaVersion", "createdAt", "updatedAt"]) {
+                if (frozen[key] !== workspace[key])
+                    add(resource, "workspace-metadata-mismatch", `Frozen and current ${key} differ.`, { [key]: frozen[key] }, { [key]: workspace[key] });
+            }
+        }
+        for (const entry of writableEntries(workspace)) {
+            const projectResource = `${resource}/${entry.projectId}`;
             const resultCommit = candidate?.gitSnapshot?.projects.find(({ projectId }) => projectId === entry.projectId)?.commit;
-            if (candidate?.workspace === undefined
-                || !isDeepStrictEqual(candidate.workspace, workspace)
-                || resultCommit === undefined
-                || (candidateId === undefined && resultCommit !== workspaceHeadCommit)) {
-                throw new Error(`WorkItem Project no longer matches its frozen result: ${item.id}/${entry.projectId}.`);
+            if (resultCommit === undefined)
+                add(projectResource, "frozen-commit-missing", "The governing Candidate has no frozen Project commit.", "frozen commit", null);
+            if (resultCommit !== undefined) {
+                // An explicit historical selection is proved against its immutable
+                // integrated commit, not mislabeled as the workspace's current HEAD.
+                const integrated = this.store.listIntegrationAttempts(item.taskId).some(integration => integration.status === "committed"
+                    && integration.projectId === entry.projectId
+                    && integration.source.kind === "work-item"
+                    && integration.source.workItemId === item.id
+                    && integration.source.startCommit === entry.baseCommit
+                    && integration.source.resultCommit === resultCommit);
+                if (!integrated) {
+                    add(projectResource, "result-not-integrated", "WorkItem result is not integrated.", { baseCommit: entry.baseCommit, resultCommit }, "no committed Integration with these exact commits");
+                }
+                projects.push({ projectId: entry.projectId, baseCommit: entry.baseCommit, headCommit: resultCommit });
             }
-            // An explicit historical selection is proved against its immutable
-            // integrated commit, not mislabeled as the workspace's current HEAD.
-            const headCommit = resultCommit;
-            const integrated = this.store.listIntegrationAttempts(item.taskId).some((integration) => (integration.status === "committed"
-                && integration.projectId === entry.projectId
-                && integration.source.kind === "work-item"
-                && integration.source.workItemId === item.id
-                && integration.source.startCommit === entry.baseCommit
-                && integration.source.resultCommit === headCommit));
-            if (!integrated) {
-                throw new Error(`WorkItem result is not integrated: ${item.id}/${entry.projectId}.`);
+            if (entry.path !== join(workspace.root, entry.directory)) {
+                add(projectResource, "workspace-path-mismatch", "Current path differs from the exact owner-root/Project location.", workspacePathValue(workspace, join(workspace.root, entry.directory)), workspacePathValue(workspace, entry.path));
+                continue;
+            }
+            try {
+                const path = await lstat(entry.path).catch(error => {
+                    if (error.code === "ENOENT")
+                        return null;
+                    throw error;
+                });
+                if (path !== null && (path.isSymbolicLink() || await realpath(entry.path) !== entry.path)) {
+                    add(projectResource, "workspace-identity-mismatch", "WorkItem path resolves through a symbolic link.", "real owned directory", "symbolic link");
+                    continue;
+                }
+                // 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 (candidateId === undefined && resultCommit !== undefined && resultCommit !== workspaceHeadCommit) {
+                    add(projectResource, "head-mismatch", "Current HEAD no longer matches the frozen result.", resultCommit, workspaceHeadCommit ?? null);
+                }
+                if (path !== null && !await git.inspectClean(entry.path)) {
+                    add(projectResource, "dirty-worktree", "WorkItem Project workspace is not clean.", "clean", "dirty");
+                }
+            }
+            catch (error) {
+                checks.push(...cleanupCheckFromError(error, projectResource, sources, actions));
             }
-            projects.push({
-                projectId: entry.projectId,
-                baseCommit: entry.baseCommit,
-                headCommit
-            });
         }
-        return {
-            workItemId: item.id,
-            ...(item.assignee === undefined ? {} : { assignee: item.assignee }),
-            workspace,
-            projects
-        };
+        return { checks, proof: checks.length > 0 ? null : {
+                workItemId: item.id,
+                ...(item.assignee === undefined ? {} : { assignee: item.assignee }),
+                workspace,
+                projects
+            } };
     }
     /**
      * Fail-closed proof that retiring the aggregate will not hide unrecorded Git
@@ -109,6 +184,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/agent-result-consumption.md

@@ -2,6 +2,10 @@
 
 # Agent result consumption
 
+For candidate discovery before reading original results, use the
+[bounded Task catalog](task-discovery.md). A catalog summary never replaces a
+requirement or the original result.
+
 Every explicitly dispatched AgentRun produces one durable original result.
 Ordinary notification and native conversation do not implicitly create Runs.
 The next Agent in the ownership chain reads the exact result and decides what

package/docs/agent-result-consumption.zh-CN.md

@@ -2,6 +2,9 @@
 
 # Agent 结果消费
 
+读取原始结果前，可用[有界 Task 目录](task-discovery.zh-CN.md)发现候选任务。
+目录摘要不替代需求正文或原始结果。
+
 每一次显式派发的 AgentRun 都产生一个持久的原始结果。普通通知和原生对话不会
 隐式创建 Run。所有权链上的下一个 Agent 读取这个精确结果并判断它意味着什么。
 

package/docs/agent-runtime-drivers.md

@@ -67,6 +67,13 @@ than guessed. Incremental observers report health and coverage; sampling does
 not block lifecycle events. Metrics never trigger model selection, wake, retry,
 resource release or acceptance.
 
+[Task usage and time](observability/README.md#task-usage-and-time) reuse this
+reducer across historical Sessions. Task-fenced observations are not a billing
+completeness guarantee. Native child counters are excluded from parent Session
+totals without an explicit non-overlap contract; they are never extra requests.
+Raw cumulative Session counters and safely attributable Task increments remain
+distinct, and only exact request/Run bindings support WorkItem allocation.
+
 ## Native children
 
 Native subagents are collaboration inside a parent conversation, not Yui Roles,

package/docs/agent-runtime-drivers.zh-CN.md

@@ -56,6 +56,11 @@ Task 完成。
 和覆盖度；采样不阻塞生命周期事件。度量绝不触发模型选择、唤醒、重试、资源释放
 或接受。
 
+[Task 用量与耗时](observability/README.zh-CN.md#task-用量与耗时)跨历史 Session
+复用此 reducer。Task 围栏内的观察不是完整账单保证。缺少明确互斥合同时，原生
+子计数不加入父 Session 总量，也不作为额外请求。原始 Session 累计值与安全归属
+的 Task 增量分开；仅精确请求/Run 绑定支持 WorkItem 分配。
+
 ## 原生子代
 
 原生 subagent 是父对话内部的协作，不是 Yui Role、Lane 或独立的受管工作区 owner。

package/docs/architecture/README.md

@@ -20,11 +20,13 @@ not a claim that every real Provider scenario has been validated.
 | Question | Current document |
 | --- | --- |
 | How do Session, AgentRun, messages and activation fit together? | [Session and AgentRun runtime](../managed-turn-and-session-runtime.md) |
+| What can Web control, and how do queue, steer and interrupt differ? | [Web permissions](capabilities-and-resources.md#cli-and-web) · [Input timing](../managed-turn-and-session-runtime.md#input-timing-queue-steer-and-interrupt) |
 | Who consumes results, synthesis and review? | [Result consumption](../agent-result-consumption.md) |
 | When is a WorkItem dependency satisfied? | [Task dependencies](../task-dag-semantics.md) |
 | How are records referenced inside a Task? | [Task-local identity](../task-local-identity.md) |
 | How do Roles, Profiles and run configuration take effect? | [Roles and configuration](../roles-and-configuration.md) |
 | How do delivery, integration and archive work? | [Task delivery](../task-delivery.md) |
+| What does Project refresh synchronize, and how are partial failures reported? | [Project refresh](../project-refresh.md) |
 | How do Provider, ACP and configuration facts connect? | [Provider runtime](../provider-runtime.md) |
 | Who interprets runtime observations and errors? | [Agent Drivers](../agent-runtime-drivers.md) |
 | How are plugins created, validated and adopted? | [Plugin SDK](../plugin-sdk.md) |

package/docs/architecture/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 - [English README](../../README.md)：安装、配置和日常使用。
 - [中文 README](../../i18n/README.zh-CN.md)：同一产品入口的中文说明。
-- [总体架构](../../ARCHITECTURE.md)：职责、权威和端到端流程（英文）。
+- [总体架构](../../ARCHITECTURE.zh-CN.md)：职责、权威和端到端流程。
 - [能力、资源与 Surface](capabilities-and-resources.zh-CN.md)：扩展入口、实例所有权和资源效果。
 
 ## 领域合同
@@ -16,11 +16,13 @@
 | 问题 | 当前文档 |
 | --- | --- |
 | Session、AgentRun、消息和激活如何配合？ | [执行与会话](../managed-turn-and-session-runtime.zh-CN.md) |
+| Web 可以控制什么，queue、steer 和 interrupt 有何区别？ | [Web 权限](capabilities-and-resources.zh-CN.md#cli-与-web) · [输入时机](../managed-turn-and-session-runtime.zh-CN.md#输入时机queuesteer-与-interrupt) |
 | 谁消费结果、综合与审查？ | [结果消费](../agent-result-consumption.zh-CN.md) |
 | WorkItem 依赖何时满足？ | [Task 依赖](../task-dag-semantics.zh-CN.md) |
 | Task 内记录如何引用？ | [局部身份](../task-local-identity.zh-CN.md) |
 | Role、Profile 与运行配置如何生效？ | [角色与配置](../roles-and-configuration.zh-CN.md) |
 | 怎样交付、集成和归档？ | [交付生命周期](../task-delivery.zh-CN.md) |
+| Project refresh 同步什么，怎样报告部分失败？ | [Project refresh](../project-refresh.zh-CN.md) |
 | Provider、ACP 与配置事实如何接入？ | [Provider Runtime](../provider-runtime.zh-CN.md) |
 | 运行观察和错误由谁解释？ | [Agent Drivers](../agent-runtime-drivers.zh-CN.md) |
 | 如何创建、验证与采用插件？ | [插件 SDK](../plugin-sdk.zh-CN.md) |

package/docs/architecture/capabilities-and-resources.md

@@ -111,8 +111,33 @@ capability's original name. A Web panel accepts only controlled text, an HTTP(S)
 link or a JSON query description — not author scripts or arbitrary HTML.
 
 The Web listener is started and stopped by the Controller and allows loopback
-only. A browser write goes through an existing domain transaction, and its error
-distinguishes a definite non-commit from a committed-but-unknown result. A query
-panel cannot use the browser's identity to run a mutation or manage plugins. A
-terminal connection only attaches a client; it does not take over durable
-ownership of the native conversation.
+only (`127.0.0.1`, `::1` or `localhost`; default port 4173). `yui web` opens this
+local surface, not a remote multi-user service or an OS sandbox.
+
+The page supplies a token that authenticates all HTTP API reads and writes via
+`x-yui-web-token`; the server also checks the loopback Host. These controls act
+as the trusted local user, not a Role selected by the request body. They support
+Task metadata edits, messages, InputRequest answers, and explicit
+`queue / steer / interrupt` for Task or Global Roles. Managed Agent capability
+RPC retains its own Session authentication and scope; a browser token is not
+a way for an Agent or plugin to bypass those boundaries.
+
+Read-only dashboard, Context and query-panel projections remain separate from
+these mutations. A query panel cannot borrow the browser's user authority to
+mutate state or manage plugins. Task controls share the public CLI's domain
+commands; Global Role controls share the Global handler but currently lack a
+registered top-level CLI path. Message submission intent
+(`record / discuss / develop`, default `discuss`) is
+separate from [input timing](../managed-turn-and-session-runtime.md#input-timing-queue-steer-and-interrupt).
+Transport acceptance does not establish implementation or Task acceptance.
+
+A browser write uses an existing domain transaction. Errors distinguish proven
+`not-submitted` from `unknown`, which can include an already-committed Message
+whose native delivery failed or is unconfirmed. Read the original Message,
+control receipt and current Session before choosing recovery; do not blindly
+resubmit under a new request ID or switch actions.
+
+A terminal WebSocket checks the token and same-origin handshake. It attaches a
+client without taking over durable conversation ownership, and respects the
+connection's `readOnly` flag. A terminal attachment is not a grant to control a
+different Session.