@zq-silk/yui 1.1.2 → 2.0.0

package/dist/output/boundedRead.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { usageError } from "../errors/cliError.js";
+export const READ_PAGE_BYTES = 32 * 1024;
+export const INLINE_DOCUMENT_BYTES = 16 * 1024;
+function assertSource(source) {
+    if (Buffer.byteLength(source) > 1024)
+        throw usageError("Read source identity exceeds its 1024-byte budget.");
+}
+export function readDigest(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+/** A save receipt is not another read of the submitted body. Keep the exact
+ * delivery/control facts and identity; body/history are read on demand.
+ */
+export function messageReceipt(message) {
+    const { body: _body, ...facts } = message;
+    return { ...facts, digest: readDigest(message), bodyBytes: Buffer.byteLength(message.body) };
+}
+export function encodeReadCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor)).toString("base64url");
+}
+export function decodeReadCursor(raw, source, digest) {
+    let cursor;
+    try {
+        if (raw.length > 4096)
+            throw new Error();
+        cursor = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+        if (cursor.source !== source || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0
+            || typeof cursor.digest !== "string")
+            throw new Error();
+    }
+    catch {
+        throw usageError("Invalid read cursor for this source/scope.");
+    }
+    if (cursor.digest !== digest)
+        throw usageError("Read source changed; restart the read instead of mixing versions.");
+    return cursor.offset;
+}
+export function readLimit(value) {
+    const limit = value ?? 20;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+        throw usageError("Read limit must be between 1 and 100.");
+    }
+    return limit;
+}
+/** For small in-memory authorized collections. Authorize/filter BEFORE calling.
+ * Cursors bind the selected collection, never grant access, and store no state.
+ */
+export function recordPage(records, source, options = {}) {
+    assertSource(source);
+    const limit = readLimit(options.limit);
+    const digest = readDigest(records);
+    const offset = options.cursor === undefined ? 0 : decodeReadCursor(options.cursor, source, digest);
+    if (offset > records.length)
+        throw usageError("Read cursor exceeds this collection.");
+    const items = [];
+    // Reserve room for identities, counts and continuation. Oversized individual
+    // records belong in a document read, not silently truncated list metadata.
+    let bytes = 0;
+    for (const record of records.slice(offset, offset + limit)) {
+        const size = Buffer.byteLength(JSON.stringify(record)) + 1;
+        if (size > READ_PAGE_BYTES / 2)
+            throw usageError("List entry exceeds its summary budget; read the exact record.");
+        if (bytes + size > READ_PAGE_BYTES - 4096)
+            break;
+        items.push(record);
+        bytes += size;
+    }
+    const end = offset + items.length;
+    return {
+        source, digest, items, total: records.length, complete: end === records.length,
+        nextCursor: end < records.length ? encodeReadCursor({ source, digest, offset: end }) : null,
+        limits: { items: limit, bytes: READ_PAGE_BYTES }
+    };
+}
+/** Small exact details stay native JSON. Large details explicitly become a
+ * contentPage. Concatenate text in order, then JSON.parse once, never each chunk.
+ * JSON character offsets (not bytes) preserve Unicode and escaped controls.
+ * The source is an exact authorized read identity; reauthorize every page.
+ */
+export function boundedDocument(value, source, cursor) {
+    assertSource(source);
+    const text = JSON.stringify(value);
+    const totalBytes = Buffer.byteLength(text);
+    if (cursor === undefined && totalBytes <= INLINE_DOCUMENT_BYTES)
+        return value;
+    const digest = readDigest(value);
+    const offset = cursor === undefined ? 0 : decodeReadCursor(cursor, source, digest);
+    if (offset >= text.length && offset !== 0)
+        throw usageError("Read cursor exceeds this document.");
+    let end = Math.min(offset + 4096, text.length);
+    // Never cut between UTF-16 surrogate halves.
+    if (end < text.length && /[\uD800-\uDBFF]/u.test(text[end - 1]))
+        end--;
+    return { contentPage: {
+            source, digest, encoding: "json", offset, totalCharacters: text.length,
+            totalBytes, text: text.slice(offset, end), complete: end === text.length,
+            nextCursor: end < text.length ? encodeReadCursor({ source, digest, offset: end }) : null
+        } };
+}
+/** Shared parser for list/detail command tails; no options reach mutations. */
+export function readOptions(args, flags = ["--cursor", "--limit"]) {
+    const positionals = [];
+    const values = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        if (!flags.includes(arg) || values.has(arg) || args[i + 1] === undefined || args[i + 1].startsWith("--")) {
+            throw usageError(`Invalid read option: ${arg}.`);
+        }
+        values.set(arg, args[++i]);
+    }
+    return { positionals, values, cursor: values.get("--cursor"),
+        ...(values.has("--limit") ? { limit: Number(values.get("--limit")) } : {}) };
+}

package/dist/release/releaseWorkflowEngine.js

@@ -228,7 +228,8 @@ async function runReleaseWorkflowLocked(store, taskId, workflowId, ports, option
         if (grant === null) {
             return finish(workflow, "unauthorized", "unauthorized:grant-missing", attempted);
         }
-        const params = resolveParams(workflow, plan);
+        const params = grant.authorizationSource === undefined ? resolveParams(workflow, plan)
+            : Object.freeze({ ...resolveParams(workflow, plan), sourceCommit: workflow.source.commit });
         const effectiveIrreversibility = effectiveStepIrreversibility(plan);
         const decision = checkGrant(grant, {
             action: grantAction(plan),
@@ -615,6 +616,12 @@ function cliUpdateVersionDenial(plan, params) {
 function versionTagCheckoutDenial(grant, plan, params) {
     if (plan.kind !== "version-tag")
         return undefined;
+    // Leader authorization names a release version; the adapter pushes tag,
+    // not version. Validate that actual effect before consuming a grant use.
+    if (grant.authorizationSource !== undefined
+        && (!params.version || ![params.version, `v${params.version}`].includes(params.tag ?? ""))) {
+        return "grant-version-tag-mismatch";
+    }
     const repositories = grant.scope.repositories;
     if (repositories === undefined || repositories.length === 0)
         return undefined;

package/dist/runtime/managedCaller.js

@@ -30,8 +30,8 @@ export function requireManagedGlobalCaller(store, env) {
  */
 export class ManagedRuntimeDriftError extends Error {
     name = "ManagedRuntimeDriftError";
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
     }
 }
 /** Reads the process's own immutable managed identity, or undefined when unmanaged. */

package/dist/runtime/runtimeCoherence.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { StorageSchemaError } from "../storage/storageSchema.js";
 import { isStorageVersion, compareStorageVersions } from "../storage/storageVersions.js";
 import { callController as defaultCallController, ControllerClientError } from "../core/controllerClient.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
@@ -8,10 +9,12 @@ export async function assertRuntimeCoherence(input, options = {}) {
     const identity = validateVersionIdentity(options.identity ?? yuiVersionIdentity());
     const storage = (options.inspectStorage ?? inspectStorageSchema)(home);
     if (storage.status !== "current") {
-        throw new Error(`Managed control-plane storage is not current: ${storage.status}.`);
+        throw new StorageSchemaError(storage.status === "uninitialized" ? "STORAGE_UNINITIALIZED"
+            : storage.status === "unsupported" ? "STORAGE_SCHEMA_UNSUPPORTED" : "STORAGE_SCHEMA_INVALID", `Managed control-plane storage is not current: ${storage.status}.`
+            + ("detail" in storage && typeof storage.detail === "string" ? ` ${storage.detail}` : ""));
     }
     if (storage.currentVersion !== identity.storageVersion) {
-        throw new Error("Managed control-plane storage version is incompatible "
+        throw new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", "Managed control-plane storage version is incompatible "
             + `(expected ${identity.storageVersion}, found `
             + `${storage.currentVersion ?? "unknown"}).`);
     }
@@ -37,7 +40,7 @@ export async function assertRuntimeCoherence(input, options = {}) {
 }
 export function assertControllerStatusIdentity(status, expected = yuiVersionIdentity()) {
     if (!isRecord(status) || status.running !== true) {
-        throw new Error("Controller status does not describe a running Controller.");
+        throw new ControllerClientError("INVALID_RESPONSE", "Controller status does not describe a running Controller.");
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
     assertControllerField(status.version, expected.version, "version");
@@ -66,20 +69,19 @@ function validateVersionIdentity(value) {
 }
 function assertControllerContinuityIdentity(status, expected) {
     if (!isRecord(status) || status.running !== true) {
-        throw new Error("Controller status does not describe a running Controller.");
+        throw new ControllerClientError("INVALID_RESPONSE", "Controller status does not describe a running Controller.");
     }
     if (typeof status.version !== "string" || status.version.trim().length === 0) {
-        throw new Error("Controller version is invalid at the managed continuity gate.");
+        throw new ControllerClientError("CONTROLLER_PROTOCOL_MISMATCH", "Controller version is invalid at the managed continuity gate.");
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
     assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
 }
 function assertControllerField(actual, expected, label) {
     if (actual !== expected) {
-        throw new Error(`Controller ${label} is incompatible with the exact control plane `
+        throw new ControllerClientError("CONTROLLER_PROTOCOL_MISMATCH", `Controller ${label} is incompatible with the exact control plane `
             + `(expected ${expected}, found ${typeof actual === "string" || typeof actual === "number" ? actual : "unknown"}). `
-            + "Run controller restart through the matching exact control-plane invocation "
-            + "before writing new Task records.");
+            + "Verify Home, CLI and Controller identity before an authorized restart through the matching invocation.");
     }
 }
 function requireText(value, label) {

package/dist/storage/sqliteSchema.js

@@ -24,6 +24,16 @@ const MINOR_UPGRADES = Object.freeze([{
         targetChecksum: CURRENT_SCHEMA_CHECKSUM,
         sql: "",
         dataMigration: "task-main-workspace"
+    }, {
+        fromVersion: "1.1",
+        toVersion: "1.2",
+        name: "task-authorization-source",
+        introducedIn: "next",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // New grants can carry source evidence. Valid historical Operator grants
+        // remain unchanged; migration must not invent authorization provenance.
+        sql: ""
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)

package/dist/storage/storageVersions.js

@@ -1,4 +1,4 @@
-export const CURRENT_STORAGE_VERSION = "1.1";
+export const CURRENT_STORAGE_VERSION = "1.2";
 export const MIN_SUPPORTED_STORAGE_VERSION = "1.0";
 export const STORAGE_FORMAT = "yui-home";
 export function isStorageVersion(value) {

package/dist/storage/taskStore.js

@@ -180,6 +180,8 @@ export function storedCapabilityGrant(value) {
         fields.push("revokedAt");
     if (grant.revokedBy !== undefined)
         fields.push("revokedBy");
+    if (grant.authorizationSource !== undefined)
+        fields.push("authorizationSource");
     exact(grant, fields, "Capability grant");
     requireRecordIdentity(grant.id, "Capability grant id");
     requireRecordIdentity(grant.taskId, "Capability grant Task id");
@@ -303,6 +305,7 @@ export function isValidCapabilityGrantTransition(existing, candidate) {
     const immutable = candidate.id === existing.id
         && candidate.taskId === existing.taskId
         && candidate.granter === existing.granter
+        && isDeepStrictEqual(candidate.authorizationSource, existing.authorizationSource)
         && isDeepStrictEqual(candidate.scope, existing.scope)
         && isDeepStrictEqual(candidate.actions, existing.actions)
         && isDeepStrictEqual(candidate.parameterBounds, existing.parameterBounds)

package/dist/task/leaderArchive.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { runTaskCommand } from "../commands/taskCommands.js";
+import { archiveExecutionChecks, archiveSettlementChecks } from "./archivePreflight.js";
+import { admitLeaderArchive, assertLeaderArchiveAdmission } from "./leaderArchiveAuthority.js";
+import { assertTaskRemoteDeliveryIntegrated, createTaskRemoteDeliveryProof } from "./remoteDeliveryService.js";
+import { selectNewTaskRoleSession } from "../executor/agentExecutor.js";
+/** A single foreground Controller operation survives stopping its requesting
+ * Session. It has no retry worker: uncertain receipts are inspected, not
+ * replayed. All existing settlement, delivery and cleanup checks remain. */
+export async function archiveLeaderTask(store, coordinator, taskId, environment, request) {
+    const inputDigest = createHash("sha256").update(JSON.stringify(request)).digest("hex");
+    const previous = store.listEvents(taskId).find(event => event.type === "task.leader-archive-started" && event.payload.requestId === request.requestId);
+    if (previous) {
+        if (previous.payload.inputDigest !== inputDigest)
+            throw new Error("Archive request id names different input.");
+        const result = store.listEvents(taskId).find(event => event.type === "task.leader-archive-result" && event.payload.requestId === request.requestId);
+        return { taskId, requestId: request.requestId, status: result?.payload.status ?? "unknown",
+            detail: result?.payload.detail, replayed: true };
+    }
+    const admission = admitLeaderArchive(store, taskId, environment, request.sourceMessage, request.purpose);
+    const task = store.getTask(taskId);
+    const settlement = archiveSettlementChecks(store, task);
+    if (settlement.length)
+        throw new Error(`Archive is unsettled: ${JSON.stringify(settlement)}`);
+    const session = store.getTaskRoleSessionSet(taskId, "leader");
+    const ownInput = session?.providerBinding?.run;
+    // Only the requesting no-Run Leader may be stopped as part of this action.
+    // Another Run, Job, unknown input, or then handoff is not archive authority.
+    const ownResources = `role:${taskId}/leader`;
+    const execution = archiveExecutionChecks(store, taskId).filter(check => !(check.resource === ownResources
+        && ownInput?.runId === undefined && ownInput?.status === "accepted"
+        && ["unresolved-provider-input", "unresolved-mailbox"].includes(check.reason)));
+    if (execution.length)
+        throw new Error(`Archive execution is unresolved: ${JSON.stringify(execution)}`);
+    if (store.listMessages(taskId).some(message => message.interruptThen?.targetNativeSessionId === admission.source.nativeSessionId
+        && message.continuation === undefined && message.interruptThen.notDeliveredReason === undefined)) {
+        throw new Error("Settle the original input handoff before archive.");
+    }
+    let candidate = null;
+    const workspace = store.getTaskWorkspace(taskId);
+    if (task.projectBindings.length && workspace) {
+        const snapshot = await coordinator.preparer.snapshotDirectTaskMain(workspace, task.projectBindings.map(binding => binding.projectId));
+        candidate = { schemaVersion: 1, projects: snapshot.projects.map(project => ({
+                projectId: project.projectId, commit: project.headCommit
+            })) };
+    }
+    const proof = createTaskRemoteDeliveryProof(store, task, candidate);
+    assertTaskRemoteDeliveryIntegrated(proof.delivery);
+    for (const owned of store.listManagedWorkspaces(taskId)) {
+        const disposition = owned.owner.type === "work-item"
+            && store.getWorkItem(taskId, owned.owner.workItemId)?.status === "retired" ? "abandoned" : "integrated";
+        const checks = await coordinator.preparer.inspectWorkspaceCleanup(owned, disposition);
+        if (checks.some(check => !(owned.owner.type === "task" && check.reason === "git-worktree-registrations"))) {
+            throw new Error(`Archive workspace is not clean/removable: ${JSON.stringify(checks)}`);
+        }
+    }
+    // Reauthenticate after asynchronous inspection, before the first effect.
+    admitLeaderArchive(store, taskId, environment, request.sourceMessage, request.purpose);
+    assertLeaderArchiveAdmission(store, taskId, admission);
+    const record = (type, payload) => store.transaction(tx => tx.saveEvent(taskId, createTaskEvent(tx.nextEventId(taskId), taskId, type, { requestId: request.requestId, ...payload }, new Date())));
+    const started = store.transaction(tx => {
+        assertLeaderArchiveAdmission(tx, taskId, admission);
+        const events = tx.listEvents(taskId);
+        const prior = events.find(event => event.type === "task.leader-archive-started"
+            && event.payload.requestId === request.requestId);
+        if (prior) {
+            if (prior.payload.inputDigest !== inputDigest)
+                throw new Error("Archive request id names different input.");
+            return false;
+        }
+        const unsettled = events.find(event => event.type === "task.leader-archive-started"
+            && !events.some(result => result.type === "task.leader-archive-result"
+                && result.payload.requestId === event.payload.requestId));
+        if (unsettled)
+            throw new Error(`Inspect unresolved archive ${unsettled.payload.requestId} before another operation.`);
+        tx.saveEvent(taskId, createTaskEvent(tx.nextEventId(taskId), taskId, "task.leader-archive-started", { requestId: request.requestId, inputDigest, authorizationSource: JSON.stringify(admission.source) }, new Date()));
+        return true;
+    });
+    if (!started)
+        return { taskId, requestId: request.requestId, status: "unknown", replayed: true };
+    try {
+        await coordinator.runtime.stopTaskRoleSessions(taskId, ["leader"]);
+        store.transaction(tx => {
+            assertLeaderArchiveAdmission(tx, taskId, admission);
+            const stopped = tx.getTaskRoleSessionSet(taskId, "leader");
+            const current = stopped?.sessions[stopped.activeAgentId];
+            if (!stopped || current?.nativeSessionId !== admission.source.nativeSessionId
+                || current.status !== "ended" || current.endReason !== "stopped") {
+                throw new Error("Leader Session changed before archive runtime retirement.");
+            }
+            // Retain the exact stopped caller in history and clear its resumable
+            // binding. Generic workspace cleanup must not stop that caller again:
+            // the first verified stop already released its physical owner records.
+            tx.saveTaskRoleSessionSet(selectNewTaskRoleSession(stopped, stopped.activeAgentId, new Date()));
+        });
+        const cleanup = await coordinator.cleanupTaskForArchive(taskId, "integrated");
+        if (cleanup.status !== "removed")
+            throw new Error(cleanup.error ?? `Archive cleanup ${cleanup.status}.`);
+        runTaskCommand(["archive", taskId, "--integrated"], store, {
+            environment, archiveLeaderAdmission: admission, archiveRemoteDeliveryProof: proof
+        });
+        record("task.leader-archive-result", { status: "archived" });
+        return { taskId, requestId: request.requestId, status: "archived" };
+    }
+    catch (error) {
+        record("task.leader-archive-result", { status: store.getTask(taskId)?.status === "archived" ? "archived" : "failed",
+            detail: error instanceof Error ? error.message : String(error) });
+        throw error;
+    }
+}

package/dist/task/leaderArchiveAuthority.js

@@ -0,0 +1,24 @@
+import { taskAuthorizationSource } from "../grant/taskAuthorization.js";
+const admissions = new WeakSet();
+const terminalIdentity = (store, taskId) => {
+    const task = store.getTask(taskId);
+    if (!task || !["completed", "cancelled"].includes(task.status))
+        throw new Error("Ordinary Leader archive requires a terminal Task.");
+    return JSON.stringify({
+        status: task.status, completedAt: task.completedAt, completionSummary: task.completionSummary,
+        retiredAt: task.retiredAt, retirementSummary: task.retirementSummary,
+        projectBindings: task.projectBindings
+    });
+};
+export function admitLeaderArchive(store, taskId, environment, messageId, purpose) {
+    const source = taskAuthorizationSource(store, taskId, environment, messageId, purpose);
+    const admission = Object.freeze({ taskId, source, terminalIdentity: terminalIdentity(store, taskId) });
+    admissions.add(admission);
+    return admission;
+}
+export function assertLeaderArchiveAdmission(store, taskId, admission) {
+    if (!admissions.has(admission) || admission.taskId !== taskId
+        || terminalIdentity(store, taskId) !== admission.terminalIdentity) {
+        throw new Error("Archive admission is untrusted or its terminal Task changed.");
+    }
+}

package/dist/tmux/commandExecutor.js

@@ -4,8 +4,8 @@ export class CommandExecutionError extends Error {
     code;
     exitStatus;
     stderr;
-    constructor(code, exitStatus, stderr = "") {
-        super(commandExecutionMessage(code));
+    constructor(code, exitStatus, stderr = "", options) {
+        super(commandExecutionMessage(code), options);
         this.code = code;
         this.exitStatus = exitStatus;
         this.stderr = stderr;
@@ -102,15 +102,17 @@ export class NodeCommandExecutor {
 }
 function stableCommandExecutionError(error) {
     const details = errorDetails(error);
+    const cause = typeof error === "object" && error !== null && "error" in error
+        && error.error instanceof Error ? { cause: error.error } : undefined;
     if (details.code === "ENOENT") {
-        return new CommandExecutionError("COMMAND_NOT_FOUND", details.exitStatus, details.stderr);
+        return new CommandExecutionError("COMMAND_NOT_FOUND", details.exitStatus, details.stderr, cause);
     }
     if (details.code === "ETIMEDOUT"
         || details.signal === "SIGTERM"
         || details.signal === "SIGKILL") {
-        return new CommandExecutionError("COMMAND_TIMED_OUT", details.exitStatus, details.stderr);
+        return new CommandExecutionError("COMMAND_TIMED_OUT", details.exitStatus, details.stderr, cause);
     }
-    return new CommandExecutionError("COMMAND_FAILED", details.exitStatus, details.stderr);
+    return new CommandExecutionError("COMMAND_FAILED", details.exitStatus, details.stderr, cause);
 }
 function errorDetails(error) {
     if (typeof error !== "object" || error === null)

package/docs/architecture/README.md

@@ -24,6 +24,7 @@ not a claim that every real Provider scenario has been validated.
 | 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 bounded discovery, full originals and mutation receipts work? | [CLI information contract](../cli-information-contract.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) |

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

@@ -20,6 +20,7 @@
 | 谁消费结果、综合与审查？ | [结果消费](../agent-result-consumption.zh-CN.md) |
 | WorkItem 依赖何时满足？ | [Task 依赖](../task-dag-semantics.zh-CN.md) |
 | Task 内记录如何引用？ | [局部身份](../task-local-identity.zh-CN.md) |
+| 有界发现、完整原文与变更回执如何配合？ | [CLI 信息契约](../cli-information-contract.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) |

package/docs/cli-information-contract.md

@@ -0,0 +1,107 @@
+# CLI information contracts
+
+Yui separates a command's effect from discovery and full evidence. Queries
+never consume Messages or start subsequent work. Mutation receipts describe
+saved/requested/accepted/unknown facts; `ok: true` means the CLI invocation
+succeeded, not that a Task, native Turn or remote delivery completed.
+
+This is the current wire contract, not a compatibility mode. Stored Tasks,
+Messages, results, Snapshots and Session histories are unchanged. No persistent
+schema migration or new snapshot/cache store is introduced.
+
+## Daily read path
+
+| Question | Entry | Default information / further reading |
+| --- | --- | --- |
+| Which Task? | `task list` | Existing bounded catalog, filters, attention and cursor |
+| What is current? | `task context <task>` | Current Task/Brief/Role/Project/workspace facts, active work and Runs, open inputs, active decisions, unresolved jobs, recent Message references; no event or terminal-Run dump |
+| What records exist? | `task context list <task> --store <family>` | One authorized family, summaries and exact digest-bearing references |
+| What does it actually say? | `task context inspect <task> --store <family> --ref <id> --digest <digest>` | Exact current record, including original result expansion; long documents are paged |
+| What changed? | `task context delta <task> --after <cursor>` | Immutable events with a fixed upper bound, not a snapshot of current mutable state |
+| Which Global input? | `session context <role>` | Identity, profile, authority, current native Turn/retry and separate bounded pending/recent Message pages |
+| Read Global input | `role message list <role> [--pending]`, `role message show <role> <id>` | Scoped discovery, then exact original; queue acceptance never erases history |
+| What arrived in this wake? | `task wake show <task> <wake>` | Fixed window and Message/Run/Event read pointers, not duplicated bodies |
+| What was assigned? | `task run context <task>/<run>` | Frozen authority and a single `pointers` inventory with summaries; changed identities in `deltaRefs`; current observations remain separate |
+| Which configuration is real? | `task role session inspect <task> <role>` | Task/Role identity, desired binding, frozen Session, current Provider binding, retry and explicit Host observation; no full Task/Role copies or Provider conversation history |
+
+Domain lists for Task Messages, events, WorkItems, Runs, decisions, milestones,
+publications and InputRequests use the same summary/reference paging contract.
+Task Role-status and wake-history lists also page, with explicit detail commands.
+Role discovery reports `recordedHealth` and `hostObservation: "not-requested"`,
+not live Host health. Even a normal recorded status cannot rule out a failed Host
+or unacknowledged terminal; follow the row's `task role status` read to inspect it.
+Context lists additionally expose candidates, reviews, jobs, Project Knowledge,
+workspaces and other authorized record families. `--status`, `--after` and
+`--work-item` narrow Context discovery; every continuation must retain filters.
+Run listing accepts a Task or `task/work` target.
+
+Current Context's `attention.messages` counts all authorized Messages, not only
+undelivered input. `collections` counts and `omitted` explicitly describe
+incomplete discovery. Recent samples are not proof that no older pending or
+relevant input exists. Read the relevant fixed wake and original Messages;
+use family discovery when a broader requirement/history audit is needed.
+
+## Budgets and continuations
+
+- Discovery pages default to 20 items, accept 1–100, and reserve a 32 KiB
+  compact-JSON budget. Items contain summaries, never full Message/report bodies.
+- Current Task Context has at most 64 records, with a 24 KiB record/attention
+  budget inside a 32 KiB response budget. Single inline values are at most
+  2 KiB; large values and Message/Run/WorkItem/Knowledge bodies use references.
+  Each collection contributes at most eight sampled records at entry.
+- Global entry samples up to eight pending and eight recent Messages separately.
+  They have independent continuations, so a long historical list cannot crowd
+  pending input out of the entry view.
+- Detail documents up to 16 KiB remain ordinary JSON. Larger documents return
+  `contentPage`: exact source, SHA-256 digest, JSON-character offset, total bytes
+  and characters, text, completeness and a next cursor. Chunks contain at most
+  4096 UTF-16 code units without splitting surrogate pairs, keeping escaped
+  wire output below 32 KiB. There is no 4 MiB cutoff that makes a legal original
+  permanently unreadable.
+- Task metadata/next-action/remote-delivery, Brief, WorkItem, Message, Run,
+  decision/milestone/event, Role show/status/Session inspection, wake detail,
+  InputRequest, Run context and frozen expansion use bounded detail reads.
+
+Use `--json` and read the top-level `data`. Run context and expansion use
+`data.context`; Run Context delta uses `data.contextDelta`. For a long detail, repeat that same read with
+`--cursor <contentPage.nextCursor>`. Concatenate `text` in offset order, checking
+the same source and digest, and parse the combined JSON once. Do not parse
+chunks individually or treat a first chunk as the complete report.
+
+List responses carry `items`, `total`, `complete`, and `nextCursor`. Counts,
+items and cursor validation occur inside the same authorized scope. Cursors
+are opaque positions, not access tokens: every page reauthorizes. A changed
+collection or document returns an explicit source-changed error; restart rather
+than mix versions. No persisted pagination session is needed. Mutable collection
+continuations intentionally do not promise uninterrupted traversal during
+concurrent writes. For append-only event traversal use fixed-bound Context delta.
+Discovery currently scans the selected authorized family to fingerprint it;
+its output, not total storage-reading cost, is bounded.
+
+## Effects and exceptions
+
+Message send/queue/steer receipts preserve identity, digest, body byte count and
+the original submission/delivery/control states without echoing the body.
+Brief updates return a saved reference. No new wait, retry, acknowledgement or
+approval phase is added. Repeating a read cursor must never repeat a mutation.
+
+Whole-transaction operations (activation, completion, integration and input
+control) remain atomic business operations even when their mechanics have
+several steps. Their state-specific receipts and existing unknown-effect
+diagnostics are retained; they are not flattened into a generic “executed” flag.
+
+This change covers daily Agent context, collaboration discovery and original
+evidence reads, not every diagnostic or export in the product. Existing
+specialized log-tail/artifact limits, Task catalog pagination and bounded error
+diagnostics retain their contracts. Configuration catalogs, Project/config
+administration, resource inventories, archive diagnostics, release operations,
+and specialized integration/changeset reads remain purpose-specific; this
+document does not claim a universal 32 KiB cap for them. Full-detail Web
+projections are separate consumers, not silently replaced with CLI summaries.
+Use targeted Context discovery for large Project Knowledge and Task evidence.
+
+For a typical notification, read current Context once, read the fixed wake once,
+then read each relevant original once (or its complete document pages).
+Do not reread an aggregate to obtain a detail it intentionally omits.
+Full-original reading costs additional calls only when the original exceeds
+the inline budget; it is never replaced by a summary.

package/docs/cli-information-contract.zh-CN.md

@@ -0,0 +1,81 @@
+# CLI 信息契约
+
+Yui 将命令的效果、发现和完整证据读取分开。查询不会消费 Message，也不启动后续工作。
+变更回执说明 saved/requested/accepted/unknown 等真实事实；`ok: true` 只说明这次
+CLI 调用成功，不代表 Task、原生 Turn 或远端投递完成。
+
+这是当前通信契约，不是兼容模式。已保存的 Task、Message、结果、Snapshot 和 Session
+历史保持不变；没有持久 schema 迁移，也没有新增快照或缓存存储。
+
+## 日常读取路径
+
+| 问题 | 入口 | 默认信息与下一步 |
+| --- | --- | --- |
+| 找哪个 Task？ | `task list` | 既有有界目录、过滤器、attention 与游标 |
+| 当前有什么？ | `task context <task>` | 当前 Task/Brief/Role/Project/工作区事实、活跃工作与 Run、开放输入、有效决策、未解决 Job、近期 Message 引用；不倾倒事件或终态 Run |
+| 有哪些记录？ | `task context list <task> --store <family>` | 一种获授权的记录、摘要与带 digest 的确切引用 |
+| 原文是什么？ | `task context inspect <task> --store <family> --ref <id> --digest <digest>` | 确切当前记录，含原始结果展开；长文档分页 |
+| 发生了什么变化？ | `task context delta <task> --after <cursor>` | 固定上界内的不可变事件，不是可变当前状态的快照 |
+| Global 收到了什么？ | `session context <role>` | 身份、Profile、权限、当前原生 Turn/retry，以及分别有界的 pending/recent Message 页 |
+| 读取 Global 输入 | `role message list <role> [--pending]`、`role message show <role> <id>` | 在自身范围内发现，再读完整原文；队列接受不删除历史 |
+| 本次唤醒带来什么？ | `task wake show <task> <wake>` | 固定窗口与 Message/Run/Event 读取指针，不重复正文 |
+| 分配了什么？ | `task run context <task>/<run>` | 冻结授权与一份带摘要的 `pointers` 目录；`deltaRefs` 表示变化身份；当前观察独立 |
+| 实际配置是什么？ | `task role session inspect <task> <role>` | Task/Role 身份、期望绑定、冻结 Session、当前 Provider 绑定、retry 与显式 Host 观察；不复制整个 Task/Role 或 Provider 会话历史 |
+
+Task Message、事件、WorkItem、Run、决策、里程碑、publication 和 InputRequest 列表
+共用摘要/引用分页。Role 状态与 wake 历史列表也分页，并给出详情命令。
+Role 发现返回 `recordedHealth` 与 `hostObservation: "not-requested"`，不是实时 Host
+健康度。记录状态正常也不能排除 Host 失败或终态未确认；需沿条目的 `task role status`
+读取指针检查。
+Context 列表还暴露候选、Review、Job、Project Knowledge、工作区等获授权的记录。
+`--status`、`--after`、`--work-item` 缩小发现范围；续读必须保留过滤条件。
+Run 列表接受 Task 或 `task/work` 目标。
+
+当前 Context 的 `attention.messages` 统计全部获授权 Message，不仅是未投递输入。
+`collections` 计数与 `omitted` 明确表达发现不完整。近期抽样不能证明没有更早的待处理
+或相关输入。读取相关固定 wake 与原始 Message；更广的需求/历史审计使用分类发现。
+
+## 预算与续读
+
+- 发现页默认 20 条，可选 1–100，紧凑 JSON 预算 32 KiB。条目包含摘要，不含完整报告正文。
+- 当前 Task Context 至多 64 条，记录与 attention 共 24 KiB，响应预算 32 KiB。
+  单个内联值至多 2 KiB；大值及 Message/Run/WorkItem/Knowledge 正文用引用。
+  入口每个集合最多抽样八条。
+- Global 入口分别抽样八条 pending 与八条 recent；独立续读，历史不能挤掉待处理输入。
+- 不超过 16 KiB 的详情保持普通 JSON。更大详情返回 `contentPage`：确切来源、
+  SHA-256 digest、JSON 字符偏移、总字节数/字符数、文本、完整性与下一游标。
+  每块最多 4096 个 UTF-16 单元，不拆代理对，转义后的输出低于 32 KiB。
+  不再因 4 MiB 上限而永久无法读取合法原文。
+- Task 元信息/next-action/remote-delivery、Brief、WorkItem、Message、Run、
+  决策/里程碑/事件、Role show/status/Session 检查、wake 详情、InputRequest、
+  Run Context 与冻结展开使用有界详情读取。
+
+使用 `--json` 读取顶层 `data`；Run Context 和展开使用 `data.context`，Run Context delta 使用 `data.contextDelta`。
+长详情用同一读取命令加 `--cursor <contentPage.nextCursor>` 继续。按 offset 顺序拼接
+`text`，校验相同 source 与 digest，最后一次性解析 JSON。不要分别解析块，也不要把
+第一块当成完整报告。
+
+列表包含 `items`、`total`、`complete`、`nextCursor`。计数、条目和游标校验处于同一
+授权范围。游标是不透明位置，不是通行令牌：每页重新授权。集合或文档改变时明确报错，
+重新读取，不混合版本；无需持久分页 Session。可变集合不保证并发写入期间无中断遍历。
+追加事件遍历使用固定上界 Context delta。目前分类发现扫描选定的授权集合来计算指纹；
+有界的是输出，不是总存储读取成本。
+
+## 效果与例外
+
+Message send/queue/steer 回执保留身份、digest、正文字节数及原有提交/投递/control
+状态，不回显正文。Brief 更新返回 saved 引用。没有新增等待、重试、确认或审批阶段。
+重复读游标绝不能重放变更。
+
+激活、完成、集成和输入控制仍是完整事务业务操作，即使内部有多步工程机制。
+其特定状态回执与已有未知效果诊断保留，不压平成通用“已执行”标志。
+
+本次覆盖日常 Agent Context、协作发现和原始证据读取，并非产品全部诊断或导出。
+既有日志尾部/artifact 限制、Task 目录分页、有界错误诊断保留各自契约。
+配置目录、Project/config 管理、资源清单、归档诊断、发布操作和专用集成/change-set
+读取仍有自己的用途契约；不宣称它们全部受 32 KiB 限制。Web 全详情投影是独立消费者，
+不会被 CLI 摘要悄悄替代。大 Project Knowledge 与 Task 证据用定向 Context 发现。
+
+典型通知读取一次当前 Context、一次固定 wake，再逐条读取相关原文（或其全部文档页）。
+不要为了入口故意省略的详情重复读聚合。只有原文超过内联预算才增加原文分页调用；
+摘要不能代替完整原文。