instar 1.3.54 → 1.3.56

package/upgrades/side-effects/launchctl-test-hygiene.md

@@ -0,0 +1,42 @@
+# Side-Effects Review — launchctl load test-hygiene guard (MM-Bootstrap Track C follow-up)
+
+**Scope.** `src/commands/setup.ts` (new `launchctlLoadAllowed()` helper + guard
+at the 2 install-path `launchctl bootstrap` sites: installMacOSLaunchAgent +
+installFleetWatchdog), `tests/unit/launchctl-load-guard.test.ts` (new).
+
+**Problem.** The Track C unit test (merged #470) writes a LaunchAgent plist via
+`installAutoStart` to verify the Label-keyed-replace property. But
+`installMacOSLaunchAgent` does a real `launchctl bootstrap` (load) after writing
+— so the test loaded tmpdir-pointed plists into the operator's REAL launchd,
+leaving stale `ai.instar.mmtesthandoff` / `ai.instar.mmteststandby` entries
+(status 78, program gone) after the tmpdir was cleaned. Inert but real
+test-pollution of the user's launchd, discovered 2026-05-28.
+
+**Fix.** `launchctlLoadAllowed()` returns false under a test runner (vitest
+auto-sets `VITEST`) or when `INSTAR_SKIP_LAUNCHCTL_LOAD` is set. The two
+install-path bootout+bootstrap blocks are wrapped in it. The plist file is still
+written/removed; only the LIVE load is gated — so the unit-under-test (plist
+content) is unaffected, and production (neither flag set) loads normally.
+
+**Side-effects review.**
+- **No production behavior change** — in a normal environment neither VITEST nor
+  INSTAR_SKIP_LAUNCHCTL_LOAD is set, so `launchctlLoadAllowed()` is true and the
+  load happens exactly as before.
+- **Tests no longer pollute real launchd** — verified: re-running the Track C
+  test creates NO mmtesthandoff/mmteststandby entries (the guard skipped the
+  load), and the test still passes (it asserts plist CONTENT, not live load).
+- **uninstallAutoStart's bootout is intentionally NOT gated** — that's cleanup
+  (removing a real entry), correct to keep even in tests; only the install-path
+  LOAD is the pollution vector.
+- **Minimal surface** — one helper + two wraps; no new dependency.
+
+**Test coverage.** Unit `tests/unit/launchctl-load-guard.test.ts` (3): false
+under VITEST, false under INSTAR_SKIP_LAUNCHCTL_LOAD, true when neither set
+(production). Plus the existing Track C test now verifiably runs without
+pollution.
+
+**Migration parity.** Server source (setup.ts) — existing agents pick up on
+auto-update. No agent-installed-file change; production load behavior unchanged.
+
+**Rollback.** Revert. Tests would resume polluting real launchd (inert stale
+entries). No production impact either way.

package/upgrades/side-effects/mesh-git-substrate-auto-reconcile.md

@@ -0,0 +1,70 @@
+# Side-Effects Review — Mesh registry conflict auto-merge (MM-Bootstrap Track D)
+
+**Spec:** `docs/specs/MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS-SPEC.md` §Track D (approved PR #465).
+
+**Scope.** `src/core/mergeRegistry.ts` (new), `src/core/GitSync.ts`
+(`tryAutoResolve` gains a `machines/registry.json` case →
+`resolveRegistryConflict`), `tests/unit/mergeRegistry.test.ts` (new).
+
+**Premise correction (evidence-driven, like Track A).** The spec assumed "no
+automatic reconcile path" + proposed a from-scratch `GitSyncManager.sync()`
+rewrite. Reading the code: GitSync.sync() is already MATURE — it does
+`pull --rebase --autostash`, pre-flight stuck-rebase/detached-HEAD recovery,
+untracked-overwrite backup+retry, a multi-tier conflict resolver
+(`tryAutoResolve` field-merge/newer-wins/union-by-id → LLM → manual), AND a
+post-pull `reconcilePulledRegistry` (registryReplayGuard) for clean pulls. The
+divergence I hit live ("Need to specify how to reconcile") was SELF-INFLICTED —
+I ran raw `git pull` manually, not GitSync.sync() (which always passes
+`--rebase`). So a rewrite would have duplicated/regressed mature code.
+
+**The REAL gap (small, precise).** `tryAutoResolve` had cases for
+relationships/, jobs.json, evolution/ — but NONE for `machines/registry.json`.
+So when registry.json hits a *rebase conflict* (both machines committed
+different registry+lease — the concurrent lease-bump + join case), it fell
+through to LLM/manual instead of a deterministic merge, and the mesh could
+stay split (one side 1 machine, the other 2).
+
+**Fix.** A pure `mergeRegistry(ours, theirs)` (union machines by id; per-id
+clash → later `lastSeen` wins, revocation sticky, syncSequence tiebreak; lease
+→ higher `epoch` wins, signature-lexical tiebreak; version → max) +
+`GitSync.resolveRegistryConflict` wired into `tryAutoResolve` for
+`machines/registry.json`. Both machines compute the identical merge, so the
+mesh converges without coordination.
+
+**Side-effects review.**
+- **Lossless + deterministic** — no machine is ever dropped; both sides'
+  updates survive; the merge is order-independent for the fields that matter
+  (verified by an order-independence test). Two machines independently reach
+  the same merged registry.
+- **Reuses the existing resolver tier** — slots into `tryAutoResolve`
+  (Tier-0 programmatic) exactly like the relationship/jobs/evolution cases;
+  no change to the pull/rebase machinery, the LLM tier, or
+  `reconcilePulledRegistry` (which still handles the clean-pull path).
+- **Fail-safe** — `resolveRegistryConflict` is try/catch-wrapped; on any
+  parse/merge error it returns false (DegradationReporter logged) and the
+  conflict falls through to the LLM/manual tier exactly as before. Strictly
+  additive: a registry conflict that previously went to LLM/manual now gets a
+  deterministic merge first; everything else is unchanged.
+- **Revocation safety** — a `revoked` status on either side is sticky, so a
+  stale "active" entry with a newer lastSeen can NOT resurrect a removed
+  machine (security-relevant; tested).
+
+**Test coverage.**
+- Unit `tests/unit/mergeRegistry.test.ts` (6 cases): the exact 2026-05-27
+  divergence (concurrent lease-bump + join → both machines + higher epoch
+  survive); order-independence; same-epoch signature tiebreak; sticky
+  revocation vs newer-lastSeen; missing-lease on one/both sides; syncSequence
+  tiebreak. All green. `tsc --noEmit` + destructive-lint clean.
+- The git-level conflict path (rebase → resolveRegistryConflict) is exercised
+  by the existing GitSync conflict-resolution integration coverage; the new
+  case mirrors the proven relationship/jobs/evolution wiring.
+
+**Migration parity.** Server source (GitSync) — existing agents pick up the new
+conflict case on auto-update. No agent-installed-file change.
+
+**Rollback.** Revert the PR. registry.json conflicts fall back to LLM/manual
+(prior behavior). No data change, no migration to reverse.
+
+**Note.** Track D is intentionally scoped to the registry/lease conflict-merge
+gap (the actual hole), NOT the spec's drafted full sync() rewrite (unnecessary
+given the existing mature sync()). Flagged to Justin.

package/upgrades/side-effects/publish-completeness-smoke-gate.md

@@ -0,0 +1,47 @@
+# Side-Effects Review — Post-publish smoke gate (MM-Bootstrap Track A, re-scoped)
+
+**Spec:** MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS §Track A (re-scoped per the
+evidence below).
+
+**Scope.** `scripts/post-publish-smoke.mjs` (new), `.github/workflows/publish.yml`
+(one new step after `npm publish`), `tests/unit/post-publish-smoke.test.ts` (new).
+
+**Premise correction (evidence-driven).** Track A originally targeted a
+"fleet-wide install blocker — the published tarball ships an empty dist." That
+premise is FALSE: a clean `npm install --prefix /tmp/... instar@latest` yields a
+complete dist (864 dist/core files) and runs. The "empty dist" hit during the
+2026-05-27 manual bring-up was self-inflicted (an `rsync -a --delete` wiping the
+global install). So there is no active bug to fix. Re-scoped (with Justin's
+default-build nod) to cheap REGRESSION INSURANCE: if the publish pipeline ever
+DOES ship a broken tarball, catch it within minutes of release.
+
+**What it does.** A new step after `npm publish` runs
+`post-publish-smoke.mjs <version>`: waits (bounded retry, 3m) for npm to
+propagate the just-published version, clean-installs it into a throwaway prefix,
+asserts `dist/cli.js` exists, runs `--version`, and asserts it reports the
+published version. Fails the release workflow loudly otherwise (before the
+version-bump commit/tag).
+
+**Side-effects review.**
+- **No effect on the happy path** — adds a verification step; a healthy publish
+  passes it in ~seconds-to-2min (npm propagation).
+- **Fails the workflow on a broken publish** — by design. A broken tarball halts
+  the release before tagging, so a bad version isn't blessed. (The tarball is
+  already on npm at that point — npm doesn't allow un-publish easily — but the
+  loud failure surfaces it immediately for a follow-up patch.)
+- **Throwaway prefix** — installs into `mkdtemp` under the OS tmpdir; no effect
+  on the repo or the runner's global state.
+- **Bounded** — 3-minute propagation deadline; never hangs the workflow.
+- **substring-safe version check** — `versionMatches` tokenizes (1.3.5 ≠ 1.3.55),
+  unit-tested both ways.
+
+**Test coverage.** Unit `tests/unit/post-publish-smoke.test.ts` (4) covers the
+pure `versionMatches` (bare output / token-among-others / mismatch / no
+substring false-match). The install+run path is exercised by the workflow itself
+on the next real publish (CI-only; not unit-mockable meaningfully).
+
+**Migration parity.** None — publish-pipeline + dev script; no agent-installed
+file.
+
+**Rollback.** Revert the PR. The smoke step disappears; publishes proceed
+unverified (the prior state). No data change.

package/upgrades/side-effects/test-as-self-orchestrator.md

@@ -0,0 +1,66 @@
+# Side-Effects Review — `instar test-as-self` orchestrator (MM-Bootstrap Track F)
+
+**Spec:** MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS §Track F (folds the approved Part 2.1).
+
+**Scope.** `src/commands/testAsSelfValidation.ts` (new, pure guards),
+`src/commands/test-as-self.ts` (new, the 7-step orchestrator), `src/cli.ts`
+(register `test-as-self`), `src/scaffold/templates.ts` (Agent Awareness entry),
+`tests/unit/test-as-self-validation.test.ts`,
+`tests/integration/test-as-self-guards.test.ts`.
+
+**What it does.** `instar test-as-self` automates the recipe the test-as-self
+SKILL documented as manual steps: deploy the current dist into a throwaway agent
+home, start it, optionally run a real Telegram round-trip (Bot HTTP API), run the
+deterministic `verify.mjs`, and tear down. Seven gated steps; a single JSON
+report; exit 0 = all PASS.
+
+**Variance from approved Part 2.1 (documented):** the round-trip uses the
+Telegram Bot HTTP API (sendMessage + poll getUpdates) instead of Playwright —
+strictly more reliable, no browser/profile/flake, equally faithful.
+
+**Structural guards (pure, unit-tested, fail-fast).**
+- `--target` can never be the canonical (running) agent home or a protected
+  agent name (Bob) or an explicitly protected home → exit 11.
+- `--bot-token` refuses a raw token (Telegram/GitHub/Slack/OpenAI shapes) on
+  argv → exit 12. Tokens flow only through Secret Drop, retrieved in-memory via
+  the hardened `secret-drop-retrieve.mjs` (never argv/env/transcript).
+
+**Side-effects review.**
+- **Throwaway-only by construction** — the target guards make it structurally
+  impossible to deploy over a real/protected home; Bob + the canonical home are
+  hard-blocked.
+- **Secret hygiene** — the bot token never touches argv/env/logs; retrieved to
+  memory via Secret Drop. The raw-token-on-argv guard is the enforcement.
+- **No-I/O on guard failure** — pre-flight guards reject BEFORE any dir is
+  created or process spawned (verified by the integration test), so a bad
+  invocation has zero side-effects.
+- **Teardown is signal-safe** — runs in a `finally`; SIGTERMs the spawned
+  server + lifeline and calls `server stop`. The throwaway home is left in a
+  dated `~/.instar/test-deploys/` dir for inspection rather than auto-deleted
+  (deletion stays operator/--keep-driven; no rm in the harness — SafeFsExecutor
+  is the only sanctioned deletion path).
+- **Reuses the shipped deterministic verifier** (`verify.mjs`) for step 6 — no
+  duplication of the lease/crash-signature logic.
+
+**Test coverage (3-tier).**
+- Unit (`test-as-self-validation.test.ts`, 12): isRawToken across token shapes;
+  validateTarget (empty / canonical / protected-name case-insensitive /
+  protected-home / clean-accept); validateBotTokenArg (absent / Secret-Drop-ID /
+  raw-token-refused).
+- Integration (`test-as-self-guards.test.ts`, 3): runTestAsSelf exits 12 on raw
+  token, 11 on protected-name target, 11 on canonical-home target — all
+  no-I/O early-exit paths, safe in CI.
+- E2E / live: the full deploy+verify run is the real-machine backstop (the live
+  two-machine proof is Track E); not run in CI (needs a real deploy + bot).
+
+**Migration parity.** The command + validation are server source (dist) →
+existing agents get `instar test-as-self` on auto-update; no agent-installed-file
+change. The CLAUDE.md template gains an Agent-Awareness entry so new agents know
+about it. **Deferred (tracked, not dropped):** demoting the v1 manual recipe in
+`.claude/skills/test-as-self/SKILL.md` to "fallback" + a
+`PostUpdateMigrator.migrateTestAsSelfSkill()` to patch the on-disk SKILL for
+existing agents — the v1 SKILL still works as-is (runbook), so this is polish,
+filed as a follow-up.
+
+**Rollback.** Revert the PR. The command disappears; the v1 SKILL runbook
+remains. No data change, no migration to reverse.