instar 1.0.13 → 1.1.1

package/upgrades/1.1.1.md

@@ -0,0 +1,58 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**fix(monitoring): native-module heal failures now surface on the DegradationReporter alert path.**
+`NativeModuleHealer` already rebuilds better-sqlite3 when a NODE_MODULE_VERSION
+mismatch breaks `SemanticMemory` / `TopicMemory` / `MemoryIndex` / `TokenLedger`,
+but a *failed* rebuild only landed in `<stateDir>/native-module-heals.jsonl`
+and a `console.error` line — the agent then silently ran with the affected
+feature unavailable and no Telegram alert ever fired. The healer's own jsdoc
+already named `DegradationReporter` as a consumer ("consumed by health checks
+and DegradationReporter") but no consumer was wired. This PR adds the missing
+bridge: a tiny `onHealEvent(listener)` registration surface on the healer
+and a `NativeHealDegradationBridge` subscriber wired in `AgentServer` boot
+that translates failure events into `DegradationReporter.report(...)` calls
+with component-specific impact lines (per-component dedupe; success events
+intentionally silent). No change to the heal path itself, no change to the
+jsonl log, no new dependencies.
+
+## Evidence
+
+Prior to this PR, `src/memory/NativeModuleHealer.ts` writes a `HealEvent`
+row to `<stateDir>/native-module-heals.jsonl` and `console.error`s on
+failure, but `grep -rn "DegradationReporter\|degradation"` against
+`src/memory/NativeModuleHealer.ts` and
+`src/remediation/runbooks/node-abi-mismatch.ts` returns zero call sites
+— the heal-failure event never reached the existing Telegram alert path.
+After this PR, nine new unit tests in
+`tests/unit/NativeHealDegradationBridge.test.ts` pin the wiring (reports
+on failure, silent on success, dedupes per component, returns an
+unsubscribe handle that detaches the listener, swallows listener errors,
+and exercises `NativeModuleHealer.onHealEvent` through the real
+`healBetterSqlite3Sync` early-exit path with a mocked install-prefix
+resolver) and `AgentServer` calls `bridgeNativeHealToDegradation()` next
+to the existing `NativeModuleHealer.configure(...)` call so every
+server boot gets the subscriber. Pre-existing `NativeModuleHealer`
+(17 tests) and `degradation-reporter*` (22 tests) suites pass
+unchanged.
+
+Spec: `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` (DegradationReporter
+is the v1 signal producer per §A28 / §A33; this PR adds the missing
+emit-site for heal-failure events the W-1 runbook already implied).
+Side-effects review:
+`upgrades/side-effects/native-heal-degradation-bridge.md` with
+second-pass independent audit appended (concurred).
+
+## What to Tell Your User
+
+- "When the agent's database driver gets out of sync with your Node version and can't repair itself, you now get a Telegram alert telling you what broke. Previously the agent quietly kept running with persistent memory turned off and you only found out by noticing things weren't sticking."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Native-module heal failures alert the user | Automatic. `AgentServer` wires `NativeHealDegradationBridge` at boot; any `NativeModuleHealer` rebuild that fails surfaces as a `DegradationReporter` event (Telegram alert via the agent-attention path, structured row in `<stateDir>/degradations.json`). Success heals stay silent. |
+| `NativeModuleHealer.onHealEvent(listener)` | New public registration point on the healer singleton — listener fires after every persisted heal event. Returns an unsubscribe function. Errors thrown by a listener are swallowed so observability cannot break the heal path. |

package/upgrades/side-effects/agent-worktree-convention-layer-1-2-5.md

@@ -0,0 +1,280 @@
+# Side-Effects Review — Agent Worktree Convention (Layers 1, 2, 5)
+
+**Version / slug:** `agent-worktree-convention-layer-1-2-5`
+**Date:** `2026-05-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+(see §"Phase 5 trigger check" below — this change does not touch the
+high-risk surfaces listed in the /instar-dev skill.)
+
+## Summary of the change
+
+Implements three of the five layers of the
+`docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md` (status: approved by
+Justin 2026-05-17 22:35 UTC):
+
+- **Layer 1 — `instar worktree create <branch>` CLI subcommand.** New
+  command under the existing `worktree` group. Creates a sandbox-safe
+  git worktree of the shared instar repo at
+  `~/.instar/agents/<agent>/.worktrees/<slug>/`. Refuses any other
+  destination. All validation logic lives in a new
+  `src/core/InstarWorktreeManager.ts` so it can be unit-tested without
+  spawning the CLI.
+- **Layer 2 — Scaffold seed for new agents.** `generateClaudeMd()`
+  gains a top-level "Worktree Convention" section with the literal
+  spec text plus the `GIT_AUTHOR_NAME` / `GIT_COMMITTER_EMAIL`
+  env-override caveat. `generateMemoryMd()` seeds a feedback-style
+  entry under "Project Patterns". `MachineIdentity.ts`
+  `GITIGNORE_ENTRIES` adds `.worktrees/` (consumed by `ensureGitignore`
+  on `instar init`).
+- **Layer 5 — Documentation & discoverability.**
+  `docs/self-knowledge/worktrees.md` is the authoritative reference
+  (linked from the seed CLAUDE.md). The `worktree` command group's
+  `.description()` is updated to distinguish `create` (this spec) from
+  the existing `register-keypair` (parallel-dev cryptography).
+
+**Files touched:**
+- `src/core/InstarWorktreeManager.ts` (new, ~430 lines)
+- `src/commands/worktree.ts` (existing, +~22 lines for `createWorktree` shim)
+- `src/cli.ts` (existing, +~28 lines for `create` subcommand and updated group description)
+- `src/scaffold/templates.ts` (existing, +~25 lines for Worktree Convention section + MEMORY.md entry)
+- `src/core/MachineIdentity.ts` (existing, +2 lines in `GITIGNORE_ENTRIES`)
+- `docs/self-knowledge/worktrees.md` (new)
+- `tests/unit/InstarWorktreeManager.test.ts` (new, 27 cases)
+- `tests/unit/scaffold-worktree-convention.test.ts` (new, 5 cases)
+- `tests/integration/instar-worktree-create.test.ts` (new, 6 cases)
+- `upgrades/NEXT.md` (appended one section)
+
+Layers 3 (PostUpdateMigrator step for existing agents) and 4 (lifeline
+detector) are deliberately deferred to the next `/instar-dev` cycle —
+PostUpdateMigrator changed substantially in the v1.0.x portability
+work that just landed on main, and splitting keeps the diff readable.
+Layer 3 is what propagates the convention to existing agents on
+update; until it ships, existing agents continue to use the hand-rolled
+bash helper that already exists in each agent's `.bin/`. New agents
+created via `instar init` get the seed (Layer 2) immediately.
+
+## Decision-point inventory
+
+- **CLI accept/refuse on worktree placement** — *add*. Refuses any
+  destination outside `<agent_home>/.worktrees/`. Structural
+  hard-invariant validation (path containment via `realpath`), not a
+  judgment call. Falls under the "safety guard on irreversible action"
+  carve-out in `docs/signal-vs-authority.md`.
+- **CLI accept/refuse on agent-home resolution** — *add*. Refuses
+  unregistered homes, hostile-CWD-planted `AGENT.md`, and paths that
+  don't match the `^<instarHome>/agents/[a-z0-9_-]+/?$` regex.
+  Hard-invariant validation.
+- **CLI accept/refuse on `INSTAR_REPO`** — *add*. Refuses repos whose
+  `remote.origin.url` is not in the bake-in allowlist (extendable via
+  `worktree.repoUrlAllowlist` in `~/.instar/config.json`) or whose
+  `core.hooksPath` resolves outside the repo. Hard-invariant.
+- **Audit ledger writes** — *add*. Two append paths (local
+  `.worktrees/.ledger.jsonl` + audit mirror under
+  `<stateDir>/audit/worktree-ops.jsonl`). No block/allow surface;
+  signal-only for downstream consumers. `O_NOFOLLOW` + `fstat`
+  owner/mode gate is structural validation of a security invariant,
+  not a brittle filter.
+
+No new authorities introduced. No detectors with blocking power.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **Calls from a directory that is not under any registered agent
+  home** are refused. *Intentional* — the whole point of the
+  convention is "from inside an agent home, into the agent home." If
+  an operator legitimately wants to create a worktree from a non-agent
+  shell, they use raw `git worktree add` (still works, but the Layer 4
+  detector — once it ships — will surface a one-time attention item).
+- **`INSTAR_REPO` pointing at a fork** with a non-allowlisted remote
+  URL is refused. *Operator-controllable* via
+  `worktree.repoUrlAllowlist` in `~/.instar/config.json`. Default
+  closed.
+- **Slugs containing legitimate Unicode** (anything outside
+  `[A-Za-z0-9._-]`) are refused. *Intentional*: the slug becomes a
+  directory name passed to `git worktree add`, and the threat model
+  (prompt-injection-driven slug pollution → path traversal back into
+  the shared checkout) outweighs the convenience of accepting Unicode
+  branch labels. Operators with Unicode branch names get the default
+  hyphenation of slashes; if they want a custom slug, they pass an
+  ASCII one explicitly.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Raw `git worktree add` into the shared checkout is not
+  intercepted.** Spec explicitly out-of-scope ("Non-goals"). Mitigation
+  is the Layer 4 detector (deferred to next `/instar-dev` cycle) +
+  scaffold seed memory + per-agent CLAUDE.md mention.
+- **A compromised local user** (same uid, full execution privilege)
+  can rewrite `~/.instar/config.json` to widen the
+  `worktree.repoUrlAllowlist`, plant files in `~/.instar/agents/`, or
+  replace the binary. Explicitly out-of-scope per the spec's threat
+  model boundary in §Non-goals.
+- **The agent-name segment can be any registered name**, not strictly
+  "the agent whose `INSTAR_AGENT_HOME` env var resolved here." This is
+  intentional — the env var IS the canonical identity transport set by
+  the launcher; if the env var is wrong, the launcher is broken and
+  the validation flags only structural problems (regex, registry
+  membership, realpath containment). The walk-up fallback only triggers
+  when the env var is unset and resolves against the real CWD, so
+  there's no path where a different agent's home is silently selected
+  while the current agent is running.
+- **`GIT_AUTHOR_NAME` / `GIT_COMMITTER_EMAIL` env vars override** the
+  per-worktree identity the CLI sets. The seed CLAUDE.md and
+  self-knowledge doc both warn about this; we can't override env
+  precedence without breaking legitimate per-call attribution.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+- The CLI subcommand and the manager class live where every other
+  instar CLI tool lives: `src/cli.ts` → `src/commands/<group>.ts` →
+  `src/core/<Manager>.ts`. The split between the picocolors-printing
+  command shim and the manager class matches `WorktreeKeyVault`,
+  `BackupManager`, etc. — manager has no I/O on stdout, command shim
+  has no business logic.
+- The scaffold seed change is one entry in `GITIGNORE_ENTRIES` and one
+  literal-text section in `generateClaudeMd`/`generateMemoryMd`. No
+  new code path — it rides on top of `ensureGitignore` which already
+  runs on every relevant `instar init` codepath.
+- The self-knowledge doc lives in `docs/self-knowledge/` (new
+  directory). The TreeGenerator integration (a node sourced from this
+  file) is left as a follow-up — the runtime discoverability that
+  matters for v1 is the seed CLAUDE.md mention + the `--help` text,
+  both of which are wired here.
+
+A lower-level primitive (`GITIGNORE_ENTRIES`) already exists and is
+used; the new `.worktrees/` entry just feeds it. A higher-level gate
+(the Layer 4 detector) is what the convention will eventually feed —
+that's a follow-up, but the audit ledger this change writes is the
+signal that detector will 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 has no judgment-call block/allow surface. The
+  blocks are all structural hard-invariant validation (`realpath`
+  containment, regex on agent-name segment, registry-membership lookup,
+  `git check-ref-format`, `O_NOFOLLOW` + `fstat`), which fall under the
+  "hard-invariant validation" and "safety guards on irreversible
+  actions" carve-outs documented at the bottom of
+  `docs/signal-vs-authority.md`.
+- The audit ledger is explicitly a **signal**. The spec restates this
+  in §Design ("Ledger is signal, never authority") and the manager
+  comment at `worktreeDedupeKey` carries the same invariant for the
+  Layer 4 detector — the detector's authority rule is path-based, not
+  ledger-membership-based.
+- No new LLM-backed gates introduced. No new authorities introduced.
+
+## 5. Interactions
+
+- **Shadowing:** The `worktree` command group's existing
+  `register-keypair` subcommand is unaffected — different verb,
+  different action method, different command path. Group description
+  updated to distinguish them so `instar worktree --help` is honest
+  about both purposes.
+- **Double-fire:** The hand-rolled bash helper in echo/bob's `.bin/`
+  (`instar-worktree-create.sh`) continues to exist and continues to
+  work. After Layer 3 ships, the wrapper refresh re-exports it to
+  `exec` into `instar worktree create` so the two paths converge; for
+  now, both are functional but the bash helper is the primary path on
+  echo's machine until Layer 3 lands.
+- **Races:** The CLI runs `git worktree prune` before every `add`, and
+  on add-failure it does NOT remove any partial directory — git owns
+  rollback. Two agent homes targeting the same `INSTAR_REPO` cannot
+  produce partial state on either side: each path is contained inside
+  its own `.worktrees/`, and the `worktree-list`/`prune`/`add`
+  sequence is git's own atomicity contract.
+- **Feedback loops:** None. The ledger feeds nothing in this PR (Layer
+  4 is the consumer, deferred). The scaffold seed is one-shot at
+  `instar init`.
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** the seed change shows up only
+  in *newly initialized* agent homes (Layer 2 path). Existing agents
+  see nothing until Layer 3 ships.
+- **Other users of the install base:** no — same as above. The new
+  CLI subcommand is available to anyone who upgrades, but it's purely
+  additive; no existing command's behaviour changes.
+- **External systems:** none. No network calls. No Telegram. No
+  GitHub. The integration test creates a local bare git repo in `os.tmpdir()`.
+- **Persistent state:** two new JSONL files per agent home
+  (`.worktrees/.ledger.jsonl` + `<stateDir>/audit/worktree-ops.jsonl`)
+  appended on every successful create. Both are bounded — the spec
+  defers ring-rotation to the PostUpdateMigrator (Layer 3) — and both
+  are git-ignored in the agent home. Rollback is `rm` of the two
+  files, no schema migration.
+- **Timing / runtime conditions:** the manager calls out to `git`
+  shell-out (via `execFileSync`). The integration test exercises this
+  against a real `git init`. No long-running operations; no timeouts
+  needed.
+
+## 7. Rollback cost
+
+- **Code:** revert these commits. The hand-rolled bash helper in
+  echo/bob `.bin/` already exists, has been in production today, and
+  continues to work. No agent is dependent on `instar worktree create`
+  yet because Layer 3 (migrator) hasn't shipped — until it does, no
+  existing agent has the wrapper that calls into Layer 1.
+- **Persistent state:** the two JSONL files. `rm
+  <agent_home>/.worktrees/.ledger.jsonl` and
+  `rm <stateDir>/audit/worktree-ops.jsonl` are safe one-liners; both
+  are signal-only and consumed by nothing in this PR.
+- **Agent state repair:** none required.
+- **User visibility during rollback:** the only user-visible surface
+  is the `instar worktree create` subcommand, which simply disappears.
+  Anyone using it would fall back to the bash helper.
+
+Total rollback time: under 5 minutes (one revert, two `rm`).
+
+## Conclusion
+
+The change is purely additive at the CLI layer, additive in the
+scaffold layer (new agents only), and one-shot at the `.gitignore`
+seed. All decision points are structural validators in the spec's
+hard-invariant / safety-guard carve-outs. No new authorities. No
+detectors with blocking power. 38 new tests pass (27 unit + 5
+scaffold-unit + 6 integration). Rollback is straightforward and the
+hand-rolled bash helper continues to function as a fallback.
+
+Phase 5 trigger check: the change does **not** touch outbound or
+inbound messaging dispatch, session lifecycle (spawn/restart/kill),
+compaction/respawn, coherence gates, idempotency at the transport
+layer, trust levels, or anything named sentinel/guard/gate/watchdog.
+No second-pass reviewer required.
+
+Clear to ship.
+
+## Evidence pointers
+
+- **Unit tests:** `tests/unit/InstarWorktreeManager.test.ts` (27
+  cases — agent-home resolution including the hostile-CWD path,
+  INSTAR_REPO validation including unallowlisted remote +
+  out-of-repo `core.hooksPath`, slug/branch validation including
+  path-traversal and `--upload-pack=` injection, ledger O_NOFOLLOW
+  + fstat owner/mode gate).
+- **Scaffold tests:** `tests/unit/scaffold-worktree-convention.test.ts`
+  (5 cases — literal-text assertions on the seed sections + idempotent
+  `.gitignore` addition).
+- **Integration tests:** `tests/integration/instar-worktree-create.test.ts`
+  (6 cases — happy path with identity verification + ledger + mirror,
+  node_modules default symlink, `--no-share-node-modules` opt-out,
+  slug collision without removing partial state, path-containment
+  refusal of a pre-planted symlink at `.worktrees/`, refusal of a
+  repo with unset remote).
+- **Spec:** `docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md` (approved
+  2026-05-17 22:35 UTC).
+- **ELI16:** `docs/specs/AGENT-WORKTREE-CONVENTION-ELI16.md`.
+- **Convergence report:**
+  `docs/specs/reports/agent-worktree-convention-convergence.md`.

package/upgrades/side-effects/agent-worktree-convention-layer-3-4.md

@@ -0,0 +1,285 @@
+# Side-Effects Review — Agent Worktree Convention (Layers 3 + 4)
+
+**Version / slug:** `agent-worktree-convention-layer-3-4`
+**Date:** `2026-05-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (see §"Phase 5 trigger check" below)
+
+## Summary of the change
+
+Completes the agent worktree convention spec by adding the two layers
+that propagate the convention to **existing** agents and observe
+violations on every agent boot.
+
+- **Layer 3 — `PostUpdateMigrator.migrateWorktreeConvention`.** Runs on
+  every agent update tick. Validates the agent home against Layer 1's
+  shape contract (registry membership + anchored regex), refuses if
+  `<agent_home>/.bin` is a symlink, then installs/refreshes the
+  `instar-worktree-create.sh` wrapper (always-overwrite per Migration
+  Parity Standard), idempotently adds `.worktrees/` to
+  `<agent_home>/.gitignore`, and ensures `<agent_home>/.worktrees/`
+  exists with mode `0700`. Plus a **Migration Parity Standard backfill**
+  in `migrateClaudeMd`: the "Worktree Convention" section is appended
+  to existing agents' CLAUDE.md (the scope-coherence checkpoint caught
+  this gap earlier — without it, only fresh `instar init` agents would
+  ever see the convention text). Mirrored to AGENTS.md / GEMINI.md via
+  the v1.0.15 shadow-capability mirror (added one entry to the markers
+  list).
+- **Layer 4 — `AgentWorktreeDetector`.** Runs once per agent server
+  boot, from `startServer()`. Resolves the canonical instar repo
+  deterministically (config `worktree.repoPath` or default fallback
+  chain — explicitly NOT `INSTAR_REPO` env, because env vars can
+  differ between lifeline boot and interactive sessions and the
+  detector wants consistent results across both). Runs `git worktree
+  list --porcelain` with a 2-second timeout, skips the main checkout
+  and bare entries, and emits an AttentionItem-shaped record for every
+  remaining worktree whose path is not under any registered agent's
+  `.worktrees/`. **Signal-only**: never blocks, never moves, never
+  deletes. Dedupe via the documented `worktree-misplaced:sha256(path)`
+  key. When no Telegram adapter is configured, appends to a JSONL
+  fallback at `<stateDir>/audit/worktree-detector.jsonl` (O_NOFOLLOW +
+  fstat owner/mode gate, 24h rolling-window dedupe).
+
+**Files touched:**
+
+- `src/core/PostUpdateMigrator.ts` (+~130 lines: `migrateWorktreeConvention` method, registration in `migrate()`, marker addition in `migrateFrameworkShadowCapabilities`, "Worktree Convention" section in `migrateClaudeMd`, import of `resolveAgentHome` from Layer 1's manager).
+- `src/core/AgentWorktreeDetector.ts` (new, ~330 lines).
+- `src/commands/server.ts` (+~35 lines: detector invocation after `registerAgent`).
+- `src/templates/scripts/instar-worktree-create.sh` (new — canonical wrapper template the migrator installs into `<agent_home>/.bin/`).
+- `scripts/lint-no-direct-destructive.js` (+8 lines — adds the wrapper template to `SHELL_ALLOWLIST` with documented rationale).
+- `tests/unit/migrateWorktreeConvention.test.ts` (new, 5 cases).
+- `tests/unit/AgentWorktreeDetector.test.ts` (new, 10 cases).
+- `upgrades/NEXT.md` (appended section + capabilities-table rows + updated deferred list).
+
+## Decision-point inventory
+
+- **Migrator refusal on `.bin/` symlink** — *add*. Structural safety guard
+  on an irreversible action (would write a wrapper script via a symlink
+  that resolves outside the agent home, e.g., to `/usr/local/bin`).
+  Hard-invariant: `lstat`-based, no judgment call. Carve-out applies.
+- **Migrator silent-skip on non-conforming agent home** — *add*. Refuses
+  to install the wrapper for project-bound agents whose home isn't
+  `~/.instar/agents/<name>/`. The convention only applies to
+  agent-home-living agents; project-bound agents have the project dir
+  as their primary working directory and the wrapper is meaningless
+  for them. Hard-invariant via the same regex+registry contract as
+  Layer 1.
+- **Detector — AttentionItem emission** — *add*. Pure signal. Emits to
+  AttentionQueue (which already exists as the authority for what to do
+  with attention items). Never blocks; the agent boots regardless.
+  Compliant with signal-vs-authority per the spec's explicit
+  "signal only" framing.
+- **Detector — path-based filter rule** — *add*. The detector's only
+  authoritative rule is `realpath(worktree_path) startsWith
+  realpath(<safe_root>)` for some registered agent. Pure structural
+  validator, no judgment.
+
+No new authorities introduced. No detectors hold blocking power.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **Migrator** silently skips agents whose home doesn't match the
+  `<instarHome>/agents/<name>/` shape. *Intentional* — project-bound
+  agents would receive a wrapper that points at their project dir but
+  the convention's spec is specific to agent-home-living agents.
+- **Migrator** refuses if `<agent_home>/.bin` is a symlink. Operators
+  who deliberately symlink `.bin/` to a shared dir would be refused.
+  This is documented in the spec adversarial-finding section; the
+  alternative (silently writing into the symlink target) was rejected
+  as a security regression.
+- **Detector** flags every worktree of the canonical instar repo
+  outside the safe-root set. **First-run on echo's machine will emit
+  ~30 attention items** (one per pre-existing worktree). Each is
+  deduped for 24h. Operator must drain or relocate. This is the spec's
+  documented "one-time burst" and is in the Deferred list of NEXT.md.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Migrator** does not detect or repair drift in `.worktrees/` mode
+  beyond re-asserting 0700 on every run. If something changes the
+  permissions on individual worktree directories underneath, that's
+  not policed. *Acceptable* — those are operator-managed
+  per-worktree.
+- **Detector** treats stale `git worktree list` entries (paths whose
+  worktree dir was rm'd outside `git worktree prune`) as not-misplaced
+  (they're skipped via the existsSync check). This is intentional —
+  the spec wants signal on real misplacements, not on stale
+  metadata. A separate detector for stale-metadata could be a
+  follow-up.
+- **Detector** does not yet feed AttentionQueue when Telegram is
+  configured — it falls back to JSONL in v1 because TelegramAdapter
+  initializes later in `startServer` than the detector. NEXT.md
+  Deferred list documents this; the JSONL trail is the durable
+  observation surface for v1.
+- **Compromised local user** (same uid, full execution privilege)
+  remains explicitly out-of-scope per the spec's threat-model
+  boundary.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+- **Migrator step** lives where every other `PostUpdateMigrator`
+  step lives, registered in `migrate()`. The bash-wrapper template is
+  in `src/templates/scripts/` alongside other agent-installed scripts
+  (`git-sync-gate.sh`, etc.) — same pattern as
+  `migrateConversationalCatalogPlaybookManifest`.
+- **CLAUDE.md backfill** is a content-sniffing patch inside the
+  existing `migrateClaudeMd`, matching the pattern every other Capability
+  section already uses (`Self-Discovery`, `Cloudflare Tunnel`,
+  `Dashboard`, etc.). One marker added to
+  `migrateFrameworkShadowCapabilities` is the minimal touch needed for
+  Codex/Gemini shadow propagation.
+- **Detector** is a standalone module under `src/core/` (alongside
+  Layer 1's `InstarWorktreeManager`). It's invoked once from
+  `startServer()` — a deliberate placement after `registerAgent` so
+  the registry is populated before `enumerateSafeRoots()` walks it.
+- Reused primitives: `resolveAgentHome` and `resolveInstarRepo` (from
+  Layer 1's manager) — keeps the validation rules in one place so the
+  CLI and the migrator/detector can't disagree about "what an agent
+  home is" or "what a valid instar repo is."
+
+A lower-level primitive (Layer 1's manager) is consumed; the higher
+layer (AttentionQueue) is fed via signal-only emission. No new
+authority introduced.
+
+## 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 — the migrator's blocks are structural safety guards
+  (`.bin/` symlink refusal, agent-home regex+registry check) — both
+  carve-outs in `docs/signal-vs-authority.md` ("hard-invariant
+  validation" and "safety guards on irreversible actions").
+- [x] No — the detector is **explicitly signal-only** per spec. It
+  emits AttentionItems / appends JSONL; the AttentionQueue is the
+  authority that decides what to do with them. The detector's filter
+  rule is path-based hard-invariant (no judgment).
+
+The detector's invariant — "the rule lives here and only here, never
+the audit ledger" — is restated in the file-level comment so future
+maintainers can't drift toward ledger-membership.
+
+## 5. Interactions
+
+- **Shadowing:** the migrator runs in the `migrate()` chain after
+  `migrateConversationalCatalogPlaybookManifest` and before the async
+  `migrateParityRenderings` (in `migrateAsync()`). It doesn't share
+  state with adjacent steps. The `migrateClaudeMd` backfill rides on
+  top of the existing patched-content flow, sharing `patched` with
+  earlier sections so the file is written once.
+- **Double-fire:** the wrapper template the migrator installs is now
+  the canonical source. The hand-rolled wrappers in echo + bob's
+  `.bin/` will be refreshed by the migrator on their next update tick.
+  Until then they coexist (both work — they're functionally
+  equivalent).
+- **Races:** the detector runs once per agent boot, before the server
+  starts listening. No concurrent invocations from the same agent.
+  Two agents booting concurrently could each enumerate the same
+  worktree list — each emits its own AttentionItem with the same
+  `worktree-misplaced:sha256(path)` id, which the AttentionQueue
+  collapses to a single topic per the existing dedupe contract (line
+  2949 of `TelegramAdapter.ts`). The JSONL fallback dedup is per-file
+  (each agent has its own state dir).
+- **Feedback loops:** the detector reads `git worktree list`. The
+  Layer 1 CLI writes to that list. There's no infinite-loop concern
+  because the detector emits to AttentionQueue (or JSONL), not back
+  into `git worktree`.
+- **Migration Parity:** the Layer 2 changes (seed CLAUDE.md +
+  GITIGNORE_ENTRIES) are now also delivered to existing agents on
+  update — closing the parity gap. Without the Layer 3
+  `migrateClaudeMd` backfill, existing agents would never see the
+  convention text; with it, they pick it up on the next update tick.
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** every agent picks up the
+  wrapper, the `.gitignore` entry, the `.worktrees/` directory, and
+  the CLAUDE.md section on its own next update tick. Single-agent
+  scope per spec — no cross-agent writes.
+- **Other users of the install base:** purely additive. Existing
+  workflows are unchanged. The wrapper just makes the safe path the
+  default; raw `git worktree add` still works (and gets flagged by
+  the detector).
+- **External systems:** none. No network. The detector calls `git`
+  locally, with a 2-second timeout.
+- **Persistent state:**
+  - `<agent_home>/.bin/instar-worktree-create.sh` (new file per agent
+    on update tick — always-overwrite).
+  - `<agent_home>/.gitignore` (idempotent line addition).
+  - `<agent_home>/.worktrees/` (directory creation, mode 0700).
+  - `<agent_home>/CLAUDE.md` (single section appended, idempotent
+    via content-sniff).
+  - `<agent_home>/AGENTS.md` / `GEMINI.md` (single section mirrored
+    when those shadows exist).
+  - `<stateDir>/audit/worktree-detector.jsonl` (append-only signal
+    log; bounded by 24h rolling-window dedupe before append).
+  - All git-ignored or per-machine. Rollback is `rm` of these files.
+- **Timing:** the detector's 2-second timeout means a hung
+  `git worktree list` doesn't block agent boot beyond that window.
+
+## 7. Rollback cost
+
+- **Code:** revert this commit. The Layer 1 CLI subcommand (PR #277)
+  continues to function for fresh `instar worktree create` calls.
+  Existing agents that already received the wrapper on a prior update
+  tick keep it (it works — it delegates to Layer 1).
+- **Persistent state:**
+  - The wrapper, `.gitignore` entry, and `.worktrees/` directory in
+    each agent home are harmless leftovers. No removal required.
+  - JSONL fallback files are signal-only and consumed by nothing on
+    rollback. `rm` is a safe one-liner per agent.
+  - CLAUDE.md "Worktree Convention" section is documentation only —
+    leaving it in is benign.
+  - AGENTS.md / GEMINI.md mirrored sections — same.
+- **Agent state repair:** none required.
+- **User visibility during rollback:** none.
+
+Total rollback time: under 5 minutes (one revert + optional cleanup
+sweep).
+
+## Conclusion
+
+Completes the agent worktree convention spec. Migrator backfills
+existing agents with the on-disk surface (wrapper, gitignore, dir
+permissions, CLAUDE.md section, AGENTS/GEMINI mirror) so the
+convention applies fleet-wide on the next update tick — closing the
+Migration Parity gap the scope-coherence checkpoint flagged during
+Layer 1+2+5 implementation. Detector emits signal per misplaced
+worktree without ever blocking. All structural validators are in the
+signal-vs-authority carve-outs. 15 new tests pass (5 migrator + 10
+detector). Pre-push gate green.
+
+Phase 5 trigger check: the change does **not** touch outbound/inbound
+messaging dispatch, session lifecycle, compaction, coherence gates,
+idempotency at transport, trust levels, or anything named
+sentinel/guard/gate/watchdog (the "Detector" naming is intentional —
+it's a signal producer, not a gate). No second-pass reviewer required.
+
+Clear to ship.
+
+## Evidence pointers
+
+- **Migrator unit tests:** `tests/unit/migrateWorktreeConvention.test.ts`
+  (happy path with wrapper + .worktrees/0700 + .gitignore;
+  idempotency; always-overwrites tampered wrapper; refuses
+  `.bin/`-as-symlink; silently skips project-bound agents).
+- **Detector unit tests:** `tests/unit/AgentWorktreeDetector.test.ts`
+  (silent when no misplaced; skips main checkout entry; emits one
+  AttentionItem per misplaced via injected emitter; skips when under
+  safe root; JSONL fallback writes; 24h JSONL dedupe; refuses
+  pre-planted symlink at the fallback path; resolveDetectorInstarRepo
+  honors config and returns null on no-repo).
+- **Spec:** `docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md` (approved
+  2026-05-17 22:35 UTC).
+- **Sibling artifact:**
+  `upgrades/side-effects/agent-worktree-convention-layer-1-2-5.md`
+  (Layers 1+2+5, merged in PR #277 as commit `bdf8508f`).