@event4u/agent-config 9.34.0 → 9.35.0

package/src/scripts/lint_framework_leakage_allowlist.json

@@ -1,152 +1,160 @@
 {
   "version": 1,
-  "_doc": "Each entry: { file: relative path from repo root, lines: [int,...] | \"*\" for whole file, reason: short justification }. Use sparingly — first ask whether the file should be neutralized or carved out. Policy cap: > 20 entries means the linter (or the content) is wrong — fix the tool or the text, never grow the list. Rebuilt 2026-07-12 (road-to-opt-hygiene-and-debt Phase 1): 104 → minimal set after heuristic upgrades + 25 content neutralizations + 2 carve-outs.",
+  "_doc": "Each entry: { file: relative path from repo root, anchor: a substring of the exempted line (the ONLY per-line key — position keys are refused by validate_allowlist), or lines: \"*\" for the whole file, reason: short justification }. Use sparingly — first ask whether the file should be neutralized or carved out. Policy cap: > 20 exempted FILES means the linter (or the content) is wrong — fix the tool or the text, never grow the list. The cap counts files because that is the unit it was written in, when one entry meant one file; entries are now per-line, so the two numbers differ on purpose (15 files / 31 entries as of the anchor migration) and the entry count is not the cap. Rebuilt 2026-07-12 (road-to-opt-hygiene-and-debt Phase 1): 104 -> minimal set after heuristic upgrades + 25 content neutralizations + 2 carve-outs. Re-keyed to content anchors 2026-08-12: 8 of the 39 exempted lines were found to exempt nothing — three named blank or out-of-range lines, five named lines that produce no hit — and were dropped rather than carried forward; the gate now refuses both shapes.",
   "entries": [
-    {
-      "file": "src/rules/code-comment-discipline.md",
-      "lines": [
-        100
-      ],
-      "reason": "Worked PHP docblock demo inside the rule's own wrong/right example block — quoted teaching content."
-    },
     {
       "file": "src/skills/api-testing/SKILL.md",
-      "lines": [
-        218
-      ],
+      "anchor": "- Don't test framework internals (e.g., \"does Laravel return",
       "reason": "Quoted example of a framework-internal behavior explicitly marked as what NOT to test — meta content, not a mandate."
     },
     {
       "file": "src/skills/learning-to-rule-or-skill/SKILL.md",
-      "lines": [
-        320,
-        322
-      ],
+      "anchor": "Decision: Create focused skill for Laravel route inspection ",
+      "reason": "Example learnings/decisions quoted verbatim in the promotion-flow walkthrough — meta content."
+    },
+    {
+      "file": "src/skills/learning-to-rule-or-skill/SKILL.md",
+      "anchor": "Learning: \"I forgot to run PHPStan once.\"",
       "reason": "Example learnings/decisions quoted verbatim in the promotion-flow walkthrough — meta content."
     },
     {
       "file": "src/skills/markitdown/SKILL.md",
-      "lines": [
-        74,
-        111
-      ],
+      "anchor": "uv pip install 'markitdown-mcp==0.0.1a4'",
       "reason": "Tool-intrinsic install lines — markitdown IS a pip package; the install command is the tool's identity, not stack leakage."
     },
+    {
+      "file": "src/skills/markitdown/SKILL.md",
+      "anchor": "Plugins enable arbitrary code paths inside the conversion pi",
+      "reason": "Tool-intrinsic install lines — markitdown IS a pip package; the install command is the tool's identity, not stack leakage."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "### Laravel HMVC carve-out",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "│   ├── api.php   web.php   console.php",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "**Auto-loading:** `app/Providers/ModuleServiceProvider.php` ",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "`app/Modules/` and registers routes (`Routes/api.php` → `/ap",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "`api` middleware; `Routes/web.php` → `web` middleware) plus ",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "// Routes/api.php — auto-prefixed /api",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
     {
       "file": "src/skills/module-management/SKILL.md",
-      "lines": [
-        87,
-        99,
-        107,
-        108,
-        109,
-        115,
-        124,
-        156,
-        172
-      ],
+      "anchor": "### Symfony DDD-lite carve-out",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "metadata in `pyproject.toml`.",
       "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
     },
     {
       "file": "src/skills/po-discovery/SKILL.md",
-      "lines": [
-        45
-      ],
+      "anchor": "(\"upgrade Laravel to 11\") — discovery adds noise; skip.",
       "reason": "Quoted example ticket title ('upgrade Laravel to 11') illustrating when discovery adds noise — meta content."
     },
     {
       "file": "src/skills/repomix-packer/SKILL.md",
-      "lines": [
-        44
-      ],
+      "anchor": "npm install -g repomix",
       "reason": "Tool-intrinsic install line — repomix IS an npm package."
     },
     {
       "file": "src/skills/rule-writing/SKILL.md",
-      "lines": [
-        78
-      ],
+      "anchor": "description: \"Writing or reviewing PHP code — strict types, ",
       "reason": "Quoted rule-description example (the php-coding rule's own description string) — meta content. Re-anchored 76→78 after the description-cap edit above it."
     },
-    {
-      "file": "src/skills/security-audit/SKILL.md",
-      "lines": [
-        122
-      ],
-      "reason": "Multi-ecosystem XSS row (Blade/JSX/Jinja peers on one line) + a quoted false-positive example ('Laravel's CSRF is already handled') — documentation, not a mandate."
-    },
     {
       "file": "src/skills/skill-reviewer/SKILL.md",
-      "lines": [
-        70
-      ],
+      "anchor": "- ❌  Describing how Laravel middleware works (in a middlewar",
       "reason": "Quoted anti-example ('❌ Describing how Laravel middleware works') — the line teaches what NOT to write."
     },
     {
       "file": "src/skills/skill-writing/SKILL.md",
-      "lines": [
-        148,
-        456
-      ],
+      "anchor": "Use when creating Laravel middleware for request filtering",
       "reason": "Quoted description examples + the 'too-broad skill (Laravel skill)' anti-pattern — meta content."
     },
     {
       "file": "src/skills/supply-chain-intake/SKILL.md",
-      "lines": [
-        80,
-        82
-      ],
+      "anchor": "rg -n '\"[^\"]+\":\\s*\"(\\^|~|\\*|latest)' package.json",
       "reason": "Per-ecosystem check commands in fenced blocks; the pip/composer siblings sit farther apart than the ±10-line window — genuine multi-ecosystem documentation."
     },
     {
-      "file": "src/skills/test-driven-development/SKILL.md",
-      "lines": [
-        197,
-        200,
-        208,
-        212
-      ],
-      "reason": "Worked Example A (PHP/Pest) paired with Example B (TypeScript/Jest) farther apart than the ±10-line window — canonical two-stack demo."
+      "file": "src/skills/supply-chain-intake/SKILL.md",
+      "anchor": "[ -f package.json ] && [ ! -f package-lock.json ] && echo \"n",
+      "reason": "Per-ecosystem check commands in fenced blocks; the pip/composer siblings sit farther apart than the ±10-line window — genuine multi-ecosystem documentation."
+    },
+    {
+      "file": "src/skills/testing-anti-patterns/SKILL.md",
+      "anchor": "Replacement: a `tests/Support/cleanupSession.php` helper or ",
+      "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
+    },
+    {
+      "file": "src/skills/testing-anti-patterns/SKILL.md",
+      "anchor": "**Concrete capture tools** for recording the real shape: `cu",
+      "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
     },
     {
       "file": "src/skills/testing-anti-patterns/SKILL.md",
-      "lines": [
-        87,
-        124,
-        185
-      ],
+      "anchor": "rg -n '\\b(it|test|describe)\\.skip\\b|\\.only\\b|xit\\(|xdescribe",
       "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
     },
     {
       "file": "src/skills/test-driven-development/SKILL.md",
-      "lines": [
-        228,
-        231,
-        239,
-        243
-      ],
+      "anchor": "### Example A — PHP / Pest",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "// tests/Unit/EmailValidatorTest.php — RED",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "Run: `./vendor/bin/pest --filter='rejects empty email'` → fa",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "// app/Validators/EmailValidator.php — GREEN (minimum)",
       "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
     },
     {
       "file": "src/skills/image-editing/SKILL.md",
-      "lines": [
-        48
-      ],
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/ada",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     },
     {
       "file": "src/skills/image-generation/SKILL.md",
-      "lines": [
-        45
-      ],
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/ada",
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
+    },
+    {
+      "file": "src/skills/prompt-engineering-image/SKILL.md",
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/adapters/<provider>.sh`",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     },
     {
       "file": "src/skills/prompt-engineering-image/SKILL.md",
-      "lines": [
-        74,
-        115
-      ],
+      "anchor": "- `node_modules/@event4u/agent-config/src/scripts/ai-image/a",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     }
   ]

package/src/scripts/memory_lookup.ts

@@ -529,8 +529,7 @@ function* _iter_knowledge_entries(): Generator<[string, Record<string, unknown>]
 /**
  * Naive relevance score: max over keys of (glob-match | substring).
  *
- * Good enough for the `absent` path where retrieval is best-effort.
- * The `present` path returns a real score from agent-memory.
+ * Retrieval is best-effort by design — this is the only scoring path.
  *
  * DOCUMENTED FALLBACK (road-to-reachable-code-memory Phase 6 / ADR-129):
  * this is the primary, always-available scorer. It has a known correctness

package/src/scripts/schemas/command.schema.json

@@ -257,6 +257,10 @@
       "type": "boolean",
       "description": "AI OS Product UI allowlist (road-to-ai-os-product-ui.md Phase 1). When true, the command is exposed in the browser /tasks surface and may be spawned by POST /api/v1/task/run. Default false — commands that touch git, secrets, or run destructive migrations must stay false (terminal only). Per-command opt-in, never opt-out."
     },
+    "requires_confirmation": {
+      "type": "boolean",
+      "description": "Optional, additive: the command's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). Twin of the same key in skill.schema.json's execution block; commands carry no execution block, so it sits top-level. A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. Mechanism: stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate with `agent-config gates --pending`. Nothing BINDS on it yet (blocker confirmation-degraded-host-semantics: 5 of 8 hosts have no pre_tool_use slot)."
+    },
     "auto_detect": {
       "type": "boolean",
       "description": "6.1.0 orchestrator auto-detection opt-in (Step 1, non-interactive-contract). When true, the orchestrator auto-detects its sub-command per the confidence-tiered detection table instead of always showing the menu, honoring the non-interactive-contract (TTY/CI detection, --yes/--json, abort schemas). Per-orchestrator kill-switch: set false to always show the menu; overridable globally via commands.auto_detect in .agent-settings.yml and per-invocation via --no-auto-detect. Only orchestrators (type: orchestrator) carry it."

package/src/scripts/schemas/skill.schema.json

@@ -222,6 +222,10 @@
           },
           "description": "U3 (ecosystem harvest): optional deny-list layered UNDER allowed_tools — defense-in-depth; a tool matching here is refused even if a broad allow pattern would admit it. Supports the scoped-grant syntax (e.g. Bash(git push:*))."
         },
+        "requires_confirmation": {
+          "type": "boolean",
+          "description": "Optional, additive: the skill's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. The mechanism is stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate what is pending with `agent-config gates --pending`. Nothing BINDS on this flag yet: on 5 of 8 hosts there is no pre_tool_use slot, so a guard would degrade to prose while the flag reads like a control — that decision is deferred behind blocker confirmation-degraded-host-semantics."
+        },
         "command": {
           "type": "array",
           "minItems": 1,

package/src/scripts/session_register_hook.ts

@@ -53,12 +53,15 @@ import { fileURLToPath } from 'node:url';
 import { current_branch } from './_lib/git_common_dir.js';
 import {
     HEARTBEAT_REACHABLE_PLATFORMS,
+    type Collision,
     type SessionRecord,
+    classify_collisions,
     delete_record,
     foreign_live_records,
     iso_now,
     read_own_record,
     register_dir,
+    safe_stem,
     stop_means_session_end,
     ttl_is_measured,
     ttl_seconds_for,
@@ -79,29 +82,181 @@ const REPLAY_ENV_VAR = 'AGENT_CONFIG_REPLAY';
  * the claim lands at most one turn later and the model never needs to know the
  * register's path or format.
  */
-export const ROADMAP_CLAIM_REL = path.join('agents', 'runtime', 'state', 'roadmap-claim.json');
+const _STATE_REL = path.join('agents', 'runtime', 'state');
+
+export const ROADMAP_CLAIM_REL = path.join(_STATE_REL, 'roadmap-claim.json');
+
+/**
+ * Per-SESSION claim path. The legacy single file above is a claim on the
+ * WORKTREE, not on the session, and that was a measured defect rather than a
+ * theoretical one: four live records once carried one identical slug — naming a
+ * roadmap that was already archived — because every session in the same checkout
+ * read the last claim written there. A session inheriting a peer's claim reports
+ * work it is not doing, and a session whose claim was overwritten reports none.
+ *
+ * `session_id` is available on both paths: the hook gets it from the envelope,
+ * and `sessions:claim` resolves it from the host environment. When it is not
+ * resolvable the legacy path is still written and still read, so an older claim
+ * keeps working — the fallback degrades to the previous behaviour instead of
+ * losing the claim.
+ */
+export function roadmap_claim_rel(session_id: string | null | undefined): string {
+    const id = String(session_id ?? '').trim();
+    if (id === '') {
+        return ROADMAP_CLAIM_REL;
+    }
+    // `safe_stem` collapses `..` and both separators, so the stem cannot traverse.
+    // The containment assertion below is nonetheless real rather than ceremonial:
+    // the adversarial gate's finding was "the defense relies on caller honesty",
+    // and it is right that a guarantee living in another module's implementation is
+    // one refactor away from being untrue here. This one is local and mechanical —
+    // if the joined path ever leaves the state directory, fall back to the shared
+    // file rather than write outside it.
+    const rel = path.join(_STATE_REL, `roadmap-claim-${safe_stem(id)}.json`);
+    const norm = path.normalize(rel);
+    if (!norm.startsWith(`${_STATE_REL}${path.sep}`) || norm.includes('..')) {
+        return ROADMAP_CLAIM_REL;
+    }
+    return norm;
+}
+
+/** The shape `sessions:claim` writes. `session_id` is absent on legacy files. */
+export interface RoadmapClaim {
+    slug: string;
+    written_at?: string;
+    session_id?: string | null;
+}
 
 function _is_replay_mode(): boolean {
     return String(process.env[REPLAY_ENV_VAR] ?? '').trim() !== '';
 }
 
-/** The roadmap slug this session has claimed, or `null`. Never throws. */
-export function read_claimed_slug(workspace_root: string): string | null {
+function _read_claim_file(file: string): RoadmapClaim | null {
     try {
-        const raw = fs.readFileSync(path.join(workspace_root, ROADMAP_CLAIM_REL), 'utf-8');
-        const parsed: unknown = JSON.parse(raw);
-        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-            const slug = (parsed as Record<string, unknown>)['slug'];
-            if (typeof slug === 'string' && slug.trim().length > 0) {
-                return slug.trim();
-            }
+        const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
         }
-        return null;
+        const rec = parsed as Record<string, unknown>;
+        const slug = rec['slug'];
+        if (typeof slug !== 'string' || slug.trim().length === 0) {
+            return null;
+        }
+        const sid = rec['session_id'];
+        return {
+            slug: slug.trim(),
+            ...(typeof sid === 'string' && sid.trim() !== '' ? { session_id: sid.trim() } : {}),
+        };
     } catch {
         return null;
     }
 }
 
+/**
+ * The roadmap slug THIS session has claimed, or `null`. Never throws.
+ *
+ * Two reads, in order, and the second one is why a peer's claim can no longer be
+ * inherited: the per-session file first, then the legacy per-worktree file —
+ * and the legacy file counts only when it carries no `session_id`, or one that
+ * matches. A legacy claim written by a DIFFERENT session in the same checkout is
+ * that session's claim, and reading it as this session's is exactly the defect
+ * that put one archived slug on four live records.
+ */
+export function read_claimed_slug(
+    workspace_root: string,
+    // REQUIRED, on the reviewer's point: an optional id means a caller that forgets
+    // it silently gets legacy semantics instead of a type error, and there is
+    // exactly one call site that matters (`build_record`). `null` stays a legal
+    // value — it is the host-exports-nothing case — but it has to be passed.
+    session_id: string | null,
+): string | null {
+    const own = roadmap_claim_rel(session_id);
+    if (own !== ROADMAP_CLAIM_REL) {
+        const mine = _read_claim_file(path.join(workspace_root, own));
+        if (mine !== null) {
+            return mine.slug;
+        }
+    }
+    const legacy = _read_claim_file(path.join(workspace_root, ROADMAP_CLAIM_REL));
+    if (legacy === null) {
+        return null;
+    }
+    const id = String(session_id ?? '').trim();
+    // A session that CAN identify itself never writes the legacy path, so a legacy
+    // file it did not write is either a peer's (a host with no id, in this same
+    // checkout) or a claim from before this file was keyed on the session. Those
+    // two are indistinguishable to a reader, and only one of them can win:
+    // inheriting a peer's claim is the measured defect, while losing a
+    // pre-upgrade claim costs one re-run of `sessions:claim`. So the identified
+    // session declines it.
+    //
+    // The previous shape compared `legacy.session_id` and was unreachable —
+    // `cmd_claim` serialises `session_id: null` on that path and `_read_claim_file`
+    // drops a null, so the comparison never ran and every legacy claim was read as
+    // "mine". R2 finding 6; the test that covered it hand-wrote a record
+    // production cannot produce.
+    if (id !== '') {
+        return null;
+    }
+    return legacy.slug;
+}
+
+/**
+ * Does a roadmap by this slug still exist as open work?
+ *
+ * A slug survives in a claim file after its roadmap is archived, and a stale slug
+ * is worse than no slug: it renders as an active claim, so a screening session
+ * reads "that roadmap is taken" about work that shipped, and — measured — reads
+ * "nobody claimed anything else" from four records that were all simply out of
+ * date. Only the ACTIVE tree counts; `archive/`, `later/` and `skipped/` are the
+ * dispositions that make a claim meaningless.
+ */
+export function claim_is_stale(
+    workspace_root: string,
+    slug: string | null,
+    peer_worktree?: string | null,
+): boolean {
+    if (slug === null || slug.trim() === '') {
+        return false;
+    }
+    const base = slug.trim().replace(/\.md$/, '');
+    // Containment, not a character blacklist. A blacklist answers "does this look
+    // hostile"; this answers the question that matters — "would the read leave the
+    // roadmaps directory" — and it is the same check for a traversal, an absolute
+    // path, and an encoding nobody enumerated. A slug that fails it is reported
+    // stale rather than resolved, so no read happens at all.
+    const rel = path.normalize(path.join('agents', 'roadmaps', `${base}.md`));
+    const inside = rel.startsWith(`agents${path.sep}roadmaps${path.sep}`) && !rel.includes('..');
+    if (!inside || path.isAbsolute(base)) {
+        return true; // not a slug this repo can hold; never render it as live work
+    }
+    // Resolved in the PEER's worktree when one is known, and only then in ours.
+    //
+    // R2 finding 1: worktrees share one register while sitting on different
+    // commits, so a checkout branched before the roadmap file existed would read a
+    // genuinely live peer claim as stale — and both consumers treat stale as "no
+    // claim", which disables the refusal and the warning in exactly the
+    // multi-worktree case this exists for. Asking the peer's own tree first makes
+    // the verdict a fact about the peer rather than about our checkout's age.
+    //
+    // Absent in BOTH trees still means stale: a slug no tree can resolve names no
+    // work. Present in either means live — the asymmetry is deliberate, because a
+    // false "live" costs one question and a false "stale" costs a duplicated PR.
+    const roots = [peer_worktree, workspace_root].filter(
+        (r): r is string => typeof r === 'string' && r.trim() !== '',
+    );
+    for (const root of roots) {
+        try {
+            if (fs.existsSync(path.join(root, rel))) {
+                return false;
+            }
+        } catch {
+            return false; // unreadable tree — fail open, same as every other read here
+        }
+    }
+    return true;
+}
+
 /**
  * Build this session's record from live state.
  *
@@ -121,7 +276,7 @@ export function build_record(
         platform,
         worktree: workspace_root,
         branch: current_branch(workspace_root),
-        roadmap_slug: read_claimed_slug(workspace_root),
+        roadmap_slug: read_claimed_slug(workspace_root, session_id),
         started_at,
         last_seen: iso_now(now),
     };
@@ -164,23 +319,42 @@ export function foreign_sessions_block(
     if (others.length === 0) return null;
 
     const here = current_branch(workspace_root);
+    const my_slug = read_claimed_slug(workspace_root, session_id);
     const lines: string[] = [];
-    let collision: SessionRecord | null = null;
+
+    // A stale slug is reported as stale and then treated as ABSENT for collision
+    // purposes: a claim naming an archived roadmap is not a claim, and counting
+    // it would fire the new warning on four records that were merely out of date.
+    const live_others: SessionRecord[] = [];
 
     for (const r of others) {
         const age_min = Math.max(0, Math.round((now.getTime() - Date.parse(r.last_seen)) / 60000));
-        const slug = r.roadmap_slug === null ? 'no roadmap claimed' : `roadmap: ${r.roadmap_slug}`;
+        const stale = claim_is_stale(workspace_root, r.roadmap_slug, r.worktree);
+        const slug =
+            r.roadmap_slug === null
+                ? 'no roadmap claimed'
+                : stale
+                  ? `roadmap: ${r.roadmap_slug} (STALE — no such open roadmap; treat as no claim)`
+                  : `roadmap: ${r.roadmap_slug}`;
         const ttl_note = ttl_is_measured(r.platform)
             ? ''
             : ` · unmeasured host, TTL falls back to ${Math.round(ttl_seconds_for(r.platform) / 3600)}h`;
         lines.push(
             `- ${r.platform} · branch \`${r.branch ?? 'detached'}\` · ${slug} · last seen ${age_min} min ago${ttl_note}\n  worktree: ${r.worktree}`,
         );
-        if (collision === null && here !== null && r.branch === here) {
-            collision = r;
-        }
+        live_others.push(stale ? { ...r, roadmap_slug: null } : r);
     }
 
+    const collisions: Collision[] = classify_collisions(live_others, {
+        branch: here,
+        roadmap_slug: claim_is_stale(workspace_root, my_slug) ? null : my_slug,
+    });
+    // ALL roadmap peers, not the first. `classify_collisions` returns every one on
+    // purpose and a test pins that; reporting one understated the count whenever
+    // several records described the same work (R2 finding 14).
+    const roadmap_hits = collisions.filter((c) => c.kind === 'roadmap');
+    const branch_hit = collisions.find((c) => c.kind === 'branch') ?? null;
+
     const parts = [
         '<session-register>',
         'The following OTHER agent sessions are live on this repository right now.',
@@ -189,7 +363,36 @@ export function foreign_sessions_block(
         ...lines,
     ];
 
-    if (collision !== null) {
+    // Roadmap first, deliberately. This is the expensive collision — the work is
+    // being done twice and one of the two PRs is thrown away — and it is the one
+    // that went unreported twice while the cheap branch warning fired correctly.
+    //
+    // HONEST SCOPE (R2 finding 5): this block is emitted on `session_start`, where
+    // this session's own slug is normally `null` because the roadmap is picked
+    // later — so it fires only when a claim is already on disk at start, i.e. on a
+    // RESUMED session that claimed in an earlier run. The check that covers the
+    // picking moment is `sessions:claim` itself, which refuses before writing. This
+    // is the resumed-session half of the same guard, not the primary one, and
+    // deleting it would leave a resumed session unwarned.
+    if (roadmap_hits.length > 0) {
+        parts.push(
+            '',
+            `DUPLICATE WORK: ${roadmap_hits.length} other live session(s) claim the SAME roadmap \`${my_slug}\`.`,
+            ...roadmap_hits.map(
+                (h) =>
+                    `  · branch \`${h.record.branch ?? 'detached'}\` in ${h.record.worktree}`,
+            ),
+            'A different branch name does NOT make this a different task — measured twice,',
+            'two sessions built one roadmap phase under two branch names and one PR was wasted.',
+            'STOP before writing code. Ask the user ONCE, as numbered options:',
+            '  1. Take a different roadmap (`agent-config sessions:list` shows what is held)',
+            '  2. Split the roadmap explicitly — name which phases are yours',
+            '  3. Continue anyway, accepting that one of the two results is discarded',
+            'Never decide silently, in either direction.',
+        );
+    }
+
+    if (branch_hit !== null) {
         parts.push(
             '',
             `COLLISION: another live session already holds branch \`${here}\`.`,
@@ -238,6 +441,23 @@ export function main(): number {
         if (event === 'session_end' || (event === 'stop' && stop_means_session_end(platform))) {
             const dir = register_dir(root);
             if (dir !== null) delete_record(dir, session_id);
+            // The claim file dies with the session too. Keyed on a session id it is
+            // never read again once that session ends, so leaving it behind grows one
+            // file per session forever — the same unbounded-growth defect the register
+            // itself spends code avoiding (R2 finding 3). Only ever this session's own
+            // file: the shared legacy path may belong to a peer.
+            // Whichever file THIS session writes is the file it removes — the
+            // per-session one when it has an id, the shared one when it does not.
+            // The reviewer's second point: nothing removed the shared file, so a
+            // pre-change claim survived every release, every session end and every
+            // upgrade, unbounded. An id-less session owns that file by construction,
+            // so its end is the honest moment to drop it. An identified session still
+            // leaves it alone: it may be a peer's.
+            try {
+                fs.unlinkSync(path.join(root, roadmap_claim_rel(session_id)));
+            } catch {
+                /* absent or unwritable — a leftover claim expires with its record */
+            }
             return 0;
         }