instar 1.3.577 → 1.3.579

package/upgrades/1.3.578.md

@@ -0,0 +1,64 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A new constitutional standard ("An Autonomous Run Must Outlive Its Session") plus the
+fix behind it. The mid-work resume queue (the system that revives a reaped autonomous
+run, #1157) takes a host-local lock so two machines can't corrupt its shared state.
+A machine RENAME used to leave a stale lock the queue mistook for a shared-volume
+conflict — so it silently disabled the entire run-revival guard and never said so
+(the 2026-06-15 incident). Two changes:
+
+- **Rename-aware lock (GAP-D).** When the lock shows a different host, the queue now
+  distinguishes a single-host rename (provably host-local disk + dead pid + ≥5min
+  stale heartbeat → auto-heal the lock via an O_EXCL first-writer-wins takeover) from
+  a genuine shared-volume conflict (stay disabled). FAIL-CLOSED on any uncertainty
+  (unknown filesystem, `df` failure, live pid, fresh heartbeat). The original HARD
+  INVARIANT — never pid-probe a foreign-host lock — is fully preserved when auto-heal
+  is off. Ships **fleet-default OFF** (`monitoring.resumeQueue.autoHealStaleHostLock`),
+  dev-agent dryRun-first (logs "would auto-heal" without rewriting) before going live.
+- **A disabled revival queue is now LOUD (D2).** The queue self-reports to the
+  guard-posture inventory (`GUARD_MANIFEST` entry + `guardStatus()` + an unconditional
+  registration), so a disabled revival queue reads `off-runtime-divergent` on
+  `GET /guards` and raises one aggregated attention item — never silently inert.
+
+No new route. New code-defaulted config key (kept out of ConfigDefaults to preserve
+the fleet flip, consistent with #1157). Signal-only surfacing; the only authority is
+the queue refusing to start itself (bounded self-recovery, fail-closed).
+
+## What to Tell Your User
+
+- **Your autonomous work survives a machine rename now** (dev agent): "If I rename or
+  restore this machine, the system that brings a reaped autonomous run back no longer
+  quietly switches itself off. On a provable same-machine rename it heals its own lock
+  (carefully — only on a local disk, with the old process gone); on anything uncertain
+  it stays cautious. And if that revival system is ever genuinely disabled, you'll see
+  it flagged on the guards view with one alert instead of silence." ⚗️ Experimental —
+  the self-heal ships dark on the fleet (dev-agent first) and rolls out more widely
+  only after it's proven safe.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| A machine rename auto-heals the resume-queue lock instead of silently disabling revival | Automatic on the dev agent (`monitoring.resumeQueue.autoHealStaleHostLock`; fleet default off) |
+| A disabled revival queue surfaces as `off-runtime-divergent` | `GET /guards` (automatic) |
+| Diagnose "why didn't my autonomous run come back?" | `GET /guards` + `GET /sessions/resume-queue` (disabled reason) |
+
+## Evidence
+
+- Unit (`tests/unit/resume-queue-autoheal-lock.test.ts`, 11): the FD1 device-source
+  truth-table (local `/dev/*` → local; `//host`/`host:/path` → not; unknown/tmpfs/map →
+  fail-closed); auto-heal fires only on local-FS + dead-pid + stale-heartbeat; stays
+  disabled on a non-local FS or a live pid; dryRun logs-but-does-not-rewrite; auto-heal
+  off preserves today's behavior; `guardStatus()` reporting.
+- Integration (`tests/integration/resume-queue-guard-posture.test.ts`, 3): a
+  runtime-disabled queue classifies `off-runtime-divergent` through the real
+  GUARD_MANIFEST entry + `deriveGuardRow`; a healthy queue does not.
+- Regression: the full resume-queue unit + route suite (100 tests) stays green —
+  including the existing HARD-INVARIANT test that a foreign-host lock is never
+  pid-probed (which guards against re-introducing the cross-host probe). tsc clean;
+  `lint-guard-manifest` clean. Independent Phase-5 second-pass review concurred.

package/upgrades/1.3.579.md

@@ -0,0 +1,63 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A signal-only backstop for the word≠action gap: when the agent says a CONCRETE
+future action in a conversational turn ("I'll restart the server", "relaunching
+now", "pushing the change"), a thin Stop hook posts the turn to a new server route
+`POST /action-claim/observe`, which classifies the claim and opens an idempotent
+follow-through **commitment** for the topic — so the existing PromiseBeacon + the
+revival path make sure the action actually happens instead of being silently
+dropped.
+
+- `src/core/action-claim.ts` — deterministic, high-precision classifier (closed
+  concrete-verb set; first-person-scoped; sentence-initial-participle for the
+  "Relaunching now" idiom; rejects vague filler, past tense, quotes, and
+  imperatives/questions/third-person directed at others). Fails toward NOT
+  registering.
+- `CommitmentTracker.record()` — idempotent `externalKey` create (the missing
+  dedupe primitive): a restated claim updates ONE commitment instead of spawning N.
+- The route enforces a per-topic cap + a 6h auto-expiry. The hook ALWAYS exits 0 —
+  it never blocks a message. Off by default behind `messaging.actionClaim.enabled`.
+
+Completed-action verification (checking "I already pushed it" against real evidence)
+is a tracked follow-up <!-- tracked: CMT-1554-sibling action-claim-A2-evidence-primitive --> — it needs a per-turn tool-call-evidence primitive that
+doesn't exist yet; the founding incident was a future-action claim, which this
+covers.
+
+## What to Tell Your User
+
+- **A concrete thing I say I'll do becomes a tracked promise** (when enabled): "If I
+  say I'll restart/push/deploy/merge something, that now opens a tracked commitment
+  so I actually follow through — instead of it being a sentence that might quietly
+  never happen. It's careful (vague 'I'll take a look' doesn't trigger it), it never
+  blocks my messages, and it de-duplicates so restating the same thing doesn't pile
+  up reminders." ⚗️ Experimental — ships off by default; enabled on the dev agent
+  first to prove it out before any fleet rollout.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| A concrete future-action claim opens a tracked follow-through commitment | Automatic when `messaging.actionClaim.enabled` (off by default) |
+| Idempotent — a restated claim updates one commitment, not many | Automatic (`externalKey` dedupe) |
+| Diagnose "why did a commitment appear when I said I'd restart X?" | `GET /commitments` — that's this sentinel tracking the stated action |
+
+## Evidence
+
+- Unit (`tests/unit/action-claim.test.ts`, 9): classifier both sides — catches the
+  founding "Relaunching now" + first-person near-future forms + participle
+  normalization; rejects vague filler, past tense, quotes, AND
+  imperatives/questions/third-person directed at others (the Phase-5 precision fix).
+- Unit (`tests/unit/CommitmentTracker-externalKey-dedupe.test.ts`, 3): `record()`
+  returns the existing open commitment on a repeated `externalKey`; distinct keys →
+  distinct; no-key → unchanged behavior.
+- Integration (`tests/integration/action-claim-route.test.ts`, 6): `POST
+  /action-claim/observe` over the real HTTP pipeline — flag-off no-op, register,
+  dedupe, non-claim no-op, per-topic cap, 400.
+- Regression: 87 existing CommitmentTracker tests green; tsc clean; settings-template
+  valid JSON. Phase-5 second-pass review raised a precision concern (third-person
+  false positives) which was fixed and re-verified.

package/upgrades/side-effects/action-claim-followthrough-sentinel.md

@@ -0,0 +1,109 @@
+# Side-Effects Review — Action-Claim Follow-Through Sentinel (P2)
+
+Spec: `docs/specs/action-claim-followthrough-sentinel.md` (converged + approved).
+Change: a thin Stop hook posts each finished conversational turn to a new server
+route `POST /action-claim/observe`, which classifies a CONCRETE future-action claim
+("I'll restart it", "relaunching now") and opens an idempotent follow-through
+commitment. Signal-only, dark by default. (A2 — completed-action verification —
+is DESCOPED, tracked: no per-turn evidence primitive exists.)
+
+Files:
+- `src/core/action-claim.ts` — `classifyActionClaim` + `classifyDfSourceLocal`-style deterministic classifier (FD2/FD4).
+- `src/monitoring/CommitmentTracker.ts` — `record()` idempotent `externalKey` create (FD3, the missing dedupe primitive).
+- `src/server/routes.ts` — `POST /action-claim/observe` (flag-gated, server-side classify + idempotent create + per-topic cap + expiry; signal-only).
+- `src/core/PostUpdateMigrator.ts` — `getActionClaimFollowthroughHook()` + migrateHooks deploy + migrateSettings Stop-register + migrateClaudeMd awareness.
+- `src/templates/hooks/settings-template.json` — Stop entry (new agents).
+- `src/scaffold/templates.ts` — generateClaudeMd awareness line.
+- Tests: `tests/unit/action-claim.test.ts` (7), `tests/unit/CommitmentTracker-externalKey-dedupe.test.ts` (3), `tests/integration/action-claim-route.test.ts` (6).
+
+## 1. Over-block
+Nothing is blocked — the hook ALWAYS `exit(0)`; the route never blocks a send. The
+only "over-fire" risk is registering a spurious commitment. Mitigated by FD2 (closed
+concrete-verb set; vague filler like "I'll take a look" does NOT trigger; fail toward
+NOT-registering on ambiguity) + FD3 (dedupe + auto-expiry + per-topic cap). Verified
+by the unit truth-table (both sides) + the integration no-op/cap tests.
+
+## 2. Under-block
+Misses: (a) completed-action claims ("I already pushed it") — A2, deliberately
+descoped (no per-turn evidence channel; tracked); (b) creatively-worded future
+claims outside the closed verb set — accepted under-coverage (precision over recall,
+since a false commitment nags). Both are the safe direction.
+
+## 3. Level-of-abstraction fit
+Correct. The thin hook mirrors the proven `response-review.js` Stop-hook siting; the
+classifier + dedupe run SERVER-SIDE (a plain-JS hook can't import the TS classifier);
+the dedupe lives IN `CommitmentTracker.record()` (the one writer of that store); the
+follow-through rides the EXISTING PromiseBeacon + revival path rather than a new
+mechanism. No new notification surface.
+
+## 4. Signal vs authority compliance (docs/signal-vs-authority.md)
+COMPLIANT. The hook is a pure side-effect POST that never emits `decision:block`
+(always exit 0). The route opens a commitment (a signal/record) and never gates,
+delays, or rewrites a message. The classifier is a brittle deterministic matcher used
+ONLY as a signal — never as blocking authority. The whole feature is off by default.
+
+## 5. Interactions
+- Builds ON the existing `detectTimePromise`/PromiseBeacon path rather than a second
+  classifier; the dedupe `externalKey` is tagged `actionclaim:` so the per-topic cap
+  can count its own commitments without colliding with other externalKey users.
+- `record()` idempotency is additive: absent `externalKey` → unchanged behavior
+  (verified — 87 existing CommitmentTracker tests still pass + a no-key test).
+- The Stop hook is registered AFTER the existing Stop hooks (stop-gate-router stays
+  first); it can't shadow them (it never blocks).
+
+## 6. External surfaces
+- New route `POST /action-claim/observe` (auth'd like all routes). New Stop hook
+  registered in `.claude/settings.json` (new + existing agents via migrateSettings).
+  New config keys under `messaging.actionClaim.*` (read with safe defaults).
+- No change visible to other agents/users when the flag is off (the fleet default).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+MACHINE-LOCAL BY DESIGN. The hook fires on the machine running the conversational
+turn and registers a commitment in THAT machine's CommitmentTracker — exactly where
+the turn happened and where the PromiseBeacon that follows it through runs. Commitment
+cross-machine replication (if ever wanted) rides the existing `stateSync` family,
+out of scope here. No URLs/notices that must survive a machine boundary.
+
+## 8. Rollback cost
+Trivial. The feature is off unless `messaging.actionClaim.enabled` is set; setting it
+back to false (or absent) fully disables it — the hook no-ops at its first config
+read, the route returns `feature-disabled`. The `record()` dedupe is inert without an
+`externalKey`. No migration, no data repair.
+
+## Decisions (mine, per the run's full preapproval)
+- **No `migrateConfig` entry for the flag.** Absent = off is the correct dark default,
+  consistent with how the resume-queue keys are deliberately kept out of ConfigDefaults
+  to preserve the fleet flip. The dev agent enables `messaging.actionClaim.enabled`
+  explicitly to soak before any fleet default flip (a separate reviewed decision).
+- **A2 descoped + tracked** — building it would lean on a per-turn evidence primitive
+  that doesn't exist (the P1 lesson); the founding incident was a future-action claim,
+  which the v1 feature covers.
+
+## Test coverage (Testing Integrity)
+- Unit: classifier truth-table both sides (FD2/FD4) + dedupe idempotency (FD3).
+- Integration: `POST /action-claim/observe` over the real HTTP pipeline — flag-off
+  no-op, register, dedupe (restated claim → same commitment), non-claim no-op,
+  per-topic cap, 400 on bad input.
+- E2E (`tests/e2e/action-claim-lifecycle.test.ts`, 2): boots a REAL Express server on
+  a real port and hits `POST /action-claim/observe` — the "feature is alive"
+  assertion (200, not 404/503) + a concrete claim opens a real commitment
+  (`getActive()` for the topic) + a benign message registers nothing.
+- Regression: 87 existing CommitmentTracker tests green; tsc clean; settings-template valid JSON.
+
+## Second-pass review
+**Concern raised → FIXED → re-verified.** The independent Phase-5 reviewer confirmed
+signal-only (hook always exit 0, route never blocks), correct `record()` idempotency
+(early-return before id/emit; `getActive()` excludes terminal so a terminal same-key
+mints fresh; CAS untouched; 87 existing tests green), per-topic cap counts only
+`actionclaim:`-tagged commitments, and full Migration Parity wiring — BUT found a real
+FD2 precision bug: the third classifier regex (bare present-participle + trailer) was
+NOT first-person scoped, so it false-positived on imperatives/questions/third-person
+("Did you restart it?", "Please merge the PR", "He is deploying it", "The script
+reverts …"). Left unfixed, enabling the flag would mint spurious follow-through
+commitments — the exact false-commitment-nag FD2 exists to prevent.
+
+FIX: the third regex now requires a SENTENCE-INITIAL PARTICIPLE (`(?:^|[.!?]\s+)` +
+the `-ing` form only) — keeps the founding "Relaunching now" / "Done. Pushing it now."
+and rejects all eight flagged false positives. Re-verified: classifier unit tests
+9/9 (added the third-person/imperative/interrogative rows + a sentence-initial-after-
+boundary row), route integration 6/6 — 15 green. Verdict after fix: concur.

package/upgrades/side-effects/autonomous-run-outlives-session.md

@@ -0,0 +1,114 @@
+# Side-Effects Review — autonomous-run-outlives-session
+
+Spec: `docs/specs/autonomous-run-outlives-session.md` (converged + approved).
+Change: GAP-D — the resume-queue host-lock distinguishes a single-host RENAME
+(auto-heal) from a genuine shared-volume conflict (stay disabled), fail-closed;
+a disabled revival queue self-reports to the guard-posture inventory; + the
+constitutional standard "An Autonomous Run Must Outlive Its Session".
+
+Files:
+- `src/monitoring/ResumeQueue.ts` — `classifyDfSourceLocal` + `isStateDirHostLocalDefault` (FD1), foreign-host rename-vs-conflict classifier (FD2), `takeOverLockAtomic` (FD4), `guardStatus()` (D2), `autoHealStaleHostLock` config field (FD5).
+- `src/monitoring/guardManifest.ts` — `GUARD_MANIFEST` entry `monitoring.resumeQueue.enabled` (component `ResumeQueue`).
+- `src/commands/server.ts` — dev-gate resolves `autoHealStaleHostLock`; UNCONDITIONAL `guardRegistry.register` for the queue.
+- `src/core/types.ts` — `autoHealStaleHostLock?` config field.
+- `docs/STANDARDS-REGISTRY.md` — the new standard.
+- `src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` — Agent Awareness line (new + deployed agents).
+- Tests: `tests/unit/resume-queue-autoheal-lock.test.ts` (11), `tests/integration/resume-queue-guard-posture.test.ts` (3).
+
+## 1. Over-block (what legitimate inputs does this reject that it shouldn't?)
+The auto-heal is STRICTLY ADDITIVE and gated: it can only turn a currently-DISABLED
+foreign-host case into an enabled one. It never disables a case that previously
+worked. The risk direction is "fails to heal a legitimate rename" → the queue
+stays disabled exactly as today (no regression), just with a louder surface.
+Fail-closed on any uncertainty (unknown FS, df failure, live pid, fresh heartbeat)
+means some genuine renames won't auto-heal — acceptable: the operator clears the
+lock manually as before, and the guard-posture alert now tells them to.
+
+## 2. Under-block (what failure modes does this still miss?)
+- pid recycling (FD3, accepted): a recycled dead pid that maps to a live unrelated
+  process reads as a live conflict → stays disabled + LOUD (safe direction; worst
+  case a false escalation, never corruption).
+- The narrow double-boot unlink race in `takeOverLockAtomic` (two server boots on
+  one machine within ms of each other post-rename): O_EXCL gives EEXIST to the
+  loser in the common case; the residual double-unlink window is backstopped by
+  the next-acquire live-pid + heartbeat check. Not corruption — at worst a
+  transient re-evaluation.
+- Genuine shared-volume setups where `df -P` reports a device string we don't
+  recognize as network: classified unknown → NOT local → stays disabled (correct).
+
+## 3. Level-of-abstraction fit
+Correct layer. The lock classifier lives IN `ResumeQueue.acquireLock` (the only
+place that owns the lock), and the surfacing rides the EXISTING guard-posture
+inventory (GUARD_MANIFEST + GuardRegistry + GuardPostureProbe) rather than a new
+parallel alert path. No new notification surface invented — it feeds the one that
+already aggregates and dedups (Bounded Notification Surface).
+
+## 4. Signal vs authority compliance (docs/signal-vs-authority.md)
+COMPLIANT. The auto-heal is bounded SELF-RECOVERY of the queue's own lock with a
+fail-closed default — not a brittle gate holding blocking authority over agent
+behavior or message flow. The guard-posture surfacing is a pure SIGNAL-producer
+(it reports a disabled state; it never blocks, delays, or rewrites anything). The
+default `autoHealStaleHostLock:false` keeps the behavior change off the fleet until
+proven; the dev-agent runs it dryRun-first (logs intent without rewriting).
+
+## 5. Interactions
+- Preserves the original HARD INVARIANT (never pid-probe a foreign lock) when
+  auto-heal is OFF — verified by the existing `resume-queue.test.ts:417` invariant
+  test (which initially regressed and was fixed by gating all probing behind
+  `autoHealStaleHostLock`).
+- The new GUARD_MANIFEST entry passes `lint-guard-manifest` (the drainer is not
+  auto-flagged, so no orphan NOT_A_GUARD entry — which would itself fail the lint).
+- `guardRegistry.register` is UNCONDITIONAL (even when start() returns false) so a
+  lock-disabled queue reads `off-runtime-divergent`, not `missing`.
+- Does NOT touch `evidenceEligible` / the #1157 revival path — strictly the lock
+  gate. No double-fire with the existing same-host stale reclaim (that path is
+  unchanged; this is the foreign-host branch only).
+
+## 6. External surfaces
+- New config key `monitoring.resumeQueue.autoHealStaleHostLock` (fleet default
+  false). No new route. `GET /guards` and `GET /sessions/resume-queue` gain a
+  truthful disabled-state read; no schema break (additive).
+- CLAUDE.md template + migrator add one awareness bullet (new + deployed agents).
+- No external network/timing dependence beyond a single bounded (3000ms) `df -P`
+  at lock-acquisition.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+MACHINE-LOCAL BY DESIGN, and that is the whole point: the resume-queue lock + its
+state dir are deliberately host-local (a shared volume across two hosts is
+unsupported — the invariant this change PROTECTS). The fix makes the host-local
+assumption ROBUST to a rename of the SAME machine without ever weakening the
+cross-host protection (a genuine foreign live host still disables). guardStatus is
+read per-machine; each machine's `/guards` reports its own queue. No replication
+needed or wanted (a lock is intrinsically local).
+
+## 8. Rollback cost
+Cheap and immediate. `monitoring.resumeQueue.autoHealStaleHostLock:false` (the
+fleet default) fully disables the new auto-heal — reverting to today's
+disable-on-mismatch behavior — with no restart-data implications (config read at
+queue construction; next server start picks it up). The guard-posture surfacing is
+inert when the queue is healthy and harmless when disabled (it only reads state).
+No migration, no data repair. The constitutional-standard doc + CLAUDE.md lines are
+documentation (no runtime surface).
+
+## Test coverage (Testing Integrity)
+- Unit: `resume-queue-autoheal-lock.test.ts` — FD1 truth-table; auto-heal on
+  provable rename; stays-disabled on non-local FS / live pid / fresh heartbeat;
+  dryRun no-rewrite; auto-heal-off preserves original behavior; guardStatus.
+- Integration: `resume-queue-guard-posture.test.ts` — a runtime-disabled queue
+  classifies `off-runtime-divergent` through the real GUARD_MANIFEST entry +
+  `deriveGuardRow` (the route's path); a healthy queue does not.
+- E2E: the existing `tests/e2e/resume-idle-autonomous-lifecycle.test.ts` exercises
+  the queue alive end-to-end; this change is additive and those pass. (A dedicated
+  boot-with-stale-lock E2E is a candidate enhancement; the unit+integration tiers
+  cover the new logic and its wiring.)
+- Regression: full resume-queue unit + route suite (100 tests) green; tsc clean;
+  lint-guard-manifest clean.
+
+## Second-pass review
+**Concur with the review.** Independent Phase-5 audit (guard/recovery path) verified, citing code:
+1. Auto-heal can NEVER fire on a genuine shared volume with a live remote holder — `fsLocal` is dispositive and `&&`-short-circuits before any pid probe; `df -P` on a network mount never reports `/dev/*`.
+2. The HARD INVARIANT (never pid-probe a foreign lock) is preserved when auto-heal is OFF (the fleet default) — all probing is gated behind `if (this.cfg.autoHealStaleHostLock)`; the existing invariant test (default config) still asserts `probed===false`.
+3. `takeOverLockAtomic` O_EXCL first-writer-wins is correct; the only residual is the documented narrow double-boot unlink window, backstopped by the next-acquire live-pid+heartbeat check — transient/self-correcting, never durable corruption.
+4. Signal-vs-Authority compliant — the only authority is the queue refusing to start itself (bounded self-recovery, fail-closed); `guardStatus()` is a pure signal producer.
+5. No common-path regression — a healthy boot never enters the foreign-host branch and never calls `df`.
+Verdict: sound, fail-closed in the right direction, well-tested on both sides of every decision boundary, safely gated.