@event4u/agent-config 9.28.0 → 9.30.0

package/dist/agent-src/contexts/execution/subagent-routing.md

@@ -36,24 +36,26 @@ THE SAME MINUS THE QUOTA WIN.
    the tier/model choice is unchanged. This is the only place the
    "Sonnet-has-its-own-allowance" idea lives, and it lives as a runtime-detected
    flag, never as portable prose.
-4. **Budget routing** (`subagents.budget_routing != off`,
+4. **Budget routing** (design:
    [`budget-routing` contract](../../../../docs/contracts/budget-routing.md)) →
-   AFTER the tier resolves per 1–3, apply the budget relation via
-   `pickTier` (`src/scripts/_lib/tier_budget_routing.ts`): cheapest
+   AFTER the tier resolves per 1–3, the budget relation via `pickTier`
+   (`src/scripts/_lib/tier_budget_routing.ts`) would apply: cheapest
    classifier-adequate tier WITH available budget; that tier exhausted or
    cooling → next tier up with budget; all unavailable → session model +
    surfaced one-line notice. Work is never blocked to save money. Before
    the dispatch is created, acquire the atomic reserve
    (`acquireBudgetPermit`; check state via `node src/scripts/cost/budget.mjs
    tier <t>`); a 429/quota error trips `tripCooldown` for that tier and
-   falls back per the relation — never a retry loop. Under
-   `budget_routing: ask`, the FIRST budget-motivated downshift of a session
-   is confirmed once, in the shape
-   [`settings-ask-protocol`](../../rules/settings-ask-protocol.md) fixes and
-   without persisting the answer (`subagents.budget_routing` is class C);
-   `auto` proceeds silently. Every budget-routed
-   dispatch emits one `orchestration_record` line (tier + provenance-tagged
-   token delta) so realized savings are measured, not asserted.
+   falls back per the relation — never a retry loop.
+   `subagents.budget_routing` was removed as a settings key (always-on
+   orchestration, road-to-always-on-orchestration Phase 1: no per-layer
+   on/off switch survives) — `pickTier` has NO production caller today, so
+   this point documents the DESIGNED relation, not a currently wired one;
+   wiring it is a later phase of that roadmap (council-side
+   `cli_call_budget`/`cost_budget` are the caps that replace the settings
+   gate). Every budget-routed dispatch, once wired, would emit one
+   `orchestration_record` line (tier + provenance-tagged token delta) so
+   realized savings are measured, not asserted.
 
 **Cache trade-off (road-to-cache-economy Phase 4).** A tier downshift changes
 the sub-task's model, and the prompt cache is keyed by `(model, prefix)` — so

package/dist/agent-src/contexts/execution/subagent-spawn-contract.md

@@ -64,6 +64,31 @@ ADR-109 response contract — it replaces nothing. Live evidence
 (2026-07-28): four lookup-class workers burned 280–327k tokens each on tasks
 a deterministic primitive answers for <1k.
 
+### Capsule watermark — the line below the kill line
+
+The budget now carries **two** lines. `capsule_watermark` sits at
+`CAPSULE_WATERMARK_FRACTION` (0.8) of `max_tokens_per_worker` and is **derived**
+from it in `composeSpawnBrief`, never set independently — a watermark that could
+drift away from the budget it sits under is a watermark nobody can reason about.
+Reaching it means: emit a `CHECKPOINT` capsule
+([response contract](subagent-response-contract.md#checkpoint-capsule--the-generation-handoff))
+**while there is still headroom to write one**. A worker at 100 % of its budget
+cannot summarise itself; that headroom is the entire mechanism.
+
+`evaluateWorkerBudget` reports the band between the two lines as
+`watermark_hit` — the only window in which a capsule can be written at all.
+
+**Shadow only, today.** The worker still runs on to the stop-loss and still
+returns the `BLOCKED` partial result exactly as before; the capsule is recorded,
+never acted on. Behaviour is unchanged on purpose, so the Phase-1 measurement is
+not confounded by the mechanism it is measuring. A second candidate trigger —
+novelty-per-step saturation
+([`capsule_trigger.ts`](../../../../src/scripts/_lib/capsule_trigger.ts),
+term-frequency, no embeddings) — is logged alongside it, and the paired
+comparison is pre-registered as `worker-capsule-trigger-arm` in
+[`docs/CLAIMS.md`](../../../../docs/CLAIMS.md) with both arms losing as an
+explicitly publishable outcome.
+
 ## Bundle resolver — bind to the existing surfaces
 
 The brief is **resolved**, not hand-built. `resolveBundle(slice)` maps a task

package/dist/agent-src/contexts/execution/subagent-steering.md

@@ -144,11 +144,14 @@ dashboards alone look fine while quality regresses.
 ## Kill-switch
 
 ```
-subagents.enabled: false   (or  subagents.auto: off)
+emergency.orchestration_halt: true
 ```
 
-A single, no-deploy settings flip fully disables the layer (`isLayerDisabled()`).
-This is the canonical disable — no code change, effective on the next run.
+A single, no-deploy settings flip fully disables the layer (`isLayerDisabled()`)
+for the duration of an incident — the one audited switch that survives
+always-on orchestration (road-to-always-on-orchestration Phase 1;
+`docs/contracts/settings-classes.md` § "The one exception"). Disarming it
+requires a non-empty `emergency.orchestration_halt_justification`.
 
 ## Reference implementation
 

package/dist/agent-src/rules/delegation-policy.md

@@ -46,16 +46,18 @@ Only when the activation gate from
 [`auto-orchestration-activation`](../contexts/execution/auto-orchestration-activation.md)
 clears — all of:
 
-- `subagents.enabled` **and** `subagents.auto != off`,
+- `emergency.orchestration_halt` is not set,
 - the host-capability manifest reports `subagent_spawn: true`,
 - the task is classified **delegable** per
   [`auto-dispatch-classification`](../contexts/execution/auto-dispatch-classification.md)
   (≥1 independent, well-specified slice above the size floor).
 
-`subagents.auto: ask` → ask once before dispatching, in the shape
-[`settings-ask-protocol`](settings-ask-protocol.md) fixes (the answer is not
-persisted — `subagents.auto` is class C); `auto: on` → surface the chosen mode
-+ per-subtask tiers in one line. Any gate failing, or `auto: off`, or no host
+Always-on orchestration (road-to-always-on-orchestration Phase 1) removed the
+`subagents.enabled`/`subagents.auto` settings this used to gate on — there is
+no more per-layer on/off setting. A matched delegable signal → dispatch,
+surfacing the chosen mode + per-subtask tiers in one line, never silent. An
+AMBIGUOUS verdict (no enumerated signal matched) → **ask**, always — a verdict
+to the user, never a speculative spawn. The emergency halt, or no host
 primitive → run in-session (clean no-op).
 
 ## What it makes binding
@@ -100,8 +102,10 @@ no-review session — verified; its advisory line reaches the dispatcher
 output, but host-side forwarding of stop-slot context to the model is
 unverified, so the model-facing end-review carrier is the AGENTS.md line
 plus this telemetry). The
-capability gate itself resolves from the committed host registry in
-`src/scripts/_lib/host_capability.ts` (settings override wins). What stays
+capability gate itself resolves from the committed host registry merged with a
+live environment probe in `src/scripts/_lib/host_capability.ts`
+(`probeHostCapabilities` — capability is a fact about the host, never a
+settings override). What stays
 model-carried, honestly: the decomposition itself, the per-return
 verification, and every dispatch on hosts without hook slots. The nudges are
 advisory by design — whether they change behaviour is measured by the

package/dist/agent-src/rules/preservation-guard.md

@@ -26,6 +26,15 @@ the result must be **at least as strong** as the original.
 
 ## Iron Laws — every passage stays, telegraph is fine
 
+```
+EVERY PASSAGE STAYS — PARAGRAPH FOR PARAGRAPH, BULLET FOR BULLET, FENCE FOR FENCE.
+IRON LAW HEADINGS SURVIVE VERBATIM AT THEIR LEVEL. FENCED BLOCKS SURVIVE BYTE-FOR-BYTE.
+NEGATION CLAUSES (NO X / NEVER Y / NOT Z) STAY IN.
+NEVER WEAKEN: MUST STAYS MUST. ROUTING AND DECISION LOGIC STAY AS STRONG.
+NEVER BROADEN SCOPE BY MERGING UNRELATED WORKFLOWS.
+TELEGRAPH THE WORDING AS HARD AS YOU WANT — CONDENSE, NEVER DELETE, NEVER SOFTEN.
+```
+
 Sections marked **Iron Law** (any heading matching `# Iron Law`, `# Iron Laws`,
 `# The Iron Law`, at any heading level, including numbered variants like
 `Iron Law 1`, `Iron Law 2`) are **non-negotiable** and require the strictest

package/dist/agent-src/rules/settings-ask-protocol.md

@@ -7,7 +7,6 @@ triggers:
   - keyword: "settings:set"
   - keyword: "canary_name"
   - keyword: "rich_skills"
-  - keyword: "budget_routing"
   - keyword: "adversarial_council"
   - keyword: "learn_on_session_end"
   - keyword: "open_edited_files"
@@ -34,7 +33,7 @@ obligation_frequency: "per-task"
 # Settings-Ask Protocol
 
 A settings question is the one ask where the agent poses the question *and* owns
-where the answer goes. Nine keys can produce one, in two mechanisms that look
+where the answer goes. Seven keys can produce one, in two mechanisms that look
 identical from outside and differ completely underneath.
 
 ## The Iron Law
@@ -70,7 +69,7 @@ How long it stays cached in working state is the key's own business, and several
 keys state their own scope. Reading the C path as "re-ask every execution" would
 turn a fence against illegal writes into a source of extra questions.
 
-## The nine keys
+## The seven keys
 
 **Class B — persist once**: `personal.canary_name` ·
 `personal.open_edited_files` · `memory.learn_on_session_end`. Each ships a
@@ -78,10 +77,12 @@ conservative default (`""`, `false`, `false`), so absent is indistinguishable
 from *no* and never from *yes*.
 
 **Class C carrying an `ask` value in its own enum** — a runtime question whose
-answer dies with the run: `subagents.budget_routing` and `worktrees.mode` (both
-**ship** as `ask`), plus `tokens.rich_skills`, `subagents.auto`,
-`subagents.adversarial_council`, `decision_engine.on_block` (which can be set to
-`ask` by a human but do not ship that way).
+answer dies with the run: `worktrees.mode` (**ships** as `ask`), plus
+`tokens.rich_skills`, `subagents.adversarial_council`, `decision_engine.on_block`
+(which can be set to `ask` by a human but do not ship that way). Always-on
+orchestration (road-to-always-on-orchestration Phase 1) deleted
+`subagents.auto` and `subagents.budget_routing` — the layer no longer carries a
+setting for this protocol to route.
 
 ## The budget
 

package/dist/agent-src/rules/token-budget-discipline.md

@@ -139,7 +139,7 @@ its obligation on line 300.
 
 ## The size band is measured, and only its ceiling is gated
 
-The `rich` band is **2,000–3,500 tokens** ([ADR-217](../docs/decisions/ADR-217-rich-class-band-measured-and-enforced.md)).
+The `rich` band is **2,000–3,500 tokens** (ADR-217, `docs/decisions/ADR-217-rich-class-band-measured-and-enforced.md`).
 It was 2,000–5,000 and enforced by nothing until that record: measured with the
 exact BPE tokenizer, the largest rich artifact in the tree is 3,331 tokens, so
 the old ceiling described no artifact that existed. An unused permission costs

package/dist/agent-src/scripts/roadmap_gates.ts

@@ -0,0 +1,312 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config gates` — the open decisions that need the user, as actions.
+ *
+ * The dashboard (`update_roadmap_progress`) already parses every `## Blockers`
+ * entry and already counts them per roadmap. What it does not do is separate
+ * the blockers the *user* must resolve from the ones the maintainer or an
+ * external party owns: the count links into a per-roadmap breakdown, so
+ * answering "what do I have to do" means opening every anchor and filtering
+ * `Owner:` by hand across the whole file. The fields exist, are CI-enforced by
+ * `lint_roadmap_blockers`, and never reach the user in a form they can act on.
+ *
+ * This command is that missing projection, and nothing more: same parser
+ * (`parse_blockers` / `collect`, imported — never re-implemented), filtered by
+ * owner, ordered by how much each blocker unblocks, rendered action-first.
+ *
+ * Deliberately NOT a gate: it exits 0 whether or not decisions are pending.
+ * Blocking a pipeline on "the user has an open decision" would turn a
+ * visibility aid into a second thing to fight.
+ *
+ * Invocation (from project root):
+ *   ./agent-config gates            # decisions owned by the user
+ *   ./agent-config gates --all      # every open blocker, grouped by owner
+ *   ./agent-config gates --json     # machine-readable
+ */
+
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+import {
+    collect,
+    blocker_needs_user as needsUser,
+    type Blocker,
+} from './update_roadmap_progress.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Hard wrap for the rendered body — keeps output readable in a narrow pane. */
+const WIDTH = 78;
+
+interface Entry {
+    blocker: Blocker;
+    roadmapRel: string;
+    /** Open steps in the roadmap this blocker sits in — the "unblocks" weight. */
+    openSteps: number;
+}
+
+/**
+ * Rejoin wrapped continuation lines into one step each.
+ *
+ * `parse_blockers` returns `todo` as raw stripped lines, so a step that wraps
+ * over three source lines arrives as three entries. A new step starts at an
+ * ordered marker (`1.`, `2)`) or a bullet; everything else continues the one
+ * before it.
+ */
+function regroupTodo(todo: readonly string[]): string[] {
+    const steps: string[] = [];
+    for (const line of todo) {
+        const startsStep = /^(\d+[.)]|[-*+])\s/.test(line);
+        if (startsStep || steps.length === 0) {
+            steps.push(line);
+        } else {
+            steps[steps.length - 1] = `${steps[steps.length - 1] as string} ${line}`;
+        }
+    }
+    return steps;
+}
+
+/** Wrap `text` to `width`, indenting every line after the first by `indent`. */
+function wrap(text: string, width: number, indent: string): string[] {
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+        return [];
+    }
+    const lines: string[] = [];
+    let cur = '';
+    for (const w of words) {
+        const candidate = cur === '' ? w : `${cur} ${w}`;
+        if (candidate.length > width && cur !== '') {
+            lines.push(cur);
+            cur = w;
+        } else {
+            cur = candidate;
+        }
+    }
+    if (cur !== '') {
+        lines.push(cur);
+    }
+    return lines.map((l, i) => (i === 0 ? l : indent + l));
+}
+
+/**
+ * Column width for the label gutter — sized to the longest label in use
+ * (`Blocked until:`, 14 chars) plus one separating space, so no value ever
+ * runs flush against its own label.
+ */
+const LABEL_W = 15;
+
+/** A labelled block: `  Label:  value`, wrapped and hanging-indented. */
+function field(label: string, value: string): string[] {
+    const pad = '  ' + label.padEnd(LABEL_W);
+    const indent = ' '.repeat(pad.length);
+    const lines = wrap(value, WIDTH - pad.length, indent);
+    if (lines.length === 0) {
+        return [];
+    }
+    return [pad + lines[0], ...lines.slice(1)];
+}
+
+function collectEntries(roadmapRoot: string): Entry[] {
+    const entries: Entry[] = [];
+    for (const r of collect(roadmapRoot)) {
+        for (const b of r.open_blockers) {
+            entries.push({ blocker: b, roadmapRel: r.rel, openSteps: r.open_ });
+        }
+    }
+    // Most-unblocking first; ties broken deterministically so two runs on an
+    // unchanged tree print byte-identical output.
+    entries.sort(
+        (a, b) =>
+            b.openSteps - a.openSteps ||
+            a.roadmapRel.localeCompare(b.roadmapRel) ||
+            a.blocker.id.localeCompare(b.blocker.id),
+    );
+    return entries;
+}
+
+/**
+ * The parser's legacy fallback synthesises one blocker per `> Blocked until …`
+ * note under the fixed id `legacy`. That id is an implementation detail and
+ * says nothing to a reader, and its text is a *condition* ("blocked until X"),
+ * not an imperative — so both the heading and the field label are renamed for
+ * this one parser-defined case rather than dressed up as a step list.
+ */
+function isLegacy(b: Blocker): boolean {
+    return b.id === 'legacy';
+}
+
+function renderEntry(e: Entry, index: number): string[] {
+    const head = `${index} · ${isLegacy(e.blocker) ? 'blocked-until note' : e.blocker.id}`;
+    const tail =
+        e.openSteps > 0 ? `unblocks: ${e.openSteps} step${e.openSteps !== 1 ? 's' : ''}` : '';
+    const dashes = Math.max(3, WIDTH - head.length - tail.length - 6);
+    const out: string[] = [
+        '',
+        `── ${head} ${'─'.repeat(dashes)} ${tail}`.trimEnd(),
+        ...field('Roadmap:', e.roadmapRel),
+        ...field('Blocks:', e.blocker.blocks),
+    ];
+
+    const doLabel = isLegacy(e.blocker) ? 'Blocked until:' : 'Do this:';
+    const steps = regroupTodo(e.blocker.todo);
+    if (steps.length === 0) {
+        out.push(
+            ...field(
+                doLabel,
+                '(no steps recorded — the blocker entry in the roadmap needs a ' +
+                    '**What to do:** list)',
+            ),
+        );
+    } else {
+        out.push(...field(doLabel, steps[0] as string));
+        for (const s of steps.slice(1)) {
+            // Steps 2..n have no label of their own — align them under the
+            // first step's text, i.e. the same gutter `field()` produces.
+            const indent = ' '.repeat(LABEL_W + 2);
+            const lines = wrap(s, WIDTH - LABEL_W - 2, indent);
+            out.push(...lines.map((l, i) => (i === 0 ? indent + l : l)));
+        }
+    }
+    out.push(...field('Done when:', e.blocker.resolvedWhen));
+    return out;
+}
+
+function render(entries: readonly Entry[], all: boolean): string {
+    const mine = entries.filter((e) => needsUser(e.blocker.owner));
+    const others = entries.filter((e) => !needsUser(e.blocker.owner));
+    const shown = all ? entries : mine;
+    const lines: string[] = [];
+
+    if (mine.length === 0) {
+        lines.push(
+            others.length === 0
+                ? 'No open blockers at all.'
+                : `Nothing is waiting on you. ${others.length} open blocker` +
+                      `${others.length !== 1 ? 's' : ''} sit with maintainer/external` +
+                      `${all ? '' : ' — see --all'}.`,
+        );
+    } else {
+        const head =
+            `${mine.length} decision${mine.length !== 1 ? 's' : ''} need${mine.length === 1 ? 's' : ''} you`;
+        const rest =
+            others.length > 0
+                ? ` · ${others.length} more with maintainer/external${all ? '' : ' (--all)'}`
+                : '';
+        lines.push(head + rest);
+    }
+
+    let n = 0;
+    for (const e of shown) {
+        n += 1;
+        lines.push(...renderEntry(e, n));
+    }
+    if (shown.length > 0) {
+        lines.push('');
+    }
+    return lines.join('\n') + '\n';
+}
+
+function renderJson(entries: readonly Entry[], all: boolean): string {
+    const pick = all ? entries : entries.filter((e) => needsUser(e.blocker.owner));
+    return (
+        JSON.stringify(
+            {
+                needsYou: entries.filter((e) => needsUser(e.blocker.owner)).length,
+                other: entries.filter((e) => !needsUser(e.blocker.owner)).length,
+                blockers: pick.map((e) => ({
+                    id: e.blocker.id,
+                    roadmap: e.roadmapRel,
+                    owner: e.blocker.owner,
+                    needsYou: needsUser(e.blocker.owner),
+                    blocks: e.blocker.blocks,
+                    unblocksSteps: e.openSteps,
+                    todo: regroupTodo(e.blocker.todo),
+                    resolvedWhen: e.blocker.resolvedWhen,
+                })),
+            },
+            null,
+            2,
+        ) + '\n'
+    );
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Same repo-root resolution as the dashboard: honour the cwd when it holds
+ * `agents/roadmaps`, otherwise fall back to the git toplevel (monorepo
+ * sub-project support).
+ */
+function _resolveRepoRoot(start: string): string {
+    if (_isDir(path.join(start, 'agents', 'roadmaps'))) {
+        return start;
+    }
+    try {
+        const r = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: start,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        const top = (r.stdout || '').trim();
+        if (r.status === 0 && top !== '' && _isDir(path.join(top, 'agents', 'roadmaps'))) {
+            return top;
+        }
+    } catch {
+        /* not a git repo / git missing — keep the cwd default */
+    }
+    return start;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const all = args.includes('--all');
+    const json = args.includes('--json');
+
+    const repoRoot = _resolveRepoRoot(process.cwd());
+    const roadmapRoot = path.join(repoRoot, 'agents', 'roadmaps');
+    if (!_isDir(roadmapRoot)) {
+        process.stdout.write(
+            json ? '{"needsYou":0,"other":0,"blockers":[]}\n' : 'No roadmaps directory — nothing to report.\n',
+        );
+        return 0;
+    }
+
+    const entries = collectEntries(roadmapRoot);
+    process.stdout.write(json ? renderJson(entries, all) : render(entries, all));
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvPath = path.resolve(process.argv[1]);
+    if (import.meta.url === pathToFileURL(argvPath).href) {
+        return true;
+    }
+    // A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
+    // macOS /var → /private/var) makes the raw URLs differ: import.meta.url is
+    // the resolved real path while argv[1] keeps the symlink. Compare realpaths
+    // so the entry guard still fires through the projection.
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(argvPath);
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}
+
+export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson };
+export type { Entry };

package/dist/agent-src/scripts/update_roadmap_progress.ts

@@ -398,14 +398,32 @@ function _blockerField(slice: string, label: string): string | null {
     return parts.length ? parts.join(' ') : null;
 }
 
-/** Lines under `- **What to do:**` up to the next `- **Field:**` marker. */
+/**
+ * The `- **What to do:**` text: the remainder of the marker line, plus every
+ * line under it up to the next `- **Field:**` marker.
+ *
+ * The marker line's own remainder is load-bearing and used to be dropped.
+ * Authors write both shapes — a numbered list under the marker, and prose that
+ * starts inline (`- **What to do:** the build work is done; only real …`) —
+ * and every *other* blocker field reads the inline part via `_blockerField`.
+ * Skipping it here truncated instructions mid-sentence in both the dashboard
+ * and `agent-config gates`, which is precisely the content those surfaces
+ * exist to deliver.
+ */
 function _blockerTodo(slice: string): string[] {
     const lines = _splitlines(slice);
-    const startIdx = lines.findIndex((l) => /^-[ \t]*\*\*What to do:\*\*/i.test(_strip(l)));
+    const markerRe = /^-[ \t]*\*\*What to do:\*\*[ \t]*(.*)$/i;
+    const startIdx = lines.findIndex((l) => markerRe.test(_strip(l)));
     if (startIdx === -1) {
         return [];
     }
     const out: string[] = [];
+    const inline = _stripComment(
+        (markerRe.exec(_strip(lines[startIdx] as string))?.[1] as string) ?? '',
+    );
+    if (inline) {
+        out.push(inline);
+    }
     for (let i = startIdx + 1; i < lines.length; i++) {
         const trimmed = _strip(lines[i] as string);
         if (BLOCKER_FIELD_RE.test(trimmed) || trimmed.startsWith('#')) {
@@ -458,18 +476,56 @@ function parse_blockers(raw_text: string): Blocker[] {
     }
     const legacyMatch = LEGACY_BLOCKED_UNTIL_RE.exec(text);
     if (legacyMatch) {
+        // The legacy note is a blockquote and routinely wraps over several
+        // `> ` lines. The regex captures one line, so the continuation used to
+        // be dropped and the instruction ended mid-sentence — the same defect
+        // `_blockerTodo` carried above. Walk the following quoted lines until
+        // the quote block ends.
+        const parts = [_strip(legacyMatch[1] as string)];
+        const allLines = _splitlines(text);
+        const noteIdx = allLines.findIndex((l) => LEGACY_BLOCKED_UNTIL_RE.test(_strip(l)));
+        for (let i = noteIdx + 1; noteIdx !== -1 && i < allLines.length; i++) {
+            const quoted = /^>[ \t]?(.*)$/.exec(_strip(allLines[i] as string));
+            if (!quoted) {
+                break;
+            }
+            const cont = _strip(quoted[1] as string);
+            if (cont === '') {
+                break;
+            }
+            parts.push(cont);
+        }
         blockers.push({
             id: 'legacy',
             status: 'open',
             owner: 'user',
             blocks: 'entire roadmap',
-            todo: [_strip(legacyMatch[1] as string)],
+            todo: [parts.join(' ')],
             resolvedWhen: 'condition described above clears',
         });
     }
     return blockers;
 }
 
+/**
+ * Does this blocker need the human at the keyboard, rather than the maintainer
+ * or an external party?
+ *
+ * Owner values in the wild are not the clean `user | maintainer | external`
+ * enum the template comment suggests — real entries carry qualifiers
+ * (`user (billable spend)`, `user / maintainer`, `maintainer (security role)`).
+ * Word-boundary matching on `user` keeps the qualified forms and rejects
+ * `maintainer`. A shared `user / maintainer` blocker deliberately counts as the
+ * user's: showing one decision too many costs a line, hiding one costs the wait.
+ *
+ * Lives here rather than in `roadmap_gates` because it is owner *semantics*,
+ * not presentation — the dashboard header and `agent-config gates` must agree
+ * on the split, and two copies of this regex would drift.
+ */
+function blocker_needs_user(owner: string): boolean {
+    return /\buser\b/i.test(owner);
+}
+
 function parse_roadmap(p: string, roadmap_root: string): RoadmapStats | null {
     const text = fs.readFileSync(p, { encoding: 'utf-8' });
     const phase_matches: Array<{ start: number; end: number; g2: string; g3: string | undefined }> =
@@ -674,6 +730,14 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
     const total_open_blockers = roadmaps.reduce((s, r) => s + r.open_blockers.length, 0);
+    // The count alone answers "is something blocked", never "is it on me" —
+    // and the per-roadmap anchors make the owner split a manual read across the
+    // whole file. Name the user's share here and point at the command that
+    // renders those entries as actions.
+    const user_open_blockers = roadmaps.reduce(
+        (s, r) => s + r.open_blockers.filter((b) => blocker_needs_user(b.owner)).length,
+        0,
+    );
     const lines: string[] = [];
     lines.push('# Roadmap Progress\n');
     const header_meta =
@@ -682,7 +746,10 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
         ' · [roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · ' +
         '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)' +
         (total_open_blockers > 0
-            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}`
+            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}` +
+              (user_open_blockers > 0
+                  ? `, **${user_open_blockers}** need you → \`agent-config gates\``
+                  : '')
             : '') +
         '\n';
     lines.push(
@@ -1074,6 +1141,7 @@ export {
     is_roadmap_candidate,
     count_checkboxes,
     parse_blockers,
+    blocker_needs_user,
     parse_roadmap,
     bar,
     collect,