@zq-silk/yui 1.1.0 → 2.0.0

package/dist/kernel/builtinCapabilities.js

@@ -1,8 +1,10 @@
+import { assertTaskLocalResourcePath, taskAuthorizationSource } from "../grant/taskAuthorization.js";
+import { createTaskEvent } from "../event/taskEvent.js";
 import { listArtifactsCapability, readArtifactCapability, saveArtifactCapability } from "../artifacts/artifactCapability.js";
 import { runConfigCommand } from "../commands/configCommands.js";
 import { sendTaskMessageCommand, updateTaskMetadataCommand } from "../commands/taskCommands.js";
 import { CONFIG_DOMAINS } from "../config/configCatalog.js";
-import { inspectTaskContext, readTaskContext, readTaskContextDelta, withContextObservations } from "../context/taskContext.js";
+import { inspectTaskContext, listTaskContext, readTaskContext, readTaskContextDelta, withContextObservations } from "../context/taskContext.js";
 import { createJobCallAuthority, parseDurableJobStartParams } from "../controller/jobControl.js";
 import { inspectJobOperation } from "../job/jobOperation.js";
 import { assertJobAssignmentScope } from "../job/jobAssignmentScope.js";
@@ -41,11 +43,18 @@ const definitions = [
         inputSchema: object({ taskId: text, after: text, continuation: text, limit: { type: "integer" } }, ["taskId", "after"]),
         outputSchema: { type: "object", required: ["events", "throughCursor"] }
     },
+    {
+        name: "context.list", summary: "Discover one authorized record family with bounded summaries and exact references.",
+        effect: "query", requiredPermissions: ["task:read"], source: "listTaskContext",
+        inputSchema: object({ taskId: text, store: text, cursor: text, limit: { type: "integer" },
+            status: text, after: text, workItemId: text }, ["taskId", "store"]),
+        outputSchema: { type: "object", required: ["items", "total", "complete", "nextCursor"] }
+    },
     {
         name: "context.inspect", summary: "Expand an authorized current record; optionally require its exact digest.",
         effect: "query", requiredPermissions: ["task:read"], source: "inspectTaskContext",
-        inputSchema: object({ taskId: text, store: text, refId: text, digest: text }, ["taskId", "store", "refId"]),
-        outputSchema: { type: "object", required: ["ref", "value", "coreCursor"] }
+        inputSchema: object({ taskId: text, store: text, refId: text, digest: text, cursor: text }, ["taskId", "store", "refId"]),
+        outputSchema: { type: "object" }
     },
     {
         name: "artifact.save", summary: "Save a file artifact by relativePath into the Task's local Git repository; returns a commit-pinned reference.",
@@ -94,9 +103,14 @@ const definitions = [
         inputSchema: taskInput, outputSchema: { type: "array", items: recordOutput }
     },
     {
-        name: "resource.local.register", summary: "Register a user-owned local directory by canonical identity (Operator); registration does not grant use.",
+        name: "task.archive", summary: "Archive this terminal Task with original user authorization; may end the requesting Leader Session. Inspect durable archive receipts after interrupted delivery.",
+        effect: "local-mutation", requiredPermissions: ["task:manage"], source: "LeaderArchive",
+        inputSchema: object({ taskId: text, sourceMessage: text, purpose: text }), outputSchema: recordOutput
+    },
+    {
+        name: "resource.local.register", summary: "Register a user-owned local directory by canonical identity (Operator or source-authorized Task Leader); registration does not grant use.",
         effect: "local-mutation", requiredPermissions: ["resource:register"], source: "ProjectResources.registerLocalDirectory",
-        inputSchema: object({ displayName: text, path: text }), outputSchema: recordOutput
+        inputSchema: object({ displayName: text, path: text, sourceMessage: text, purpose: text }, ["displayName", "path"]), outputSchema: recordOutput
     },
     {
         name: "resource.local.read", summary: "Read an explicitly granted local resource.",
@@ -217,7 +231,7 @@ export const BUILTIN_CAPABILITIES = definitions.map((entry) => ({
 }));
 /** One registry with separate managed credentials and in-process Web query
  * issuance. Socket possession or caller-scope JSON never issues a Web context. */
-export function createBuiltinCapabilities(host, store, jobs, signal = () => undefined, contextProviders = []) {
+export function createBuiltinCapabilities(host, store, jobs, signal = () => undefined, contextProviders = [], archiveTask) {
     const authority = createJobCallAuthority(store);
     const resources = createProjectResources(store);
     const callers = new WeakMap();
@@ -243,6 +257,16 @@ export function createBuiltinCapabilities(host, store, jobs, signal = () => unde
                 throw new Error("Capability target is outside the authenticated Task.");
             }
             const taskId = invocation.context.targetId;
+            if (name === "task.archive") {
+                if (!archiveTask)
+                    throw new Error("Controller archive execution is unavailable.");
+                if (!invocation.requestId)
+                    throw new Error("Archive requires a stable requestId.");
+                return archiveTask(taskId, callerEnvironment(caller), {
+                    sourceMessage: params.sourceMessage, purpose: params.purpose,
+                    requestId: invocation.requestId
+                });
+            }
             if (name === "message.send") {
                 // A managed Task Session resolves to Leader/role authority and never
                 // gains develop from an intent argument; only a global Operator Session
@@ -277,9 +301,16 @@ export function createBuiltinCapabilities(host, store, jobs, signal = () => unde
                     after: params.after, continuation: params.continuation,
                     limit: params.limit
                 }, callerEnvironment(caller));
+            if (name === "context.list")
+                return listTaskContext(store, taskId, params.store, {
+                    cursor: params.cursor, limit: params.limit,
+                    status: params.status, after: params.after,
+                    workItemId: params.workItemId
+                }, callerEnvironment(caller));
             if (name === "context.inspect")
                 return inspectTaskContext(store, taskId, {
-                    store: params.store, refId: params.refId, digest: params.digest
+                    store: params.store, refId: params.refId, digest: params.digest,
+                    cursor: params.cursor
                 }, callerEnvironment(caller));
             // File/directory artifacts live in the Task's local Git repository, not
             // the DB. Save commits exactly one path and returns a self-certifying
@@ -316,7 +347,18 @@ export function createBuiltinCapabilities(host, store, jobs, signal = () => unde
             if (name === "environment.list")
                 return store.listEnvironmentPreparations(taskId);
             if (name === "resource.local.register")
-                return resources.registerLocalDirectory(params.displayName, params.path);
+                return store.transaction(tx => {
+                    const source = caller.scope === "task"
+                        ? taskAuthorizationSource(tx, taskId, callerEnvironment(caller), params.sourceMessage, params.purpose)
+                        : undefined;
+                    if (source)
+                        assertTaskLocalResourcePath(tx, params.path);
+                    const resource = resources.registerLocalDirectory(params.displayName, params.path);
+                    if (source)
+                        tx.saveEvent(taskId, createTaskEvent(tx.nextEventId(taskId), taskId, "resource.local.registered", { resourceId: resource.id, path: resource.path,
+                            authorizationSource: JSON.stringify(source) }, new Date()));
+                    return resource;
+                });
             if (name === "resource.local.read")
                 return resources.readLocalResource(taskId, params.resourceId);
             if (name === "project.context")
@@ -375,6 +417,13 @@ export function createBuiltinCapabilities(host, store, jobs, signal = () => unde
             throw new Error("Capability target is outside the authenticated Task.");
         }
         for (const permission of descriptor?.requiredPermissions ?? []) {
+            if (caller.scope === "task" && descriptor?.effect !== "query"
+                && ["task:manage", "plugin:manage", "resource:register"].includes(permission)) {
+                const sessions = store.getTaskRoleSessionSet(task.id, caller.role);
+                if (sessions?.sessions[sessions.activeAgentId]?.effective.executionAuthority !== "delivery") {
+                    throw new Error("Planning Sessions cannot mutate delivery environments or plugins.");
+                }
+            }
             if (permission === "job:start" && caller.scope === "task") {
                 const sessions = store.getTaskRoleSessionSet(task.id, caller.role);
                 if (sessions?.sessions[sessions.activeAgentId]?.effective.executionAuthority !== "delivery") {
@@ -394,6 +443,9 @@ export function createBuiltinCapabilities(host, store, jobs, signal = () => unde
             // adopted environments and exact plugin.execute grants remain separate.
             if (permission === "plugin:manage" && caller.scope === "task" && caller.role === "leader")
                 continue;
+            if (permission === "resource:register" && descriptor?.name === "resource.local.register"
+                && caller.scope === "task" && caller.role === "leader")
+                continue;
             if ((permission === "config:read" || permission === "plugin:manage" || permission === "resource:register")
                 && caller.scope === "global" && caller.role === "operator")
                 continue;

package/dist/kernel/kernelPorts.js

@@ -6,14 +6,14 @@ import { InstanceHost } from "./instanceHost.js";
  * another Controller, or provide arbitrary persistence to plugin code.
  * T02 registers contributions on this Host and wraps this same Job control.
  */
-export function createKernelPorts(store, runner, signal = () => undefined, contextProviders = []) {
+export function createKernelPorts(store, runner, signal = () => undefined, contextProviders = [], archiveTask) {
     const host = new InstanceHost();
     const runnerImplementation = host.attach(JOB_RUNNER_IMPLEMENTATION, runner);
     const runnerHandle = host.acquire(runnerImplementation);
     const jobImplementation = host.attach({ id: "yui:job-control", generation: "1" }, createDurableJobControl(store));
     // The Controller is a long-lived consumer of this exact implementation.
     const jobHandle = host.acquire(jobImplementation);
-    const capabilities = createBuiltinCapabilities(host, store, jobHandle.value, signal, contextProviders);
+    const capabilities = createBuiltinCapabilities(host, store, jobHandle.value, signal, contextProviders, archiveTask);
     return {
         host,
         capabilities,

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) |