instar 0.28.102 → 0.28.104

package/upgrades/side-effects/f7-post-update-migrator-atomic-step.md

@@ -0,0 +1,129 @@
+# Side-Effects Review — F-7: PostUpdateMigrator atomic-step + announceOnce primitives (Tier-2)
+
+**Version / slug:** `f7-post-update-migrator-atomic-step`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Ships F-7 from the Self-Healing Remediator v2 spec (`docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §R1 Upgrade invariants + §A35 backup/sync wiring + §A50 hook-shape corrections + §A57 Tier-2 phase manifest).
+
+Two new primitives plus the A35 hook-shape changes:
+
+1. **`MigratorStepEngine`** — atomic, idempotent, run-once-per-version migration steps. Steps are registered by name + version. The engine writes a ledger at `<stateDir>/migrator-steps-completed.json` keyed by `<version>:<step-name>`. A step failure records `outcome: 'failed'` and does NOT roll back prior steps or block subsequent steps — each step is self-contained.
+
+2. **`AnnouncementManager`** — `announceOnce(id, message, channel)` primitive. Emits a message exactly once per id, then never again. Ledger at `<stateDir>/announcements-shown.json`. Used for surfacing migration completions and structural-change notices without spamming the user across restarts.
+
+3. **A35 hook-shape — `GitStateManager.DEFAULT_GITIGNORE` extension.** Const literal now contains five remediation runtime path globs (`remediation/system-reviewer-state-*.json`, `remediation/inbox-*.jsonl`, `remediation/audit-projection-*.jsonl`, `remediation/cross-process-attempts-*.jsonl`, `remediation/llm-raw-*.jsonl`). Exported as `REMEDIATION_GITIGNORE_ENTRIES` for the F-7 atomic step to use as the source-of-truth list.
+
+4. **A35 hook-shape — `BackupManager` exclusion list with feature-flag gate.** New const `REMEDIATION_EXCLUDED_PATH_PREFIXES` (exported) — the five remediation path prefixes. New optional constructor arg `isRemediationEnabled?: () => boolean` parallels the existing `isIntegratedBeingEnabled` gate. When the gate is ON, the prefixes drop any user-added `includeFiles` entry that begins with a remediation prefix. When OFF (or absent), the prefixes are inactive — strictly additive, no back-compat break.
+
+Files touched:
+- `src/core/MigratorStepEngine.ts` (add)
+- `src/core/PostUpdateMigrator.ts` (modify — add `registerStep` + `runPendingSteps` + lazy engine field; existing constructor + all 15 existing migration methods unchanged)
+- `src/core/GitStateManager.ts` (modify — extend `DEFAULT_GITIGNORE` const literal; export `REMEDIATION_GITIGNORE_ENTRIES`)
+- `src/core/BackupManager.ts` (modify — add `REMEDIATION_EXCLUDED_PATH_PREFIXES` const + export; add 5th optional constructor arg `isRemediationEnabled`; gate logic in `resolveIncludedFiles`)
+- `tests/unit/PostUpdateMigrator-atomicStep.test.ts` (add — 8 cases)
+- `tests/unit/AnnouncementManager.test.ts` (add — 5 cases)
+- `tests/unit/PostUpdateMigrator-a35-remediationPaths.test.ts` (add — 5 cases)
+- `upgrades/NEXT.md` (modify — preserves all existing entries; adds A35 + announceOnce entries)
+
+## Decision-point inventory
+
+- `PostUpdateMigrator.registerStep()` — **add** — delegates to lazy `MigratorStepEngine`. Existing 15 `migrate*` methods + `migrate()` orchestrator untouched.
+- `PostUpdateMigrator.runPendingSteps()` — **add** — async; returns `{ steps: [{name, outcome, details}] }`. Never throws.
+- `MigratorStepEngine.registerStep()` — rejects duplicate names, missing version/run.
+- `MigratorStepEngine.runPendingSteps()` — three skip reasons: `already-recorded:<outcome>`, `future-version:<step.version> > <toVersion>`, and explicit `'skipped'` from the step itself. Failed steps record `outcome: 'failed'` and DO NOT retry (operator must clear the ledger entry to retry — surfaces the failure in the report).
+- `MigratorStepEngine.writeLedger()` — atomic temp-file → fsync → rename, `0600` perms.
+- `AnnouncementManager.announceOnce()` — three-input validation (id, message, channel); records BEFORE sink-invoke so a flaky sink cannot cause duplicate emission. Sink throws are swallowed (ledger entry stands).
+- `GitStateManager.DEFAULT_GITIGNORE` const literal — **modify** — append remediation block. Backwards-compatible: previously private const is now exported (no internal call sites broken).
+- `BackupManager` constructor — **modify** — append 5th optional argument. All four existing call sites pass ≤4 args and continue to work.
+- `BackupManager.resolveIncludedFiles()` — **modify** — adds gated exclusion loop. When gate is OFF (the default — every existing caller), behavior is identical to pre-PR.
+
+No new HTTP routes. No new daemon processes. No new file types beyond two JSON ledgers in `<stateDir>`.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **A future-version step is silently skipped.** Intended. The ledger is NOT written when the step's version > `toVersion`, so the next upgrade boundary that crosses the threshold runs the step.
+- **A failed step is NOT auto-retried on the next `runPendingSteps()` invocation.** This could be seen as over-blocking — a transient failure (disk full, network blip) gets recorded as `failed` and stays that way. Trade-off accepted because the alternative (unbounded retry on every update) lets a broken step DoS every release. Operator-facing mitigation: the failed entry surfaces in the migration report; clearing the ledger key allows retry.
+- **The `BackupManager` remediation-prefix gate, when ON, drops includeFiles entries whose paths begin with a remediation prefix.** A user who manually adds `.instar/remediation/system-reviewer-state-mine.json` to `config.backup.includeFiles` will see it silently dropped. Mitigated by: (a) the gate defaults to OFF until remediation is enabled; (b) the prefixes are documented in code + spec; (c) this is the explicit spec requirement (A14 "Backed up? no" rows).
+
+No unintended over-blocks.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **No cross-machine coordination of step execution.** Two machines updating to the same version in parallel each run their own steps independently. The ledger is per-machine. This is the correct model for per-machine state (gitignore lives in `<stateDir>/.gitignore` which is per-machine via the `.instar` git repo), but a future cross-machine migration would need additional coordination.
+- **Step `run()` is not deadline-enforced.** A hung step could block subsequent steps. The engine relies on step authors to be well-behaved. Real-world steps are file I/O against `<stateDir>` and complete in <50ms; a step that calls external APIs should add its own timeout. Worst case: the migrator hangs, the next update boundary sees the same situation; the user can `kill` the process and the ledger remains consistent.
+- **The `announceOnce` sink does not retry.** If a sink fails (e.g. Telegram offline), the announcement is recorded as shown but never delivered. This is the deliberate signal-vs-authority separation: the brittle sink layer does not have authority over the ledger. A future enhancement could add a separate delivery queue; F-7 keeps the primitive minimal.
+- **Ledger corruption is treated as empty.** If `migrator-steps-completed.json` becomes corrupt (truncated, bad JSON), the engine falls back to an empty ledger. This is intentional — the alternative (refuse to migrate) would be worse. Cost: a corrupt ledger causes one round of step re-runs; each step is idempotent by spec.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The two primitives sit at the `src/core/` layer — the same layer as `PostUpdateMigrator`, `GitStateManager`, `BackupManager`. They compose on top of `node:fs` only; no dependency on the Remediator (Tier-2 surfaces will register their own steps via `migrator.registerStep(...)` after import). The A35 const-literal extensions sit where the const lives — `GitStateManager` for the gitignore, `BackupManager` for the exclusion prefixes. No new plugin/register API was introduced per A50's explicit ruling.
+
+The `PostUpdateMigrator` class is the right owner for the public-facing `registerStep`/`runPendingSteps` methods even though the engine logic lives in `MigratorStepEngine` — the existing class is already the documented entry point for "thing that runs on update boundary". Tier-2/Tier-3 surfaces (S-2, S-3) will reach for `PostUpdateMigrator` first.
+
+---
+
+## 4. Signal-vs-authority compliance
+
+The brittle/low-context layers (file I/O ledger reads, sink invocations) are signal layers. The higher-context layer (the `runPendingSteps` orchestrator) is the authority. Specifically:
+
+- A corrupt ledger does NOT block migration — the ledger is treated as a signal ("here's what we believe happened"), and the engine recovers by treating it as empty. Authority over "should this step run" lives in the in-memory step list + the version comparison.
+- A failing sink does NOT block `announceOnce` from recording the announcement — sink delivery is signal; the ledger record is authority over "have we already attempted to surface this".
+- A failing step does NOT block other steps — the per-step try/catch isolates signals; the engine retains authority over the run sequence.
+
+This matches the §A50 / signal-vs-authority principle in MEMORY.md.
+
+---
+
+## 5. Interactions with existing surfaces
+
+- **`PostUpdateMigrator.migrate()` is untouched.** Existing callers (`src/update/UpdateService.ts`, `src/commands/init.ts`, etc.) continue to work — they call `migrate()` and never touch the new methods.
+- **`GitStateManager.init()`** — writes `DEFAULT_GITIGNORE` only when no `.gitignore` exists. Existing repos with `.gitignore` already on disk are unaffected. New repos get the remediation entries pre-included.
+- **`BackupManager` callers** — 14 existing call sites pass at most 4 constructor args. The new 5th arg is optional + defaults to no-op behavior. Verified by running the full `backup-manager.test.ts` (44 cases) and `BackupManager-sharedState.test.ts` (3 cases) — all pass unchanged.
+- **`upgrades/NEXT.md`** — only appended to (preserving the W-1, F-8, F-3, F-4, F-1..F-2 entries already on main).
+
+---
+
+## 6. Rollback cost
+
+Low. The two new modules (`MigratorStepEngine.ts`, the new methods on `PostUpdateMigrator.ts`) are dormant unless something calls `registerStep` — and nothing calls it in this PR. Tier-2 surfaces will be the first consumers. Reverting requires:
+
+1. `git revert` the PR. No data migration. No format changes. Existing `migrate()` behavior is untouched.
+2. If any agent has already created `migrator-steps-completed.json` or `announcements-shown.json` files, they become unused leftovers — no harm. They can be deleted at leisure.
+
+The A35 const-literal changes are inline edits to existing files; revert restores the prior literal. The `BackupManager`'s 5th constructor arg is optional and unused by every current caller, so removing it has zero blast radius.
+
+---
+
+## Tests
+
+- `tests/unit/PostUpdateMigrator-atomicStep.test.ts` — 8 cases covering: step runs once and records completion; step is skipped on subsequent runs; failed step records failure and doesn't block other steps; future-version step skipped without ledger entry; state persists across instances; semver compare correctness.
+- `tests/unit/AnnouncementManager.test.ts` — 5 cases covering: first-true / subsequent-false; independent ids; persistence across instances; sink-throw does not cause re-emission; input validation.
+- `tests/unit/PostUpdateMigrator-a35-remediationPaths.test.ts` — 5 cases covering: `DEFAULT_GITIGNORE` contains all five remediation entries; `REMEDIATION_EXCLUDED_PATH_PREFIXES` exported correctly; gate ON drops remediation entries; gate OFF preserves them; absent callback = back-compat (gate OFF).
+
+All 18 new tests pass. All 76 pre-existing `PostUpdateMigrator-*` tests pass unchanged. All 47 `BackupManager*` tests pass unchanged. TypeScript clean (`tsc --noEmit`).
+
+---
+
+## Gate trace
+
+- side-effects review: this document
+- NEXT.md: amended, preserving every prior entry
+- spec citation: `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §R1 + §A35 + §A50 + §A57
+- worktree: `/tmp/instar-f7-post-update-migrator` (branch `f7-post-update-migrator`)
+- no bypass; no `--no-verify`

package/upgrades/side-effects/f8-remediator-skeleton.md

@@ -0,0 +1,153 @@
+# Side-Effects Review — F-8: Remediator orchestrator skeleton (Tier-1 subset)
+
+**Version / slug:** `f8-remediator-skeleton`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Ships the Tier-1 subset of F-8 from the Self-Healing Remediator v2 spec (`docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §A1 manifest, §A2 lock-bound co-existence, §A3 capability-token context, §A4 deadline enforcement, §A6 errorCode-provenance gate, §A21 verify-failed strict typing, §A36 essential-runbook validator, §A57 phase tiering).
+
+New module: `src/remediation/Remediator.ts`. A single orchestrator class plus the surface types `ApprovedRunbook`, `RemediationContext`, `ExecutionResult`, `VerifyOutcome`, `BlastRadius`, `Reversibility`, `DispatchOutcome`.
+
+What this PR DOES include (per A57's Tier-1 carve-out):
+- Runbook registration with §A6 + §A36 registry-load-time refusal.
+- Dispatch loop: match by `eventPrefilter` (errorCode + provenance) + `match()`; refuse `provenance: 'free-text'` events at the matcher; pick highest-priority candidate.
+- Lock acquisition via the F-4 `MachineLock` using `tupleHash = sha256(runbookId + signatureHash)`. Existing in-flight lock with same tuple → `covered-by-inline`.
+- Intent journal declaration via the F-4 `IntentJournal` (durable witness before any mutation).
+- `RemediationContext` carrying `attemptId, runbookId, lockHandle, auditToken (leaf from F-1 keyVault), abortSignal, expiresAt, monotonicDeadline`.
+- Deadline enforcement (§A4): an `AbortController` fires at `expectedRuntimeMs`; the dispatcher races the surface against the timer; on deadline, the result is `aborted-deadline` and the lock is released in the `finally` block.
+- Verify-outcome wiring (§A21): verify is only called when surfaceCallable returned `outcome: 'success'`; verify-THROW is mapped to `verify-inconclusive` (probe error), never `verify-failed`.
+- Audit-append via the F-4 `AuditWriter` at every state transition (`started`, `verified-healthy | verify-failed | verify-inconclusive`, `aborted-deadline`, `no-matching-runbook`, `covered-by-inline`).
+
+What this PR explicitly does NOT include (per A57 Tier-2 carve-out, deferred):
+- Trust elevation source.
+- Probe authentication (A40, A52).
+- Capability-token HMAC enforcement on the surface side (A3, A23, A42).
+- Supervisor handshake (A15).
+- Runbook registry validation against a signed manifest (A56, A66).
+- Child-process SIGTERM/SIGKILL escalation — surfaces (W-1..W-4) implement that; the skeleton's AbortSignal is the in-process enforcement handle only.
+
+Files touched:
+- `src/remediation/Remediator.ts` (add)
+- `tests/unit/Remediator.test.ts` (add — 12 cases)
+- `upgrades/NEXT.md` (modify — preserves F-1..F-4 + Phase 4/5 + ELI16 + API-safety entries)
+
+## Decision-point inventory
+
+- `Remediator.registerRunbook()` — **add** — registry-load-time gate; rejects free-text-provenance prefilters (§A6) and essential-on-non-machine (§A36). Hard error: throws on misconfig so boot fails fast.
+- `Remediator.dispatch()` — **add** — orchestration entry; produces a `DispatchOutcome` discriminated union. Five terminal states. Does not throw on policy rejections; throws only on infrastructure failures (lock acquire error not covered by `covered-by-inline`).
+- Internal: `matchRunbook()` — defends-in-depth against `provenance: 'free-text'` events even if a runbook somehow registered such a prefilter.
+- Internal: deadline race via `Promise.race(racePromise, deadlinePromise)` — the AbortController is the surface-facing signal; the race is the dispatcher-side authority.
+
+No new HTTP routes. No new persistent files beyond what F-4 already creates (audit-projection-*, intent-journal-*, machine-locks/*). The skeleton consumes those primitives; it does not create new file types.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **`provenance: 'free-text'` events never match.** This is by design (§A6). Legacy `.report(...)` callers normalize through DegradationReporter's F-3 shim to `free-text` provenance and route to `no-matching-runbook` (which is fine — they still produce an audit entry; SystemReviewer clusters them for novel-failure proposals). The "rejection" is exactly what §A6 mandates as the structural defense against attacker-shaped error text.
+- **Concurrent dispatch against the same tuple while in-flight → `covered-by-inline`.** Intended (§A2). The second caller is not silently dropped — it receives a structured outcome naming the existing attempt. The caller can subscribe to the audit log for the in-flight attempt's terminal outcome.
+- **Essential on non-machine blast radius rejected at register-time.** Intended (§A36). A boot-time misconfig fails fast rather than allowing a non-machine runbook to skip auto-quarantine (which would be a DoS vector).
+- **Verify probe error → `verify-inconclusive`.** Intended (§A21). The spec explicitly carves out probe error / timeout / unsigned payload as `verify-inconclusive` so attackers cannot DoS a working heal by making the verify probe fail.
+
+There is no legitimate path this PR over-blocks. The four rejections above are all structural defenses with no false-positive surface.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **No capability-token HMAC enforcement on the surface side.** A surface that receives `RemediationContext` could theoretically be invoked by a forged context (no token verification on the surface). Tier-2 fixes this with A3 + A23 + A42. The Tier-1 skeleton's mitigation: only the dispatcher creates contexts, and the surface package is co-installed with the dispatcher; in this PR there are no real surface consumers yet (W-1 ships the first one). Forging requires in-process code-exec, at which point all bets are off anyway.
+- **No probe authentication.** Verify outcomes from the runbook's `verify()` callback are trusted by-signature only insofar as the runbook author wrote them correctly. A40 will harden this with per-probe leaf-key signatures over the verify envelope. Tier-1 trusts the runbook code itself.
+- **No cross-machine coordination.** The lock is per-machine. Two machines healing the same tuple are not coordinated by F-8. Cross-process attempt ledger (A7) and primary-aggregator lease (A47) handle that at Tier-2/Tier-3.
+- **No child-process abort escalation.** A surface that spawns a child process and ignores `abortSignal` won't be force-killed by F-8; the dispatcher only signals. Child-process SIGTERM/SIGKILL ladder is W-1's concern. Mitigation: the lock IS released by the dispatcher's `finally` block, so the orphaned child does not block a re-dispatch.
+- **No deadline enforcement on `verify()` itself.** If a surface succeeds but verify hangs, the same AbortController fires and the dispatcher returns `aborted-deadline` (the deadline race is around the entire `surfaceCallable + verify` chain). However, verify is not given a separate deadline budget. Tier-2 may refine this.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The Remediator is the orchestrator — its job is *to compose* the F-1..F-4 primitives. It owns:
+- Match policy (which runbook fires for which event).
+- Coordination policy (lock acquire, tuple compute, covered-by-inline detection).
+- Deadline policy (AbortController + timer race).
+- Verify-outcome interpretation (success/failure/inconclusive mapping).
+
+It does NOT own:
+- Key material (F-1).
+- Lock-file format (F-4 MachineLock).
+- Intent durability semantics (F-4 IntentJournal).
+- Audit-token verification (F-4 AuditWriter's injected verifier).
+- Surface implementations (W-*).
+
+Each of those concerns lives in its rightful module. The dispatcher is the thin glue layer that the spec mandates.
+
+No higher-level smart gate is shadowed. The dispatch decision is structural (does the event match this runbook's prefilter?), not heuristic. The signal-vs-authority principle is honoured because matching is deterministic and the authority is bounded to "which surfaceCallable to invoke" — a runbook-author-controlled invariant, not a content-classifier's call.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface beyond structural primitives (errorCode equality, provenance enum membership, runbook id presence).
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic — STOP.
+
+The match function `eventPrefilter.errorCode.includes(event.errorCode) && eventPrefilter.provenance.includes(event.provenance) && runbook.match(event)` is precise, not heuristic. There is no regex, no string-pattern matching, no LLM call. The only "intelligence" is the runbook author's `match()` callback, which is structural code shipped in `src/remediation/runbooks/*` (none exist yet — W-* PRs add them).
+
+The blocking decisions held by the dispatcher (free-text rejection, essential validator, deadline enforcement) are all over precise structural inputs:
+- §A6 free-text rejection: enum equality.
+- §A36 essential validator: enum equality + boolean.
+- §A4 deadline: monotonic clock comparison.
+
+These are exactly the kind of authority that *should* be hard-coded structurally. The smart gate (the runbook author + the user who approves runbook PRs through `/instar-dev`) holds policy authority over which runbooks exist; the dispatcher's job is to enforce structural invariants on registration and dispatch.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** None. There is no existing dispatcher in `src/remediation/`. The closest prior art is the in-line `NativeModuleHealer` path inside the existing native-binding error handling — that path remains untouched in this PR. W-1 ships the wrapper that makes the inline healer addressable from F-8 *as a runbook*, at which point §A2's lock-bound co-existence rule kicks in (both the inline and the F-8 path acquire the same MachineLock tuple; only one runs).
+- **Race with adjacent cleanup:** The dispatcher's `finally` block always releases the lock. If `acquireInFlight` succeeded but the surface throws before `surfaceCallable` is invoked (currently impossible — the dispatcher calls it directly), the lock would still be released. The release is idempotent (F-4 contract).
+- **Double-fire:** `dispatch()` for the same event called twice concurrently → second call observes the first's lock and returns `covered-by-inline`. `dispatch()` called sequentially → second call proceeds (the first released its lock).
+- **DegradationReporter wiring:** F-3 ships `setRemediator(remediatorLike)`. THIS PR does not call `setRemediator()` from anywhere — the dispatcher is constructible but not yet wired into the DegradationReporter pipeline. A subsequent PR (or W-1) wires the dispatcher into the reporter, at which point legacy events route through `dispatch()`. Until then, the dispatcher only fires when called explicitly (e.g., from tests).
+- **Audit-projection consumer:** F-4's `AuditProjection` reads from the same file the dispatcher writes to. Live: as soon as the dispatcher is invoked, `AuditProjection.recentByRunbook()` reflects the new entries. No coupling beyond the file path contract.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible to other agents, other users, other systems?**
+
+- No HTTP routes, no Telegram surfaces, no dashboard tabs, no config-flip entries, no CLI commands.
+- No new file types on disk. The dispatcher consumes the F-4 primitives' files (`<stateDir>/machine-locks/in-flight/*.lock`, `<stateDir>/remediation/intent-journal-*.jsonl`, `<stateDir>/remediation/audit-projection-*.jsonl`, `<stateDir>/remediation/audit-rejected.jsonl`). Files only materialize when the dispatcher is actually invoked.
+- The default exported class is a new symbol. No existing imports break.
+- The DegradationReporter `RemediatorLike` interface declared in F-3 is structurally compatible with the new `Remediator.dispatch()` signature: both accept `NormalizedDegradationEvent` and return `Promise`. The dispatcher's return type is richer (`DispatchOutcome`), which is a widening from F-3's `Promise<void>` — backwards-compatible.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivially low. The dispatcher is a new symbol that is not yet imported by any production code path. `git revert` of this PR removes the class and the test file with zero state migration cost. The on-disk artifacts (audit-projection, intent-journal, machine-locks) are F-4's responsibility; the revert doesn't touch them, and they remain consumable by whichever future PR re-introduces the dispatcher.
+
+If a future consumer-PR (W-1) wires the dispatcher into `setRemediator()` and a bug surfaces, the back-out path is "revert the consumer PR" — the dispatcher itself never runs without a caller. The fail-safe shape of the design means a dispatcher bug cannot break legacy `.report(...)` flow (which never reaches the dispatcher absent a `setRemediator()` call).
+
+---
+
+## Reviewer concurrence (Phase 5)
+
+Not required. This change introduces no live consumers, no block/allow surface for messaging, no session lifecycle, no coherence/sentinel/gate authority. It is foundation infrastructure that becomes load-bearing only once W-1 wires a real runbook. At that point W-1 carries its own side-effects review covering the dispatcher's first production caller.

package/upgrades/side-effects/f8-rest-enforcement.md

@@ -0,0 +1,72 @@
+# Side-effects review — F-8 rest of Tier-2 enforcement
+
+**Spec**: `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` (§A3, §A23, §A40, §A42, §A52, §A57 Tier-2 carve-outs)
+
+**Scope**: Wires the security enforcement that the Tier-1 F-8 skeleton (PR #201) deferred — capability-token HMAC on dispatched RemediationContext, probe-source-binding + scope check at dispatch entry, trust-elevation source consult on lifecycle transitions, supervisor-handshake closure (`RegisteredRemediator` implementation + `requestPlannedRestart`), and one smoke-test probe scope export.
+
+---
+
+## 1. What changes about the running system
+
+Nothing observable today. Every new constructor option (`trustSource`, `serverSupervisor`, `probeSourceRegistry`) and every new method (`canTransition`, `requestPlannedRestart`, `getCapabilityLeafKey`, `onRestartComplete`) is OPT-IN. The default `Remediator` shape unchanged for existing Tier-1 / W-1 tests. No production code instantiates a `Remediator` yet; `DegradationReporter.setRemediator()` is still uncalled.
+
+The one structural surface change is on `NormalizedDegradationEvent`: a new optional `source.probeSignature` field is added. This is additive and serializes to `undefined` for every existing emit site.
+
+## 2. Over-block / under-block
+
+**Over-block risk** — when a `probeSourceRegistry` IS wired, every `provenance: 'probe-id'` event must carry a verified envelope inside the declared scope. An emit-site that forgot to sign is silently routed to `no-matching-runbook` with reason `probe-event-unsigned`. The Tier-3 fleet migration is the rollout for this; F-8-rest only wires ONE probe (`LifelineProbe`) and the registry is not constructed at all in production paths yet. So today: zero over-block.
+
+**Under-block risk** — when the registry is UNWIRED, no probe enforcement happens. A malicious or buggy emit-site could mint a `provenance: 'probe-id'` event with no signature and the Tier-1 path would dispatch normally. The spec accepts this for Tier-2 (the registry-wiring step is the Tier-3 fleet rollout — see §A57). The Tier-2 unit tests assert presence of the gate; production wiring is the next-tier work item.
+
+**Capability-token verify under-block** — `NativeModuleHealer.invokeFromRemediator` only enforces when BOTH a `keyVault` is passed AND `ctx.hmac` is set. Existing W-1 callers (test fixtures) pass neither, so they continue to work. Production wiring (a future PR) will always pass both. This is intentional backward compat per the user request "the in-line `openWithHeal` path MUST stay working."
+
+## 3. Level-of-abstraction fit
+
+- `RemediationContext` sign/verify lives in `src/remediation/RemediationContext.ts` — same directory as the consumers, no cross-tree dep.
+- The surface-side verify in `NativeModuleHealer` deliberately INLINES the canonical-body byte layout (it does NOT import from `src/remediation/`) so the legacy `openWithHeal` CLI path stays usable on installs without the remediation tree. A small chunk of byte-layout duplication is the explicit price; the test fixture asserts both implementations agree.
+- Probe-source binding lives in `src/monitoring/probes/__shared.ts` — co-located with the consumers (probe modules) per A52.
+- The `DefaultProbeSourceRegistry` impl + canonical envelope helper live in `Remediator.ts` so the wire format has ONE owner; tests can also stub the interface.
+
+## 4. Signal-vs-authority compliance
+
+- The Remediator REMAINS the authority layer (it makes block / allow decisions).
+- Probes are SIGNAL emitters — they sign their envelopes, declare their scope, but the Remediator decides what to do with each event.
+- `TrustElevationSource` is the authority for lifecycle transitions; the Remediator delegates without re-interpreting.
+- `ServerSupervisor` retains authority over restart sequencing; the Remediator only REQUESTS via HMAC-signed payload — the supervisor's existing fail-closed checks (handshake-version match, staleness window, blast-radius allowlist, HMAC verify) are unchanged.
+
+No new authority migrated to a low-context filter.
+
+## 5. Interactions with existing behavior
+
+- **`openWithHeal` (legacy)** — Unchanged. Doesn't construct `invokeFromRemediator` ctx, so the new verification path is skipped entirely. Verified by `tests/unit/NativeModuleHealer.test.ts` (12 tests pass unchanged).
+- **W-1 runbook fixture path** — `invokeFromRemediator(ctx)` without keyVault → §A3 verification skipped → existing behavior. 12 `NativeModuleHealer-invokeFromRemediator` tests pass unchanged.
+- **F-4 audit primitives** — No change. The existing `tokenVerifier` injection is still the authoritative gate for audit writes; F-8-rest does not modify the audit pipeline.
+- **F-5 TrustElevationSource** — Used through its public `canTransition()` only. The 25 source-side tests pass unchanged.
+- **F-6 ServerSupervisor handshake** — The Remediator now CLOSES the loop by implementing `RegisteredRemediator`. The 9 supervisor-handshake tests pass unchanged.
+- **F-7 PostUpdateMigrator** — Untouched.
+
+## 6. Rollback cost
+
+Pure additive surfaces. Reverting the PR:
+- Drops `signRemediationContext` / `verifyRemediationContext` / `canonicalProbeEnvelopeBody` / `DefaultProbeSourceRegistry`.
+- Drops the three optional `RemediatorOptions` fields + the new methods.
+- Drops `__verifyScope` from `LifelineProbe` (one const export).
+- Drops the `hmac` field on `RemediationContext` (optional, no caller required to set).
+- Drops the `source.probeSignature` field on `NormalizedDegradationEvent` (optional, no emit site sets it).
+- Drops 21 new tests.
+
+No data-format migrations, no on-disk schema change, no live consumer wired. Rollback cost: low.
+
+## 7. Test plan
+
+- 7 unit tests on `signRemediationContext` / `verifyRemediationContext` round-trip + every tamper / mismatch failure path.
+- 10 unit tests on Remediator F-8-rest enforcement (probe-source binding 4 cases, ctx signed by dispatch, trust-source delegation 3 cases, canonical-envelope determinism 2 cases).
+- 4 unit tests on NativeModuleHealer §A3 enforcement (valid hmac runs, forged hmac falls back, aborted fallback short-circuits, no-keyVault legacy compat).
+- All 57 pre-existing Tier-2 / W-1 / Tier-1 tests in `Remediator.test.ts`, `runbooks/node-abi-mismatch.test.ts`, `NativeModuleHealer-invokeFromRemediator.test.ts`, `NativeModuleHealer.test.ts`, `ServerSupervisor-handshake.test.ts` pass unchanged.
+- All 25 `TrustElevationSource.test.ts` + 4 `AuditWriter.test.ts` tests pass unchanged.
+
+Total: 107 / 107 remediation-side tests green.
+
+## Second-pass review
+
+Not required (this PR introduces no new dispatch logic that would change live-system behavior — every change is gated behind opt-in constructor options that are unwired in production).

package/upgrades/side-effects/file-viewer-jobs-instar-never-editable.md

@@ -0,0 +1,41 @@
+# Side-effects review — File Viewer extends never-editable to .instar/jobs/instar/
+
+## What changed
+
+Two-line spec compliance item from INSTAR-JOBS-AS-AGENTMD §Decision Points:
+
+- `src/server/fileRoutes.ts:NEVER_EDITABLE_PREFIXES` adds `.instar/jobs/instar/`. Any `PATCH /api/files/config` attempt to declare an `editablePath` under that prefix is rejected with HTTP 400 + "never editable" error. Direct save attempts on a file under that path are rejected the same way.
+- Migrator-emitted CLAUDE.md doc string (`PostUpdateMigrator.ts` line 1501) updated to list `.instar/jobs/instar/` alongside the existing never-editable namespaces.
+
+## Why
+
+The `.instar/jobs/instar/` namespace is owned by the update process and signed against the bundled lock-file. A Dashboard editor that lets the operator edit a default's body would (a) be overwritten on next update, (b) break the body-hash verification, and (c) bypass the spec's intended override flow (fork to `.instar/jobs/user/` via the Override action).
+
+## Side-effects review
+
+### 1. Over-block / under-block
+
+- **Over-block:** none for users — the override flow is the documented path for customizing a default. Hand-edits in the file viewer were never useful here (they'd revert on update).
+- **Under-block:** the prefix check is exact-startswith. A path like `.instar/jobs/instar.lock.json` is NOT under `.instar/jobs/instar/` (different filename), so the lock-file itself remains read-accessible. That's correct: the lock-file is JSON that the operator may want to view for debugging.
+
+### 2. Level-of-abstraction fit
+
+One entry in a closed-set array. Zero new code paths.
+
+### 3. Signal-vs-authority compliance
+
+`NEVER_EDITABLE_PREFIXES` is the authority for "what can be edited via the Dashboard." Adding to the list strengthens, not weakens, the structural property.
+
+### 4. Interactions
+
+- **Phase 2 installBuiltinJobs** — already writes `.instar/jobs/instar/<slug>.md` on init + update; the never-editable list is the matching read-only enforcement.
+- **Phase 4 Dashboard UI rewrite (future)** — the future override/unfork UI lives at a different path; not affected by this change.
+- **File Viewer config UI** — config save endpoint already rejects never-editable prefixes; this addition is automatically enforced there.
+
+### 5. Rollback cost
+
+Trivial. Remove one line + revert one CLAUDE.md doc-string line.
+
+## Test coverage
+
+`tests/e2e/file-viewer-e2e.test.ts` adds one case in the existing "rejects editablePaths targeting <never-editable>" cluster — same shape as the `node_modules/` test. The pre-existing file-viewer-e2e suite covers the read/write enforcement that the new prefix automatically inherits.

package/upgrades/side-effects/frontmatter-interpolation-breakout-test.md

@@ -0,0 +1,48 @@
+# Side-effects review — Frontmatter interpolation breakout test
+
+## What changed
+
+New unit test `tests/unit/scheduler/JobScheduler.frontmatter-breakout.test.ts` asserts the structural defense the spec calls out:
+
+> Frontmatter-field interpolation breakout — any frontmatter field interpolated into prompt must pass slug regex or be JSON-stringified; breakout payload tested.
+
+The current implementation already meets the spec: `JobScheduler.buildPrompt(job)` for `execute.type: "agentmd"` does NOT interpolate any frontmatter field into the prompt. The body is the prompt; framing constants (notification protocol, view metadata) come from source-level string literals, not from job data.
+
+This test ASSERTS that property so a future refactor introducing frontmatter interpolation cannot land without (a) breaking this test and (b) forcing the author to think about breakout surface.
+
+## Side-effects review
+
+### 1. Over-block / under-block
+
+- **Over-block:** none — the test asserts what the code already does. Pass rate today: 100%.
+- **Under-block:** the test covers four breakout categories (shell injection, template injection, prompt injection, null-byte / control characters) plus an explicit "rendered prompt contains body verbatim" assertion plus a slug-regex defense assertion. If a future refactor introduces a NEW breakout surface I didn't anticipate, the four-category coverage still catches the common shapes.
+
+### 2. Level-of-abstraction fit
+
+Pure unit test. Calls `JobScheduler.buildPrompt` (private, accessed via type-cast escape — same pattern as other internal tests in the suite). No new code paths, no new behavior.
+
+### 3. Signal-vs-authority compliance
+
+The test is a signal that the no-interpolation property is intact. The authority is `buildPrompt` itself — which is the single point that decides what string becomes the spawn's `--prompt` argument.
+
+### 4. Interactions
+
+- **Phase 1b agentmd dispatch** — the test covers the same path Phase 1b shipped.
+- **Phase 2 templates** — the templates themselves are markdown bodies; this test asserts that even if someone shipped a malicious frontmatter alongside a benign body, the malicious content never reaches the spawn.
+
+### 5. Rollback cost
+
+Trivial. Single test file. Delete to revert.
+
+## Test coverage
+
+6 cases in `tests/unit/scheduler/JobScheduler.frontmatter-breakout.test.ts`:
+
+1. Shell-injection frontmatter payload absent from rendered prompt
+2. Template-injection frontmatter payload absent
+3. Prompt-injection frontmatter payload absent
+4. Null-byte / control-character payloads absent
+5. Body bytes are present verbatim; frontmatter bytes are not
+6. Slug regex rejects all breakout-shaped slugs (defense-in-depth)
+
+All 6 pass locally. Lint + type-check pass.

package/upgrades/side-effects/jobs-as-agentmd-phase-2.md

@@ -0,0 +1,78 @@
+# Side-effects review — Phase 2 (default job conversion + asset packaging)
+
+## What changed
+
+Phase 2 converts the 14 prompt-type instar default jobs from inline JSON strings in `getDefaultJobs()` to standalone markdown templates that can be reviewed, diffed, and verified at runtime against the signed lock-file. Script-type and skill-type defaults stay as legacy `getDefaultJobs()` entries — agentmd format is only appropriate for prompt-bearing jobs.
+
+New artifacts:
+
+- **`src/scaffold/templates/jobs/instar/<slug>.md`** — 14 shipped templates, one per prompt-type default. Body is the EXACT bytes of `execute.value`. Frontmatter captures name, description, schedule, priority, expectedDurationMinutes, model, enabled, tags, optional gate, toolAllowlist:"*", unrestrictedTools:true. The "*" + unrestrictedTools:true pair preserves today's full-tool behavior for every shipped default (no behavioral regression). Phase 4 will narrow these per slug.
+- **`scripts/regen-default-job-templates.mjs`** — generator that reads `getDefaultJobs()` and writes templates. Run on every default-job edit to keep templates in sync with the canonical source.
+- **`src/scheduler/InstallBuiltinJobs.ts`** — new `installBuiltinJobs()` function. Reads templates from `<packageRoot>/dist/scaffold/...` (prod) or `<packageRoot>/src/scaffold/...` (dev), writes per-slug bodies to `.instar/jobs/instar/<slug>.md`, per-slug manifests to `.instar/jobs/schedule/<slug>.json`, copies the signed lock-file from `dist/jobs/instar.lock.json` to `.instar/jobs/instar.lock.json`, and the bundled public key to `.instar/keys/instar-release-pub.pem`.
+- **`getDefaultJobs` export** — was a non-exported helper; now exported so the regen script can call it without re-parsing init.ts.
+- **PostUpdateMigrator.migrateBuiltinJobs** — invokes installBuiltinJobs on every update. Failures are reported in the migration result, never fatal.
+- **init.ts** — fresh-install path also invokes installBuiltinJobs (right after installBuiltinSkills, before CLAUDE.md write).
+- **package.json#files** — `src/scaffold` added so the templates ship in the npm tarball.
+
+## Side-effects review (mandatory gate)
+
+### 1. Over-block / under-block
+
+- **Over-block:** none. `installBuiltinJobs` overwrites `.instar/jobs/instar/<slug>.md` on every update — this is the contract for instar-namespace files (the namespace IS managed by updates per the spec's `Concrete Paths`). The user namespace (`.instar/jobs/user/`) is structurally untouched.
+- **Under-block:** the operator-disabled state on a default is preserved across updates (the per-slug manifest's `enabled` and `disabledAtBodyHash` are read from the existing manifest before being rewritten). A retired default has its body removed and its manifest marked retired+disabled+timestamped, so Phase 4 Dashboard can surface it.
+
+### 2. Level-of-abstraction fit
+
+`installBuiltinJobs` is a pure file-system shaper. It does not invoke the scheduler, does not touch state.json, does not emit events. It writes files and returns a report. This keeps it composable: both init and PostUpdateMigrator call it; tests run it against a synthetic workspace; future Phase 5 `instar jobs migrate` will also call it as part of the migration sequence.
+
+The destructive operations (template removal on retire, stale lock-file cleanup) go through `SafeFsExecutor.safeUnlinkSync` with explicit operation strings, satisfying the destructive-tool funnel gate.
+
+### 3. Signal-vs-authority compliance
+
+The signed lock-file remains the trust authority — `installBuiltinJobs` is just the courier. It copies the lock-file from `<packageRoot>/dist/jobs/` to `.instar/jobs/` without inspecting or modifying its contents. The runtime verifier (Phase 1c-runtime) reads the lock-file and decides trust. Phase 2 does NOT touch the lockTrust decision path.
+
+### 4. Interactions
+
+- **Phase 1c-runtime** — the bundled public key copy step keeps the verifier able to validate lock-files on every update (no chicken-and-egg if the public key is rotated mid-rollout).
+- **Phase 1c-build** — when a signing key is configured, `npm run build` produces `dist/jobs/instar.lock.json`; `installBuiltinJobs` copies it. When no signing key is configured (current pre-GHA-secret state), the signer skips lock-file generation; `installBuiltinJobs` removes any stale lock-file from agent disk so the runtime sees `state: absent` → `lockTrust=untrusted-no-lockfile`.
+- **Legacy `jobs.json` seeding** — init.ts still calls `getDefaultJobs()` and writes the legacy `jobs.json`. The JobLoader already handles `schedule/<slug>.json` shadowing `jobs.json` entries with the same slug — no conflict. Phase 3 will migrate `jobs.json` entries that match an agentmd template to `origin:instar` form and drop the body; Phase 5 auto-runs this.
+- **`origin:instar` namespace ownership** — invariant 4 of the Seamless Migration Guarantee (PR #180) is verified by the `NEVER touches .instar/jobs/user/` test plus the symlink-refusal test.
+- **Idempotency** — installer is idempotent. Run-twice test asserts the on-disk content is byte-stable across repeated invocations.
+
+### 5. Rollback cost
+
+Trivial. Removing `installBuiltinJobs` call from init + PostUpdateMigrator restores prior behavior. Agents that already have `.instar/jobs/instar/` populated keep the files (the loader handles them via Phase 1a path); no on-disk corruption.
+
+### 6. Seamless Migration Guarantee compliance
+
+This PR ships the Seamless Migration Guarantee fixtures' first hook: installer behavior under the `pristine` shape (fresh agent, default-only state). The dedicated guarantee suite (`tests/integration/migration-guarantee.test.ts`) lands in Phase 3 with the migration script. Phase 2's installer tests assert:
+
+- Invariant 4 (user namespace untouched) — `NEVER touches .instar/jobs/user/` test
+- Symlink refusal (defense-in-depth for invariant 4) — `refuses to install if .instar/jobs/user/ is a symlink`
+- Idempotency boundary for the installer — `is idempotent — running twice produces the same on-disk state`
+- Retired-default flow (no orphan state) — `retires a default that is removed from the shipped templates`
+
+## Test coverage
+
+`tests/unit/scheduler/InstallBuiltinJobs.test.ts` — 10 cases:
+
+1. Installs each shipped template + per-slug manifest
+2. Port-sentinel substitution (`:-4042}` → `:-<agentPort>}`)
+3. Preserves operator-disabled state on update
+4. Retires defaults removed from templates
+5. NEVER touches `.instar/jobs/user/` (invariant 4)
+6. Refuses install if user dir is a symlink (defense-in-depth)
+7. Copies signed lock-file + bundled public key when present
+8. Removes stale lock-file when no signed file ships
+9. Returns error when templates dir is absent or empty
+10. Idempotent — run-twice produces byte-stable on-disk state
+
+All 10 tests pass locally.
+
+## What is NOT in this PR
+
+- **Drift classifier** — the spec mentions populating `significantChanges` in the lock-file at build time. That's a Phase 4 Dashboard concern; the lock-file format already accommodates it (optional field). Will land with the Dashboard rewrite.
+- **`instar jobs migrate` CLI** — Phase 3.
+- **Auto-migration on update** — Phase 5 (PostUpdateMigrator will auto-run the migration script when `jobs.json` + no `.migration-complete.json`).
+- **Full Seamless Migration Guarantee suite** — Phase 3 ships the suite with the migration script.
+- **Per-slug narrow allowlists** — every shipped default currently has `toolAllowlist: "*"`. Narrowing is a per-slug review Phase 4 will run.

package/upgrades/side-effects/jobs-as-agentmd-phase-3.md

@@ -0,0 +1,76 @@
+# Side-effects review — Phase 3 (`instar jobs migrate`)
+
+## What changed
+
+`instar job migrate` ships as the operator-initiated path for converting a legacy `jobs.json`-only agent to the new per-slug-manifest layout. Idempotent. Reversible via `--abandon`. Non-destructive on `jobs.json` (only writes a backup and the new `.instar/jobs/...` tree).
+
+New files:
+
+- **`src/commands/jobMigrate.ts`** — pure function `jobsMigrate(opts)`. Reads `jobs.json`, classifies each entry against the shipped templates (body-match SHA-256 with normalize), writes per-slug bodies to `.instar/jobs/instar/` (for matched defaults) or `.instar/jobs/user/` (for user jobs and forked defaults), writes per-slug manifests to `.instar/jobs/schedule/`, and writes a backup at `.instar/jobs.json.pre-migrate-<ts>`.
+- **CLI subcommand** — `instar job migrate [--default-action=fork|rename|skip|fail] [--report] [--abandon]`. Mirrors the spec's `instar jobs migrate` invocation contract.
+- **11 unit tests** — `tests/unit/commands/jobMigrate.test.ts`.
+
+Behavior matrix:
+
+| Pre-migration entry shape | Classification | What gets written |
+|---|---|---|
+| Slug ∈ shipped + body matches (normalize SHA-256) | `migrated-instar` | per-slug manifest only (body lives in `src/scaffold/templates/jobs/instar/`) |
+| Slug ∈ shipped + body differs | `near-miss-default` + `--default-action` | fork to user OR rename to `<slug>-user` OR skip OR abort (`fail`) |
+| Slug ∉ shipped | `kept-user` | per-slug body in `user/` + manifest |
+| `execute.type !== 'prompt'` (script/skill) | `skipped` | nothing (legacy path keeps them) |
+
+## Side-effects review (mandatory gate)
+
+### 1. Over-block / under-block
+
+- **Over-block:** none on first migration. `--default-action=fail` (the default) is the safety-first choice — it refuses to write ANY partial state if a near-miss is detected, leaving `jobs.json` untouched. The operator must explicitly choose fork/rename/skip via flag (or via the future Dashboard interactive prompt) to proceed past a near-miss.
+- **Under-block:** the script does NOT auto-write `.migration-complete.json`. The release-cut gate (spec §Migration completion predicate) requires the operator to confirm via Dashboard. Phase 3's responsibility ends at "all the new files are in place." Phase 4 builds the confirm UI.
+
+### 2. Level-of-abstraction fit
+
+`jobsMigrate` is a pure function on the file system + a structured outcome record. It DOES NOT invoke the scheduler, DOES NOT emit state events, DOES NOT modify `jobs.json` (only reads + backs up). This keeps it testable in a synthetic workspace and lets Phase 5's PostUpdateMigrator wrap it cleanly with auto-run + Dashboard banner emission.
+
+The destructive operations (`--abandon` rm of `schedule/` and `instar/`; old abandonment marker cleanup) route through `SafeFsExecutor.safeRmSync` / `safeUnlinkSync` with explicit operation strings.
+
+### 3. Signal-vs-authority compliance
+
+The CLI sub-command is a signal (operator says "I want to migrate"). The migration script is the authority on routing each entry (does the slug+body match a shipped default? → which destination?). The release-cut gate is the higher authority that will eventually allow `jobs.json` to be deleted. This PR ships the signal + the routing; Phase 4 ships the operator-confirm step that flips the release-cut gate's check from "no" to "yes."
+
+### 4. Interactions
+
+- **Phase 1a JobLoader** — already shadows `jobs.json` entries with `.instar/jobs/schedule/` entries on same-slug. So immediately after migrate, the scheduler reads from the new path while the old `jobs.json` remains for back-compat. Zero scheduling drift during the transition window.
+- **Phase 2 installBuiltinJobs** — already wrote `.instar/jobs/instar/<slug>.md` for every shipped default on every update. Migrate complements this by ALSO writing the per-slug manifest at `.instar/jobs/schedule/<slug>.json` based on the operator's pre-migration `jobs.json` (preserves cron/enabled state from the operator's setup).
+- **Phase 1c-runtime** — the per-slug body's normalize SHA-256 is what the lock-file verifier uses. Migration uses the SAME normalize function (CRLF→LF, ZWSP/ZWNJ/ZWJ/BOM strip, trimEnd + single newline) via inline code that mirrors `AgentMdLockFile.ts`. The roundtrip is structural.
+- **PostUpdateMigrator** — Phase 3 deliberately does NOT auto-run migrate. The spec says Phase 5 ships that.
+- **Release-cut gate** — Phase 3 does NOT auto-write `.migration-complete.json`. Phase 4 Dashboard ships the operator confirm button.
+
+### 5. Rollback cost
+
+`--abandon` is the one-button rollback. It removes the new `schedule/` and `instar/` directories, writes `.migration-abandoned.json`, and leaves `jobs.json` intact. The next scheduler boot reads `jobs.json` as before. Tested by `--abandon removes schedule/ and writes the abandonment marker`.
+
+### 6. Seamless Migration Guarantee compliance
+
+This PR fills in the guarantee suite's CLI-path coverage (spec §Seamless Migration Guarantee Rollout interaction). Asserted invariants:
+
+- Invariant 1 (zero job loss) — `non-prompt entries (script/skill) are skipped (legacy path keeps them)` + every prompt entry appears in `outcome.perEntry` with a non-failed action OR an explicit error
+- Invariant 2 (zero schedule drift) — `migrates a body-matched default to origin:instar with manifest only` asserts schedule field preserved verbatim
+- Invariant 5 (one-button rollback) — `--abandon removes schedule/ and writes the abandonment marker`
+- Invariant 9 (fail-closed on any failure) — `refuses to proceed on near-miss when --default-action=fail` writes no partial state
+- Backup invariant (rollback anchor) — `writes a pre-migrate backup of jobs.json before any destructive operation`
+- Idempotency — `is idempotent — re-running produces stable on-disk state`
+
+The Dashboard-path coverage (invariants 4, 7, 8) lands with Phase 4. The PostUpdateMigrator-path coverage (full guarantee on update) lands with Phase 5.
+
+## Test coverage
+
+`tests/unit/commands/jobMigrate.test.ts` — 11 cases.
+
+All pass locally. Lint + type-check pass.
+
+## What is NOT in this PR
+
+- **PostUpdateMigrator auto-run** — Phase 5.
+- **Dashboard "migration available" attention notice** — Phase 4.
+- **Dashboard "Confirm migration complete" button** — Phase 4.
+- **Release-cut gate enforcement of `.migration-complete.json`** — Phase 4 / Phase 5.
+- **Interactive three-choice prompt for near-miss** — would need TTY detection + readline; the `--default-action` flag covers the non-interactive use case. Interactive UX lands with Phase 4 Dashboard.