instar 1.3.299 → 1.3.301

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T14:27:07.241Z",
-  "instarVersion": "1.3.299",
+  "generatedAt": "2026-06-05T14:40:29.461Z",
+  "instarVersion": "1.3.301",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1498,7 +1498,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "69c747497d3a6c2c7fab7060c821308cbb0c5f79d977b725327ec28cb1d487ad",
+      "contentHash": "9723a92c2d4d70ff496e1e7ffe5922afc81b918c5b4fc07d66cd840e7209c7fc",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {
@@ -1530,7 +1530,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "04be68d3457455aafe0b05870dea817aea8204ff1b4fd5f899781530d869e714",
+      "contentHash": "b52da3c14379f20c8200730995dcb3303b5a55b9a5e50cb84b9307b8b5250a36",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.300.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The migration readiness checker's two "go check the live source" triggers (the
+parity pass and the import rehearsal) now enforce ONE live fetch at a time. A
+second trigger while one is running gets an immediate, clearly-worded refusal
+instead of silently starting another full download next to the first. And when
+an operator widens the fetch budgets for a slow source, the HTTP response
+window now widens with them instead of cutting out at a fixed 6 minutes.
+
+## What to Tell Your User
+
+Nothing user-visible changes by default. If your agent drives a data-migration
+readiness check against a slow source, its checks are now polite under
+pressure: one live check at a time, and patient response windows that match the
+budgets you configured.
+
+## Summary of New Capabilities
+
+- `POST /cutover-readiness/parity-pass` and `POST /cutover-readiness/import-dryrun`
+  refuse a concurrent trigger with 409 `live source fetch already in flight
+  (<op> started <time>)` — one live source fetch at a time, shared across both.
+- The two routes' response budgets track `feedbackMigration.paritySource.totalTimeoutMs`
+  (+60s slack) when configured; the previous 360s constant remains the floor.
+- Maturity: stable (behavioral hardening of existing routes; no new surface).
+
+## Evidence
+
+Found live (2026-06-05): while feeding the migration parity window against a
+degraded source, a sequential caller turned into FOUR concurrent full fetches —
+each trigger's response died at the fixed route budget while its work kept
+running, so the caller retried, and every retry stacked another fetch onto the
+struggling source. Both halves are now under test: 10 new unit tests (guard
+refuses concurrent triggers, releases after success AND failure, is shared
+across both trigger types; route budgets derive from config, never below the
+old floor, bogus values fall back), plus a full-pipeline integration test
+proving the second concurrent POST gets a 409 and exactly one pass records.

package/upgrades/1.3.301.md

@@ -0,0 +1,44 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Two of the project's own CI guards — the no-shell-exec security check and the
+"every capability reaches every agent" delivery-completeness check — had been
+parked in a skip-list and quietly stopped guarding. Both are fixed and turned
+back on. While parked, they missed two real issues, now also fixed: one
+internal monitor used a shell pipeline where a no-shell call belongs, and the
+coordination-mandate capability family (mandate gate, ReviewExchange, Cutover
+Readiness) was never mirrored to Codex/Gemini agents' awareness files.
+
+## What to Tell Your User
+
+Nothing user-visible on Claude-based agents. If you run Codex or Gemini
+framework agents: on their next update they gain awareness of the
+coordination-mandate capabilities (how to check a mandate before acting,
+the structured review-sign-off flow, and the migration-readiness read
+surface) — previously these were Claude-only knowledge.
+
+## Summary of New Capabilities
+
+- AGENTS.md / GEMINI.md shadows now receive the **Coordination Mandate**,
+  **ReviewExchange**, and **Cutover Readiness** sections on migration (the
+  existing idempotent mirroring mechanism; append-only).
+- The security gate (no bare `execSync` outside the audited funnels) and the
+  feature-delivery-completeness gate (template ↔ migrator ↔ shadow parity) run
+  in CI again.
+- Two unit suites no longer fail on machines whose shell exports a real
+  `INSTAR_AUTH_TOKEN` (test sandboxes strip ambient credentials).
+- Maturity: stable (guard re-arms + behavior-preserving refactor; the only
+  agent-visible delta is additive shadow-file content).
+
+## Evidence
+
+2026-06-05 full-suite triage: 37 local failures enumerated; classification
+separated quarantined-guard rot (these fixes), ambient-credential env leaks
+(these fixes), one incomplete local node_modules, and box-load flakes. The
+re-armed guards pass 84/84 deterministically; the migrator + shadow surface is
+green at 49 files / 324 tests; touched suites re-run green WITH the real token
+exported, proving the hygiene fix.

package/upgrades/side-effects/parity-pass-inflight-guard.md

@@ -0,0 +1,54 @@
+# Side-effects review — parity-pass single-flight guard + budget-derived route timeout
+
+Live incident (2026-06-05 ~12:16Z, while feeding the migration parity window
+against a degraded source): a sequential feeder fired 4 parity passes; every
+POST died at the route's constant 360s budget while its handler KEPT RUNNING
+(the always-logged-outcome contract from #807) — so 4 CONCURRENT full live
+fetches piled onto an already ~16×-degraded Portal read path, each slowing the
+others. Two distinct gaps, both closed here.
+
+## 1. The change
+
+- `CutoverReadiness`: a **single-flight guard over the live source fetch**,
+  shared by `runParityPass()` and `runImportDryRunPass()` (both page the full
+  live source). A concurrent trigger is refused IMMEDIATELY with
+  `live source fetch already in flight (<op> started <ISO>)` — surfaced as the
+  routes' existing 409-records-nothing contract. The guard is released in
+  `finally` (a failed check can never wedge future passes).
+- `buildRequestTimeoutOverrides()`: the parity-pass/import-dryrun route budgets
+  now **derive from the configured source budget**
+  (`feedbackMigration.paritySource.totalTimeoutMs` + 60s slack), never below
+  the existing 360s floor. Widening the source budgets for a degraded source
+  (the #820 knobs) now widens the response window with them — previously the
+  route 408'd at the constant regardless, which is what turned a sequential
+  caller into a concurrent pile-up.
+- `AgentServer`: passes the configured `totalTimeoutMs` into the builder
+  (single-source-of-truth map unchanged otherwise).
+
+## 2. Blast radius
+
+Small and behavioral-only at the two cutover-readiness trigger routes:
+- A concurrent trigger that previously started a hidden second fetch now gets
+  an immediate 409. No caller could ever OBSERVE two concurrent passes succeed
+  (the second response was always a 408), so no working flow breaks.
+- Route timeouts for the two routes grow ONLY when an operator has explicitly
+  widened `totalTimeoutMs` in config; with no config the constant floor holds,
+  so default installs see zero change. Unrelated routes unaffected (asserted).
+- No new config keys, no migrations, no durable-state shape changes, no new
+  routes. The refusal reason string is new (additive).
+
+## 3. Test coverage
+
+- Unit (5 new, cutover-readiness.test.ts → 20): concurrent parity pass refused
+  + records nothing; guard releases after success; guard releases after a
+  FAILED check (no wedge); guard shared dry-run↔parity in both directions,
+  refusal names the holding op and persists nothing.
+- Unit (5 new, AgentServer-outbound-timeout.test.ts → 20): derived budget =
+  total+slack for both routes (the live 4200s case); below-floor configs stay
+  at the floor; zero/NaN/Infinity/negative fall back to the floor; unrelated
+  routes undisturbed; AgentServer wiring regex updated to the config-fed call.
+- Integration (1 new, cutover-readiness-routes.test.ts → 10): full-pipeline
+  concurrency — slow in-flight pass, second POST 409 'already in flight',
+  cross-op dry-run 409 names 'parity-pass', release → first completes 200 with
+  exactly one recorded pass.
+- E2E: existing cutover-readiness lifecycle suite re-run green (no new routes).

package/upgrades/side-effects/test-debt-rearm.md

@@ -0,0 +1,61 @@
+# Side-effects review — re-arm two quarantined CI gates + ambient-credential test hygiene
+
+Found during the 2026-06-05 full-suite triage (37 local failures enumerated and
+classified to root cause). Two of the repo's own source-content GUARDS had
+rotted while parked in the vitest.push.config.ts quarantine list — CI never ran
+them, so the exact bug classes they exist to catch reached main unnoticed.
+
+## 1. The change
+
+- **`src/monitoring/mcpProcessReaperDeps.ts`** — the `ps | egrep | grep -v`
+  shell pipeline (bare `execSync`) becomes `execFileSync` with argv arrays (no
+  shell, no interpolation surface); the coarse egrep pre-filter moves into JS
+  (`new RegExp(mcpGrepAlternation(), 'i')`) ahead of the existing precise
+  `matchMcpSignature` second stage. Behavior-preserving: same ps fields, same
+  two-stage filtering, same empty-string-on-failure contract.
+- **`src/core/PostUpdateMigrator.ts`** — `migrateFrameworkShadowCapabilities`
+  markers[] gains the coordination-mandate capability family
+  (`**Coordination Mandate**`, `**ReviewExchange (autonomous code review)**`,
+  `**Cutover Readiness**`). These are framework-agnostic HTTP capabilities in
+  BOTH templates.ts and the migrator, but were never mirrored to AGENTS.md /
+  GEMINI.md — a Codex/Gemini agent under a future mandate would never learn
+  `/mandate/evaluate` and would improvise around the gate (the Secret Drop
+  lesson). Mirroring is the existing idempotent slice-and-append mechanism;
+  no new mechanism.
+- **`tests/unit/feature-delivery-completeness.test.ts`** — tracks the mandate
+  family as featureSections (template ↔ migrator ↔ shadow-marker parity now
+  enforced) + the four content-sniff keys as alternate checks.
+- **`tests/unit/watchdog-bind-probe.test.ts` /
+  `tests/unit/serendipity-capture.test.ts`** — ambient-credential hygiene: both
+  spread `...process.env` into child envs, and on agent boxes the REAL
+  `INSTAR_AUTH_TOKEN` preempted the fixture tokens (Authorization-header and
+  HMAC-key assertions failed locally while green in CI). The sandboxes now
+  strip the ambient token; a test that wants one sets it explicitly.
+- **`vitest.push.config.ts`** — security.test.ts +
+  feature-delivery-completeness.test.ts REMOVED from the quarantine (re-armed;
+  both are deterministic source guards — the "environment-dependent" label was
+  wrong). TunnelManager.test.ts stays parked but its label now states the
+  truth: 22/29 tests fail because the suite predates the provider/tier rewrite
+  with the real reachability probe; rewrite tracked as a durable commitment.
+
+## 2. Blast radius
+
+- The reaper deps refactor is invisible to consumers (identical output
+  contract; the factory has no direct unit tests — covered by typecheck and
+  the McpProcessReaper suite, re-run green).
+- The markers addition only ever APPENDS missing sections to existing
+  AGENTS.md/GEMINI.md shadows on the next migration run — idempotent,
+  no-op for Claude-only installs, copies content verbatim from the
+  just-migrated CLAUDE.md so the files cannot drift.
+- Re-arming the two gates makes CI run 84 currently-green deterministic tests
+  it previously skipped. Risk is future-positive: regressions in these guards
+  now fail PRs instead of rotting.
+
+## 3. Test coverage
+
+- 5 directly-touched/affected files re-run green locally: 164 tests
+  (run WITH the real INSTAR_AUTH_TOKEN still exported — proving the hygiene
+  fix, since these exact assertions failed before it).
+- Full PostUpdateMigrator + shadow-capability surface: 49 files / 324 tests
+  green after the markers change.
+- `npx tsc --noEmit` clean.