instar 1.3.53 → 1.3.55

package/upgrades/1.3.53.md

@@ -4,43 +4,35 @@
 
 ## What Changed
 
-**Credential redaction in URL logging (security fix).** `instar join` could log a
-clone URL containing a live GitHub token on certain failure paths — Node's own
-fetch/URL errors echo the full credentialed URL in `err.message`, so catching
-the error and logging it leaked the secret. New `redactUrl()` / `redactUrlsInText()`
-funnel (`src/core/redactUrl.ts`) strips `user:pass@` userinfo and scrubs standalone
-known-token shapes (GitHub, Slack, Telegram, OpenAI). Applied at the three join-flow
-log sites. A new lint rule (`scripts/lint-no-direct-url-log.js`, wired into
-`npm run lint`) bans credentialed-URL logging going forward.
-
-Also: the outbound-message convergence-check gate now trusts the agent's own tunnel
-domain (read live from tunnel state) + the common tunnel domains, so an agent can
-send links to its own private views without the gate flagging them as fabricated.
+**`instar join` now installs auto-start for the joined home (mesh bootstrap fix).**
+Previously a joined mesh agent had no LaunchAgent/systemd unit, so it never
+auto-started — and a stale auto-start entry from a prior `instar init` of the same
+name (at a different directory) would keep respawning a server against the WRONG
+home, fighting the joined one for the port. join now installs auto-start for its
+own home; because the unit is keyed on the agent name, this cleanly replaces any
+stale same-name unit. One unit, pointing at the right home.
 
 ## What to Tell Your User
 
-- A security fix: when joining two machines into a mesh, an error message used to be
-  able to print a GitHub access token to the screen. It no longer can — credentials
-  are scrubbed from anything that gets logged. Nothing changes in how you use the
-  agent; this just closes a leak.
-- A small papercut fix: I can now send you links to my own private-view / dashboard
-  pages without my safety gate mistakenly treating my own tunnel address as suspicious.
+- Joining a second machine to your agent's mesh now "just works" for staying alive
+  across reboots — the joined machine sets up its own background auto-start, and it
+  won't collide with leftovers from an earlier setup attempt of the same agent. You
+  no longer have to hand-start the joined agent or manually clean up a stale startup
+  entry.
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| `redactUrl()` / `redactUrlsInText()` | Internal — route any URL or error-message string through these before logging. `src/core/redactUrl.ts`. |
-| `lint-no-direct-url-log` | Automatic in `npm run lint` / CI — fails the build if a credentialed URL is logged without redaction. |
-| Convergence-check own-tunnel trust | Automatic — the message gate no longer flags the agent's own tunnel URLs as unfamiliar. |
+| join installs auto-start | Automatic — `instar join` now registers the joined home's background auto-start (LaunchAgent on macOS, systemd on Linux), replacing any stale same-name unit. |
 
 ## Evidence
 
-**Security fix + defense-in-depth, no behavior change to join logic.** Unit tests
-`tests/unit/redactUrl.test.ts` (13 cases, all green) include the EXACT 2026-05-27
-leak string and assert no `gho_…` token survives; plus basic-auth, token-in-query,
-Telegram-bot-token path form, multiple-URLs-in-one-string, malformed-input-never-throws,
-idempotency. `tsc --noEmit` clean. The lint rule passes on the redacted tree and
-would fail on the pre-fix `machine.ts`. Side-effects review:
-`upgrades/side-effects/credential-redaction-in-url-logging.md`. Spec: Track B of
+**Small, contained join-flow addition; no change to init.** Unit test
+`tests/unit/init-join-launchd-handoff.test.ts` (2 cases, darwin-gated, sandboxed
+$HOME) proves the Label-keyed replace: two installs for the same name + different
+dirs leave ONE plist pointing at the second (joined) dir; standby install writes
+server-start (not lifeline) args. `tsc --noEmit` clean. The autostart install is
+try/catch-wrapped so a failure never fails the join. Side-effects review:
+`upgrades/side-effects/init-join-launchagent-handoff.md`. Spec: Track C of
 `docs/specs/MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS-SPEC.md`.

package/upgrades/1.3.54.md

@@ -0,0 +1,43 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Mesh registry conflicts now auto-merge deterministically (multi-machine
+robustness).** When two machines concurrently update the shared mesh state — e.g.
+one bumps the awake-lease while another joins — their `machines/registry.json`
+commits can collide on rebase. GitSync's conflict resolver previously had no case
+for the registry, so such a conflict fell to LLM/manual and the mesh could stay
+split (one machine seeing a different roster than the other). New `mergeRegistry`
+merges them losslessly: union the machines (fresher `lastSeen` wins per machine,
+revocations sticky), keep the higher-epoch lease. Both machines compute the
+identical result, so the mesh converges on its own.
+
+## What to Tell Your User
+
+- Running your agent across two machines is now more robust: if both machines
+  record a change to the shared roster at the same moment, they'll automatically
+  reconcile to the same view instead of disagreeing about who's awake or which
+  machines are in the mesh. Nothing for you to do — it just self-heals.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `mergeRegistry(ours, theirs)` | Internal — deterministic semantic merge of two mesh registries (union machines, higher-epoch lease). |
+| GitSync registry conflict auto-resolve | Automatic — a `machines/registry.json` rebase conflict now merges deterministically instead of escalating to LLM/manual. |
+
+## Evidence
+
+**Small, precise fix — NOT the spec's drafted sync() rewrite (sync() is already
+mature; the real gap was a missing conflict-resolution case).** Unit test
+`tests/unit/mergeRegistry.test.ts` (6 cases) covers the exact 2026-05-27
+divergence (concurrent lease-bump + join → both machines + higher epoch survive),
+order-independence, same-epoch tiebreak, sticky revocation, missing lease, and
+syncSequence tiebreak. `tsc --noEmit` + destructive-lint clean. The fix slots into
+GitSync's existing Tier-0 `tryAutoResolve` (same wiring as relationships/jobs/
+evolution) and is try/catch fail-safe (falls back to the prior LLM/manual tier on
+any error). Side-effects review:
+`upgrades/side-effects/mesh-git-substrate-auto-reconcile.md`. Spec: Track D of
+`docs/specs/MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS-SPEC.md`.

package/upgrades/1.3.55.md

@@ -0,0 +1,38 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Post-publish smoke gate (publish-pipeline regression insurance).** A new step
+after `npm publish` clean-installs the just-published version into a throwaway
+prefix and runs `instar --version`, asserting the tarball actually installs and
+reports the right version. If the publish pipeline ever ships a tarball missing
+its compiled output, this catches it within minutes of release instead of when a
+fresh install fails in the wild. (Track A was re-scoped from a "fix" to this gate:
+the original "empty dist" scare was self-inflicted, not a real publish bug.)
+
+## What to Tell Your User
+
+- Internal release-pipeline hardening: after I publish a new version, CI now
+  immediately does a clean install of it and checks it runs, so a broken release
+  can't slip out unnoticed. Nothing changes for you — it's a safety net on my own
+  shipping process.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Post-publish smoke gate | Automatic in the publish workflow — clean-installs the just-published version + asserts `instar --version`. |
+
+## Evidence
+
+**Re-scoped to regression insurance (the original premise was a self-inflicted
+artifact, not a bug).** `scripts/post-publish-smoke.mjs` waits for npm
+propagation, clean-installs into a throwaway prefix, asserts `dist/cli.js` exists
++ `--version` matches. Unit test `tests/unit/post-publish-smoke.test.ts` (4)
+covers the pure version-match logic incl the 1.3.5-vs-1.3.55 substring trap.
+`publish.yml` validates as YAML; the step mirrors the existing publish steps'
+structure + gating. Side-effects review:
+`upgrades/side-effects/publish-completeness-smoke-gate.md`. Spec: Track A of
+`docs/specs/MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS-SPEC.md`.

package/upgrades/side-effects/init-join-launchagent-handoff.md

@@ -0,0 +1,62 @@
+# Side-Effects Review — Init→Join LaunchAgent handoff (MM-Bootstrap Track C)
+
+**Spec:** `docs/specs/MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS-SPEC.md` §Track C (approved PR #465).
+
+**Scope.** `src/commands/machine.ts` (joinMesh — add Step 6: install auto-start
+for the joined home), `tests/unit/init-join-launchd-handoff.test.ts` (new).
+
+**Problem.** `instar join` never installed an auto-start plist for the joined
+home. So a joined agent had no LaunchAgent/systemd unit (operator had to
+hand-start it), and — worse — a stale `ai.instar.<projectName>` plist left by a
+prior `instar init` of the SAME name at a DIFFERENT home kept respawning a
+server against the wrong directory, fighting the joined one for the port +
+identity (observed live 2026-05-27 during the mesh bring-up).
+
+**Fix.** joinMesh now calls `installAutoStart(projectName, joinedProjectDir,
+hasTelegram)` after the gitignore step. Because the auto-start plist Label is
+keyed on `projectName` (`ai.instar.<name>`), installing for the joined dir
+cleanly REPLACES any stale same-name plist — one unit, pointing at the joined
+home, zero orphans.
+
+**Design note (supersedes the spec's drafted pointer-file C-2).** The spec
+drafted a pointer-file (`active-home`) + plist-wrapper approach. Implementation
+found that unnecessary: the Label is already keyed on projectName, so a
+re-install naturally replaces. The simpler fix (join calls installAutoStart) is
+less code, no new mechanism, same guarantee. Flagged to Justin via Telegram.
+
+**Side-effects review.**
+- **No change to `instar init`'s behavior** — init still installs its plist as
+  before. Only join now ALSO installs (for its own home).
+- **hasTelegram=false-derived-from-config for the standby** — a joined standby
+  installs a server-start unit (ready to take over), not a lifeline. The shipped
+  poll-ownership lease prevents dual-poll if telegram is configured on both ends,
+  so even if a future config sets hasTelegram=true the 409 class can't recur.
+- **Idempotent + safe** — installAutoStart overwrites the same Label; re-running
+  join is harmless. The call is wrapped in try/catch (@silent-fallback-ok): a
+  failed auto-start install does NOT fail the join (join still succeeds; operator
+  can hand-start).
+- **No new orphans** — the replace property is the whole point; verified by test.
+
+**Test coverage.**
+- Unit `tests/unit/init-join-launchd-handoff.test.ts` (2 cases, darwin-gated,
+  sandboxed $HOME so it never touches the real LaunchAgents dir): (1) two installs
+  same-name + different-dir → ONE plist pointing at the second (joined) dir, init
+  dir gone; (2) standby install (hasTelegram=false) writes server-start args, not
+  lifeline.
+- E2E launchd lifecycle is quarantined per spec (INSTAR_E2E_LAUNCHD) — macOS-only,
+  not run in CI.
+
+**Deferred (own follow-up, noted not silently dropped).** The join config-creation
+sub-gap (joined home lacks config.json because it's gitignored; a config.json.bak
+is committed) is a SEPARATE bootstrap gap surfaced the same night. Out of Track C's
+tight autostart scope; tracked for a follow-up so it isn't lost.
+
+**Migration parity.** Server source — existing agents pick up the fix on
+auto-update. New joins get the behavior immediately. Existing JOINED agents (rare,
+since join didn't install autostart before) won't have a plist; the forward fix
+covers all new joins, and `instar server start` self-heals an autostart install at
+boot (server.ts autostart-check), so an existing joined agent gets a plist the next
+time its server starts anyway.
+
+**Rollback.** Revert the PR. join stops installing autostart (prior behavior).
+No migration to reverse, no data change.

package/upgrades/side-effects/mentee-reply-leg.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — mentor-cycle reply leg over /a2a/inbox
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Recipient side (§281:
+"Codey's reply goes back via sendAgentMessage role=mentor-reply"; §250:
+finding-emission-only capability handle). Fourth + final fast-follow closing
+the round-trip. Same approved spec — implementing the reply half with the
+HTTP-transport substitution established in #466 (Telegram blocks bot-to-bot).
+
+**Change:** `src/server/AgentServer.ts` only (+ 1 new test file).
+- `installMentorMessageHook` generalized: builds a combined a2a hook on the
+  primary adapter covering BOTH `mentor` (mentee side, from `config.mentee`)
+  and `mentor-reply` (mentor side, from `config.mentor.menteeBotId`).
+- New `deliverA2aMessage` private helper: unified same-machine `/a2a/inbox`
+  (HTTP) + Telegram-fallback transport for both directions.
+- `deliverToMentee` refactored to call `deliverA2aMessage` (removes the inline
+  #466 logic, fixes the `\n\n` marker bug).
+- Mentee reply capture: last-non-empty-while-alive (reap-race fix).
+- `tests/e2e/mentor-reply-via-inbox.test.ts` (new, 1).
+
+## The seven questions
+
+1. **Over-block.** N/A — additive. Non-a2a traffic falls through unchanged;
+   the consolidated hook only adds role-handlers.
+2. **Under-block.** Spoof defense unchanged (decideRoute's bot-id allowlist,
+   covered by the primitive's own unit tests). The mentor-reply handler stays
+   finding-emission-only (persist to jsonl + clear OutstandingPromptTracker —
+   no spawn/deliver/schedule), preserving the spec §250 capability-handle
+   invariant.
+3. **Level-of-abstraction fit.** Consolidates two previously-separate hook
+   installs (mentor-bot adapter + primary adapter) onto one primary-adapter
+   hook. `deliverA2aMessage` unifies what was duplicated transport logic.
+   Net reduction in surface.
+4. **Signal vs authority.** The hook decides route/drop (spec routing matrix);
+   handlers are capture-only / finding-emission-only; `deliverA2aMessage`
+   audits every send to the ledger. No new authority.
+5. **Interactions.** Reuses AgentRegistry + AgentTokenManager + the existing
+   `/a2a/inbox` route (#466) + `getOrCreateMentorOutstanding` + the a2a ledger.
+   `installMentorReceiverHook` (mentor-BOT adapter, Telegram path) is left in
+   place for cross-machine; the primary-adapter hook is the same-machine path.
+   Both write to the same `mentor-replies.jsonl` (append-only, safe).
+6. **External surfaces.** No new routes, no new config keys. `mentor-replies.jsonl`
+   rows gain a `transport` field (additive).
+7. **Rollback cost.** Trivial — revert restores the per-side installs +
+   inline deliverToMentee logic. No migration, no config change.
+
+## Testing
+
+1 new E2E (`mentor-reply-via-inbox`): a `mentor-reply` marker POSTed to
+`/a2a/inbox` on a mentor-configured server routes through the consolidated
+hook + persists to `mentor-replies.jsonl` with the right corr/from/message/
+transport. All 22 prior mentor/mentee/inbox tests still green (no regression).
+`tsc --noEmit` clean.
+
+Live round-trip verification (test-as-self) is performed post-release against
+the live Echo↔Codey pair — the autonomous run's completion criterion.
+
+## Migration parity
+
+No new config keys; the consolidated hook reads the existing `config.mentee`
++ `config.mentor` blocks. Purely additive — agents with neither configured
+get no hook (same as before). No PostUpdateMigrator change required.

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.