@event4u/agent-config 9.32.0 → 9.34.0

package/src/scripts/_cli/cmd_doctor.ts

@@ -90,6 +90,8 @@ import * as installed_tools from '../_lib/installed_tools.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
 import { censusDuplicateScope } from '../_lib/duplicate_scope_census.js';
+import * as preamble_byte_census from '../preamble_byte_census.js';
+import * as dispatch_economy_report from '../dispatch_economy_report.js';
 import { git_common_dir } from '../_lib/git_common_dir.js';
 import * as sync_gitattributes from '../sync_gitattributes.js';
 import {
@@ -3244,6 +3246,7 @@ interface Options {
     check: string | null;
     trace_root: boolean;
     context: boolean;
+    anatomy: boolean;
     repair: string | null;
 }
 
@@ -3254,13 +3257,15 @@ const PROG = 'agent-config doctor';
 // terminal width; golden tests assert the `usage:` token + exit code only.
 const USAGE =
     `usage: ${PROG} [-h] [--project PROJECT] [--json] [--ci] [--check ID]\n` +
-    '                           [--trace-root] [--context] [--repair ID]\n';
+    '                           [--trace-root] [--context] [--anatomy]\n' +
+    '                           [--repair ID]\n';
 
 const _STORE_TRUE_FLAGS: Record<string, keyof Options> = {
     '--json': 'json',
     '--ci': 'ci',
     '--trace-root': 'trace_root',
     '--context': 'context',
+    '--anatomy': 'anatomy',
 };
 
 const _VALUE_FLAGS: Record<string, keyof Options> = {
@@ -3283,6 +3288,7 @@ function _parse(argv: string[]): Options {
         check: null,
         trace_root: false,
         context: false,
+        anatomy: false,
         repair: null,
     };
 
@@ -3408,6 +3414,65 @@ function _run_context(opts: Options): number {
     return 0;
 }
 
+/**
+ * `--anatomy` — the injection anatomy, rendered from measurements that already
+ * exist. Composes `preamble_byte_census` (what occupies the always-loaded
+ * preamble) with `dispatch_economy_report` (what the dispatch legs cost). It
+ * takes NO new measurement and adds no threshold: both sources are advisory
+ * reports and stay advisory here.
+ *
+ * Neither module runs anything at import time — `preamble_byte_census` gained
+ * the `__AGENT_CONFIG_BUNDLE__` guard for exactly this import, since inside the
+ * `build:cli-delegate` bundle its old entry check would have matched whenever
+ * this command was invoked directly.
+ */
+function _run_anatomy(opts: Options): number {
+    const census = preamble_byte_census;
+    const economy = dispatch_economy_report;
+
+    const byteCensus = census.buildReport(census.parseArgs([]));
+
+    // The economy half reads transcripts and a registration file; either can be
+    // absent on a consumer machine. An absent half is reported as absent, never
+    // as a zero — a fabricated zero is the failure both source reports already
+    // refuse to make.
+    let economyReport: ReturnType<typeof economy.buildReport> | null = null;
+    let economyError: string | null = null;
+    try {
+        economyReport = economy.buildReport({
+            root: economy.DEFAULT_PROJECTS_ROOT,
+            auditDir: path.join(process.cwd(), economy.DEFAULT_AUDIT_DIR),
+            maxAgeDays: 14,
+        });
+    } catch (err) {
+        economyError = err instanceof Error ? err.message : String(err);
+    }
+
+    if (opts.json) {
+        print(
+            _jsonDumpsIndentAscii(
+                {
+                    preamble_byte_census: byteCensus,
+                    dispatch_economy: economyReport,
+                    dispatch_economy_unavailable: economyError,
+                } as unknown as Dict,
+                2,
+            ),
+        );
+        return 0;
+    }
+
+    print('── injection anatomy ─────────────────────────────────────────');
+    print(census.renderText(byteCensus));
+    print('');
+    print(
+        economyReport !== null
+            ? economy.renderText(economyReport)
+            : `dispatch-economy report unavailable: ${economyError}`,
+    );
+    return 0;
+}
+
 function _run_repair(opts: Options): number {
     const target = opts.repair;
     if (target === 'wizard-state') {
@@ -3464,6 +3529,9 @@ function main(argv: string[] | null = null): number {
     if (opts.context) {
         return _run_context(opts);
     }
+    if (opts.anatomy) {
+        return _run_anatomy(opts);
+    }
     let project_root: string;
     let origin: string;
     try {

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -57,8 +57,13 @@ export function templateEnvelope(): Record<string, unknown> {
         acceptance_criteria: ['<what done means, one line each>'],
         remaining: ['<open work, one line each>'],
         not_carried_forward: ['<what the successor must re-derive from source>'],
-        decisions: ['<decision — one-line rationale>'],
+        decisions: ['<decision — one-line rationale> [reversible]'],
         constraints: ['<binding constraint>'],
+        // Ships EMPTY, unlike the prose lists above: the entries are path refs,
+        // and a `<placeholder>` left in by a hurried writer would be a fake path
+        // rather than obvious filler. An empty list is also the honest default —
+        // nothing off limits is the common case.
+        do_not_touch: [],
         open_worker_envelopes: [],
         artifact_paths: ['<path to a deliverable / note / evidence file>'],
         assumptions: [],
@@ -73,6 +78,7 @@ interface ParsedArgv {
     message?: string;
     file?: string;
     template?: boolean;
+    verify?: boolean;
 }
 
 export function parseArgv(argv: readonly string[]): ParsedArgv {
@@ -81,6 +87,8 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
         const a = argv[i] as string;
         if (a === '--template') {
             parsed.template = true;
+        } else if (a === '--verify') {
+            parsed.verify = true;
         } else if (a === '--file') {
             const value = argv[i + 1];
             if (!value) return { ok: false, message: '--file requires a path' };
@@ -102,7 +110,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
  */
 export function runSessionRecycle(
     input: string,
-    opts: { cwd: string; now?: Date },
+    opts: { cwd: string; now?: Date; verify?: boolean },
 ): RecycleResult {
     const out: string[] = [];
     const err: string[] = [];
@@ -171,6 +179,15 @@ export function runSessionRecycle(
         };
     }
 
+    // `--verify` stops HERE: every rejection above has already run, and the
+    // only thing skipped is the write. Validating through a different path
+    // than the one that writes would make the check a second implementation
+    // to keep in sync — the failure this suite refuses elsewhere.
+    if (opts.verify === true) {
+        out.push(`recycle envelope VALID — ${bytes} bytes, not written (--verify).`);
+        return { code: 0, out, err };
+    }
+
     const target = path.join(projectRoot, RECYCLE_ENVELOPE_REL);
     try {
         atomic_write_json(target, envelope);
@@ -193,9 +210,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const parsed = parseArgv(argv);
     if (!parsed.ok) {
         const usage = [
-            'usage: agent-config session:recycle [--file <envelope.json>] [--template]',
+            'usage: agent-config session:recycle [--file <envelope.json>] [--template] [--verify]',
             '  --file <path>   read the envelope JSON from a file (default: stdin)',
             '  --template      print a skeleton envelope and exit',
+            '  --verify        validate only — same rejections, no write',
         ].join('\n');
         if (parsed.message === 'usage') {
             process.stdout.write(`${usage}\n`);
@@ -225,7 +243,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
 
-    const result = runSessionRecycle(input, { cwd: process.cwd() });
+    const result = runSessionRecycle(input, {
+        cwd: process.cwd(),
+        ...(parsed.verify === true ? { verify: true } : {}),
+    });
     for (const line of result.out) process.stdout.write(`${line}\n`);
     for (const line of result.err) process.stderr.write(`${line}\n`);
     return result.code;

package/src/scripts/_dispatch.bash

@@ -130,7 +130,7 @@ Tier 1 — power-user (release shape, audit, migration):
                              user-authored files; persists standing consent
                              (install.auto_converge) on first use.
                              Flags: --dry-run | --yes
-  conformance:behavior       Replay local transcripts through the mechanised conformance checks
+  conformance:behavior       Replay local transcripts through the mechanised conformance checks (--why <id> traces one)
   conformance                Consumer conformance contract: doctor --ci +
                              installed-and-firing checks. Exits non-zero on
                              a failed check.
@@ -197,7 +197,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              session register). Flags: --json
   sessions:claim             Claim a roadmap for this session so other sessions skip
                              it; --release clears the claim
-  session:recycle            Validate + write the main-session recycle envelope
+  session:recycle            Validate + write the main-session recycle envelope (--verify validates only)
                              (deliberate recycle instead of auto-compact). Flags:
                              --file <json> | --template; default reads stdin
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
@@ -207,7 +207,9 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   gates                      Open decisions that need you, rendered as actions —
                              roadmap blockers filtered by owner, most-unblocking
                              first. Flags: --all (include maintainer/external),
-                             --json
+                             --json, --reply (reply-close form: the one blocking
+                             decision in full, the rest as a count; prints
+                             nothing when none are yours)
   capabilities:index         Regenerate CAPABILITIES.yaml — the package coverage index
                              (capability area → coverage → backing skills/commands → gaps).
                              Pass --check to fail if stale (for CI). Reads src/ (package repo).

package/src/scripts/_lib/env_kill_switch.ts

@@ -0,0 +1,37 @@
+/**
+ * One definition of "is this env kill-switch on?".
+ *
+ * WHY THIS EXISTS: the predicate was written out twice, byte-for-byte —
+ * `ai_council/events_log.ts` and `ai_team/review_gate.ts` each carried a
+ * private `_kill_switch_active()` with the identical body AND the identical
+ * env var (`AGENT_CONFIG_NO_EVENTS_LOG`). `diff` over the two blocks was empty
+ * and no shared helper existed. Two copies of a boolean coercion is two places
+ * for the next accepted spelling to land in only one.
+ *
+ * The subtle half is why `'false'` is listed at all: `process.env` values are
+ * strings, so the obvious `Boolean(process.env.X)` reads the *string* `'false'`
+ * as true and silently arms a switch the operator explicitly disarmed. The
+ * off-set is therefore explicit — unset, `''`, `'0'`, `'false'`, `'False'` —
+ * and everything else is on, so a typo fails toward the safer direction (the
+ * switch suppresses a log; a spurious suppression is visible, a spurious write
+ * is not).
+ *
+ * SCOPE, stated because the source over-claimed it. `grep -rn "=== 'false'"
+ * src/scripts/` returns 10 hits; only the two migrated here share one
+ * predicate. The others are deliberately different and stay put:
+ * `orchestration_record.ts` is a CLI-flag coercion whose invalid-string
+ * fall-through is documented, `turn_end_gate_hook.ts` additionally accepts
+ * `yes`/`on`, and `validate_frontmatter.ts` is a YAML scalar parser. Folding
+ * those in would change three behaviours to remove three lines.
+ */
+
+/** The env values that mean "off". Everything else — including a typo — is on. */
+const _OFF_VALUES: ReadonlySet<string> = new Set(['', '0', 'false', 'False']);
+
+/**
+ * True when the named environment variable is set to anything outside the
+ * off-set. Unset reads as off.
+ */
+export function isEnvKillSwitchActive(name: string): boolean {
+    return !_OFF_VALUES.has(process.env[name] ?? '');
+}

package/src/scripts/_lib/orchestration_record.ts

@@ -64,6 +64,20 @@ export interface RecordInput {
     dispatch_tokens?: number | null | undefined;
     /** The orchestrator's own tier — the baseline the downshift cost-% measures against. */
     session_tier?: string | null | undefined;
+    /**
+     * The model id that was ASKED for. `tier_chosen`, `tier_source`,
+     * `session_tier` and the downshift cost-percentage are all read off the
+     * requested tier, so on an alias or a provider substitution every one of
+     * them attributes the saving to a model that never ran. Recording the
+     * requested id beside the served one is what makes that detectable.
+     */
+    model_requested?: string | null | undefined;
+    /**
+     * The model id the provider reported SERVING. `''` / null when the
+     * transport reports none (every CLI client) — absent is honest, not a
+     * defect, and is NOT a divergence.
+     */
+    model_served?: string | null | undefined;
     dispatch_outcome?: DispatchOutcome | undefined;
     verify_mode?: VerifyMode | undefined;
     /** QUALITY: subagent return adopted without parent rework. Optional boolean (null = not measured). */
@@ -176,6 +190,23 @@ function isInt(n: unknown): n is number {
     return typeof n === 'number' && Number.isFinite(n) && Number.isInteger(n);
 }
 
+/**
+ * Did the provider answer with a different model than the one requested?
+ *
+ * `null` — not decidable — whenever either id is missing or empty. That is the
+ * common case (every CLI transport reports no served id) and it is not the
+ * same as "no divergence": a `false` here would claim a comparison that never
+ * happened, which is the exact mis-attribution this field exists to expose.
+ */
+function modelDivergent(
+    requested: string | null | undefined,
+    served: string | null | undefined,
+): boolean | null {
+    if (typeof requested !== 'string' || typeof served !== 'string') return null;
+    if (!requested || !served) return null;
+    return requested !== served;
+}
+
 /**
  * Build + validate the audit-log-v1 line. Returns `{line, errors}`; when
  * `errors` is non-empty, `line` is null and the caller must NOT write.
@@ -290,6 +321,13 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         errors.push(`trigger_arm_earlier must be one of ${TRIGGER_ARMS.join(' | ')} (or omitted / null when neither arm fired)`);
     }
 
+    for (const [key, v] of [
+        ['model_requested', input.model_requested],
+        ['model_served', input.model_served],
+    ] as const) {
+        if (v != null && typeof v !== 'string') errors.push(`${key} must be a string or omitted`);
+    }
+
     if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
     if (!input.id) errors.push('id (ULID or content hash) is required');
 
@@ -310,6 +348,13 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         tier_source: input.tier_source ?? null,
         dispatch_tokens: input.dispatch_tokens ?? null,
         session_tier: input.session_tier ?? null,
+        // Served-model attribution. `model_divergent` is DERIVED, never
+        // supplied: `null` when either id is absent — a transport that reports
+        // no served id cannot disagree with anything, and calling that `false`
+        // would read as "checked, and they matched".
+        model_requested: input.model_requested ?? null,
+        model_served: input.model_served ?? null,
+        model_divergent: modelDivergent(input.model_requested, input.model_served),
         first_pass_success: input.first_pass_success ?? null,
         escalated: input.escalated ?? null,
         agent_combo: input.agent_combo ?? [],

package/src/scripts/_lib/security_lint.ts

@@ -408,10 +408,13 @@ export function* iter_corpus(
  * Exit 1 iff at least one finding `is_fail` (HIGH + full weight). WARN-level
  * (weighted-down or < HIGH) findings print but never fail the build.
  */
-export function report(findings: readonly Finding[], opts: { check_label: string }): number {
+export function report(
+    findings: readonly Finding[],
+    opts: { check_label: string; scanned_roots?: readonly string[] },
+): number {
     const check_label = opts.check_label;
     if (findings.length === 0) {
-        process.stdout.write(`✅  ${check_label}: clean (${_corpus_note()}).\n`);
+        process.stdout.write(`✅  ${check_label}: clean (${_corpus_note(opts.scanned_roots)}).\n`);
         return 0;
     }
 
@@ -459,8 +462,19 @@ function _pyG(n: number): string {
     return s;
 }
 
-function _corpus_note(): string {
-    return 'scanned ' + DEFAULT_SCAN_ROOTS.join(', ');
+// The clean-path line names the corpus the caller ACTUALLY walked, not the
+// shared default. Two of five callers diverge from `DEFAULT_SCAN_ROOTS`
+// (`lint_skill_frontmatter_safety` replaces the set outright,
+// `lint_mcp_config_security` appends `src/templates`), so a hardcoded note made
+// this gate report a scope in both directions at once: it claimed `src/rules`
+// and `dist/agent-src`, which it never reads, and omitted `src/subagents`,
+// which is the one root holding the artefact its over-broad-grant check exists
+// for. A reader verifying that root by running the gate read the opposite of
+// the truth. Same contract as `_lib/scan_scope.reportScanned` — the emitted
+// scope is the scope that was walked.
+function _corpus_note(scanned_roots?: readonly string[]): string {
+    const roots = scanned_roots && scanned_roots.length > 0 ? scanned_roots : DEFAULT_SCAN_ROOTS;
+    return 'scanned ' + roots.join(', ');
 }
 
 // ---------------------------------------------------------------------

package/src/scripts/_lib/self_repair.ts

@@ -538,6 +538,66 @@ export function fingerprint(defect_class: DefectClass, evidence: string): string
 }
 
 /** Fold a finding into an existing record, or open a new one. */
+// ── creation rate cap ──────────────────────────────────────────────
+//
+// `upsertFinding` folds on fingerprint, so a *recurring* defect increments one
+// record and adds no file. What nothing bounded is **creation**: the fingerprint
+// is `defect_class + evidence`, and evidence is a quoted span from the turn, so a
+// defect whose span varies per turn mints a fresh record every time. The only
+// cap in the module pair was `MAX_EVIDENCE`, which bounds a span's *length* and
+// says nothing about how many records may exist.
+//
+// The cap is per `source` because the two intake paths have different plausible
+// rates and a runaway on one must not consume the other's headroom: a
+// `user-reported` record needs the user to complain, and `self-detected` fires at
+// most once per turn per detector. `NEW_RECORDS_PER_SOURCE_PER_WINDOW` sits above
+// any plausible day (three detector classes, a few evidence variants each) and
+// far below a runaway (one per turn over a long session).
+export const NEW_RECORDS_PER_SOURCE_PER_WINDOW = 20;
+export const CREATION_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * How many records of `source` were CREATED inside the window ending at `now`.
+ * Counts `first_seen`, never `last_seen` — an old record still being folded into
+ * is not creation and must not consume the budget.
+ */
+export function recentCreations(
+    existing: readonly DefectRecord[],
+    source: DefectSource,
+    now: string,
+): number {
+    const end = Date.parse(now);
+    if (Number.isNaN(end)) {
+        return 0;
+    }
+    return existing.filter((r) => {
+        if (r.source !== source) {
+            return false;
+        }
+        const t = Date.parse(r.first_seen);
+        // An unparseable stamp is counted: a malformed record is exactly what a
+        // runaway writer produces, and failing open there would uncap the store.
+        return Number.isNaN(t) || (end - t < CREATION_WINDOW_MS && end - t >= 0);
+    }).length;
+}
+
+/**
+ * Whether opening a NEW record for `finding` is over budget. A fingerprint that
+ * already exists is a fold, never a creation, so it is never capped — the cap
+ * must not silence a defect the store is already tracking.
+ */
+export function creationCapReached(
+    existing: readonly DefectRecord[],
+    finding: DefectFinding,
+    now: string,
+): boolean {
+    const fp = fingerprint(finding.defect_class, finding.evidence);
+    if (existing.some((r) => r.fingerprint === fp)) {
+        return false;
+    }
+    return recentCreations(existing, finding.source, now) >= NEW_RECORDS_PER_SOURCE_PER_WINDOW;
+}
+
 export function mergeRecord(
     existing: DefectRecord | null,
     finding: DefectFinding,

package/src/scripts/_lib/self_repair_store.ts

@@ -11,7 +11,14 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-import { type DefectFinding, type DefectRecord, fingerprint, mergeRecord } from './self_repair.js';
+import {
+    creationCapReached,
+    type DefectFinding,
+    type DefectRecord,
+    type DefectSource,
+    fingerprint,
+    mergeRecord,
+} from './self_repair.js';
 
 export const STORE_REL = path.join('agents', 'runtime', 'self-repair');
 
@@ -61,7 +68,10 @@ export function listRecords(root: string): DefectRecord[] {
     }
     const out: DefectRecord[] = [];
     for (const n of names.sort()) {
-        if (!n.endsWith('.json')) {
+        // The overflow counter shares the directory and the extension but is not
+        // a record. `isRecord` would reject it anyway; naming it here keeps the
+        // exclusion intentional rather than incidental.
+        if (!n.endsWith('.json') || n === OVERFLOW_FILE) {
             continue;
         }
         const rec = readRecord(root, n.slice(0, -'.json'.length));
@@ -77,13 +87,63 @@ export function openRecords(root: string): DefectRecord[] {
     return listRecords(root).filter((r) => r.status === 'open');
 }
 
+/**
+ * Per-source counters for findings the creation cap refused. ONE file for the
+ * whole store, so the overflow record is bounded by construction — it is the
+ * counter a runaway writer increments instead of the file it would otherwise
+ * mint. Deliberately NOT a `DefectRecord`: an overflow is not a defect and must
+ * not need a `DefectClass`, an issue-form dropdown entry, or an egress route.
+ */
+export const OVERFLOW_FILE = '_overflow.json';
+
+export type OverflowCounts = Partial<Record<DefectSource, { dropped: number; last_seen: string }>>;
+
+function overflowPath(root: string): string {
+    return path.join(storeDir(root), OVERFLOW_FILE);
+}
+
+export function readOverflow(root: string): OverflowCounts {
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(overflowPath(root), 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null ? (parsed as OverflowCounts) : {};
+    } catch {
+        return {};
+    }
+}
+
+function bumpOverflow(root: string, source: DefectSource, now: string): void {
+    const counts = readOverflow(root);
+    const prev = counts[source]?.dropped ?? 0;
+    counts[source] = { dropped: prev + 1, last_seen: now };
+    const dir = storeDir(root);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(overflowPath(root), `${JSON.stringify(counts, null, 2)}\n`, 'utf-8');
+}
+
 /**
  * Fold a finding into the store: increments the existing record when the
- * fingerprint matches, otherwise opens a new one. Returns the stored record.
+ * fingerprint matches, otherwise opens a new one. Returns the stored record, or
+ * `null` when the per-source creation cap refused to open a new one.
+ *
+ * A refusal is COUNTED, never silent — `readOverflow` carries the per-source
+ * drop tally, so "the cap fired" is a readable fact rather than a defect that
+ * disappeared. A cap that quietly discarded reports would break this loop's own
+ * Iron Law (a defect is queued, never shrugged off) in the name of bounding it.
  */
-export function upsertFinding(root: string, finding: DefectFinding, now: string): DefectRecord {
+export function upsertFinding(
+    root: string,
+    finding: DefectFinding,
+    now: string,
+): DefectRecord | null {
     const fp = fingerprint(finding.defect_class, finding.evidence);
-    const merged = mergeRecord(readRecord(root, fp), finding, now);
+    const existing = readRecord(root, fp);
+    // The fold path never consults the cap: a fingerprint already in the store
+    // adds no file, so capping it would silence a tracked defect for no bound.
+    if (existing === null && creationCapReached(listRecords(root), finding, now)) {
+        bumpOverflow(root, finding.source, now);
+        return null;
+    }
+    const merged = mergeRecord(existing, finding, now);
     writeRecord(root, merged);
     return merged;
 }

package/src/scripts/_lib/subagent_capsule.ts

@@ -232,10 +232,35 @@ export interface MainSessionRecycleEnvelope {
      * of silent. Required; an empty list is a claim, not a default.
      */
     not_carried_forward: string[];
-    /** Choices already made, each with its one-line rationale in the same line. */
+    /**
+     * Choices already made, each with its one-line rationale in the same line.
+     *
+     * A line MAY close with a reversibility tag — `[reversible]` or
+     * `[irreversible]` — so the successor can tell "we picked A over B, easy to
+     * revisit" from "we already migrated the data". The tag is OPTIONAL, so no
+     * committed envelope is retroactively invalid; when present its spelling is
+     * validated, which is what keeps it a checkable field rather than a doctrine
+     * nobody can verify. No claim is made that it improves resumption — that
+     * stays the registered, unmeasured `envelope_resume_success` metric.
+     */
     decisions?: string[];
     /** Binding constraints the successor must not silently re-open. */
     constraints?: string[];
+    /**
+     * Paths the successor must NOT modify — a parallel worktree, a file another
+     * session holds, a generated projection whose source lives elsewhere.
+     *
+     * Distinct from `constraints`, which carries decisions in prose: this is a
+     * list of path refs, so "was this path off limits?" is answerable by
+     * comparison instead of by reading. That checkability is the whole reason it
+     * is a field rather than a sentence — the same bar the handoff-envelope
+     * adjudication set (a field whose presence is checkable survives where a
+     * doctrine whose effect is unmeasured did not).
+     *
+     * Optional: an envelope with nothing off limits states nothing here, and an
+     * empty list is not a claim that everything is writable.
+     */
+    do_not_touch?: string[];
     /** Open worker CHECKPOINT envelopes by path — never inlined bodies. */
     open_worker_envelopes?: string[];
     /** Artifact paths (deliverables, notes, evidence) — refs, never bodies. */
@@ -444,6 +469,54 @@ export function hasBoundaryMarker(block: string): boolean {
     );
 }
 
+/** The two accepted reversibility tags, exact spellings. */
+export const DECISION_REVERSIBILITY_TAGS: readonly string[] = ['reversible', 'irreversible'];
+
+/**
+ * Validate the OPTIONAL trailing reversibility tag on a decision line.
+ *
+ * Fires only on a line that closes with a bracket whose content is trying to be
+ * one of the two tags — `[reversble]`, `[Irreversible!]`, `[reversible?]`. A
+ * bracket used for anything else (`[ADR-109]`, `[see #1273]`) is left alone, and
+ * a line with no bracket at all is the untagged default. So the check catches a
+ * typo in a tag someone MEANT to write, which is the only failure a
+ * presence-checkable optional field can actually have: a silently misspelled tag
+ * reads as "untagged" and loses the distinction the tag exists to carry.
+ */
+export function decisionTagErrors(decisions: unknown): string[] {
+    if (!Array.isArray(decisions)) {
+        return [];
+    }
+    const errors: string[] = [];
+    for (const line of decisions) {
+        if (typeof line !== 'string') {
+            continue;
+        }
+        const m = /\[([^\]]*)\]\s*$/.exec(line.trimEnd());
+        if (m === null) {
+            continue;
+        }
+        const inner = (m[1] ?? '').trim();
+        const lowered = inner.toLowerCase();
+        if (DECISION_REVERSIBILITY_TAGS.includes(lowered)) {
+            if (inner !== lowered) {
+                errors.push(
+                    `decisions: reversibility tag must be lower-case — got \`[${inner}]\`, expected \`[${lowered}]\``,
+                );
+            }
+            continue;
+        }
+        if (/^i?rr?ever[a-z]*[^a-z]*$/i.test(lowered)) {
+            errors.push(
+                `decisions: \`[${inner}]\` is not a reversibility tag — use exactly ` +
+                    DECISION_REVERSIBILITY_TAGS.map((t) => `\`[${t}]\``).join(' or ') +
+                    ', or drop the bracket',
+            );
+        }
+    }
+    return errors;
+}
+
 /** Every key `validateRecycleEnvelope` accepts — anything else is schema-invalid. */
 const RECYCLE_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
     'capsule_version',
@@ -457,6 +530,7 @@ const RECYCLE_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
     'not_carried_forward',
     'decisions',
     'constraints',
+    'do_not_touch',
     'open_worker_envelopes',
     'artifact_paths',
     'assumptions',
@@ -519,7 +593,10 @@ export function validateRecycleEnvelope(input: unknown): string[] {
     checkList(errors, 'remaining', e['remaining'], MAX_LINE_CHARS, true);
     checkList(errors, 'not_carried_forward', e['not_carried_forward'], MAX_LINE_CHARS, true);
     checkList(errors, 'decisions', e['decisions'], MAX_LINE_CHARS, false);
+    errors.push(...decisionTagErrors(e['decisions']));
     checkList(errors, 'constraints', e['constraints'], MAX_LINE_CHARS, false);
+    // Path refs, so the REF budget applies — not the prose one `constraints` uses.
+    checkList(errors, 'do_not_touch', e['do_not_touch'], MAX_REF_CHARS, false);
     checkList(errors, 'open_worker_envelopes', e['open_worker_envelopes'], MAX_REF_CHARS, false);
     checkList(errors, 'artifact_paths', e['artifact_paths'], MAX_REF_CHARS, false);
     checkList(errors, 'suggested_skills', e['suggested_skills'], MAX_REF_CHARS, false);