@zq-silk/yui 1.1.2 → 2.1.0

package/dist/errors/cliError.js

@@ -11,8 +11,8 @@ export class CliError extends Error {
     helpText;
     details;
     exitCode;
-    constructor(code, message, helpText, details = {}) {
-        super(message);
+    constructor(code, message, helpText, details = {}, options) {
+        super(message, options);
         this.code = code;
         this.helpText = helpText;
         this.details = details;
@@ -35,6 +35,6 @@ export function agentNotFound(id) {
 export function dataError(message) {
     return new CliError("DATA_ERROR", message);
 }
-export function runtimeError(message) {
-    return new CliError("RUNTIME_ERROR", message);
+export function runtimeError(message, options) {
+    return new CliError("RUNTIME_ERROR", message, undefined, {}, options);
 }

package/dist/errors/cliFailure.js

@@ -0,0 +1,213 @@
+import { ControllerClientError } from "../core/controllerClient.js";
+import { ManagedRuntimeDriftError } from "../runtime/managedCaller.js";
+import { redactAgentErrorText } from "../runtime/agentError.js";
+import { CommandExecutionError } from "../tmux/commandExecutor.js";
+import { StorageRecordError, StorageConflictError } from "../storage/taskStore.js";
+import { CliError } from "./cliError.js";
+const RECONCILE = "The operation may have applied; effects are not confirmed by this error. "
+    + "Do not replay a write or change its request-id. Read the original Task, Message, operation and receipt "
+    + "records using their existing identities before choosing recovery.";
+const INSPECT = "Run `yui doctor` and `yui controller status --verbose` with the same YUI_HOME and matching CLI. ";
+const IDENTITY = "Verify the Home and CLI with `yui version`, `yui controller identity` and `yui doctor`. "
+    + "Ask the Operator or user to restore the matching installation/Controller if needed; do not edit identity records.";
+const SESSION = "Use the supplied Session Manifest and exact CLI entry. Read the current scoped context if permitted; "
+    + "ask the Operator to inspect/re-enter the current Session if identity cannot be verified. "
+    + "Do not forge environment identity, edit the Manifest, or continue writes from a replaced Session.";
+/** Presentation only: no filesystem reads, subprocesses, probes, retries or state changes. */
+export function describeCliFailure(error, context = {}) {
+    const clean = (text) => sanitizeFailureText(text, context);
+    const chain = [];
+    const seen = new Set();
+    const pending = [error];
+    let controller;
+    let session = false;
+    let typedCode;
+    while (pending.length > 0 && chain.length < 8) {
+        const current = pending.shift();
+        if (current === undefined || seen.has(current))
+            continue;
+        seen.add(current);
+        if (current instanceof ControllerClientError)
+            controller ??= current;
+        if (current instanceof ManagedRuntimeDriftError)
+            session = true;
+        const code = errorCode(current);
+        if (code !== undefined && code !== "RUNTIME_ERROR")
+            typedCode ??= code;
+        chain.push({
+            name: current instanceof Error ? clean(current.name) : "Error",
+            ...(code === undefined ? {} : { code: clean(code) }),
+            // SyntaxError can quote the offending JSON (including tokens and messages).
+            message: current instanceof SyntaxError
+                ? "Input could not be parsed; raw input omitted."
+                : clean(current instanceof Error ? current.message : typeof current === "string" ? current : "Unknown failure (non-error payload omitted).")
+                    + (current instanceof CommandExecutionError
+                        ? ` Exit status: ${current.exitStatus ?? "unavailable"}.`
+                            + (current.stderr.length === 0 ? "" : ` Stderr: ${clean(current.stderr)}`) : "")
+        });
+        if (current instanceof Error && current.cause !== undefined)
+            pending.push(current.cause);
+        if (current instanceof AggregateError)
+            pending.push(...current.errors.slice(0, 8));
+    }
+    const code = error instanceof CliError ? error.code : "RUNTIME_ERROR";
+    const exitCode = error instanceof CliError ? error.exitCode : 5;
+    const diagnostic = {
+        ...(context.operation === undefined ? {} : { operation: sanitizeFailureText(context.operation, { environment: context.environment }) }),
+        ...(context.home === undefined ? {} : { home: sanitizeFailureText(context.home, { environment: context.environment }) }),
+        ...(context.cli === undefined ? {} : { cli: sanitizeFailureText(context.cli, { environment: context.environment }) }),
+        ...(context.targets === undefined || context.targets.length === 0 ? {} : { targets: context.targets.map(clean) }),
+        causes: chain,
+        ...(controller === undefined ? {} : {
+            controller: {
+                code: controller.code,
+                ...sanitizeFailureDetails(controller.diagnostic ?? {}, context)
+            }
+        })
+    };
+    const guidanceCode = controller?.code ?? typedCode ?? code;
+    const guidance = session ? SESSION
+        : error instanceof StorageRecordError ? recoveryGuidance("STORAGE_SCHEMA_INVALID")
+            : error instanceof StorageConflictError ? "Read the current record and compare the intended change with its new revision before submitting a new authorized mutation."
+                : recoveryGuidance(guidanceCode);
+    const delivery = controller?.diagnostic?.delivery;
+    const effects = controller === undefined
+        ? (code === "USAGE_ERROR" ? "Correct the reported input or prerequisite; this error alone is not a rollback receipt." : RECONCILE)
+        : delivery === "not-sent"
+            ? "This Controller request was not sent. This does not undo any earlier command steps."
+            : delivery === "response-received"
+                ? "The Controller returned an error response; it does not prove rollback of earlier effects. " + RECONCILE
+                : RECONCILE;
+    const help = error instanceof CliError && error.helpText !== undefined ? clean(error.helpText.trimEnd()) : undefined;
+    const message = [
+        ...chain.map((item, index) => `${index === 0 ? "" : "Caused by: "}${item.code === undefined ? "" : `[${item.code}] `}${item.message}`),
+        diagnostic.operation === undefined ? undefined : `Operation: ${diagnostic.operation}`,
+        diagnostic.home === undefined ? undefined : `YUI_HOME: ${diagnostic.home}`,
+        diagnostic.cli === undefined ? undefined : `CLI entry: ${diagnostic.cli}`,
+        diagnostic.targets === undefined ? undefined : `Targets: ${diagnostic.targets.join(", ")}`,
+        controller?.diagnostic === undefined ? undefined
+            : `Controller request: ${clean(controller.diagnostic.method ?? "unknown method")} id=${clean(controller.diagnostic.requestId ?? "unavailable")} delivery=${delivery}`
+                + (controller.diagnostic.socketPath === undefined ? "" : ` socket=${clean(controller.diagnostic.socketPath)}`),
+        effects,
+        guidance,
+        "Recovery commands shown as `yui` must use the same Home and matching CLI entry above; they are not run automatically.",
+        help
+    ].filter((part) => part !== undefined && part.length > 0).join("\n");
+    return {
+        code, exitCode, message,
+        details: {
+            ...(error instanceof CliError ? sanitizeFailureDetails(error.details, context) : {}),
+            diagnostic
+        }
+    };
+}
+export function renderCliFailure(failure, json, jsonCode = failure.code) {
+    return json
+        ? JSON.stringify({ ok: false, code: jsonCode, message: failure.message, details: failure.details })
+        : `${failure.code}: ${failure.message}`;
+}
+function errorCode(error) {
+    if (error === null || typeof error !== "object")
+        return undefined;
+    const code = Reflect.get(error, "code");
+    return typeof code === "string" ? code : undefined;
+}
+function recoveryGuidance(code) {
+    switch (code) {
+        case "CONTROLLER_NOT_RUNNING":
+            return INSPECT + "A missing discovery record is not proof of process exit. If confirmed stopped, run `yui start` through the user or Operator.";
+        case "CONTROLLER_UNAVAILABLE":
+        case "CONTROLLER_DISCOVERY_INVALID":
+            return INSPECT + "Process state is unverified. Inspect the reported process/socket ownership before an authorized `yui controller restart`.";
+        case "CONTROLLER_ACCESS_DENIED":
+        case "EACCES":
+        case "EPERM":
+            return "Inspect filesystem ownership and the sandbox/OS permission boundary. Ask the user or Operator for authorized access; do not alter permissions automatically.";
+        case "CONTROLLER_PROTOCOL_MISMATCH":
+        case "CONTROLLER_IDENTITY_MISMATCH":
+        case "UNAUTHORIZED":
+            return IDENTITY;
+        case "CONTROLLER_TIMEOUT":
+        case "CONTROLLER_DELIVERY_UNKNOWN":
+        case "INVALID_RESPONSE":
+            return INSPECT + "Correlate the request with durable records before recovery; a timeout is not proof that the process exited.";
+        case "CONTROLLER_HANDOVER_FENCED":
+        case "CONTROLLER_HANDOVER_TIMEOUT":
+        case "CONTROLLER_DRAINING":
+        case "SESSION_BUSY":
+            return "Read the current Controller/Session status and existing operation. Let its owner settle the active work; do not start a competing operation.";
+        case "STORAGE_UNINITIALIZED":
+            return "Verify YUI_HOME first. For an intended new empty Home, the user or Operator can run `yui setup`; do not initialize over existing evidence.";
+        case "STORAGE_SCHEMA_INVALID":
+        case "STORAGE_SCHEMA_UNSUPPORTED":
+        case "STORAGE_FORMAT_UNSUPPORTED":
+            return "Run `yui doctor` using this Home and matching CLI. Preserve the database. Use `yui upgrade` only for a diagnosed supported version transition; invalid data needs Operator diagnosis, not reinitialization.";
+        case "COMMAND_NOT_FOUND":
+            return "Inspect `yui doctor` and the configured tool executable/PATH. Have the user or Operator restore the required dependency; no installation was performed by this diagnostic.";
+        case "COMMAND_FAILED":
+        case "COMMAND_TIMED_OUT":
+            return "Inspect the command cause, exit status and dependency checks with `yui doctor`. A spawn failure alone does not establish missing execute permission; timeout does not prove external effects were undone.";
+        case "USAGE_ERROR":
+        case "INVALID_PARAMS":
+        case "INVALID_REQUEST":
+        case "MESSAGE_TOO_LARGE":
+        case "METHOD_NOT_FOUND":
+            return "Use the command's `--help` and correct its arguments/configuration within the existing authority. Do not bypass scope or validation checks.";
+        case "TASK_NOT_FOUND":
+        case "ROLE_NOT_FOUND":
+        case "AGENT_NOT_FOUND":
+        case "NOT_FOUND":
+        case "DATA_ERROR":
+            return "Verify the named record, prerequisites and current Home using the corresponding show/list/context command. Do not invent or recreate missing state from this error alone.";
+        default:
+            return "The root cause cannot be confirmed from this error alone. Preserve the operation identity and safe cause details; "
+                + "inspect its current records/status and command help, then ask the responsible Agent or Operator to diagnose. No automatic repair or safe retry is implied.";
+    }
+}
+export function sanitizeFailureText(text, context = {}) {
+    const secrets = [
+        ...(context.privateValues ?? []),
+        ...Object.entries(context.environment ?? process.env).filter(([name]) => /token|secret|password|passwd|cookie|credential|api_?key|private_?key/i.test(name)).map(([, value]) => value ?? "")
+    ].filter(value => value.length > 0).sort((a, b) => b.length - a.length);
+    let safe = text;
+    for (const value of secrets) {
+        // Short invalid operands must not replace every character of a diagnostic.
+        const escapedValue = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        safe = value.length < 4
+            ? safe.replace(new RegExp(`(?<![\\w])${escapedValue}(?![\\w])`, "g"), "[REDACTED]")
+            : safe.split(value).join("[REDACTED]");
+        const escaped = JSON.stringify(value).slice(1, -1);
+        if (escaped !== value)
+            safe = safe.split(escaped).join("[REDACTED]");
+    }
+    safe = redactAgentErrorText(safe)
+        .replace(/(\b(?:token|credential|body|prompt|content|input)(?:["']?\s*[=:]\s*))("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;}]+)/gi, "$1[REDACTED]")
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@[^\s/]+/gi, "$1[REDACTED]@host")
+        .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/g, "[REDACTED]")
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "?");
+    return safe.length > 12_000 ? safe.slice(0, 12_000) + "…[truncated]" : safe;
+}
+/** Keep existing detail fields, but never dump secret/payload fields or Error internals. */
+export function sanitizeFailureDetails(details, context = {}) {
+    const seen = new Set();
+    const visit = (value, depth) => {
+        if (typeof value === "string")
+            return sanitizeFailureText(value, context);
+        if (value === null || typeof value === "number" || typeof value === "boolean")
+            return value;
+        if (typeof value !== "object")
+            return undefined;
+        if (depth > 32 || seen.has(value))
+            return "[omitted]";
+        seen.add(value);
+        const result = Array.isArray(value) ? value.map(item => visit(item, depth + 1))
+            : Object.fromEntries(Object.entries(value).map(([key, item]) => [
+                key, /token|secret|password|passwd|cookie|credential|authorization|api.?key|private.?key|environment|^env$|^body$|^payload$|^prompt$|^argv$|^args$/i.test(key)
+                    ? "[REDACTED]" : visit(item, depth + 1)
+            ]));
+        seen.delete(value);
+        return result;
+    };
+    return visit(details, 0);
+}

package/dist/executor/fileRoleLaunchPlanner.js

@@ -354,8 +354,7 @@ export class FileRoleLaunchPlanner {
             developerInstructions: `Read and follow the exact Yui Session Manifest at ${bootstrap.manifestPath}.`,
             managedContextFile: bootstrap.manifestPath,
             sessionManifestPath: bootstrap.manifestPath,
-            sessionManifestDigest: bootstrap.manifest.digest,
-            sessionCliPath: bootstrap.sessionCliPath
+            sessionManifestDigest: bootstrap.manifest.digest
         };
         const managedRun = owner.scope === "task" && input.runId !== undefined
             ? this.store.getRun(owner.taskId, input.runId)
@@ -413,7 +412,6 @@ export class FileRoleLaunchPlanner {
         const compiled = managedCompiled;
         for (const path of [
             bootstrap.manifestPath,
-            bootstrap.sessionCliPath,
             bootstrap.roleProfilePath
         ]) {
             this.#resourceRegistrar().registerSessionContext(path, {
@@ -557,7 +555,6 @@ export class FileRoleLaunchPlanner {
                 YUI_DRIVER_ID: driver.id,
                 YUI_WORKSPACE: effectiveWorkspace,
                 YUI_SESSION_MANIFEST: sessionContext.sessionManifestPath,
-                YUI_SESSION_CLI: sessionContext.sessionCliPath,
                 ...(configured.adapterId === "codex"
                     ? { YUI_AGENT_BASE_ARGS: JSON.stringify(configured.baseArgs) }
                     : {}),

package/dist/grant/capabilityGrant.js

@@ -13,6 +13,7 @@ export function createCapabilityGrant(id, taskId, input, now) {
         id: validateTaskRecordReference({ taskId, localId: id }, "capabilityGrant").localId,
         taskId: requireIdentity(taskId, "Task id"),
         granter: requireText(input.granter, "Capability grant granter"),
+        ...(input.authorizationSource === undefined ? {} : { authorizationSource: input.authorizationSource }),
         scope: normalizeScope(input.scope, taskId),
         actions: normalizeActions(input.actions),
         parameterBounds: normalizeParameterBounds(input.parameterBounds),
@@ -110,6 +111,18 @@ export function validateCapabilityGrant(grant) {
     validateTaskRecordReference({ taskId: grant.taskId, localId: grant.id }, "capabilityGrant");
     requireIdentity(grant.taskId, "Task id");
     requireText(grant.granter, "Capability grant granter");
+    if (grant.authorizationSource !== undefined) {
+        const source = grant.authorizationSource;
+        if (typeof source !== "object" || source === null
+            || Object.keys(source).sort().join(",") !== "digest,messageId,nativeSessionId,purpose") {
+            throw new Error("Capability grant authorization source is invalid.");
+        }
+        validateTaskRecordReference({ taskId: grant.taskId, localId: source.messageId }, "message");
+        if (!/^[a-f0-9]{64}$/u.test(source.digest))
+            throw new Error("Authorization source digest is invalid.");
+        requireText(source.purpose, "Authorization purpose");
+        requireText(source.nativeSessionId, "Authorization native Session");
+    }
     validateScope(grant.scope, grant.taskId);
     normalizeActions(grant.actions);
     normalizeParameterBounds(grant.parameterBounds);

package/dist/grant/taskAuthorization.js

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { relative, isAbsolute } from "node:path";
+import { usageError } from "../errors/cliError.js";
+import { currentManagedRuntime } from "../runtime/managedCaller.js";
+export function taskAuthorizationSource(store, taskId, environment, messageId, purpose) {
+    const caller = currentManagedRuntime(store, environment, taskId, "leader");
+    if (caller?.executionAuthority !== "delivery") {
+        throw usageError("Authorization requires this Task's current delivery Leader Session.");
+    }
+    const task = store.getTask(taskId);
+    if (!task || task.status === "archived" || task.status === "draft"
+        || task.executionGate?.state === "stopped") {
+        throw usageError("Task authorization is unavailable in this lifecycle or execution gate.");
+    }
+    const message = store.listMessages(taskId).find(entry => entry.id === messageId);
+    if (!message || !((message.kind === "user" && message.author.type === "user")
+        || (message.kind === "operator" && message.author.type === "operator"))) {
+        throw usageError("Name an original user or Operator authorization Message in this Task with --source-message; a Role report is not user authority.");
+    }
+    if (!purpose?.trim() || !message.body.includes(purpose.trim())) {
+        throw usageError("--purpose must quote the original explicit authorization verbatim; an Agent's paraphrase is not source evidence.");
+    }
+    return {
+        messageId: message.id,
+        // Delivery receipts can settle after admission; they do not change what
+        // the user said. Bind the original author/content identity, not transport.
+        digest: createHash("sha256").update(JSON.stringify({
+            taskId: message.taskId, id: message.id, kind: message.kind,
+            author: message.author, body: message.body, createdAt: message.createdAt
+        })).digest("hex"),
+        purpose: purpose.trim(),
+        nativeSessionId: caller.nativeSessionId
+    };
+}
+const RELEASE_ACTIONS = new Set([
+    "pr-create-or-reuse", "ci-confirm", "merge", "version-tag",
+    "npm-publish", "fresh-install-smoke", "post-verify"
+]);
+const TASK_ACTIONS = new Set([...RELEASE_ACTIONS, "plugin.execute", "resource.local.read", "resource.local.write"]);
+/** Leader grants cannot silently become global grants. Domain consumers still
+ * enforce the exact bounds, digest, uses, expiry and irreversible ceiling. */
+export function assertLeaderGrantBounds(store, grant, now) {
+    const task = store.getTask(grant.taskId);
+    if (task.status !== "active" || task.executionGate?.state !== "enabled") {
+        throw usageError("New Leader grants require an active Task with execution enabled.");
+    }
+    if (!grant.expiresAt || Date.parse(grant.expiresAt) <= now.getTime() || !grant.maxUses) {
+        throw usageError("Leader grants require a future --expires-at and finite --max-uses.");
+    }
+    if (grant.scope.taskId !== grant.taskId
+        || grant.scope.projectIds?.some(id => !task.projectBindings.some(binding => binding.projectId === id))
+        || grant.actions.some(action => !TASK_ACTIONS.has(action))) {
+        throw usageError("Grant exceeds this Task's Project or action authority; global operations require Operator.");
+    }
+    const bounds = (names) => {
+        for (const name of names) {
+            if (!grant.parameterBounds[name]?.length)
+                throw usageError(`Leader grant requires exact --param ${name}=... bounds.`);
+        }
+    };
+    if (grant.actions.some(action => RELEASE_ACTIONS.has(action))) {
+        bounds(["sourceCommit"]);
+        if (grant.actions.includes("post-verify"))
+            bounds(["command"]);
+        if (grant.parameterBounds.sourceCommit.some(commit => !/^[a-f0-9]{40}$/u.test(commit))) {
+            throw usageError("Release sourceCommit bounds must be exact 40-hex commits.");
+        }
+        if (!grant.scope.projectIds?.length || !grant.scope.repositories?.length || grant.scope.homePath) {
+            throw usageError("Release grants require explicit Project/repository scope and cannot target a Home.");
+        }
+        const repositories = grant.scope.projectIds.map(id => store.getProject(id)?.remoteUrl)
+            .map(url => url?.replace(/\.git$/u, "").match(/[:/]([^/:]+\/[^/]+)$/u)?.[1]);
+        if (grant.scope.repositories.some(repo => !repositories.includes(`${repo.owner}/${repo.name}`))) {
+            throw usageError("Repository is outside the selected Task Projects.");
+        }
+        if (grant.actions.some(action => ["npm-publish", "fresh-install-smoke", "version-tag"].includes(action)))
+            bounds(["version"]);
+        if (grant.parameterBounds.version?.some(version => !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(version))) {
+            throw usageError("Release version bounds must name concrete versions, not tags or ranges.");
+        }
+        if (grant.actions.some(action => ["npm-publish", "fresh-install-smoke"].includes(action))
+            && !grant.scope.packages?.length)
+            throw usageError("Package effects require explicit --scope-package.");
+    }
+    if (grant.actions.includes("plugin.execute")) {
+        bounds(["pluginId", "digest", "environmentRef", "trust", "phase"]);
+        if (grant.parameterBounds.environmentRef.some(ref => !ref.startsWith(`${grant.taskId}/`))
+            || grant.parameterBounds.trust.some(trust => trust !== "trusted-local")
+            || grant.parameterBounds.phase.some(phase => !["build", "validate", "activate", "call"].includes(phase))) {
+            throw usageError("Plugin grant has an out-of-Task environment, trust or phase.");
+        }
+    }
+    if (grant.actions.some(action => action.startsWith("resource.local."))) {
+        bounds(["resourceId"]);
+        if (!grant.scope.homePath)
+            throw usageError("Local resource grants require an exact canonical --scope-home path.");
+        const path = assertTaskLocalResourcePath(store, grant.scope.homePath);
+        if (grant.parameterBounds.resourceId.some(id => store.getLocalResource(id)?.path !== path)) {
+            throw usageError("Resource identity does not match the authorized canonical path.");
+        }
+    }
+    else if (grant.scope.homePath) {
+        throw usageError("A Leader cannot grant Home access.");
+    }
+}
+export function assertTaskLocalResourcePath(store, path) {
+    const canonical = realpathSync(path);
+    if (canonical !== path)
+        throw usageError("Use the exact canonical resource directory path.");
+    const overlaps = (other) => {
+        const contains = (parent, child) => {
+            const rel = relative(parent, child);
+            return rel === "" || (rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel));
+        };
+        return contains(canonical, other) || contains(other, canonical);
+    };
+    const protectedPaths = [
+        realpathSync(store.rootDirectory()), ...store.listProjects().map(project => project.path),
+        ...store.listTasks().flatMap(task => store.listManagedWorkspaces(task.id)
+            .flatMap(workspace => [workspace.root, ...workspace.entries.map(entry => entry.path)]))
+    ];
+    if (protectedPaths.some(overlaps)) {
+        throw usageError("Resource overlaps a Yui Home, stable Project or managed workspace; use its existing authority.");
+    }
+    return canonical;
+}

package/dist/kernel/accessAssessment.js

@@ -0,0 +1 @@
+export {};

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,13 +443,43 @@ 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;
             throw new Error(`Permission unavailable: ${permission}.`);
         }
         return { taskIds: [task.id], projectIds: task.projectBindings.map((binding) => binding.projectId) };
-    }, BUILTIN_CAPABILITIES);
+    }, BUILTIN_CAPABILITIES, (context, descriptor, input) => {
+        const caller = current(context);
+        const params = input;
+        const via = caller.scope === "global" ? "operator"
+            : caller.role === "leader" ? "leader-input" : "leader-message";
+        const forCaller = (access) => caller.scope === "user" && access.state === "requestable" ? { state: "hidden" } : access;
+        const pluginAccess = plugins.assess(context.targetId, descriptor, input, via);
+        if (pluginAccess)
+            return forCaller(pluginAccess);
+        if (input === undefined)
+            return undefined;
+        if (descriptor.name === "resource.local.read") {
+            return forCaller(resources.assessLocalAccess(context.targetId, params.resourceId, "read", via));
+        }
+        if (descriptor.name === "environment.prepare") {
+            const plan = params.plan;
+            return plan.kind === "local"
+                ? forCaller(resources.assessLocalAccess(context.targetId, plan.resourceId, plan.access, via))
+                : { state: "authorized" };
+        }
+        if (descriptor.name === "task.read" || descriptor.name === "config.read"
+            || descriptor.name === "resource.workspaces" || descriptor.name === "environment.list") {
+            return { state: "authorized" };
+        }
+        // Other domain operations retain their exact execution checks. Do not
+        // claim target authorization from a descriptor's coarse permission alone.
+        return undefined;
+    });
     const plugins = createPluginService(store, host, registry);
     return {
         registry,