instar 0.28.74 → 0.28.76

package/src/templates/scripts/git-sync-gate.sh

@@ -29,6 +29,7 @@ fi
 LOCAL_CHANGES=$(git status --porcelain 2>/dev/null | head -1)
 
 # Fetch remote (silent, with timeout)
+// safe-git-allow: incremental-migration
 git fetch origin --quiet 2>/dev/null &
 FETCH_PID=$!
 sleep 5 && kill "$FETCH_PID" 2>/dev/null &
@@ -55,8 +56,11 @@ fi
 # If both sides have changes, check for potential conflicts
 if [ -n "$LOCAL_CHANGES" ] && [ "${BEHIND:-0}" -gt 0 ]; then
   # Stash local changes temporarily and try a dry-run merge
+  // safe-git-allow: incremental-migration
   git stash --quiet 2>/dev/null
+  // safe-git-allow: incremental-migration
   MERGE_OUTPUT=$(git merge-tree "$(git merge-base HEAD "$TRACKING_BRANCH")" HEAD "$TRACKING_BRANCH" 2>/dev/null)
+  // safe-git-allow: incremental-migration
   git stash pop --quiet 2>/dev/null
 
   if echo "$MERGE_OUTPUT" | grep -q "<<<<<<"; then

package/upgrades/0.28.75.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — v0.28.75
+
+<!-- bump: patch -->
+
+## What Changed
+
+`StateManager` now discriminates permission errors (`EPERM`/`EACCES`) from JSON corruption when reading state files. Previously, any failure in `getSession`, `listSessions`, `getJobState`, or `get` was reported as "Corrupted ... file" — including `EPERM` from launchd-spawned processes lacking macOS Full Disk Access on `~/Documents`. A new internal helper `describeReadError(err, filePath)` classifies failures into `permission`, `parse`, or `io` and feeds the discriminated reason into the DegradationReporter and `console.warn` line.
+
+The null-return contract is preserved exactly. `feature`, `primary`, `fallback`, and `impact` strings are unchanged. Only the `reason` content is improved. No API surface changes.
+
+Closes feedback cluster `cluster-degradation-statemanager-getjobstate-corrupted-job-state-fi` (45 reports across `ai-guy` and `sagemind` agents) and prevents future reports from being mis-clustered as corruption.
+
+## What to Tell Your User
+
+- **Clearer state-file errors**: when I can't read a state file because of a permissions issue (common on macOS when I'm started by a system service that doesn't have Full Disk Access on your Documents folder), I'll now say so plainly instead of telling you the file is corrupted. That should make the fix obvious — granting Full Disk Access in System Settings — instead of sending you on a corruption hunt.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Discriminated state-file read errors | automatic — appears in degradation reports and warnings |
+
+## Evidence
+
+Field repro: cluster `cluster-degradation-statemanager-getjobstate-corrupted-job-state-fi` shows 45 reports of `EPERM: operation not permitted, open '<path>'` mislabeled as "Corrupted job state file". Reporters: `ai-guy` and `sagemind` running instar 0.28.73 against `.instar/state/jobs/*.json` and `.instar/state/agent-attention-topic.json` files in `~/Documents/Projects/*`.
+
+Post-change verification: `tests/unit/StateManager.test.ts` 26/26 passing, including a new `discriminates permission errors from corruption (EPERM/EACCES)` test that chmod 0o000s a file and asserts the warning emitted is keyed `permission`, not `parse` or `Corrupted`.
+
+Build: clean.

package/upgrades/0.28.76.md

@@ -0,0 +1,67 @@
+# Upgrade Guide — v0.28.76
+
+<!-- bump: patch -->
+
+## What Changed
+
+`POST /internal/telegram-forward` no longer reports the backward-compat
+`TelegramLifeline.versionMissing` event into the feedback pipeline as a
+`[DEGRADATION]` signal. The condition (an upgraded but un-restarted lifeline
+forwarding a Telegram message without the Stage-B `lifelineVersion` field) is
+expected, accepted, and documented behaviour — emitting it as a critical
+degradation was producing noisy regressions in cluster
+`cmo7wswhj0000mgmdbw4j7dyd` every time any pre-Stage-B lifeline forwarded a
+message.
+
+The forward itself still succeeds via the documented backward-compat path;
+the response, the inbound-message log, and the version-handshake logic for
+lifelines that *do* send `lifelineVersion` are all unchanged. On the first
+occurrence per server process, a one-shot `console.info` is emitted so the
+operator-side observability signal is preserved without per-request log
+spam.
+
+The systemic work to give `DegradationReporter` a typed severity / category
+field (so callers can mark events as ERROR vs COMPAT_SIGNAL at the reporter
+layer rather than the call site) remains tracked under PROP-543 and is
+deliberately out of scope for this release.
+
+## What to Tell Your User
+
+- **Quieter feedback signal**: I won't keep logging a critical-looking
+  message every time my lifeline forwards a Telegram note before I've had a
+  chance to restart it. The forward still works the same way; only the
+  noisy critical report goes away.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Quieter pre-Stage-B lifeline forwards | Automatic on upgrade |
+
+## Evidence
+
+Reproduction (before fix):
+
+1. Run a lifeline at v0.28.67 or later, then upgrade the server-side package
+   without restarting the lifeline daemon.
+2. Send a Telegram message that the lifeline forwards via
+   `POST /internal/telegram-forward`.
+3. The handler accepts the forward and emits a
+   `[DEGRADATION] TelegramLifeline.versionMissing: …` feedback event,
+   classified as critical by the Portal cluster intake.
+
+After fix:
+
+1. Same setup; same forward; same successful response.
+2. On the first forward per server process, a single
+   `[telegram-forward] Accepted pre-Stage-B lifeline forward …`
+   `console.info` is emitted; subsequent forwards on the same process emit
+   nothing.
+3. No `TelegramLifeline.versionMissing` feedback events are submitted, so
+   cluster `cmo7wswhj0000mgmdbw4j7dyd` does not auto-reopen on every
+   forward.
+
+`grep -rn versionMissing src/ tests/ test/ __tests__/` shows the symbol
+appears only in `routes.ts` (the one-shot guard and the comment explaining
+it). No test changed because the call site has no existing test coverage of
+the reporter side-effect.

package/upgrades/side-effects/0.28.75.md

@@ -0,0 +1,53 @@
+# Side Effects — fix(StateManager): discriminate EPERM/EACCES from JSON corruption
+
+**Cluster**: `cluster-degradation-statemanager-getjobstate-corrupted-job-state-fi`
+**Risk**: LOW (diagnostic-only)
+**Spec**: `docs/specs/fix-statemanager-eperm-discrimination.md`
+
+## What changes (summary)
+
+`StateManager.ts` adds a `describeReadError(err, filePath)` helper that classifies read errors into `permission` (EPERM/EACCES), `parse` (SyntaxError), and `io` (other). All four read sites — `getSession`, `listSessions`, `getJobState`, `get` — use the helper to populate `console.warn` and the `DegradationReporter.report({reason})` field. The null-return contract, the `feature` field, and `primary`/`fallback`/`impact` strings are preserved.
+
+## 1. What user-facing behavior changes?
+
+The DegradationReporter `reason` text changes for state-file read failures. Permission errors now read "Permission denied reading <path> (EPERM). On macOS, launchd-spawned processes need Full Disk Access to read under ~/Documents." instead of "Corrupted job state file: EPERM: operation not permitted, open '<path>'". JSON parse errors now read "Corrupted state file <path> (JSON parse failed): <message>". I/O errors get a generic "Failed to read <path> (<code>): <message>".
+
+No CLI surface, dashboard view, or API endpoint changes shape. Anyone consuming the DegradationReporter feed sees better-targeted reasons; anyone grouping by `feature`/`fallback` is unaffected.
+
+## 2. What ledger / state / on-disk artifacts change?
+
+None. The change is in the catch handler of read paths. No writes added, no schema changes, no new files. State files on disk are read identically.
+
+## 3. What downstream agents / consumers rely on the previous behavior?
+
+The Outside-Dawn feedback pipeline currently clusters reports by `feature` and (sometimes) substring-match on `reason`. The cluster `cluster-degradation-statemanager-getjobstate-corrupted-job-state-fi` was formed by substring "Corrupted job state file" in reasons. After this fix, EPERM reports will land in a NEW cluster keyed off "Permission denied reading" — that's the intended outcome (the reporter pipeline auto-clusters new substrings into new clusters). The old cluster is being closed out as `fixed` in this same release.
+
+No agent code consumes the `reason` text programmatically (verified: grep for `Corrupted job state file` and `Corrupted state file` across `src/` shows zero hits outside `StateManager.ts`).
+
+## 4. What tests verify the change?
+
+- `tests/unit/StateManager.test.ts` — 25 pre-existing tests pass unchanged. The "Corrupted File Handling" group still asserts `null` returns for genuine parse-error inputs.
+- New test: `discriminates permission errors from corruption (EPERM/EACCES)`. Chmod 0o000s a file, captures `console.warn` calls, asserts that any warning emitted contains "permission" and none contain "parse"/"Corrupted". Skips when running as root (where chmod is bypassed) and tolerates sandboxed runners that no-op chmod.
+
+## 5. What rollback path exists?
+
+`git revert` of the StateManager.ts diff + patch release. The revert is safe at any time:
+- No persistent state needs cleanup (the change writes nothing new).
+- Agents updated to the fixed version that subsequently downgrade keep working — the same `feature` names and null-return contract apply.
+- The new feedback cluster (keyed off "Permission denied reading") simply stops receiving new reports; existing reports remain in their cluster.
+
+## 6. What's the blast radius if the change is wrong?
+
+Bounded to log/feedback-feed cosmetics. The worst case is a confusing `reason` string in a degradation report; no functional path is changed because:
+- The catch handler still returns null on every error path it previously returned null on.
+- The `feature` and `fallback` semantics are unchanged, so the scheduler/loader logic that gates on degradation reports continues to work.
+- The new helper has no I/O of its own — it's a pure string formatter over the caught error.
+
+A bug in `describeReadError` (e.g., throwing inside the formatter) would be caught by the existing outer null-return contract test cases, which would fail and block the release.
+
+## 7. What invariants must hold after this change?
+
+- `getSession`, `listSessions`, `getJobState`, `get` still return `null` (or skip the file in `listSessions`) on ANY read failure. Verified by tests.
+- `DegradationReporter.report({feature, primary, fallback, impact})` for these paths still passes the same constants — only `reason` content is discriminated. Verified by inspection.
+- `console.warn` still emits one line per failure, prefixed `[StateManager] <method> <kind>:`. Operators tailing logs see strictly more information than before.
+- No new module-load side effects: the helper is a plain function in the same module, not a new import or class.

package/upgrades/side-effects/comprehensive-destructive-tool-containment-foundation.md

@@ -0,0 +1,74 @@
+# Side-Effects Review — Comprehensive Destructive-Tool Containment (PR 1/2 — Foundation)
+
+**Version / slug:** `comprehensive-destructive-tool-containment-foundation`
+**Date:** `2026-04-26`
+**Author:** Echo
+**Spec:** `docs/specs/COMPREHENSIVE-DESTRUCTIVE-TOOL-CONTAINMENT-SPEC.md`
+**Convergence report:** `docs/specs/reports/comprehensive-destructive-tool-containment-convergence.md`
+**Commitments:** `commitments/comprehensive-destructive-tool-containment.yaml`
+**Approval:** `approved: true` by Justin via Telegram topic 8122 on 2026-04-26 after reading the bundled review doc.
+
+## Summary of the change
+
+This is the foundation half of the comprehensive containment work. It introduces two new destructive-operation funnels (`SafeGitExecutor`, `SafeFsExecutor`), a lint rule that refuses new direct destructive callsites, a CI step that catches accidental tree mutations, an audit log, and the three structural deferral-honesty layers that prevent recurrence of the "out-of-scope trap" pattern that allowed Incident B.
+
+The migration of pre-existing direct callsites (1025 of them — 6× larger than the spec's initial estimate) is a separate PR scheduled for delivery within 7 days under principal-approved deferral with monitoring trigger (`commitment://incremental-migration`, due 2026-05-03). During the transitional period a `// safe-git-allow: incremental-migration` comment marker preserves bisectability — the lint rule blocks NEW direct callsites unconditionally; pre-existing callsites pass via marker.
+
+## Decision-point inventory
+
+Changes to decision points:
+
+- **Added**: `src/core/SafeGitExecutor.ts` — single-funnel destructive git executor. Calls `assertNotInstarSourceTree` (from PR #96) against canonicalized cwd + `-C <dir>` + `--git-dir=` + `--work-tree=` targets. Strips git-redirection env vars from caller-supplied env. Injects `GIT_CONFIG_GLOBAL=/dev/null`, `GIT_CONFIG_SYSTEM=/dev/null`, `GIT_CONFIG_NOSYSTEM=1` to disable user-gitconfig alias bypasses.
+- **Added**: `src/core/SafeFsExecutor.ts` — parallel funnel for in-process destructive `fs` calls (`rm`, `unlink`, `rmdir` and their sync variants). Same canonicalization + assertion pipeline.
+- **Added**: `scripts/lint-no-direct-destructive.js` — AST rule blocking direct `execFileSync('git', …)`, `spawn('git', …)`, `simpleGit(…)`, `execSync('git …')` AND direct `fs.rm*`, `fs.unlink*`, `fs.rmdir*` outside the closed module allowlist. Catches namespace imports, aliased imports, dynamic require, namespace-imported forms.
+- **Added**: `.github/workflows/ci.yml` working-tree integrity step at end of `unit`, `integration`, `e2e` jobs — fails build if `git status --porcelain` shows mutations.
+- **Added**: `.instar/audit/destructive-ops.jsonl` audit log — every safe-executor call appends a structured JSON line (timestamp, executor, operation, verb, target, outcome, reason, caller). Fail-soft on log-write failure.
+- **Added**: Layer A — `/instar-dev` skill deferral-honesty check. LLM classifier with regex fail-closed fallback. Refuses `recurrence-risking` items entirely unless `principal-deferral-approval` lists their commitment IDs. Refuses `tactical-deferral` items without paired tracked commitments. Time horizons: 36 hours / 6 days (10× tightened from initial 14d / 60d on principal directive).
+- **Added**: Layer B — pre-commit hook deferral-section structural check (extends `scripts/instar-dev-precommit.js`). Refuses commits with "Out-of-scope follow-ups" section header but no paired commitments file.
+- **Added**: Layer C — `/spec-converge` "recurrence-containment" reviewer angle. Two questions per deferred item: "if this never ships, does the original problem recur?" and "is there any way this could be done in current scope, even at the cost of a larger PR?"
+- **Added**: 53 new unit tests covering SafeGitExecutor + SafeFsExecutor + lint-rule bypass closures, plus regression tests reproducing Incident A and Incident B at the new funnel level.
+- **Modified**: 570 pre-existing destructive callsites carry the `// safe-git-allow: incremental-migration` marker as a transitional pass-through. Lint rule honors the marker until the migration commitment lands.
+- **Allowlist (transitional)**: `src/messaging/imessage/IMessageAdapter.ts` and `src/messaging/imessage/NativeBackend.ts` are added to the lint ALLOWLIST as transitional entries (not per-line markers) so that the foundation PR does not modify adapter source files. This keeps the pre-push adapter contract test gate from triggering on what would otherwise be no-op marker comments. PR #2 (commitment://incremental-migration, due 2026-05-03) migrates these `fs.unlinkSync` calls through `SafeFsExecutor` and removes the entries.
+
+## Roll-up verdict across the seven review dimensions
+
+1. **Over-block**: minimal. The marker mechanism is intentionally transitional — pre-existing callsites pass via marker; new ones are refused unconditionally. False-block cost on a new caller is "use the safe executor"; the cost trade is correct.
+2. **Under-block**: known transitional surface — pre-existing direct callsites can still hit the source tree if a fixture passes a misconfigured cwd. Compensating mechanisms during the transitional period: PR #96's three-class constructor guard catches manager-class instantiation; the new CI tree-mutation detector catches anything that mutated the working tree post-test; the migration commitment has a 7-day hard deadline with automatic Telegram notification on the due date.
+3. **Level-of-abstraction fit**: appropriate. Funnels at the right layer (single chokepoint per domain). Lint at the right layer (compile-time AST rule). CI detector at the right layer (post-test integration). Layers A/B/C at the developer-process layer.
+4. **Signal-vs-authority compliance**: compliant. `assertNotInstarSourceTree` is the authority (carve-out applies — irreversible action class). Lint rule is brittle pattern-matcher with refusal authority on a structural rule. Layer A LLM is smart authority; Layer B grep is brittle signal-producer; Layer C reviewer prompt is smart-LLM authority. All within carve-out.
+5. **Interactions**: tested. 53 new tests pass. Three pre-existing test failures (`agent-registry.test.ts:271,287`, `ListenerSessionManager.test.ts:359`) verified to fail on baseline commit `1f06e99` before any changes — not introduced by this work. One flaky E2E (`tunnel-private-view.test.ts`) passes in isolation, fails in full-suite ordering — pre-existing flakiness. Other test suites unaffected.
+6. **External surfaces**: lint rule extends pre-commit and pre-push gates (developer-process surface, not user-runtime). CI workflow gains a post-test step (CI surface, not user-runtime). No user-runtime API changes. Audit log is local, gitignored, and informational only.
+7. **Rollback cost**: low. Per-commit revert restores prior state. No persistent state mutations beyond the new audit log file (which is informational and gitignored). The marker comments are pure no-ops — removing them is mechanical.
+
+## Second-pass review
+
+External cross-model review across GPT 5.4, Gemini 3.1 Pro, Grok 4.1 Fast. All three returned 8–9/10 CONDITIONAL. Eleven material findings between them, all addressed in spec before approval:
+
+1. Env-var redirection bypass closure (GPT)
+2. User-gitconfig alias bypass closure via `readSync` source-tree check + `GIT_CONFIG_GLOBAL=/dev/null` injection (Gemini)
+3. Namespace-import lint coverage (Gemini)
+4. `write-tree` reclassified read-only (GPT)
+5. Path canonicalization on `cwd`/`-C`/`--git-dir`/`--work-tree` (GPT)
+6. `format-patch` shape check (Grok)
+7. LLM-unavailable fail-closed regex fallback (Grok)
+8. Classifier hallucination override path (Gemini)
+9. Audit logging (GPT, Grok)
+10. Self-compliance contradiction → pulled `safe-fs` and `ci-mutation-detector` in-scope (Gemini)
+11. Comprehensive-first stance + 10× time-horizon tightening (principal directive)
+
+Synthesis at `~/.instar/agents/echo/.claude/skills/crossreview/output/20260426-131003/synthesis.md`. Convergence report Round 4 documents per-finding disposition.
+
+## Evidence pointers
+
+- 53 new unit tests in `tests/unit/SafeGitExecutor.test.ts`, `tests/unit/SafeFsExecutor.test.ts`, `tests/unit/lint-no-direct-destructive.test.ts`. All passing.
+- Incident A regression test at `tests/integration/incident-a-fs-regression.test.ts` — verifies in-process `fs.rmSync(realInstarPath, …)` is blocked.
+- Incident B regression test at `tests/integration/incident-b-regression.test.ts` — verifies test-fixture-shape `execFileSync('git', ['add', '-A'], { cwd: <instar source root> })` is blocked.
+- Cross-review raw outputs at `~/.instar/agents/echo/.claude/skills/crossreview/output/20260426-131003/{gpt,gemini,grok,synthesis}.md`.
+- Spec frontmatter records `approved: true`, `approved-by: justin`, `approved-at`, and `principal-deferral-approval` for `commitment://incremental-migration`.
+- Commitments file lists three remaining deferrals (positive-authorization-redesign, kernel-container-guards, autostash-rebase-safety) plus the new incremental-migration with 7-day deadline. All non-`unscheduled` items have automatic Telegram-notification job triggers.
+
+## Migration deferral — explicit principal-deferral-approval
+
+Justin approved the incremental-migration deferral via Telegram topic 8122 on 2026-04-26 after acknowledging the scope-reality mismatch (spec estimated ~167 callsites; actual 1025). The deferral is recorded in the spec frontmatter under `principal-deferral-approval` with full rationale. The 7-day cap is a principal-approved override of the standard 36-hour `recurrence-risking` cap, justified by the engineering reality that 1025 mechanical migrations + their full-suite test verification cannot ship in a single PR without unacceptable risk of subtle test breakage and an extended no-progress window.
+
+This is the first real exercise of the new commitment-tracker infrastructure. The migration PR (PR 2/2) follows this one in the same session.

package/upgrades/side-effects/source-tree-guard.md

@@ -0,0 +1,340 @@
+# Side-Effects Review — Destructive tool target guard
+
+**Version / slug:** `source-tree-guard`
+**Date:** `2026-04-24`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (brittle safety-guard carve-out; see §4)`
+
+## Summary of the change
+
+Adds a new primitive `src/core/SourceTreeGuard.ts` that refuses to let
+destructive managers (`GitSyncManager`, `BranchManager`,
+`HandoffManager`) be constructed against the instar source tree. The
+guard is wired as the first statement of each manager's constructor and
+throws `SourceTreeGuardError` (code `INSTAR_SOURCE_TREE_GUARD`) before
+any collaborator touches anything. Detection is the OR of three layers
+(marker file `.instar-source-tree`, canonical `origin` URL in the
+resolved common git dir's config, or `package.json name === "instar"`
+plus two-of-N signature files). Path resolution closes the
+uncreated-subdirectory bypass via a nearest-existing-ancestor walk, and
+handles worktrees via `.git`-file parsing with
+`basename(dirname(gitdir)) === "worktrees"` common-git-dir resolution.
+Fail-closed is two-tier: detector-level inability to canonicalize/ascend
+returns TRUE; layer-level inability to evaluate returns FALSE for that
+sub-check and the OR across layers decides.
+
+Files touched:
+
+- `src/core/SourceTreeGuard.ts` (new)
+- `src/core/GitSync.ts` (+1 import, +1 assert at constructor top)
+- `src/core/BranchManager.ts` (+1 import, +1 assert at constructor top)
+- `src/core/HandoffManager.ts` (+1 import, +1 assert at constructor top)
+- `.instar-source-tree` (new — marker file at repo root)
+- `tests/unit/SourceTreeGuard.test.ts` (new — 34 tests)
+- `tests/integration/source-tree-guard-wiring.test.ts` (new — 10 tests)
+- `docs/specs/DESTRUCTIVE-TOOL-TARGET-GUARDS-SPEC.md` (spec, pre-existing)
+- `docs/specs/reports/destructive-tool-target-guards-convergence.md` (report, pre-existing)
+
+Incident context: the 2026-04-22 branch-lifecycle e2e fixture wiped 1,893
+files from the real instar checkout because destructive components
+trusted an incoming `projectDir` without verification. This PR delivers
+the tactical guardrail described in the spec. E2E sandbox hardening,
+Adriana's autostash fix, the CI mutation detector, and the
+SafeGitExecutor centralization are explicitly deferred to separate PRs.
+
+## Decision-point inventory
+
+- `src/core/SourceTreeGuard.ts :: isInstarSourceTree` — **add** — new
+  detector returning boolean based on the 3-layer OR.
+- `src/core/SourceTreeGuard.ts :: assertNotInstarSourceTree` — **add** —
+  new assertion wrapper that throws `SourceTreeGuardError`.
+- `GitSyncManager` constructor — **modify** — first statement now calls
+  the assertion; no other behavior change.
+- `BranchManager` constructor — **modify** — same.
+- `HandoffManager` constructor — **modify** — same.
+
+No existing decision points are removed or repurposed.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+Concrete over-block scenarios considered:
+
+- A parallel-dev worktree *of the instar source* used as a destructive
+  target. Blocked today. This is intended — the worktree's common git
+  dir is the real repo, so `git add -A` from the worktree mutates the
+  real repo. If someone legitimately needs this, the fix is to loosen
+  the guard deliberately, not to silently permit it.
+- A fork that keeps `package.json.name === "instar"`, ships two of the
+  signature files (likely — they're core infra), and carries the
+  `.instar-source-tree` marker (only if the forker copied it; it's in
+  the upstream repo but not automatically propagated by `git clone`).
+  Fork remotes are NOT on the canonical list, so layer (b) does not
+  match. If a fork has the marker and keeps the name+signature, it
+  blocks — the fork author can delete the marker in their repo.
+- A developer who manually sets their working dir to the instar source
+  to run a one-off script. Blocked only for destructive-manager
+  construction — read-only tools are untouched. This is the entire
+  purpose of the guard.
+- Tests that deliberately construct a manager pointed at the instar
+  source to exercise error paths. Use a `mkdtemp` sandbox instead (the
+  integration tests in this PR follow that convention).
+
+No legitimate input is rejected that shouldn't be. The one "blocked by
+design" case (worktrees of the source) matches the incident shape and
+is a deliberate guard.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- Destructive components not on the three-manager list. Addressed by
+  the pre-ship enumeration below: every direct git invocation under
+  `src/` was inventoried. See §"Pre-ship grep enumeration evidence."
+- Destructive work launched via child processes or shell scripts
+  (e.g. `nuke.ts`, `init.ts`) that bypass the manager layer. These are
+  either operator-initiated (`nuke`) or target a fresh dir (`init`),
+  not the incident shape. The SafeGitExecutor follow-up PR centralizes
+  these.
+- Fork of instar that renames `package.json`, changes canonical remote,
+  and drops the marker. By design — if all three layers disagree this
+  is not the instar source tree, guard passes.
+- A manager constructed against a fresh clone that doesn't have the
+  marker yet AND has a non-canonical remote (e.g. contributor fork)
+  AND has been renamed. Same as above — by design not caught.
+
+Under-block is scoped to "things out of this PR's lane" and enumerated
+in the spec's Out-of-Scope Follow-Ups. Nothing silently degrades.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Constructor-time on the three destructive managers is the correct
+layer for this PR. It is the point at which `projectDir` first becomes
+trusted state — below this (inside `execFileSync('git', ...)`) is too
+late (damage already in flight); above this (scattered across callers)
+is the layer the incident proved unreliable.
+
+A lower-level primitive (`SafeGitExecutor`) will additionally funnel at
+the `execFileSync` boundary in a follow-up PR. The constructor wire-in
+remains as belt-and-suspenders even after that refactor.
+
+A higher-level gate does NOT already exist for this — the incident is
+specifically the absence of such a gate. This change creates it.
+
+---
+
+## 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?**
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [x] ✅ Yes, with brittle logic — **and that is correct** under the
+  carve-out in `docs/signal-vs-authority.md` lines 74–77:
+
+  > **Safety guards on irreversible actions.** `rm -rf /`,
+  > force-pushing to main, deleting the database — these can and
+  > should be hard-blocked by brittle pattern matchers, because the
+  > cost of a false pass is catastrophic and the cost of a false
+  > block is merely "try again with the right arguments."
+
+This guard is exactly that category. False-pass cost: 1,893-file wipe +
+force-push recovery (established empirically on 2026-04-22). False-block
+cost: developer edits a path or touches a marker file once. The
+asymmetry is overwhelming and the principle explicitly excludes this
+class of check from the "brittle = signal only" rule.
+
+No judgment gate is being added. No LLM-backed contextual check is
+being bypassed. The check does not reason about message content, agent
+intent, or conversational state — it asks "is this path the source
+tree?" and acts on the yes/no. Fully compliant with the
+signal-vs-authority separation.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** The guard runs as the FIRST statement of each
+  constructor, before any other validation. It cannot shadow existing
+  checks — it precedes them. If the guard throws, later validation does
+  not run, which is correct (the path is untrusted; any later check
+  against it is moot).
+- **Double-fire:** No other component performs an equivalent check
+  today (grep confirms). Once `SafeGitExecutor` lands, both will fire;
+  that's intentional redundancy, not a bug.
+- **Races:** Pure synchronous fs reads. No shared state. No
+  concurrency hazard. The detector is idempotent and side-effect-free.
+- **Feedback loops:** None. The guard does not feed any downstream
+  decision system.
+- **Test harness interaction:** All existing `mkdtemp`-based tests
+  still pass. The smoke tier (2037 tests) passes locally post-wiring.
+  Integration test confirms that a sandbox subdirectory still
+  constructs successfully.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** none. Per-process guard only.
+- **Other users of the install base:** behaviour changes only for
+  callers constructing the three managers against the instar source
+  itself — which no legitimate user does (it would mutate the instar
+  source). Forks are intentionally not caught by layer (b); layer (c)
+  catches unrenamed forks, which is arguably a feature (forkers who
+  kept the instar name probably also don't want their own repo wiped).
+- **External systems:** no network, no LLM, no IPC. Sub-millisecond
+  synchronous fs check.
+- **Persistent state:** the `.instar-source-tree` marker file at repo
+  root is new persistent state. It's a one-line inert sentinel; its
+  only consumer is this guard. Safe to leave in place on rollback.
+- **Timing / runtime conditions:** the guard runs at constructor time,
+  before any async work. Worst case ~5ms cold (three fs reads); warm
+  cache sub-millisecond. Cannot cause gate-vs-client-timeout issues.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release:** revert the commit — delete
+  `src/core/SourceTreeGuard.ts`, remove the three one-line wire-ins,
+  ship as next patch. No code outside this module depends on the new
+  symbols. The `.instar-source-tree` marker can be left in place (inert
+  without the guard reading it) — avoids a second commit.
+- **Data migration:** none. No persistent state introduced beyond the
+  inert marker file.
+- **Agent state repair:** none. Per-process guard, no shared state.
+- **User visibility:** none — rollback restores prior behaviour
+  instantly on restart. A legitimate caller that was ever blocked by
+  this guard was almost certainly pointed at the wrong tree anyway; the
+  rollback window does not expose users to regression.
+
+Estimated hot-fix time: minutes.
+
+---
+
+## Conclusion
+
+This review produced the following design decisions locked into the
+final code:
+
+- Two-tier fail-closed (detector-level = TRUE; layer-level = FALSE for
+  that sub-check) to avoid the over-block pathology flagged in the
+  convergence review.
+- Worktree common-git-dir resolution via the
+  `basename(dirname(gitdir)) === "worktrees"` rule, falling through to
+  layer (b) inconclusive on non-standard layouts rather than guessing.
+- Canonical-remote list kept intentionally narrow (three exact URLs
+  with three narrow normalization rules: strip whitespace, strip
+  trailing slash, strip trailing `.git`). No substring or regex
+  matching.
+- Error message deliberately does NOT inline bypass instructions (a
+  tutorial-in-the-error-message is a convenient "how to defeat the
+  guard" crib sheet that outlives the reason it exists).
+- Pre-ship enumeration converts the three-manager defense from "hope
+  we found them all" to "documented inventory at ship time." Findings
+  below.
+
+The change is clear to ship. It is a necessary-but-not-sufficient step
+toward the SafeGitExecutor centralization, which is scheduled as a
+follow-up PR.
+
+---
+
+## Pre-ship grep enumeration evidence
+
+```
+$ grep -rnE "execFileSync\('git'|execSync\('git |spawn\(?'git'|spawnSync\('git'" src/
+src/core/SyncOrchestrator.ts:1163    return execFileSync('git', args, {                             non-destructive (delegates to GitSync / BranchManager / HandoffManager which are now guarded)
+src/core/ProjectMapper.ts:261        execFileSync('git', ['remote', 'get-url', 'origin'], …)       non-destructive (read-only)
+src/core/ProjectMapper.ts:275        execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], …) non-destructive (read-only)
+src/core/ScopeVerifier.ts:449        execFileSync('git', ['remote', 'get-url', 'origin'], …)       non-destructive (read-only)
+src/core/BranchManager.ts:533        execFileSync('git', args, {                                    destructive — wrapped by the guarded BranchManager constructor
+src/core/AgentConnector.ts:141       execSync('git --version', …)                                   non-destructive (version query)
+src/core/ParallelDevWiring.ts:35     execFileSync('git', ['remote', 'get-url', 'origin'], …)       non-destructive (read-only)
+src/core/GitSync.ts:1006             execFileSync('git', args, {                                    destructive — wrapped by the guarded GitSyncManager constructor
+src/core/WorktreeManager.ts:756      execFileSync('git', […'rev-parse', 'HEAD'], …)                 non-destructive (read-only)
+src/core/WorktreeManager.ts:763      execFileSync('git', […'rev-parse', '--verify', branch], …)    non-destructive (read-only)
+src/core/WorktreeManager.ts:765      execFileSync('git', […'branch', branch], …)                    branch-create only; targets a worktree path, not the source tree — deferred to SafeGitExecutor PR
+src/core/WorktreeManager.ts:767      execFileSync('git', […'worktree', 'add', …], …)                creates a new worktree, does not mutate source — out of scope
+src/core/WorktreeManager.ts:879      execFileSync('git', […'worktree', 'list', …], …)              non-destructive (read-only)
+src/core/FileClassifier.ts:298       execFileSync('git', ['checkout', '--ours', …], …)             destructive — invoked only during sync under GitSyncManager's control; guard fires at manager construction upstream
+src/core/FileClassifier.ts:302       execFileSync('git', ['add', …], …)                             destructive — same as above; upstream-guarded
+src/core/FileClassifier.ts:324       execFileSync('git', ['add', relPath], …)                       destructive — same; upstream-guarded
+src/core/HandoffManager.ts:496       execFileSync('git', args, …)                                  destructive — wrapped by the guarded HandoffManager constructor
+src/server/routes.ts:2285            execFileSync('git', ['remote'], …)                             non-destructive (read-only)
+src/server/routes.ts:3035            execFileSync('git', ['remote', 'get-url', 'origin'], …)       non-destructive (read-only)
+src/lifeline/ServerSupervisor.ts:376 spawnSync('git', ['status'], …)                                non-destructive (read-only)
+src/lifeline/ServerSupervisor.ts:384 spawnSync('git', ['rebase', '--abort'], …)                     recovery-only, operates on the agent's OWN repo (not the source tree); orthogonal to this guard
+src/commands/init.ts:386             execFileSync('git', ['init'], …)                              destructive on target dir — target is a fresh user project, not the source tree; out of scope
+src/commands/init.ts:3329            execFileSync('git', ['remote'], …)                             non-destructive (read-only)
+src/commands/nuke.ts:142             execFileSync('git', ['add', '-A'], …)                          destructive — operator-initiated on the agent's own directory; documented and out of scope
+src/commands/nuke.ts:143             execFileSync('git', ['status', '--porcelain'], …)             non-destructive (read-only)
+src/commands/nuke.ts:150             execFileSync('git', ['commit', …], …)                          destructive — same as above
+src/commands/nuke.ts:156             execFileSync('git', ['push'], …)                              destructive — same
+src/commands/nuke.ts:212             execFileSync('git', ['remote'], …)                            non-destructive (read-only)
+src/commands/machine.ts:285          execFileSync('git', ['clone', …], …)                          destructive on a fresh target, not the source tree
+src/commands/setup.ts:114            execFileSync('git', ['rev-parse', '--show-toplevel'], …)      non-destructive (read-only)
+src/monitoring/WorktreeReaper.ts:208 execFileSync('git', […'worktree', 'add', …], …)               creates a new worktree, does not mutate source
+```
+
+Summary:
+- 31 direct git invocations under `src/`.
+- Destructive call sites routed through the three guarded managers:
+  `GitSync.ts:1006`, `BranchManager.ts:533`, `HandoffManager.ts:496`,
+  plus three `FileClassifier` helpers invoked only under
+  `GitSyncManager`'s control.
+- Destructive sites NOT routed through the three managers and flagged
+  for PR 2 (SafeGitExecutor centralization): `WorktreeManager.ts`
+  branch/worktree creation, `commands/init.ts`, `commands/nuke.ts`,
+  `commands/machine.ts clone`, `ServerSupervisor.ts rebase --abort`.
+  None of these target the instar source tree in their documented call
+  patterns — they either operate on fresh targets (`init`, `clone`,
+  `worktree add`) or on the agent's own dir (`nuke`, `rebase --abort`).
+- No unguarded manager-layer destructive paths found.
+
+This inventory is the "documented enumeration at ship time" the spec's
+pre-ship acceptance criterion requires.
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/DESTRUCTIVE-TOOL-TARGET-GUARDS-SPEC.md` (approved,
+  converged).
+- Convergence report:
+  `docs/specs/reports/destructive-tool-target-guards-convergence.md`.
+- Unit tests: `tests/unit/SourceTreeGuard.test.ts` — 34 tests, all
+  green locally. Covers detector layers individually, normalization
+  rules, worktree handling (standard + non-standard + malformed +
+  relative pointer), subdirectory bypass, uncreated-subdirectory
+  bypass, symlink canonicalization, two-tier fail-closed, error
+  shape.
+- Integration tests:
+  `tests/integration/source-tree-guard-wiring.test.ts` — 10 tests, all
+  green. Covers: constructor throws for each of the three managers
+  pointed at the real instar source; uncreated-subdirectory-of-instar
+  still throws; mkdtemp sandbox construction succeeds for all three;
+  subdirectory-of-sandbox also succeeds (no over-block on legitimate
+  nested paths); side-effect isolation (state dir NOT created when
+  guard fires).
+- Smoke tier pass: `npm run test:smoke` — 2037 tests passed locally
+  post-wiring (the push-hook's gate).
+- Full-suite sample: `tsc --noEmit` clean; no new warnings.