instar 1.2.3 → 1.2.5

package/src/templates/scripts/secret-drop-retrieve.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * secret-drop-retrieve.mjs — fetch a Secret Drop submission and stream the
+ * requested field value to stdout WITHOUT ever printing the response body.
+ * All informational output goes to stderr and is limited to field NAMES,
+ * lengths, and HTTP status — never values.
+ *
+ * Hardened replacement for the ad-hoc `curl + jq` / `curl + python` pattern
+ * that historically leaked credentials in plaintext into the Bash tool
+ * transcript. The lesson: when probing an unknown JSON shape, NEVER fall
+ * back to `console.log(JSON.stringify(body))` — that's how plaintext
+ * credentials end up in shell history, session transcripts, and downstream
+ * LLM context.
+ *
+ * Usage:
+ *   node .instar/scripts/secret-drop-retrieve.mjs <token> <field-name>
+ *     → prints the field value to stdout (single line, no trailing newline)
+ *     → suitable for piping: `... password | gh secret set X`
+ *
+ *   node .instar/scripts/secret-drop-retrieve.mjs <token> --names
+ *     → prints field names + lengths to stderr; nothing to stdout
+ *     → use to discover what fields the submission contains
+ *
+ *   node .instar/scripts/secret-drop-retrieve.mjs <token> <field> --consume
+ *     → opt into one-shot semantics (the submission is removed after read).
+ *     Default is peek (non-destructive) per the 2026-05-20 hardening.
+ *
+ * Config:
+ *   Reads `authToken` and `port` from `.instar/config.json` relative to cwd.
+ *   `INSTAR_PORT` env var overrides the config port.
+ *
+ * Exit codes:
+ *   0 — value or names printed successfully
+ *   1 — HTTP error, missing field, or unexpected response shape
+ *   2 — usage error (missing args, cannot read config)
+ */
+
+import * as fs from 'node:fs';
+
+const args = process.argv.slice(2);
+const token = args[0];
+const mode = args[1];
+const consume = args.includes('--consume');
+
+if (!token || !mode || mode === '--consume') {
+  process.stderr.write('usage: secret-drop-retrieve.mjs <token> <field-name|--names> [--consume]\n');
+  process.exit(2);
+}
+
+let authToken;
+let port;
+try {
+  const config = JSON.parse(fs.readFileSync('.instar/config.json', 'utf-8'));
+  authToken = config.authToken;
+  port = config.port;
+} catch (e) {
+  process.stderr.write('cannot read .instar/config.json: ' + e.message + '\n');
+  process.exit(2);
+}
+
+// Port resolution: env > config. Mirrors the telegram-reply.sh precedence
+// so a single explicit INSTAR_PORT override flows through every agent script.
+const resolvedPort = process.env.INSTAR_PORT || port;
+if (!resolvedPort) {
+  process.stderr.write('cannot resolve port: no INSTAR_PORT env and no port in .instar/config.json\n');
+  process.exit(2);
+}
+
+const url = `http://localhost:${resolvedPort}/secrets/retrieve/${token}${consume ? '?consume=true' : ''}`;
+const res = await fetch(url, {
+  method: 'POST',
+  headers: { 'Authorization': `Bearer ${authToken}` },
+});
+
+if (!res.ok) {
+  // Surface ONLY status + the structured error message field, never the body.
+  let errMsg = '(no error message)';
+  try {
+    const body = await res.json();
+    if (typeof body?.error === 'string') errMsg = body.error;
+  } catch {
+    // Don't fall back to printing raw response body — that's the leak we're
+    // explicitly hardening against. Just report the HTTP status.
+  }
+  process.stderr.write(`HTTP ${res.status}: ${errMsg}\n`);
+  process.exit(1);
+}
+
+const body = await res.json();
+
+// Locate the values bag. The server's known shape is body.values; defend
+// against future shape changes by checking the two most-likely nestings,
+// but NEVER print the body itself.
+const values = body?.values
+  ?? body?.submission?.values
+  ?? body?.fields
+  ?? null;
+
+if (!values || typeof values !== 'object') {
+  process.stderr.write('retrieve: response did not contain a values bag (keys at top: '
+    + Object.keys(body || {}).join(', ') + ')\n');
+  process.exit(1);
+}
+
+if (mode === '--names') {
+  // Field-name listing for debugging — names + lengths only, never values.
+  for (const k of Object.keys(values)) {
+    const v = values[k];
+    const len = typeof v === 'string' ? v.length : -1;
+    process.stderr.write(`  ${k} (length ${len})\n`);
+  }
+  process.exit(0);
+}
+
+const v = values[mode];
+if (typeof v !== 'string') {
+  process.stderr.write(`retrieve: field '${mode}' not found (available: `
+    + Object.keys(values).join(', ') + ')\n');
+  process.exit(1);
+}
+
+// Stream the value to stdout, no trailing newline so it pipes cleanly into
+// `gh secret set` or `bw unlock --raw`. process.stdout.write (not console.log)
+// — no extra newline, no trailing whitespace to confuse downstream consumers.
+process.stdout.write(v);

package/upgrades/1.2.4.md

@@ -0,0 +1,69 @@
+# Upgrade Guide — v1.2.4 (worktree detector → Telegram alerts)
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Layer 4 detector now surfaces misplaced worktrees through the Telegram
+attention queue, not just the JSONL fallback.** The agent worktree
+convention's lifeline detector — added in v1.1.0 (PR #278) — has been
+running on every agent server boot and dutifully appending detected
+violations to `<stateDir>/audit/worktree-detector.jsonl`, but the
+emissions never reached the operator's Telegram. That was a known
+follow-up tracked in v1.1.0's Deferred list.
+
+This release closes that gap by moving the detector invocation from
+its old position before `TelegramAdapter` was initialized to a new
+position immediately after both TelegramAdapter setup blocks (the
+send-only and full-mode paths in `src/commands/server.ts`). When the
+agent has Telegram configured, the detector now passes
+`telegram.createAttentionItem` as its emit-attention callback;
+otherwise it falls back to the JSONL append exactly as before.
+
+The detector remains **signal-only** — every emission goes through
+the existing `AttentionItem.id` dedupe contract, the JSONL fallback
+keeps its O_NOFOLLOW + fstat + 24h rolling-window dedupe, and the
+detector still never blocks, moves, or deletes anything. The only
+behavioral change visible to the operator is: misplaced-worktree
+alerts now arrive as Telegram attention topics on the next agent
+restart, instead of being silently written to a log file the
+operator was unlikely to discover.
+
+## Evidence
+
+Reproduction prior: an agent running v1.1.0–v1.2.3 with one or more
+worktrees of the shared instar repo outside any registered agent's
+`.worktrees/` safe area would, on every server boot, emit zero
+Telegram alerts and silently append JSONL lines under
+`<stateDir>/audit/worktree-detector.jsonl`. Verified by inspecting
+the server-start log on echo's machine after each release —
+"Worktree detector: N misplaced worktree(s) flagged" appeared in
+console output but no attention topic was ever created.
+
+After this PR: the same configuration produces the same JSONL line
+PLUS a Telegram attention topic per misplaced worktree, deduped by
+the same `worktree-misplaced:sha256(path)` id the JSONL already
+used. The console line gains a `via Telegram` / `via JSONL fallback`
+suffix so the operator can tell which channel ran. Verified by
+three new wireup tests in
+`tests/unit/AgentWorktreeDetector-attention-wireup.test.ts`:
+shape-compatibility between detector output and adapter input,
+async-callback await safety (the detector awaits the emit so a
+Telegram API roundtrip latency is honored), and JSONL fallback
+preservation when `emitAttention` is undefined.
+
+## What to Tell Your User
+
+- "Your agents now actually tell you when they spot a worktree in the unsafe location. Before this release, the warning was being written to a log file in the background — the agent saw it, but you never did. Now it shows up as an attention topic in Telegram the next time the agent starts up. Same dedupe rules as before, so you won't get pinged twice for the same one within a day."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Worktree detector emits to Telegram | Automatic on every agent server boot. When the agent has Telegram configured, misplaced-worktree detections create attention topics; otherwise the JSONL fallback at `<stateDir>/audit/worktree-detector.jsonl` continues as before. Dedupe is path-hash-based via the same `worktree-misplaced:sha256(path)` id the JSONL has always used. |
+| Console reports the channel | The startup log line now reads `Worktree detector: N misplaced worktree(s) flagged via Telegram` (or `via JSONL fallback`) so the operator can confirm which channel ran without grepping the audit file. |
+
+## Deferred (Tracked Follow-ups)
+
+- The 24h rolling-window JSONL dedupe runs only on the fallback path. The Telegram path leans on `AttentionItem.id` collision in TelegramAdapter's existing `attentionItems` Map — that lookup is per-process and is reset on agent restart, so two boots within 24h on a Telegram-configured agent could theoretically emit twice for the same misplaced worktree. In practice agent restarts are infrequent enough that this isn't a real source of noise; if it ever becomes one, the fix is to consult the JSONL dedupe state from the Telegram path too.
+- The detector's first-run burst on machines with many pre-existing misplaced worktrees (echo's machine has ~30 from before the convention shipped) is now Telegram-visible for the first time. Operators may want to bulk-acknowledge them with `/done` rather than processing each individually.

package/upgrades/1.2.5.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- minor = new agent-facing capability without breaking changes -->
+
+## What Changed
+
+**feat(secret-drop): ship the hardened retrieve helper as a template — and rewrite every line of agent guidance that previously taught the unsafe pattern.**
+
+The 2026-05-20 incident exposed a credential-leak class: when an agent retrieved a Secret Drop submission via a raw `curl /secrets/retrieve/TOKEN`, the response body — including the secret value — landed in the Bash tool transcript. The fix existed as a one-off `secret-drop-retrieve.mjs` on a single agent's machine, but no other agent had it, and every line of agent-facing guidance (CLAUDE.md template, the spawned-session system message, the stuck-consumer retry message) still recommended the unsafe `curl` pattern.
+
+This release closes the gap on six interlocking surfaces:
+
+1. **Ship the hardened helper as a template.** `src/templates/scripts/secret-drop-retrieve.mjs` streams the requested field value to stdout, prints field NAMES + lengths to stderr, and structurally refuses to print the response body. New agents get it via `installSecretDropRetrieve` (called from three `init.ts` paths next to `installSerendipityCapture`).
+
+2. **Migrate existing agents.** `PostUpdateMigrator.migrateScripts` always-overwrites `.instar/scripts/secret-drop-retrieve.mjs` on every update (same pattern as `convergence-check.sh`). Idempotent — running the migrator twice produces identical content.
+
+3. **Rewrite the spawn message.** `src/server/routes.ts` no longer instructs the agent to `curl ... /secrets/retrieve/TOKEN` when a Secret Drop arrives. The new message points at `node .instar/scripts/secret-drop-retrieve.mjs TOKEN <field-name>` with an explicit warning against the raw curl pattern.
+
+4. **Rewrite the stuck-consumer retry message.** Same hardened command form, same explicit warning.
+
+5. **Rewrite the CLAUDE.md template.** `src/scaffold/templates.ts` documents the hardened command as the required retrieval pattern, with a one-line explanation of the leak class.
+
+6. **Rewrite existing CLAUDE.md files.** `PostUpdateMigrator.migrateClaudeMd` detects the legacy `curl /secrets/retrieve/TOKEN` line (port-tolerant — matches any local port literal) and replaces it with the hardened guidance. Idempotent: a CLAUDE.md that already documents `secret-drop-retrieve.mjs` is left alone.
+
+7. **Update the /capabilities `secrets.retrievalHint`.** The hint now gives the actual command form so an agent reading `/capabilities` learns the safe pattern directly from the discovery surface.
+
+## What to Tell Your User
+
+No user-visible behavior change. Agents will start using the hardened retrieve helper automatically — the next time they receive a Secret Drop submission, the spawned session reads the hardened command form from the system message, not the unsafe curl. Existing agents pick up the helper script and the CLAUDE.md rewrite on the next instar update run.
+
+If you were ever shown the unsafe curl-against-secrets-retrieve pattern in chat, that guidance has been retired across every surface; the hardened helper is the only documented path now.
+
+## Summary of New Capabilities
+
+For the agent:
+
+- `.instar/scripts/secret-drop-retrieve.mjs TOKEN field-name` — streams the value to stdout, never prints the body.
+- `.instar/scripts/secret-drop-retrieve.mjs TOKEN --names` — discover field names + lengths.
+- `.instar/scripts/secret-drop-retrieve.mjs TOKEN field-name --consume` — opt into one-shot semantics.
+
+## Evidence
+
+The leak class was reproduced before the fix: running `curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:4042/secrets/retrieve/<token>` against a known submission prints the full JSON `{"values":{"password":"actual-secret-here"}, ...}` to stdout, which lands in the Bash tool transcript.
+
+After the fix, the hardened helper isolates the value path: `node .instar/scripts/secret-drop-retrieve.mjs <token> password` streams only `actual-secret-here` to stdout (no newline, pipeable), and prints nothing else. The `--names` mode prints only `password (length 16)` to stderr; stdout stays empty.
+
+New tests:
+- `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` — 8 cases covering script install (presence, executable bit, content invariants, idempotency) + CLAUDE.md rewrite (legacy → hardened, idempotent, port-tolerant).
+- The existing `tests/unit/capabilities-discoverability.test.ts` continues to pass with the updated `secrets.retrievalHint` string.
+
+Spec: `docs/specs/secret-drop-hardened-retrieve-template.md`
+ELI16: `docs/specs/secret-drop-hardened-retrieve-template.eli16.md`
+Side-effects: `upgrades/side-effects/secret-drop-hardened-retrieve-template.md`
+
+Origin: 2026-05-20 leak incident (topic 9984) + 2026-05-21 case-study audit (topic 11141, follow-up #1).

package/upgrades/side-effects/secret-drop-hardened-retrieve-template.md

@@ -0,0 +1,123 @@
+# Side-Effects Review — Secret Drop Hardened Retrieve Template
+
+**Version / slug:** `secret-drop-hardened-retrieve-template`
+**Date:** `2026-05-21`
+**Author:** `Echo (instar-developing agent)`
+**Second-pass reviewer:** `not required` (template install + documentation rewrite; no new gate/block authority)
+
+## Summary of the change
+
+Ships the hardened `secret-drop-retrieve.mjs` as an `src/templates/scripts/` template; wires it into `init.ts` (for new agents) and `PostUpdateMigrator.migrateScripts` (for existing agents); rewrites the `[secret-drop-received]` spawn message, the `[secret-drop-stuck]` retry message, the CLAUDE.md template, and the `/capabilities.secrets.retrievalHint` to instruct the hardened command form. Adds a `migrateClaudeMd` block that detects the legacy `curl /secrets/retrieve/TOKEN` line and rewrites it in place; idempotent and port-tolerant.
+
+Files touched:
+
+- `src/templates/scripts/secret-drop-retrieve.mjs` — new template.
+- `src/commands/init.ts` — `installSecretDropRetrieve` + three call sites.
+- `src/core/PostUpdateMigrator.ts` — `migrateScripts` block (always-overwrite); `migrateClaudeMd` block (port-tolerant rewrite).
+- `src/server/routes.ts` — spawn message + stuck-consumer retry message + `/capabilities.secrets.retrievalHint`.
+- `src/scaffold/templates.ts` — CLAUDE.md Secret Drop documentation block.
+- `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` — new tests (8 cases).
+- `upgrades/NEXT.md` — release notes (minor bump).
+- `docs/specs/secret-drop-hardened-retrieve-template.{md,eli16.md}` — spec + ELI16.
+
+## Decision-point inventory
+
+- `[secret-drop-received]` spawn message — **modify** — guidance the agent reads to learn how to retrieve. Unsafe → hardened.
+- `[secret-drop-stuck]` retry message — **modify** — same retrieval path on the retry branch.
+- CLAUDE.md Secret Drop block (template + migrator) — **modify** — agent's static retrieval guidance.
+- `/capabilities.secrets.retrievalHint` — **modify** — discovery-surface guidance.
+
+No new gate/block surface introduced. The `/secrets/retrieve` endpoint behavior is unchanged.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The migrator's CLAUDE.md rewrite is the closest thing to a block: it refuses to touch a CLAUDE.md that already documents `secret-drop-retrieve.mjs` (idempotent skip). That's the desired behavior — over-block would require the migrator to refuse legitimate rewrites, which it does not.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The migrator's regex matches the exact legacy-line pattern. A CLAUDE.md that someone manually customized to use a different unsafe pattern (e.g., `wget` instead of `curl`, or a piped one-liner) would slip past the rewrite. Acceptable: the rewrite is the structural fix for the documented unsafe pattern; bespoke unsafe variants are out of scope and would be visible to anyone reading their own CLAUDE.md.
+
+The hardened helper itself still reads `.instar/config.json` for the authToken. If the config file is missing, the script exits 2 with a clear stderr message; if the file is present but `authToken` is empty, the script does a request with an empty bearer and the server returns 401 — the script prints the 401 status (no body). Both paths are safe.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+The change lives at the agent-facing instruction layer, which is the correct level. Three reasons:
+
+1. The leak is caused by the agent running a documented command verbatim. The fix is to make the documented command safe.
+2. Adding a server-side gate (e.g., refuse `/secrets/retrieve` without a hardened-client header) would create a brittle detector with block authority — violating the signal-vs-authority principle. The server stays permissive; the agent layer is hardened by making safe the only documented path.
+3. The hardened helper itself is a thin wrapper around `fetch`. It doesn't introduce new architecture; it constrains how the value flows out of the response.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface at runtime.
+
+The migrator's CLAUDE.md rewrite has commit-time block authority via the precommit hook, but only by virtue of being a code change; the migrator itself does not refuse anything at runtime. The hardened helper has no gate logic — it just streams a value or exits with an error code.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** the `[secret-drop-received]` spawn message replaces the existing one verbatim (no append, no shadow). The existing 5-minute cleanup timer and the stuck-consumer event from PR #288 are unchanged — both rely on server-side state, not on the system-message content.
+- **Double-fire:** the migrator runs each of `migrateScripts` and `migrateClaudeMd` once per `instar update` invocation. Neither path is recursive.
+- **Races:** the migrator runs single-threaded against an agent that is not yet started; no concurrent writers to the files it touches.
+- **Feedback loops:** none. The agent reading the new guidance produces no input back into the migrator.
+
+The `PostUpdateMigrator.loadRelayTemplate` helper is reused (not duplicated) for loading the new template. Symmetric with `getTelegramReplyScript`.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Agents on the same machine:** yes — every existing agent picks up `.instar/scripts/secret-drop-retrieve.mjs` on the next update, and any agent whose CLAUDE.md still has the legacy retrieve line gets it rewritten in place. The behavioral change is that the agent learns a safer command form. The unsafe `/secrets/retrieve` endpoint continues to work unchanged for any caller (including custom integrations); only the guidance is updated.
+- **Other agents on the install base:** same — Codex / Gemini agents that read CLAUDE.md / AGENTS.md / GEMINI.md get the rewrite via `migrateFrameworkShadowCapabilities` (existing migrator path that mirrors CLAUDE.md changes to non-Claude shadows).
+- **External systems:** no external surface touched.
+- **Persistent state:** none beyond the file install (which is by design).
+- **Timing / runtime conditions:** the new helper makes one `fetch` call per invocation; same latency profile as the curl it replaces.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code change. Revert the migrator + init + templates + spec/artifact files. The script previously installed by the migrator stays on disk for existing agents (the rollback doesn't delete). The CLAUDE.md rewrites previously applied to existing agents also stay — which is fine because the hardened guidance points at a script that still exists (the install path doesn't go away during a code-only rollback).
+
+Realistic rollback: revert + patch release. Under 5 minutes. The only concern would be a downstream agent that started depending on a quirk of the hardened helper (e.g., expecting an exact stderr format). The script's output contract is documented in the file header; downstream tooling using it should pin against that, not against ephemeral implementation details.
+
+---
+
+## Conclusion
+
+This is a low-risk hardening change focused on agent-facing guidance. It closes the structural side of the 2026-05-20 leak class: every documented path now teaches the safe pattern. The runtime change is a script install + a sequence of string rewrites; no new decision points introduced; signal-vs-authority preserved. No second-pass review required.
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/secret-drop-hardened-retrieve-template.md`
+- ELI16: `docs/specs/secret-drop-hardened-retrieve-template.eli16.md`
+- Tests: `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` (8 cases, all green).
+- Existing coverage that continues to pass with the updated guidance strings: `tests/unit/capabilities-discoverability.test.ts`, `tests/unit/secret-drop-hardening.test.ts`.
+- Origin: 2026-05-20 leak incident (topic 9984); 2026-05-21 case-study audit (topic 11141, follow-up #1).

package/upgrades/side-effects/worktree-detector-attention-wireup.md

@@ -0,0 +1,194 @@
+# Side-Effects Review — Layer 4 detector → AttentionQueue wireup
+
+**Version / slug:** `worktree-detector-attention-wireup`
+**Date:** `2026-05-21`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (see §"Phase 5 trigger check")
+
+## Summary of the change
+
+The Layer 4 lifeline detector (from the agent worktree convention,
+shipped in v1.1.0 via PR #278) was running on every agent server boot
+and emitting to its JSONL fallback only — the Telegram AttentionQueue
+wireup was deferred because, in `startServer()`, the detector was
+invoked at line ~2208 while `TelegramAdapter` doesn't initialize until
+line ~2810/2897. The deferred state is documented in the v1.1.0 NEXT.md
+and in `upgrades/side-effects/agent-worktree-convention-layer-3-4.md`.
+
+This PR closes the gap by moving the detector invocation to **after**
+both `TelegramAdapter` setup blocks. When Telegram is configured, the
+detector now passes `telegram.createAttentionItem` as its
+`emitAttention` callback; when it isn't, the JSONL fallback fires
+exactly as before. The detector remains signal-only — no blocking,
+no moves, no deletes.
+
+**Files touched:**
+- `src/commands/server.ts` (+62 / -29 lines: removed the old early invocation, replaced with a one-paragraph stub comment; added the new conditional invocation after the full-mode Telegram block).
+- `tests/unit/AgentWorktreeDetector-attention-wireup.test.ts` (new, 3 cases — shape-compat, async-await safety, JSONL-fallback preservation).
+- `upgrades/NEXT.md` (new — fresh v1.2.4 release).
+- `package.json` (1.2.3 → 1.2.4).
+
+## Decision-point inventory
+
+- **Detector emission target selection** — *modify*. Was unconditional
+  JSONL; is now Telegram-when-configured-else-JSONL. The selection
+  rule is a pure presence check (`telegram ? emitToTelegram : undefined`),
+  no judgment. Both paths exist in the spec.
+- **AttentionItem.id dedupe** — *pass-through*. The detector already
+  produces `worktree-misplaced:sha256(path)` ids; TelegramAdapter's
+  existing `attentionItems` Map collapses repeats. No new dedupe logic.
+- **JSONL fallback rolling-window** — *unchanged*. Same 24h, same
+  O_NOFOLLOW + fstat owner/mode gate on the fallback file.
+
+No new authorities introduced. No new detectors. Just a wiring change
+that connects an existing signal producer (detector) to an existing
+authority surface (AttentionQueue).
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The detector emits
+attention items; AttentionQueue is the authority that decides what to
+do with them. Neither side rejects the user/operator from anything.
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable.
+
+A related coverage gap worth naming (and tracked in NEXT.md Deferred):
+the 24h JSONL dedupe is per-file. The Telegram path leans on
+`AttentionItem.id` collision in TelegramAdapter's in-memory
+`attentionItems` Map, which is reset on every agent restart. Two
+agent restarts within 24h on a Telegram-configured agent could
+theoretically re-emit for the same misplaced worktree path. In
+practice, agent restarts are infrequent; if noise becomes a problem,
+the fix is to consult the JSONL dedupe state from the Telegram path
+too. Acceptable for v1.
+
+## 3. Level-of-abstraction fit
+
+Right layer. The detector lives where every other lifecycle observer
+lives (`src/core/`), invoked from the agent boot path
+(`src/commands/server.ts`), feeding the existing AttentionQueue
+surface in TelegramAdapter. The move from "before TelegramAdapter
+init" to "after TelegramAdapter init" is the only change; everything
+else reuses primitives that have been in production since v1.1.0.
+
+A smarter gate (the AttentionQueue) already exists; this PR feeds it
+the signal it was always intended to consume.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] **No — this change produces a signal consumed by an existing smart gate.** The detector remains signal-only. AttentionQueue (TelegramAdapter's `attentionItems` registry) is the authority that owns dedupe, topic creation, and operator routing. The detector's only authoritative decision is the path-based "is this worktree under a registered safe root" filter, which is hard-invariant validation (carve-out in `docs/signal-vs-authority.md`).
+
+The detector's invariant that the audit ledger is **never** consumed
+as an allowlist remains in force — the path-based rule is the
+detector's only authority surface, and that rule is restated in
+`src/core/AgentWorktreeDetector.ts`'s file-level comment.
+
+## 5. Interactions
+
+- **Shadowing:** the detector now runs AFTER `telegram.start()` and
+  after the Telegram routing/callback wireup (`wireTelegramRouting`
+  + `wireTelegramCallbacks`). It still runs BEFORE the AgentServer
+  HTTP listener (line 7037), so no inbound traffic is missed during
+  the detection sweep.
+- **Double-fire:** dedupe is owned by AttentionQueue (`item.id`
+  collision) for the Telegram path and by the JSONL rolling-window
+  scan for the fallback path. Two concurrent agent boots against the
+  same instar repo would each emit; the AttentionQueue collapse
+  protects the Telegram side, and the JSONL state-dir is per-agent
+  so cross-agent file contention is impossible.
+- **Races:** the detector awaits each `emitAttention` call (verified
+  by the async-await test in
+  `tests/unit/AgentWorktreeDetector-attention-wireup.test.ts`). The
+  TelegramAdapter's `createAttentionItem` does a network roundtrip
+  (`createForumTopic`); awaiting it keeps the detector's
+  `result.emitted` counter accurate.
+- **Feedback loops:** the detector reads `git worktree list` and
+  emits attention items. AttentionQueue creates Telegram topics. No
+  loop back into `git worktree`.
+- **Startup ordering:** moving the detector down ~700 lines in
+  `startServer()` lengthens the time between `registerAgent` and
+  the first detection by the duration of TelegramAdapter init. On
+  echo's machine that's typically <500ms (the Telegram
+  `start()` call awaits a long-poll handshake). No user-visible
+  latency change.
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** none. Each agent's
+  detection emits to its own TelegramAdapter / JSONL.
+- **Other users of the install base:** purely additive — for any
+  agent that wasn't already configured for Telegram, behavior is
+  byte-identical to v1.2.3 (JSONL only). For Telegram-configured
+  agents, attention topics will appear on next agent restart per
+  misplaced worktree.
+- **External systems:** Telegram (additional topic creates via
+  `createForumTopic`). Rate-limited by Telegram's API; one topic
+  per detection emission per misplaced path per process. Real-world
+  impact on echo's machine: ~30 attention topics on first boot
+  after this release, then near-zero per subsequent boot (all
+  deduped via item.id).
+- **Persistent state:** the existing
+  `<stateDir>/audit/worktree-detector.jsonl` fallback file is
+  unchanged. Telegram attention topic registrations land in the
+  existing TelegramAdapter state (`<stateDir>/state/attention-items.json`,
+  managed by the adapter itself).
+- **Timing:** detector still uses the existing 2-second timeout
+  on `git worktree list --porcelain`. Unchanged.
+
+## 7. Rollback cost
+
+- **Code:** revert this commit. The detector returns to its pre-PR
+  position (early in `startServer()` with `emitAttention` always
+  undefined), and the JSONL fallback resumes as the only emission
+  channel. No data migration. Attention topics already created on
+  Telegram remain — they're operator-managed and don't depend on
+  this PR's wiring.
+- **Persistent state:** no schema change. The
+  `<stateDir>/state/attention-items.json` registry is the same one
+  TelegramAdapter has owned since v0.10.x.
+- **Agent state repair:** none required.
+- **User visibility during rollback:** new attention topics stop
+  appearing; existing ones stay until the operator `/done`s or
+  `/wontdo`s them. The JSONL trail continues unchanged.
+
+Total rollback time: under 2 minutes (one revert).
+
+## Conclusion
+
+Pure wireup change. The detector and AttentionQueue have both been
+in production since v1.1.0; this PR connects them. Signal-only
+contract is preserved. Three new tests pin the shape-compat,
+async-await safety, and JSONL-fallback-preservation invariants.
+Pre-push gate green.
+
+Phase 5 trigger check: the change does **not** touch outbound or
+inbound messaging *dispatch* (the detector emits a category that
+AttentionQueue already handles), session lifecycle, compaction,
+coherence gates, idempotency at transport, trust levels, or anything
+named sentinel/guard/gate/watchdog. The detector is signal-only and
+AttentionQueue is the long-existing authority. No second-pass
+reviewer required.
+
+Clear to ship.
+
+## Evidence pointers
+
+- **Wireup tests:** `tests/unit/AgentWorktreeDetector-attention-wireup.test.ts`
+  (3 cases: shape-compat between detector output and adapter input,
+  async-callback await safety, JSONL fallback preservation).
+- **Spec:** `docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md` (approved
+  2026-05-17 22:35 UTC).
+- **Sibling artifacts:**
+  - `upgrades/side-effects/agent-worktree-convention-layer-1-2-5.md`
+    (Layer 1+2+5, merged in PR #277 as `bdf8508f`).
+  - `upgrades/side-effects/agent-worktree-convention-layer-3-4.md`
+    (Layer 3+4, merged in PR #278 as `c7e8e08b`; documented this
+    wireup as deferred follow-up).