instar 1.3.54 → 1.3.56

package/scripts/post-publish-smoke.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * post-publish-smoke.mjs — regression gate that a freshly-published instar
+ * tarball actually installs + runs.
+ *
+ * Track A of MULTI-MACHINE-BOOTSTRAP-ROBUSTNESS (re-scoped). The 2026-05-27
+ * "empty dist" scare turned out to be self-inflicted (an rsync --delete), NOT a
+ * publish bug — the published tarball was complete. So this is NOT fixing an
+ * active bug; it's cheap regression insurance: if the publish pipeline EVER
+ * ships a tarball missing its compiled output, this catches it within minutes
+ * of release instead of when an agent's fresh install fails in the wild.
+ *
+ * What it does (in CI, right after `npm publish`):
+ *   1. Wait for npm to propagate the just-published version (bounded retry).
+ *   2. `npm install instar@<version>` into a throwaway prefix.
+ *   3. Run the installed `dist/cli.js --version`.
+ *   4. Assert it reports <version>. Exit 1 (fail the release workflow) otherwise.
+ *
+ * Usage:  node scripts/post-publish-smoke.mjs <version>
+ */
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+/** Pure: does the `instar --version` output report the expected version? */
+export function versionMatches(cliOutput, expected) {
+  // cli prints the bare version (commander default) possibly with surrounding whitespace/newlines.
+  return cliOutput.split(/\s+/).map((s) => s.trim()).includes(expected);
+}
+
+async function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+async function waitForPropagation(version, deadlineMs) {
+  const end = Date.now() + deadlineMs;
+  while (Date.now() < end) {
+    try {
+      const published = execFileSync('npm', ['view', `instar@${version}`, 'version'], { encoding: 'utf-8' }).trim();
+      if (published === version) return true;
+    } catch { /* not propagated yet */ }
+    await sleep(10_000);
+  }
+  return false;
+}
+
+async function main() {
+  const version = process.argv[2];
+  if (!version) { console.error('Usage: post-publish-smoke.mjs <version>'); process.exit(2); }
+
+  console.log(`[smoke] waiting for instar@${version} to propagate on npm…`);
+  if (!await waitForPropagation(version, 180_000)) {
+    console.error(`[smoke] instar@${version} did not appear on npm within 3m`);
+    process.exit(1);
+  }
+
+  const prefix = mkdtempSync(path.join(tmpdir(), 'instar-smoke-'));
+  console.log(`[smoke] clean-installing instar@${version} into ${prefix}`);
+  execFileSync('npm', ['install', '--prefix', prefix, `instar@${version}`], { encoding: 'utf-8', stdio: 'inherit' });
+
+  const cli = path.join(prefix, 'node_modules', 'instar', 'dist', 'cli.js');
+  if (!existsSync(cli)) {
+    console.error(`[smoke] FAIL: ${cli} missing — the published tarball shipped without its compiled dist.`);
+    process.exit(1);
+  }
+
+  const out = execFileSync('node', [cli, '--version'], { encoding: 'utf-8' });
+  if (!versionMatches(out, version)) {
+    console.error(`[smoke] FAIL: \`instar --version\` reported "${out.trim()}", expected "${version}".`);
+    process.exit(1);
+  }
+
+  console.log(`[smoke] ✓ instar@${version} clean-installs and runs (--version → ${version}).`);
+  process.exit(0);
+}
+
+// Only run main() when invoked directly (not when imported by the unit test).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((err) => { console.error(`[smoke] error: ${err?.message ?? err}`); process.exit(1); });
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-28T07:07:15.447Z",
-  "instarVersion": "1.3.54",
+  "generatedAt": "2026-05-28T07:50:52.270Z",
+  "instarVersion": "1.3.56",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -769,7 +769,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -777,7 +777,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -785,7 +785,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -793,7 +793,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -801,7 +801,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -809,7 +809,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -817,7 +817,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -825,7 +825,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -833,7 +833,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -841,7 +841,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -849,7 +849,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -857,7 +857,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -865,7 +865,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -873,7 +873,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -881,7 +881,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -889,7 +889,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -897,7 +897,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -905,7 +905,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -913,7 +913,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -921,7 +921,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -929,7 +929,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -937,7 +937,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -945,7 +945,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -953,7 +953,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -961,7 +961,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -969,7 +969,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -977,7 +977,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -985,7 +985,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -993,7 +993,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "2f06177819f2332512cb9fd329ef2a78613fa347b737b3ffb22554e415171861",
+      "contentHash": "61519ff00a42e4d859ad18e6ddade404309a1e047ff33cca31693e06a05bf622",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {

package/src/scaffold/templates.ts

@@ -1217,6 +1217,20 @@ Create worktrees for collaborator repos with \`instar worktree create <branch>\`
 **Why:** the macOS sandbox can revoke filesystem access to anything outside the agent home mid-session, with no in-session recovery path. The agent home (\`~/.instar/agents/<agent>/\`) is the one location the sandbox cannot revoke. \`instar worktree create\` places the worktree at \`~/.instar/agents/<agent>/.worktrees/<slug>/\` and refuses any other destination. Spec: \`docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md\`.
 
 **Caveat — git identity env vars:** the CLI sets per-worktree \`user.name\` / \`user.email\` to \`Instar Agent (<name>)\` / \`<name>@instar.local\`. \`GIT_AUTHOR_NAME\` / \`GIT_COMMITTER_EMAIL\` in the calling environment override that local config. Agents that care about commit attribution must avoid exporting those vars.
+
+## Test-As-Self (Throwaway-Deploy Harness)
+
+\`instar test-as-self\` deploys the CURRENT dist into a throwaway agent home, verifies it's healthy, optionally runs a real Telegram round-trip, and tears down — clean evidence instead of post-hoc log forensics. Use it BEFORE shipping a change to the deploy/lifeline/server path, AFTER landing one, or to reproduce a crash deterministically.
+
+\`\`\`bash
+instar test-as-self --no-roundtrip                  # deploy + verify only (no bot needed)
+instar test-as-self --bot-token <secret-drop-id>    # + a real Telegram round-trip via a throwaway bot
+instar test-as-self --keep                          # leave the throwaway running for inspection
+\`\`\`
+
+**Structural guards (you cannot foot-gun these):** \`--target\` can never be your canonical agent home or a protected agent (e.g. Bob); \`--bot-token\` refuses a raw token on the command line — pass a Secret Drop ID and the token is retrieved in-memory, never via argv. It emits a single JSON report; exit 0 = all steps PASS.
+
+**Proactive trigger:** when you're about to ship or just shipped a change touching the deploy/lifeline/server-startup path, run this against a throwaway home first — don't guess from logs.
 `;
 
   if (hasTelegram) {

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

@@ -1,57 +1,43 @@
 # Instar Upgrade Guide — NEXT
 
-<!-- bump: minor -->
+<!-- bump: patch -->
 
 ## What Changed
 
-**Mentor-cycle reply leg over same-machine /a2a/inbox — the round-trip closes.**
-PRs #462/#464/#466 built the forward path (mentor→mentee) over the
-bot-to-bot-block-immune HTTP transport. This PR closes the reply leg
-(mentee→mentor) the same way, plus fixes two bugs found in live dogfood:
-
-1. **Unified primary-adapter a2a hook.** `installMentorMessageHook` now wires
-   BOTH roles onto the primary `TelegramAdapter`: the mentee side (`mentor`
-   role, from `config.mentee`) AND the mentor side (`mentor-reply` role, from
-   `config.mentor` when `menteeBotId` is set). Previously the mentor-reply
-   handler lived only on the mentor-BOT adapter (Telegram polling), so a reply
-   arriving via `/a2a/inbox` had nowhere to land. Now Echo's primary adapter
-   persists mentee replies to `mentor-replies.jsonl` (finding-emission-only,
-   capability-handle path per spec §250).
-
-2. **`deliverA2aMessage` unified transport helper.** Both directions
-   (mentor→mentee `deliverToMentee` and mentee→mentor reply) now route through
-   one helper: same-machine peers get an HTTP POST to `/a2a/inbox`; cross-
-   machine falls back to the Telegram bot path. Fixes the **`\n\n` marker bug**
-   from #466 (`deliverToMentee` built the marker with a single `\n`; the parser
-   requires `\n\n` between marker and body — single-newline markers were
-   silently dropped as `agent-marker-malformed`).
-
-3. **Mentee reply-capture race fix.** The mentee role-handler captured the
-   tmux pane AFTER the session completed — but the reaper removes the pane
-   first, so `captureOutput` returned empty ("mentee session produced empty
-   reply"). Now it captures the last non-empty snapshot WHILE the session is
-   alive, so a completed-then-reaped session still yields its output.
+**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
 
-The cross-agent mentor cycle now round-trips end-to-end on the same machine:
-a mentor agent sends a prompt, the mentee processes it and replies, and the
-reply is captured back. The earlier releases built each half; this one closes
-the loop and fixes the bugs that only showed up in live testing. No config
-changes needed.
+- 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 |
 |-----------|-----------|
-| Unified primary-adapter a2a hook | `installMentorMessageHook` registers `mentor` and/or `mentor-reply` handlers on the primary adapter based on `config.mentee` / `config.mentor`. Reachable via `/a2a/inbox`. |
-| `deliverA2aMessage` | One transport helper for both mentor→mentee and mentee→mentor: same-machine `/a2a/inbox`, Telegram fallback cross-machine. Correct `\n\n` marker framing. |
-| Mentee reply capture-while-alive | Survives the session-reap race so the mentee's output is actually captured + replied. |
+| `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
 
-1 new E2E (`mentor-reply-via-inbox`) proving a `mentor-reply` marker POSTed to
-`/a2a/inbox` routes + persists to `mentor-replies.jsonl` with
-`transport: a2a-inbox-local`. All 22 prior mentor/mentee/inbox tests still
-green. `tsc --noEmit` clean. Side-effects review:
-`upgrades/side-effects/mentee-reply-leg.md`.
+**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.56.md

@@ -0,0 +1,35 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Test-hygiene: unit tests no longer load plists into the real launchd.** The
+auto-start installer (`installMacOSLaunchAgent` / fleet-watchdog) did a real
+`launchctl bootstrap` after writing a plist — so a unit test exercising the
+plist-writing path loaded tmpdir-pointed plists into the operator's real launchd,
+leaving inert stale entries behind. New `launchctlLoadAllowed()` gate skips the
+live load under a test runner (vitest sets `VITEST`) or when
+`INSTAR_SKIP_LAUNCHCTL_LOAD` is set. Production behavior is unchanged.
+
+## What to Tell Your User
+
+- Internal test-hygiene fix: my test suite no longer accidentally registers
+  throwaway background-service entries on the machine it runs on. Nothing
+  user-facing; production startup is unchanged.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `launchctlLoadAllowed()` gate | Automatic — skips the live `launchctl bootstrap` under VITEST / `INSTAR_SKIP_LAUNCHCTL_LOAD`; production loads normally. |
+
+## Evidence
+
+**One helper + two install-path wraps; production load path unchanged.** Unit
+test `tests/unit/launchctl-load-guard.test.ts` (3): false under VITEST, false
+under the explicit opt-out, true in production. Verified the merged Track C test
+now runs with NO real-launchd pollution (no stale mmtest* entries) while still
+passing. `tsc` clean. Side-effects review:
+`upgrades/side-effects/launchctl-test-hygiene.md`. Follow-up to Track C 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.