instar 0.28.75 → 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.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/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/telegram-lifeline-version-missing-info.md

@@ -0,0 +1,76 @@
+# Side-Effects Review — TelegramLifeline.versionMissing → info-only log
+
+**Slug:** `telegram-lifeline-version-missing-info`
+**Date:** `2026-04-27`
+**Author:** Dawn (instar-bug-fix autonomous job)
+**Cluster:** `cmo7wswhj0000mgmdbw4j7dyd` (severity: critical → resolved by reclassification)
+
+## Summary of the change
+
+In `src/server/routes.ts`, the backward-compat branch of the `POST /internal/telegram-forward` handler stops emitting `TelegramLifeline.versionMissing` as a `[DEGRADATION]` feedback event. The forward itself is still accepted via the documented backward-compat path; only the *classification* of the observed transition changes.
+
+Concretely:
+
+- The call to `DegradationReporter.getInstance().report({ feature: 'TelegramLifeline.versionMissing', … })` is removed from `routes.ts:6367-6376`.
+- A one-shot `console.info` is emitted on first occurrence per process, gated by a new module-scoped `_versionMissingLogged` flag declared next to the existing `_serverVersionParsed` cache.
+- No other lines of code change. No new files. No test files added or modified — the call site has no existing test coverage and the change is observability-only.
+
+Files touched:
+- `src/server/routes.ts` — two small edits described above.
+- `docs/specs/telegram-lifeline-version-missing-info.md` — new spec (LOW-risk autonomous-approved).
+- `upgrades/side-effects/telegram-lifeline-version-missing-info.md` — this file.
+- `upgrades/NEXT.md` — release notes appended.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None. The handler still accepts the forward; nothing is rejected. Pre-Stage-B lifelines continue to work exactly as they did, including the response body and logged inbound message. The only thing that changes is whether the acceptance is also reported as a `[DEGRADATION]` event into the feedback pipeline.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+A genuine class of "lifeline running with wrong assumptions about server" issues that *also* manifest as a missing version field would no longer raise a degradation event. In practice, `lifelineVersion === undefined` only happens in the pre-Stage-B compatibility scenario — newer lifelines always send the field. Any *new* incompatibility class would also need to hit a different branch of this handler to surface, which is the correct layer.
+
+The console.info preserves the signal in server logs (the operator-side observability surface). What we lose is the per-incident feedback-pipeline submission — which was the entire point of this change, since those submissions were being mis-classified as critical.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The right long-term fix — adding a typed severity / category field to `DegradationReporter` so callers can distinguish ERROR from COMPAT_SIGNAL — is a broader API change tracked under PROP-543. This spec deliberately stays at the call site. The call site already has the contextual knowledge that *this particular* condition is observability-only (per the existing comment "emit informational signal once per cooldown" and the original commit's "Missing field accepted for backward compat."). Encoding "this is observability, not a degradation" at the call site is correct until the typed-severity refactor lands.
+
+The chosen mechanism (module-scoped boolean + console.info) matches existing patterns in `routes.ts` (e.g. `console.log('[telegram-forward] …')` at lines 6452, 6515, 6604).
+
+## 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 has no block/allow surface. It is purely a presentation/classification change about how an *already-accepted* request is reported back into the feedback pipeline. The handler still makes the same admission decision (accept the forward) it did before.
+
+## 5. Interactions
+
+- **Shadowing:** No — there is no alternative reporting path that this could shadow. The DegradationReporter call was the only emission site for `TelegramLifeline.versionMissing`. Removing it removes the signal from the feedback pipeline and only from there.
+- **Cooldown coupling:** The previous code relied implicitly on `DegradationReporter`'s per-feature alert cooldown to avoid Telegram spam. Replacing the call with a one-shot `console.info` on the same condition removes that coupling: even without cooldown, the new path emits at most once per process. Per-process log noise is bounded; restart frequency dominates.
+- **Build manifest:** `routes.ts` is a route-group source, so `scripts/generate-builtin-manifest.cjs` re-emits its inventory. No symbol added or removed (the new boolean is local), so the manifest delta is zero entries.
+
+## 6. Test coverage
+
+**What tests changed and why.**
+
+No test file is added or modified.
+
+- The pre-fix call site had no direct test referencing `TelegramLifeline.versionMissing` (`grep` confirms). The only test surface for `/internal/telegram-forward` exercises the version-handshake decision tree, not the feedback emission side-effect.
+- A "no degradation feedback emitted" assertion on this branch would require reaching into `DegradationReporter` internals, which is brittle and out of step with the existing test harness.
+- The signal-preserving `console.info` is a logging-only side-effect; in line with existing `console.log` patterns in `routes.ts`, it is intentionally untested.
+
+If a future test ever wants to assert "backward-compat path is informational only," the natural seam is the `DegradationReporter` mock in `tests/integration/server-route-degradation.test.ts` (if/when written) — verifying the reporter is *not* called for this branch.
+
+## 7. Reviewer notes
+
+The cluster research notes cite this exact fix and acknowledge the broader systemic work as PROP-543. This change is the minimal, lowest-risk realisation of the cited fix and explicitly does not anticipate the systemic refactor.
+
+A second-pass review is not required: no signal/authority change, no contract surface, no API change, single-file edit at a documented call site with no existing tests.