@sema-agent/server 7.51.0 → 7.52.0

package/dist/rules-consent.js

@@ -1,12 +1,32 @@
 import { randomUUID } from "node:crypto";
+import { z } from "zod";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { createLogger } from "./observability/logger.js";
 import { MAX_CWD_CHARS } from "./task-cwd.js";
+import { CONTROL_AND_BIDI_CHARS, hasBidiControls } from "./text-bidi.js";
 import { confirmRuleApproval, parseAllowRuleText, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, } from "@sema-agent/core";
 import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
 export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
 export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
 export const MAX_IMPORT_CANDIDATES = 200;
+export const MAX_LOCAL_IMPORT_ROWS = MAX_IMPORT_CANDIDATES;
+export const MAX_LOCAL_IMPORT_BYTES = 256 * 1024;
+export const LOCAL_IMPORT_CLAIM_LEASE_MS = 60_000;
+const LOCAL_IMPORT_CLAIM_WAIT_MS = RULE_IMPORT_RETRY_AFTER_SEC * 1000;
+const LOCAL_IMPORT_CLAIM_POLL_MS = 25;
+const LocalImportOutcomeSchema = z
+    .object({
+    members: z.array(z
+        .object({
+        key: z.object({ rule: z.string().min(1), scope: z.string().min(1) }).strict(),
+        outcome: z.enum(["persisted", "no-op", "refused", "indeterminate"]),
+        reason: z.enum(["store_refused", "walk_failed"]).optional(),
+        detail: z.string().optional(),
+    })
+        .strict()),
+    rev: z.number().int().nonnegative().safe(),
+})
+    .strict();
 const precheckLogger = createLogger();
 export function precheckCardRuleText(text, command) {
     try {
@@ -21,7 +41,14 @@ export function precheckCardRuleText(text, command) {
     }
 }
 export function serializeRuleScope(scope) {
-    return scope.kind === "global" ? "global" : `project:${scope.root}`;
+    switch (scope.kind) {
+        case "global":
+            return "global";
+        case "project":
+            return `project:${scope.root}`;
+        case "session":
+            throw new Error("serializeRuleScope got a session scope — session consent never lands on the durable rules wire (design/382 §4.3 two-member durable face); a session row reaching this serializer is a defect upstream, not a spelling to invent");
+    }
 }
 export const MAX_RULE_SCOPE_CHARS = "project:".length + MAX_CWD_CHARS;
 export function parseRuleScope(text) {
@@ -122,11 +149,87 @@ function anchorBatchMembers(members, displayed) {
     anchored.sort((a, b) => a.memberIndex - b.memberIndex);
     return { kind: "batch", rules: anchored.map((a) => a.rule), members: anchored };
 }
+function screenLocalImportRow(row) {
+    const scope = parseRuleScope(row.scope);
+    if (scope === undefined) {
+        return { reason: "scope_unreadable", detail: "scope must be 'global' or 'project:<root>' with a non-empty root" };
+    }
+    if (scope.kind === "project" && hasBidiControls(scope.root)) {
+        return {
+            reason: "scope_bidi_controls",
+            detail: "this project root carries bidirectional control characters — the directory a reader sees is not the directory the matcher would use",
+        };
+    }
+    if (scope.kind === "project" && CONTROL_AND_BIDI_DETECT_RE.test(scope.root)) {
+        return {
+            reason: "scope_control_chars",
+            detail: "this project root carries control bytes (C0/DEL) — it is not a path, one SQL dialect refuses to store it at all, and it breaks the separator assumption this lane's comparison keys rest on",
+        };
+    }
+    const pre = precheckCardRuleText(row.rule, row.command);
+    if (pre === undefined) {
+        return { reason: "rule_uncheckable", detail: "the rule text gate could not be asked about this row (its command is absent or not a string) — the row itself is malformed" };
+    }
+    if (!pre.ok)
+        return { reason: "rule_rejected", detail: pre.message };
+    const canonical = parseAllowRuleText(pre.canonicalRule);
+    if ("reject" in canonical) {
+        return { reason: "rule_rejected", detail: `the canonical spelling the engine minted does not re-parse: ${canonical.reject.message}` };
+    }
+    const derived = canonical.rule;
+    if (derived.tool !== row.tool || derived.match !== row.match || derived.command !== row.command) {
+        return {
+            reason: "row_inconsistent",
+            detail: `this row's tool/match/command are derived facts of its rule text, and they disagree: the rule reads as ` +
+                `${derived.tool}/${derived.match}/${JSON.stringify(derived.command)} but the row says ${String(row.tool)}/${String(row.match)}/${JSON.stringify(row.command)}`,
+        };
+    }
+    return { rule: derived.rule, scope };
+}
+const LOCAL_IMPORT_LAYER_PATH = "local-import:rules";
+const CONTROL_AND_BIDI_DETECT_RE = new RegExp(`[${CONTROL_AND_BIDI_CHARS}]`);
+const LOCAL_IMPORT_KEY_SEP = "\u0000";
+function buildLocalImportLayers(candidates) {
+    const byRoot = new Map();
+    for (const c of candidates) {
+        const key = c.scope.kind === "global" ? "" : c.scope.root;
+        const bucket = byRoot.get(key);
+        if (bucket === undefined)
+            byRoot.set(key, [c.rule]);
+        else
+            bucket.push(c.rule);
+    }
+    return [...byRoot].map(([root, rules]) => ({
+        layer: root === "" ? "userSettings" : "projectSettings",
+        path: root === "" ? LOCAL_IMPORT_LAYER_PATH : `${LOCAL_IMPORT_LAYER_PATH}:${root}`,
+        root: root === "" ? "/" : root,
+        readFile: async () => JSON.stringify({ permissions: { allow: rules } }),
+    }));
+}
+function buildLocalImportMembers(members) {
+    return members.map((m) => {
+        const key = { rule: m.rule, scope: serializeRuleScope(m.scope) };
+        switch (m.status) {
+            case "persisted":
+                return { key, outcome: "persisted" };
+            case "deduped":
+                return { key, outcome: "no-op" };
+            case "refused":
+                return { key, outcome: "indeterminate", reason: "store_refused", detail: m.reason };
+            default: {
+                const unknown = m;
+                throw new Error(`unknown redeemed-batch member status: ${JSON.stringify(unknown)}`);
+            }
+        }
+    });
+}
 export function createRuleConsentLane(stores, opts) {
     const deps = { provider: stores.provider, approvals: stores.approvals, cardEdits: true };
     const ticketTtlMs = opts?.ticketTtlMs ?? RULE_IMPORT_TICKET_TTL_MS;
     const newTicketId = opts?.newTicketId ?? (() => randomUUID());
     const monotonic = opts?.monotonic ?? (() => performance.now());
+    const sleep = opts?.sleep ?? (async (ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const localImportLogger = createLogger();
     const anchors = new Map();
     const ANCHOR_CAP = 4096;
     const pruneAnchors = (nowMono) => {
@@ -150,15 +253,24 @@ export function createRuleConsentLane(stores, opts) {
     };
     return {
         async persistCardRule(input) {
-            const prepared = await prepareCardApproval({
-                principal: input.principal,
-                toolName: input.toolName,
-                command: input.command,
-                ...(input.toolCallId !== undefined ? { toolCallId: input.toolCallId } : {}),
-                ...(input.boundInputHash !== undefined ? { boundInputHash: input.boundInputHash } : {}),
-                ...(input.scope !== undefined ? { scope: input.scope } : {}),
-                deps,
-            });
+            let prepared;
+            try {
+                prepared = await prepareCardApproval({
+                    principal: input.principal,
+                    toolName: input.toolName,
+                    command: input.command,
+                    ...(input.toolCallId !== undefined ? { toolCallId: input.toolCallId } : {}),
+                    ...(input.boundInputHash !== undefined ? { boundInputHash: input.boundInputHash } : {}),
+                    ...(input.scope !== undefined ? { scope: input.scope } : {}),
+                    deps,
+                });
+            }
+            catch (err) {
+                if (err.code === "config.missing_scope") {
+                    return { ok: false, reason: "scope-unresolved", detail: err.message };
+                }
+                throw err;
+            }
             if (prepared === undefined) {
                 return { ok: false, reason: "no-candidates", detail: "the rule lane cannot speak for this command (compound / redirection / unsupported tool)" };
             }
@@ -249,19 +361,53 @@ export function createRuleConsentLane(stores, opts) {
                 return { ok: false, reason: "too-many-candidates", candidates: preview.candidates.length };
             }
             const mintedAtMono = monotonic();
-            const minted = await stores.tickets.mint({ ticketId: newTicketId(), principal, approvalId, candidates: preview.candidates, ttlMs: ticketTtlMs });
+            const minted = await stores.tickets.mint({ ticketId: newTicketId(), principal, approvalId, purpose: "cc-import", candidates: preview.candidates, ttlMs: ticketTtlMs });
             pruneAnchors(mintedAtMono);
             anchors.set(minted.ticketId, { mintedAtWall: minted.expiresAtMs - ticketTtlMs, mintedAtMono });
             return { ok: true, preview, ticket: minted.ticketId, expiresAtMs: minted.expiresAtMs };
         },
         async redeemImport(principal, ticket) {
             const clock = decisionClock(ticket);
-            const consumed = await stores.tickets.consume(ticket, principal, clock);
+            const consumeOutcomeAfterThrow = async (err) => {
+                localImportLogger.warn("cc_import_claim_write_failed", {
+                    err: err instanceof Error ? err.message : String(err),
+                    note: "the consume write failed with an ambiguous outcome (it may have committed) — classifying by the ticket's real state instead of surfacing a 500",
+                });
+                let snapshot;
+                try {
+                    snapshot = await stores.tickets.peek(ticket, principal, "cc-import");
+                }
+                catch (peekErr) {
+                    localImportLogger.warn("cc_import_ticket_state_unreadable", {
+                        err: peekErr instanceof Error ? peekErr.message : String(peekErr),
+                        note: "the ticket's state could not be read while classifying a failed consume — answering an explicit ambiguity (503) rather than declaring a terminal outcome or asserting an in-flight redemption",
+                    });
+                    return { ok: false, reason: "state-unreadable", detail: "the ticket's state could not be read while classifying a failed consume" };
+                }
+                if (snapshot === undefined)
+                    return { ok: false, reason: "ticket-unusable", detail: "unknown" };
+                if (snapshot.state === "minted") {
+                    return { ok: false, reason: "state-unreadable", detail: "the consume write did not report its outcome and may still land — the ticket's fate cannot be answered yet" };
+                }
+                if (snapshot.state === "settled") {
+                    localImportLogger.warn("cc_import_ticket_unexpectedly_settled", {
+                        note: "a cc-import ticket reads SETTLED — structurally unreachable (settle is only ever called on the local lane and purpose binding keeps the lanes apart); answering same-shape 404, loudly",
+                    });
+                }
+                return { ok: false, reason: "ticket-unusable", detail: "claim outstanding after a failed consume write" };
+            };
+            let consumed;
+            try {
+                consumed = await stores.tickets.consume(ticket, principal, "cc-import", clock);
+            }
+            catch (err) {
+                return await consumeOutcomeAfterThrow(err);
+            }
             if (!consumed.ok)
                 return { ok: false, reason: "ticket-unusable", detail: consumed.reason };
             const releaseClaim = async () => {
                 try {
-                    return await stores.tickets.release(ticket, principal, RULE_IMPORT_RETRY_AFTER_SEC * 1000, decisionClock(ticket));
+                    return await stores.tickets.release(ticket, principal, consumed.claimId, RULE_IMPORT_RETRY_AFTER_SEC * 1000, decisionClock(ticket));
                 }
                 catch (err) {
                     recordFailOpen("server.rules.ticket-claim-release-failed", err instanceof Error ? err.message : String(err));
@@ -304,6 +450,258 @@ export function createRuleConsentLane(stores, opts) {
                 return await indeterminate(err instanceof Error ? err.message : String(err));
             }
         },
+        async prepareLocalImport(principal, rows) {
+            if (rows.length > MAX_LOCAL_IMPORT_ROWS)
+                return { ok: false, reason: "too-many-rows", rows: rows.length };
+            const bytes = JSON.stringify(rows).length;
+            if (bytes > MAX_LOCAL_IMPORT_BYTES)
+                return { ok: false, reason: "batch-too-large", bytes };
+            const members = [];
+            const admitted = [];
+            const seen = new Set();
+            for (const row of rows) {
+                const screened = screenLocalImportRow(row);
+                if ("reason" in screened) {
+                    members.push({ key: { rule: row.rule, scope: row.scope }, admitted: false, reason: screened.reason, detail: screened.detail });
+                    continue;
+                }
+                const key = { rule: screened.rule, scope: serializeRuleScope(screened.scope) };
+                const dedupKey = `${key.scope}${LOCAL_IMPORT_KEY_SEP}${key.rule}`;
+                if (seen.has(dedupKey)) {
+                    members.push({ key, admitted: false, reason: "duplicate_row", detail: "this (rule, scope) appears earlier in the same batch — the engine would fold the two silently, so it is reported here instead" });
+                    continue;
+                }
+                seen.add(dedupKey);
+                members.push({ key, admitted: true });
+                admitted.push(screened);
+            }
+            if (admitted.length === 0)
+                return { ok: true, preview: { members } };
+            const { preview, approvalId } = await prepareCcImport({ layers: buildLocalImportLayers(admitted), principal, deps });
+            const engineKeys = new Set(preview.candidates.map((c) => `${serializeRuleScope(c.scope)}${LOCAL_IMPORT_KEY_SEP}${c.rule}`));
+            for (let i = 0; i < members.length; i++) {
+                const m = members[i];
+                if (m === undefined || !m.admitted)
+                    continue;
+                if (engineKeys.has(`${m.key.scope}${LOCAL_IMPORT_KEY_SEP}${m.key.rule}`))
+                    continue;
+                const why = preview.skipped.find((s) => s.rule === m.key.rule)?.reason ?? "the engine's import gate did not take it, and said nothing about it";
+                localImportLogger.warn("local_import_row_admitted_but_not_importable", {
+                    rule: m.key.rule,
+                    scope: m.key.scope,
+                    reason: why,
+                    note: "this repository's row gate and core's import gate disagree about this rule — the row is reported refused rather than silently dropped",
+                });
+                members[i] = { key: m.key, admitted: false, reason: "not_importable", detail: why };
+            }
+            if (approvalId === undefined)
+                return { ok: true, preview: { members } };
+            const mintedAtMono = monotonic();
+            const minted = await stores.tickets.mint({ ticketId: newTicketId(), principal, approvalId, purpose: "local-import", candidates: preview.candidates, ttlMs: ticketTtlMs });
+            pruneAnchors(mintedAtMono);
+            anchors.set(minted.ticketId, { mintedAtWall: minted.expiresAtMs - ticketTtlMs, mintedAtMono });
+            return { ok: true, preview: { members }, ticket: minted.ticketId, expiresAtMs: minted.expiresAtMs };
+        },
+        async redeemLocalImport(principal, ticket) {
+            const readSettled = (raw) => {
+                const parsed = LocalImportOutcomeSchema.safeParse(raw);
+                if (!parsed.success) {
+                    throw new Error(`the settled outcome recorded on this import ticket does not carry a readable shape: ${parsed.error.message}`);
+                }
+                return parsed.data;
+            };
+            const tryPeek = async () => {
+                try {
+                    return await stores.tickets.peek(ticket, principal, "local-import");
+                }
+                catch (err) {
+                    localImportLogger.warn("local_import_ticket_state_unreadable", {
+                        err: err instanceof Error ? err.message : String(err),
+                        note: "the ticket's state could not be read while classifying a failure — answering in-flight (retry with the same ticket) rather than declaring a terminal outcome",
+                    });
+                    return "unreadable";
+                }
+            };
+            const unreadableTicketState = () => ({
+                ok: false,
+                reason: "in-flight",
+                detail: "the ticket's state could not be read — retry with the same ticket",
+            });
+            const driveAndSettle = async (approvalId, payloadHash, claimId) => {
+                const tryRelease = async () => {
+                    try {
+                        return await stores.tickets.release(ticket, principal, claimId, RULE_IMPORT_RETRY_AFTER_SEC * 1000, decisionClock(ticket));
+                    }
+                    catch (err) {
+                        recordFailOpen("server.rules.ticket-claim-release-failed", err instanceof Error ? err.message : String(err));
+                        return false;
+                    }
+                };
+                const verdict = async (reason, detail) => {
+                    await tryRelease();
+                    return { ok: false, reason, detail };
+                };
+                const transient = async (detail) => {
+                    const released = await tryRelease();
+                    if (released)
+                        return { ok: false, reason: "record-unusable", detail, retryable: true };
+                    const snapshot = await tryPeek();
+                    if (snapshot === "unreadable")
+                        return unreadableTicketState();
+                    if (snapshot === undefined)
+                        return { ok: false, reason: "record-unusable", detail };
+                    if (snapshot.state === "settled")
+                        return { ok: true, outcome: readSettled(snapshot.outcome), replayed: true };
+                    return { ok: false, reason: "in-flight", detail: `${detail} — the claim could not be handed back, but the ticket is still recoverable; retry with the same ticket` };
+                };
+                let members;
+                let rev;
+                try {
+                    const record = await stores.approvals.get(approvalId);
+                    if (record === undefined)
+                        return await verdict("record-unusable", "the approval record behind this ticket is gone");
+                    if ("staleSchema" in record) {
+                        return await verdict("record-unusable", "this approval record predates the schema:2 form — re-run the import to mint a fresh record");
+                    }
+                    if (buildRulePayloadHash(record.candidates) !== payloadHash) {
+                        return await verdict("payload-mismatch", "the approval record's candidates changed after the ticket was minted");
+                    }
+                    if (record.state === "pending") {
+                        const confirmed = await confirmRuleApproval({ approvalId, principal, deps });
+                        if (!confirmed.ok) {
+                            if (confirmed.reason === "conflict")
+                                return await transient(confirmed.reason);
+                            return await verdict("record-unusable", confirmed.reason);
+                        }
+                    }
+                    const result = await redeemRuleBatch({ approvalId, principal, deps });
+                    if ("status" in result) {
+                        return await transient(result.reason);
+                    }
+                    members = buildLocalImportMembers(result.members);
+                    rev = result.rev;
+                }
+                catch (err) {
+                    return await transient(err instanceof Error ? err.message : String(err));
+                }
+                const outcome = { members, rev };
+                let settled;
+                try {
+                    settled = await stores.tickets.settle(ticket, principal, claimId, outcome);
+                }
+                catch (err) {
+                    localImportLogger.warn("local_import_settle_failed", {
+                        err: err instanceof Error ? err.message : String(err),
+                        note: "the redemption ran but its outcome could not be recorded — answering in-flight so the owner retries and reads the authoritative state, never 500 (which reads as 'nothing happened')",
+                    });
+                    const afterThrow = await tryPeek();
+                    if (afterThrow !== "unreadable" && afterThrow?.state === "settled") {
+                        return { ok: true, outcome: readSettled(afterThrow.outcome), replayed: true };
+                    }
+                    return { ok: false, reason: "in-flight", detail: "the redemption ran but its outcome could not be recorded — retry with the same ticket to read the authoritative state" };
+                }
+                if (settled)
+                    return { ok: true, outcome, replayed: false };
+                const snapshot = await tryPeek();
+                if (snapshot === "unreadable")
+                    return unreadableTicketState();
+                if (snapshot?.state === "settled") {
+                    return { ok: true, outcome: readSettled(snapshot.outcome), replayed: true };
+                }
+                if (snapshot !== undefined) {
+                    localImportLogger.warn("local_import_claim_superseded", {
+                        ticketState: snapshot.state,
+                        note: "this claim was superseded (lease takeover) before it could settle — the local outcome is NOT authoritative and is deliberately not returned; the client retries and reads the canonical settled outcome",
+                    });
+                    return { ok: false, reason: "in-flight", detail: "this redemption's claim was superseded before it settled — retry with the same ticket to read the authoritative outcome" };
+                }
+                localImportLogger.warn("local_import_outcome_not_recorded", {
+                    ticketState: "gone",
+                    note: "the redemption ran and its result is being returned truthfully, but the ticket row is gone so it could not be recorded — a lost response cannot be replayed for this one",
+                });
+                return { ok: true, outcome, replayed: false };
+            };
+            const claimOutcomeAfterThrow = async (err, what) => {
+                localImportLogger.warn("local_import_claim_write_failed", {
+                    op: what,
+                    err: err instanceof Error ? err.message : String(err),
+                    note: "a claim-changing write failed with an ambiguous outcome (it may have committed) — classifying by the ticket's real state instead of surfacing a 500",
+                });
+                const snapshot = await tryPeek();
+                if (snapshot === "unreadable")
+                    return unreadableTicketState();
+                if (snapshot === undefined)
+                    return { ok: false, reason: "ticket-unusable", detail: "unknown" };
+                if (snapshot.state === "settled")
+                    return { ok: true, outcome: readSettled(snapshot.outcome), replayed: true };
+                return { ok: false, reason: "in-flight", detail: `the ${what} write did not report its outcome — retry with the same ticket` };
+            };
+            let consumed;
+            try {
+                consumed = await stores.tickets.consume(ticket, principal, "local-import", decisionClock(ticket));
+            }
+            catch (err) {
+                return await claimOutcomeAfterThrow(err, "consume");
+            }
+            if (consumed.ok)
+                return await driveAndSettle(consumed.approvalId, consumed.payloadHash, consumed.claimId);
+            if (consumed.reason !== "consumed")
+                return { ok: false, reason: "ticket-unusable", detail: consumed.reason };
+            const deadline = monotonic() + LOCAL_IMPORT_CLAIM_WAIT_MS;
+            for (;;) {
+                const snapshot = await tryPeek();
+                if (snapshot === "unreadable")
+                    return unreadableTicketState();
+                if (snapshot === undefined)
+                    return { ok: false, reason: "ticket-unusable", detail: "unknown" };
+                switch (snapshot.state) {
+                    case "settled":
+                        return { ok: true, outcome: readSettled(snapshot.outcome), replayed: true };
+                    case "minted": {
+                        let again;
+                        try {
+                            again = await stores.tickets.consume(ticket, principal, "local-import", decisionClock(ticket));
+                        }
+                        catch (err) {
+                            return await claimOutcomeAfterThrow(err, "consume");
+                        }
+                        if (again.ok)
+                            return await driveAndSettle(again.approvalId, again.payloadHash, again.claimId);
+                        if (again.reason !== "consumed")
+                            return { ok: false, reason: "ticket-unusable", detail: again.reason };
+                        break;
+                    }
+                    case "claimed": {
+                        if (snapshot.claimAgeMs >= LOCAL_IMPORT_CLAIM_LEASE_MS) {
+                            let seized;
+                            try {
+                                seized = await stores.tickets.reclaim(ticket, principal, "local-import", LOCAL_IMPORT_CLAIM_LEASE_MS);
+                            }
+                            catch (err) {
+                                return await claimOutcomeAfterThrow(err, "reclaim");
+                            }
+                            if (seized.ok) {
+                                localImportLogger.warn("local_import_stale_claim_reclaimed", {
+                                    claimAgeMs: snapshot.claimAgeMs,
+                                    leaseMs: LOCAL_IMPORT_CLAIM_LEASE_MS,
+                                    note: "a claim outlived its lease (the replica holding it is presumed gone) — re-driving the batch, which is member-level idempotent",
+                                });
+                                return await driveAndSettle(seized.approvalId, seized.payloadHash, seized.claimId);
+                            }
+                        }
+                        break;
+                    }
+                    default: {
+                        const unknown = snapshot;
+                        throw new Error(`unknown import-ticket state: ${JSON.stringify(unknown)}`);
+                    }
+                }
+                if (monotonic() >= deadline) {
+                    return { ok: false, reason: "in-flight", detail: "another redemption of this ticket is still in flight" };
+                }
+                await sleep(LOCAL_IMPORT_CLAIM_POLL_MS);
+            }
+        },
         async listRules(bucket) {
             const stored = await storeForBucket(stores.provider, bucket).list();
             const rows = stored.rules.map((r) => ({ rule: r.rule, scope: serializeRuleScope(r.scope), tool: r.tool, match: r.match, command: r.command, adds: r.adds }));

package/dist/run-local.js

@@ -245,6 +245,7 @@ export async function runLocal(argv, deps = {}) {
     try {
         fileBackend = new FileStorageBackend({
             root,
+            ...(config.fileHistory !== undefined ? { fileHistory: config.fileHistory } : {}),
             onCorruptRead: (info) => logger.warn("file_store_corrupt_read", {
                 path: info.path,
                 reason: info.reason,

package/dist/runs.d.ts

@@ -122,6 +122,20 @@ export declare function isSessionConflictResult(result: {
  * the directory is unreachable / no resolver is wired → 503 (retry later; the sync leg forwards the
  * result's `retryAfterMs` as body `retryAfterSec`, same family shape as usage.window_exhausted). Exact
  * codes only, no memory.* family grab — an unknown sibling stays a 200-with-failed-body until cataloged.
+ *
+ * design/383 (core 7.0.0 片2/3, S-49 S-3): the session capture opt-out's four prepare-throw refusals ride the
+ * same pipe. `memory.capture_optout_denied` is TERMINAL (the principal's `allowMemoryOptOut` verdict is an
+ * explicit `false`, or the posture is `capture-required` / `governed`-with-absent-verdict — a retry cannot
+ * change it) → 403, the `memory.admission_denied` twin. `memory.capture_optout_unpersisted` is the
+ * declaration arm's "control-plane record could not be written" refusal — a store outage, retry may succeed
+ * → 503 (transient fail-closed, the `memory.admission_required` twin; no retryAfterMs on this one — core
+ * mints none, so the sync leg forwards no hint rather than inventing one). `config.memory_capture_spelling`
+ * is a TaskSpec authoring mistake (the only legal spelling is the string "off") → 400, the
+ * `config.memory_erasure_request` family shape. `config.memory_capture_unsupported` is the DEPLOYMENT SHAPE
+ * refusing the declaration (remote/per-run execution with no durable capture-record carrier: the record
+ * would not survive to a resume replica) → 409 — the request is well-formed, the deployment's state
+ * conflicts with it, the `config.refresh_unavailable` family shape ("change the deployment, not the request").
+ * Status choices are pinned by the `config.`/`memory.` family status sets in error-code-catalog-live.test.ts.
  */
 export declare function resumeAtHttpStatus(result: {
     status: string;
@@ -249,7 +263,7 @@ cascade?: CascadeConfig, instrumentDegenerate?: (result: TaskResult) => void, pl
     record: (scope: string | undefined, objective: string, completed: boolean) => void;
 }, persistThinking?: boolean, inflight?: Map<string, AbortController>, preemptable?: Map<string, AbortController>, steerable?: Map<string, TaskStream>, modelUsage?: ModelUsageTracker, elicitation?: ElicitationCoordinator, 
 /** E23: the VERIFIED principal (gatedPrincipal) that may answer this run's elicitations — matches the respond
- *  owner-gate's identity source (NOT the cost-attribution `principal`, which on a direct door is the spoofable
+ *  owner-gate's identity source (NOT the cost-attribution `principal`, which on a direct door is the self-asserted
  *  header → can be null while a JWT principal exists). Falls back to the run owner when not supplied. */
 elicitOwner?: string | null, 
 /** E18 resume-at: capture the turn's (firstTextEventId → leaf entryId) anchor at each turn_end. Built by the caller

package/dist/runs.js

@@ -73,6 +73,14 @@ export function resumeAtHttpStatus(result) {
         return 403;
     if (result.errorCode === "memory.admission_required")
         return 503;
+    if (result.errorCode === "memory.capture_optout_denied")
+        return 403;
+    if (result.errorCode === "memory.capture_optout_unpersisted")
+        return 503;
+    if (result.errorCode === "config.memory_capture_spelling")
+        return 400;
+    if (result.errorCode === "config.memory_capture_unsupported")
+        return 409;
     if (!(result.errorCode?.startsWith("resume_at.") ?? false))
         return undefined;
     return result.errorCode === "resume_at.not_found" ? 404 : 422;
@@ -176,6 +184,17 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         nowMonotonicMs: performance.now(),
     });
     const legDeadlineMonotonic = approvalLeg.legDeadlineMonotonic;
+    if (approval) {
+        const coordinator = approval.coordinator;
+        spec.onAsk = approvalLeg.windowZero
+            ? () => Promise.resolve(coordinator.unattendedAskOutcome())
+            : coordinator.boundAsk({
+                owner: elicitOwner ?? owner,
+                taskId,
+                ...(spec.sessionId ? { sessionId: spec.sessionId } : {}),
+                ...(approvalLeg.active ? { legKey: "", ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}) } : {}),
+            });
+    }
     const heartbeat = setInterval(() => {
         void runStore.heartbeat(taskId, owner).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
         if (!cancelCtrl.signal.aborted) {

package/dist/runtime-caps-resolver.d.ts

@@ -66,7 +66,7 @@ export interface EntitlementsResolverOpts {
  *  `allowObservers`(observer 开闸线,core 1.270.0/1.273.0):**极性与 allow* 相反** —
  *  core 是 `=== true` 显式 opt-in(默认 OFF,undefined ships dark)。registry-core 0.10.3 起该键已收编进
  *  `EntitlementRuntimeCaps` 类型(此前 0.10.2 走 unknown 宽读透传,现为类型直读,行为零变)。
- *  **缺键=不写键**(绝不把缺键补成显式 false —— core 是唯一默认源,补 false 语义上等价但会伪造「center
+ *  **缺键=不写键**(绝不把缺键补成显式 false —— core 是唯一默认源,补 false 语义上等价但会自造「center
  *  说过话」的显式判决,污染 env-baseline 合成序,见 applyObserverEnvOptIn)。非 boolean 虽然骗不过 core
  *  的 `=== true`(不会误 GRANT),但 PRESENT-非-boolean 与 allow* 同属同一 body 的契约破损信号 → 同款 THROW。
  *
@@ -135,6 +135,41 @@ export declare function createPrincipalEntitlementsClient(opts: EntitlementsReso
 export declare function createEntitlementsResolver(opts: EntitlementsResolverOpts): (principal: string | undefined) => Promise<RuntimeCaps | undefined>;
 /** core's `RunnerDeps.runtimeCapsResolver` seam signature (types.d.ts): sync or async, undefined = no caps. */
 export type EntitlementsResolverFn = (principal: string | undefined) => RuntimeCaps | undefined | Promise<RuntimeCaps | undefined>;
+/**
+ * design/383 §3.1(S-49 S-1 / S-50 §1.2)—— `RuntimeCaps.allowMemoryOptOut` 的 **verdict 源**(本地腿)。
+ * 唯一实现 = `plugins/memory-optout-grant-store-sql.ts`(三层折叠:per-principal 行 → 部署缺省哨兵行 →
+ * 代码缺省 allow,所以健康的源**恒答显式 boolean**;`principal` 缺席=匿名/系统 run,只看缺省行)。
+ * 契约:答非 boolean 或 throw = **面故障**(见 {@link applyMemoryOptOutGrant} 的处置)。
+ */
+export interface MemoryOptOutVerdictSource {
+    resolveAllow(principal: string | undefined): Promise<boolean>;
+}
+/**
+ * design/383 §3.1 **F2 例外臂**(server 阻断级,采;core 7.0.0 `RuntimeCaps.allowMemoryOptOut` JSDoc 的
+ * FAULT-TRANSIT CONTRACT 逐字):把本地 grant 腿的 verdict 合成进 caps resolver —— **与 allowWorkflows 家族
+ * 反向的例外臂,逐字注释**:
+ *
+ *  · 本文件 `load()` 的 catch 臂对 center 硬失败铸 `{allowWorkflows:false, allowFork:false}`(fail-closed
+ *    降级:放大面上「故障 = 拒」是安全方向)。**本键禁止照抄**:隐私轴上「拒」= 把用户明说不要记的会话
+ *    记进去(不可逆),而「错误放行」只是少记一次会话(可恢复)。core 因此把 `open` 姿态的故障臂定成
+ *    **放行 + 具名披露**,把 `governed` 姿态的故障臂定成**拒跑**;两臂都以「故障」为输入。把故障编成
+ *    显式 `false` = 把「故障」伪装成「显式 denied verdict」,遮蔽这两条分臂 —— 在 `open` 下恰是
+ *    极性反转(故障走了「显式拒」臂)。
+ *  · 故障过境形写死:本键故障 = **键缺席**(对象上不写键;core 读作 `value:undefined`)。不选 throw
+ *    透传是因为 throw 会把**同一次**解析里 center 已答好的 allowWorkflows/allowFork 一并作废(core 的
+ *    resolver-throw 降级臂),那是把一条腿的故障扩成整车的故障。缺席的代价如实记:`open` 下 core 读
+ *    「clean undefined」不铸 `faultDisclosure`(那句披露只给 throw/非 boolean),所以**本层**用 `onFault`
+ *    打一行 warn 补上披露;`governed` 下缺席 = verdict absent = 拒跑,方向正确。
+ *  · 源答非 boolean 同判故障(契约:never truthiness-read)。
+ *  · 无源 ⇒ 原 resolver **同一引用**透传(零行为差;多数部署路径)。
+ *  · `principal` 缺席也问源:部署缺省行那一层对匿名 run 同样成立(governed 部署的匿名 run 也该被
+ *    一个显式 verdict 罩住,而不是因为「没 principal」结构性拿不到 verdict 而被拒跑)。
+ *
+ * 双向 G 钉在 `test/memory-capture-optout-lane.test.ts` ②:故障 ⇒ 键缺席;显式 false ⇒ 键=false。
+ */
+export declare function applyMemoryOptOutGrant(base: EntitlementsResolverFn | undefined, source: MemoryOptOutVerdictSource | undefined, opts: {
+    onFault: (err: Error, principal: string | undefined) => void;
+}): EntitlementsResolverFn | undefined;
 /**
  * observer 开闸线的 env 半场:`EXPERIMENTAL_OBSERVER_AGENTS=true` 时把
  * `RuntimeCaps.allowObservers: true` 作为**部署基线**合成进 caps resolver(core 1.270.0/1.273.0 的

package/dist/runtime-caps-resolver.js

@@ -1,6 +1,7 @@
 import { fetchPrincipalCaps } from "./config-center/facade.js";
 import { HttpError } from "./security.js";
 import { createLogger } from "./observability/logger.js";
+import { recordFailOpen } from "./observability/fail-open.js";
 const defaultLogger = createLogger();
 const executionLaneDefaultTrace = new Map();
 export function resetExecutionLaneDefaultTraceForTest() {
@@ -156,6 +157,30 @@ export function createPrincipalEntitlementsClient(opts) {
 export function createEntitlementsResolver(opts) {
     return createPrincipalEntitlementsClient(opts).resolveRuntimeCaps;
 }
+export function applyMemoryOptOutGrant(base, source, opts) {
+    if (source === undefined)
+        return base;
+    return async (principal) => {
+        const caps = base !== undefined ? await base(principal) : undefined;
+        let allow;
+        try {
+            const v = await source.resolveAllow(principal);
+            if (typeof v !== "boolean")
+                throw new Error(`memory opt-out grant source answered a non-boolean (${typeof v}) — treated as a fault, never truthiness-read`);
+            allow = v;
+        }
+        catch (err) {
+            try {
+                opts.onFault(err instanceof Error ? err : new Error(String(err)), principal);
+            }
+            catch (hookErr) {
+                recordFailOpen("server.memory-optout-grant.onfault-hook-threw", String(hookErr));
+            }
+            return caps;
+        }
+        return { ...(caps ?? {}), allowMemoryOptOut: allow };
+    };
+}
 export function applyObserverEnvOptIn(centerResolver, opts) {
     if (!opts.experimentalObserverAgents)
         return centerResolver;