@zq-silk/yui 1.1.0 → 2.0.0

package/dist/doctor/ptyProbe.js

@@ -0,0 +1,74 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+/** Native loading and spawn happen outside Doctor: a native abort cannot kill the CLI. */
+export function inspectPty(options = {}) {
+    const started = Date.now();
+    const checks = [];
+    const major = Number(process.versions.node.split(".")[0]);
+    if (![20, 22, 24, 26].includes(major)) {
+        checks.push({
+            name: "pty Node runtime", status: "unsupported",
+            detail: `Node ${process.versions.node} is outside Yui's supported Node 20/22/24/26 range; this is not evidence of a helper permission failure.`
+        });
+    }
+    let entry;
+    let identity;
+    try {
+        const require = createRequire(options.requireFrom ?? import.meta.url);
+        entry = require.resolve("node-pty");
+        const manifest = require.resolve("node-pty/package.json");
+        const version = JSON.parse(readFileSync(manifest, "utf8")).version;
+        identity = `node-pty ${version}; entry=${entry}; package=${manifest}`;
+    }
+    catch (error) {
+        return [...checks, {
+                name: "node-pty",
+                status: error.code === "MODULE_NOT_FOUND" ? "missing" : "invalid",
+                detail: `Dependency resolution failed: ${String(error)}`
+            }];
+    }
+    const timeoutMs = options.timeoutMs ?? 1_500;
+    const result = spawnSync(process.execPath, [
+        fileURLToPath(new URL("./ptyProbeChild.js", import.meta.url)),
+        entry, String(options.probeTimeoutMs ?? 750)
+    ], {
+        // No NODE_OPTIONS, shell startup files, preload hooks or user configuration.
+        env: { PATH: "/usr/bin:/bin", LANG: "C" },
+        cwd: "/",
+        encoding: "utf8",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer: 64 * 1024
+    });
+    for (const line of (result.stdout ?? "").split("\n").filter(Boolean)) {
+        try {
+            const check = JSON.parse(line);
+            if (["node-pty", "pty helper", "pty spawn"].includes(check.name)
+                && ["ok", "missing", "invalid"].includes(check.status)
+                && typeof check.detail === "string") {
+                checks.push({ ...check, detail: `${identity}; ${check.detail}` });
+            }
+        }
+        catch { /* Native diagnostics on stdout are retained below on failure. */ }
+    }
+    const completed = checks.some(check => check.name === "pty spawn")
+        || checks.some(check => check.status !== "ok" && check.name !== "pty Node runtime");
+    if (result.error || result.signal || result.status !== 0 || !completed) {
+        const timedOut = result.error?.code === "ETIMEDOUT";
+        // A partial success line is not success if the isolated process failed to finish.
+        for (let i = 0; i < checks.length; i += 1) {
+            if (checks[i].name === "pty spawn" && checks[i].status === "ok") {
+                checks[i] = { ...checks[i], status: "invalid", detail: `${checks[i].detail}; isolated probe did not finish successfully` };
+            }
+        }
+        checks.push({
+            name: "pty probe", status: "invalid",
+            detail: `${identity}; ${timedOut ? `timeout after ${timeoutMs}ms` : "isolated probe failed"}; exit=${result.status} signal=${result.signal}; ${result.error?.message ?? ""} ${(result.stderr || result.stdout || "").trim()}`
+        });
+    }
+    return checks.map(check => ({
+        ...check, detail: `${check.detail}; elapsed=${Date.now() - started}ms`
+    }));
+}

package/dist/doctor/ptyProbeChild.js

@@ -0,0 +1,90 @@
+import { accessSync, constants, statSync, writeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join } from "node:path";
+const require = createRequire(import.meta.url);
+const entry = process.argv[2];
+const timeoutMs = Number(process.argv[3]);
+const report = (check) => writeSync(1, `${JSON.stringify(check)}\n`);
+const errorDetail = (error) => error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+async function probe() {
+    let pty;
+    try {
+        pty = require(entry);
+        if (typeof pty.spawn !== "function")
+            throw new Error("node-pty does not expose spawn");
+        report({ name: "node-pty", status: "ok", detail: "native module loaded" });
+    }
+    catch (error) {
+        report({
+            name: "node-pty", status: "invalid",
+            detail: `native load failed: ${errorDetail(error)}. If installation reported blocked lifecycle scripts, review npm allow-scripts separately; no install files were changed.`
+        });
+        return;
+    }
+    if (process.platform === "darwin") {
+        // The pinned node-pty selects build/Release, build/Debug or prebuilds.
+        // Inspect the module it actually loaded, not the first helper that exists.
+        const native = Object.keys(require.cache).find(path => basename(path) === "pty.node");
+        if (!native) {
+            report({ name: "pty helper", status: "invalid", detail: "Cannot identify the loaded pty.node; helper path is unverified." });
+            return;
+        }
+        const helper = join(dirname(native), "spawn-helper");
+        let mode = "unknown";
+        try {
+            mode = (statSync(helper).mode & 0o7777).toString(8).padStart(4, "0");
+            accessSync(helper, constants.X_OK);
+            report({ name: "pty helper", status: "ok", detail: `helper=${helper}; mode=${mode}; executable by current user` });
+        }
+        catch (error) {
+            const code = error.code;
+            report({
+                name: "pty helper", status: code === "ENOENT" ? "missing" : "invalid",
+                detail: `helper=${helper}; mode=${mode}; ${code === "EACCES" ? "permission denied for current user" : "helper check failed"}: ${errorDetail(error)}`
+            });
+            return;
+        }
+    }
+    await new Promise(resolve => {
+        const marker = "yui-pty-probe-ok";
+        let terminal;
+        let output = "";
+        let finished = false;
+        const finish = (status, detail, kill = false) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            if (kill && terminal) {
+                try {
+                    terminal.kill("SIGKILL");
+                }
+                catch (error) {
+                    detail += `; cleanup: ${errorDetail(error)}`;
+                }
+            }
+            report({ name: "pty spawn", status, detail });
+            resolve();
+        };
+        const timer = setTimeout(() => finish("invalid", `timeout after ${timeoutMs}ms waiting for output and normal exit`, true), timeoutMs);
+        try {
+            // Absolute, fixed executable; no shell, Node preloads, Agent or account access.
+            terminal = pty.spawn("/bin/echo", [marker], {
+                name: "xterm", cols: 80, rows: 24, cwd: "/",
+                env: { PATH: "/usr/bin:/bin", LANG: "C" }
+            });
+            terminal.onData(data => { output = (output + data).slice(-4096); });
+            terminal.onExit(({ exitCode, signal }) => {
+                const ok = exitCode === 0 && !signal && output.replace(/\r/g, "").trim() === marker;
+                finish(ok ? "ok" : "invalid", `${ok ? "expected output and normal exit confirmed (PTY dependency only; Web Terminal and Provider protocols unverified)" : "unexpected output or exit"}; exit=${exitCode}; signal=${signal ?? 0}; output=${JSON.stringify(output)}`);
+            });
+        }
+        catch (error) {
+            finish("invalid", `spawn failed: ${errorDetail(error)}`, true);
+        }
+    });
+}
+await probe();
+// node-pty's native watcher can retain handles; the fixed child has exited, or
+// was explicitly killed on failure. The parent also bounds native hangs/aborts.
+process.exit(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;
+}