feat(mosaic): mosaic update re-seeds framework + relaunches agents (#609)

Closes R13 (F3-m3). mosaic update installed the new npm CLI but never
re-seeded ~/.config/mosaic from the package's bundled framework/, so shipped
launcher/runtime changes (agent-name export + native HB) stayed DORMANT until
a manual re-seed — operators got the new CLI on a stale framework.

- update-checker.ts: resolveBundledFrameworkRoot, buildReseedCommand (install.sh
  in MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep — the P4 data-safe reconcile:
  framework-owned overwrite + backup-once; SOUL/USER/*.local/credentials kept),
  runFrameworkReseed, readRosterAgentNames, buildRelaunchCommands.
- cli.ts update: after a successful CLI install that includes @mosaicstack/mosaic,
  re-seed the framework (default-on; --no-reseed to skip). Then --relaunch restarts
  rostered agents (systemctl --user restart mosaic-agent@<name>), else prints clear
  activation guidance. Only re-seeds when the framework-bearing package updated.

Flow: update CLI -> re-seed framework (data-safe) -> relaunch agents (opt-in).

Verified: 6 new unit tests + 19 runtime + 26 launch tests green; tsc/eslint/
prettier clean. Sync data-safety already proven (P4 matrix + live validation).

Refs #609

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83

docs/TASKS.md

@@ -46,6 +46,15 @@ Active workstream is **W1 — Federation v1**. Workers should:
 - Cut always-injected contract AGENTS+TOOLS+RUNTIME 8,827→4,122 tok (−53%); all 12 hard gates intact.
 - Validation: deterministic gate-checklist PASS; headless A/B thin 7/9 vs monolith 5/9. Detail: scratchpads/contract-thin-core.md.
 
+## P5 — Overlay composer + cross-harness (#604) — feat/p5-overlay-composer
+
+- Status: MERGED to main (#605). R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
+- `composeContract({harness, mosaicHome})` pure fn + `.local` overlay deltas-by-value; `mosaic compose-contract <harness>` command; AGENTS bare-launch nudge; composer spec (per-tier anchor + Tier-3 byte-equality). Detail: scratchpads/p5-overlay-composer.md.
+
 ## P6 — Docs, compliance matrix, alpha tag (#606) — feat/p6-docs-compliance-alpha
 
-- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring). Remaining: aiguide reconcile (separate repo), alpha tag (Lead, post-merge). Detail: scratchpads/p6-docs-compliance-alpha.md.
+- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring + ALPHA-DOD.md). Remaining: alpha tag v0.0.39-alpha (Lead, post-merge). aiguide reconcile merged (#8). Detail: scratchpads/p6-docs-compliance-alpha.md.
+
+## F3-m3 — mosaic update re-seeds framework + relaunches agents (#609) — feat/f3-m3-update-reseed
+
+- Status: implemented + tested. Closes R13: `mosaic update` now re-seeds the framework (data-safe MOSAIC_SYNC_ONLY) after the CLI install so shipped launcher/runtime changes activate; `--relaunch` restarts rostered agents; `--no-reseed` opts out. Detail: scratchpads/f3-m3-update-reseed.md.

docs/scratchpads/f3-m3-update-reseed.md

@@ -0,0 +1,29 @@
+# F3-m3 — `mosaic update` re-seeds framework + relaunches agents (R13)
+
+- **Issue:** #609 · **Branch:** `feat/f3-m3-update-reseed`
+
+## Gap (found in 0.0.39 production validation)
+
+`mosaic update` installs the new npm CLI but never re-seeds `~/.config/mosaic/` from the package's
+bundled `framework/`. So the shipped custom Pi harness (agent-name export + native HB, 0.0.39) stays
+DORMANT until a re-seed — operators get the new CLI on a stale framework.
+
+## Implementation
+
+- `update-checker.ts`: `resolveBundledFrameworkRoot()`, `buildReseedCommand()` (install.sh in
+  `MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep` — the P4 data-safe reconcile), `runFrameworkReseed()`,
+  `readRosterAgentNames()`, `buildRelaunchCommands()` (systemctl --user restart per agent).
+- `cli.ts` `update`: after a successful CLI install that includes `@mosaicstack/mosaic`, re-seed the
+  framework (default-on; `--no-reseed` to skip). Then either `--relaunch` (restart rostered agents) or
+  print clear guidance to run `mosaic update --relaunch` / `mosaic fleet restart`.
+
+## Flow
+
+`update CLI → re-seed framework (data-safe) → relaunch agents (opt-in)` — closes R13, activates the
+native harness for every operator.
+
+## Verification
+
+- 6 new unit tests (reseed command/env, relaunch commands, roster parse, missing-installer guard).
+- 19 runtime + 26 launch tests still green; tsc/eslint/prettier clean.
+- Data-safety of the sync is already proven (P4 5-fixture matrix + live dragon-lin validation).

docs/scratchpads/p5-overlay-composer.md

@@ -0,0 +1,43 @@
+# P5 — Overlay composer + cross-harness (compose-contract)
+
+- **Issue:** #604 · **Branch:** `feat/p5-overlay-composer` · **Lineage:** #542 → constitution alpha
+- **Requirements:** R7 (compose-contract) + R8 (cross-harness) + R9 (composer test)
+- **Design of record:** `docs/design/framework-constitution/{DESIGN.md §3.2, PRD.md §4}` (on `feat/framework-constitution-alpha`)
+
+## Locked design (sequential-thinking)
+
+Current `launch.ts` assembly (`buildComposedPrompt`) injects by value: mission + PRD + hard-gate +
+CONSTITUTION + AGENTS + USER + TOOLS + runtime. It does **not** inject SOUL or STANDARDS (those are
+read-on-demand per the gutted AGENTS dispatcher), and has no `.local` overlay support.
+
+**Decision (ASSUMPTION — recorded for the PR):** overlays are injected as **deltas by value** under
+labeled sections; base files keep their existing residency.
+
+- `USER.local.md` → appended directly under the `# User Profile` block (USER is injected).
+- `SOUL.local.md` + `STANDARDS.local.md` → a trailing `# Operator Overlays` section (their bases are
+  load-on-demand, so only the small delta is injected — not the full base prose).
+- **Why:** honors DESIGN §3.2 ("model gets one pre-merged blob, no read-merge ritual") while preserving
+  the P3 byte-budget tiering (don't re-inject large SOUL/STANDARDS prose). Precedence order kept: base
+  layers first, operator overlays at recency.
+- Base-only is automatic when a `.local` file is absent (`readOptional`).
+
+## Plan
+
+| #   | Task                                                                                                   | File                                    |
+| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- |
+| 1   | Extract `composeContract({harness, mosaicHome})` pure fn; `buildComposedPrompt` delegates              | `src/commands/launch.ts`                |
+| 2   | Overlay logic (USER.local under profile; SOUL/STANDARDS.local in `# Operator Overlays`)                | `src/commands/launch.ts`                |
+| 3   | `mosaic compose-contract <harness>` command → prints blob to stdout                                    | `src/commands/launch.ts`                |
+| 4   | Bare-launch overlay nudge in self-load fallback                                                        | `framework/defaults/AGENTS.md`          |
+| 5   | `compose-contract.spec.ts`: per-tier anchor, Tier-3 byte-equality, overlay present/absent, per-harness | `src/commands/compose-contract.spec.ts` |
+
+## Deferred to P6
+
+CONTRIBUTING.md + harness×gate compliance matrix; resident line-count CI ceiling; `aiguide` reconcile;
+alpha tag `mosaic-vX.Y.Z-alpha`.
+
+## Status
+
+- [x] Phase scaffold (branch, issue #604, scratchpad, TASKS)
+- [ ] Implementation (tasks 1–5)
+- [ ] prettier + vitest green; PR via wrapper → Lead (rides 0.0.39; 0.0.38 mid-cut)

packages/mosaic/framework/defaults/AGENTS.md

@@ -9,7 +9,10 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
 1. Your context already includes `CONSTITUTION.md` + `USER.md` + the TOOLS index + the runtime
    contract (injected by `mosaic` launch) — do not re-read those. **If you were launched bare**
    (a harness started without `mosaic`, so the law is NOT in your context), read
-   `~/.config/mosaic/CONSTITUTION.md` now, before your first action.
+   `~/.config/mosaic/CONSTITUTION.md` now, before your first action. A bare launch also gets
+   **base contracts only** — operator overlays (`*.local.md`) are composed by the launcher, so if
+   `SOUL.local.md`/`USER.local.md`/`STANDARDS.local.md` exist, relaunch via `mosaic <harness>` (or run
+   `mosaic doctor`) to pick them up.
 2. Read `SOUL.md` (agent persona — small, once).
 3. Read project-local `AGENTS.md` / `CLAUDE.md` if present (these may only make behavior stricter).
 4. Read guides ONLY as triggered by the table below — pull role-relevant depth on demand, not up front.

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

packages/mosaic/src/cli.ts

@@ -26,6 +26,10 @@ import {
   checkForAllUpdates,
   formatAllPackagesTable,
   getInstallAllCommand,
+  runFrameworkReseed,
+  readRosterAgentNames,
+  buildRelaunchCommands,
+  FRAMEWORK_RESEED_PACKAGE,
 } from './runtime/update-checker.js';
 import { runWizard } from './wizard.js';
 import { ClackPrompter } from './prompter/clack-prompter.js';
@@ -404,7 +408,12 @@ program
   .command('update')
   .description('Check for and install Mosaic CLI updates')
   .option('--check', 'Check only, do not install')
-  .action(async (opts: { check?: boolean }) => {
+  .option(
+    '--no-reseed',
+    'Skip re-seeding framework files into ~/.config/mosaic after the CLI update',
+  )
+  .option('--relaunch', 'Restart durable fleet agents so the new launcher/runtime takes effect')
+  .action(async (opts: { check?: boolean; reseed?: boolean; relaunch?: boolean }) => {
     // checkForAllUpdates imported statically above
     const { execSync } = await import('node:child_process');
 
@@ -442,6 +451,51 @@ program
       console.error('\nUpdate failed. Try manually: bash tools/install.sh');
       process.exit(1);
     }
+
+    // F3-m3 / R13: the CLI is updated, but the framework files in
+    // ~/.config/mosaic/ are still the previous version. Re-seed them from the
+    // freshly-installed package so shipped launcher/runtime changes ACTIVATE.
+    // Only when the framework-bearing package itself updated.
+    const mosaicUpdated = outdated.some(
+      (r: { package: string }) => r.package === FRAMEWORK_RESEED_PACKAGE,
+    );
+    if (mosaicUpdated && opts.reseed !== false) {
+      console.log(
+        '\nRe-seeding framework files into ~/.config/mosaic (data-safe; keeps your edits)…',
+      );
+      const reseed = runFrameworkReseed();
+      if (reseed.ok) {
+        console.log('✔ Framework re-seeded.');
+        const agents = readRosterAgentNames();
+        if (agents.length > 0) {
+          if (opts.relaunch) {
+            console.log(
+              `\nRelaunching ${agents.length} fleet agent(s) to pick up the new runtime…`,
+            );
+            for (const restart of buildRelaunchCommands(agents)) {
+              try {
+                execSync(restart.join(' '), { stdio: 'inherit', timeout: 30_000 });
+              } catch {
+                console.error(`  ⚠ failed to restart agent — run: ${restart.join(' ')}`);
+              }
+            }
+            console.log('✔ Agents relaunched.');
+          } else {
+            console.log(
+              `\nℹ ${agents.length} fleet agent(s) are still running the previous runtime. ` +
+                'Restart them to activate the update:\n    mosaic update --relaunch   ' +
+                '(or: mosaic fleet restart <agent>)',
+            );
+          }
+        }
+      } else {
+        console.error(
+          `\n⚠ Framework re-seed skipped: ${reseed.reason ?? 'unknown'}.\n` +
+            '  Activate manually: bash "$(npm root -g)/@mosaicstack/mosaic/framework/install.sh" ' +
+            '(MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep)',
+        );
+      }
+    }
   });
 
 // ─── wizard ─────────────────────────────────────────────────────────────

packages/mosaic/src/commands/compose-contract.spec.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { composeContract } from './launch.js';
+
+/**
+ * Composer unit test (R7/R8/R9): asserts the launcher-composed runtime contract
+ *
+ *   - includes the per-tier anchors (CONSTITUTION / AGENTS / USER / runtime),
+ *   - keeps the CONSTITUTION block byte-equal to the on-disk file (Tier-3
+ *     byte-equality — the bare-launch fallback read must match what is injected),
+ *   - merges `*.local.md` operator overlays as deltas-by-value, and omits them
+ *     entirely when absent (base-only),
+ *   - selects the correct per-harness RUNTIME.md.
+ *
+ * `composeContract` takes `mosaicHome` as a param, so each test runs against an
+ * isolated fixture home. We also chdir to an empty temp cwd so the cwd-relative
+ * mission/PRD blocks contribute nothing (deterministic output).
+ */
+
+const CONSTITUTION = '# CONSTITUTION\n\nGATE-1: the non-negotiable law.\n';
+const AGENTS = '# Mosaic Agent Dispatcher\n\nLoad order + guide router.\n';
+const USER = '# operator\n\nName: Test Operator\n';
+const TOOLS = '# tools index\n';
+
+function makeHome(): { home: string; root: string } {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-compose-'));
+  const home = join(root, 'mosaic-home');
+  for (const h of ['claude', 'codex', 'opencode', 'pi']) {
+    mkdirSync(join(home, 'runtime', h), { recursive: true });
+    writeFileSync(join(home, 'runtime', h, 'RUNTIME.md'), `# ${h} runtime contract\n`);
+  }
+  writeFileSync(join(home, 'CONSTITUTION.md'), CONSTITUTION);
+  writeFileSync(join(home, 'AGENTS.md'), AGENTS);
+  writeFileSync(join(home, 'USER.md'), USER);
+  writeFileSync(join(home, 'TOOLS.md'), TOOLS);
+  return { home, root };
+}
+
+describe('composeContract — overlay composer', () => {
+  let fixture: ReturnType<typeof makeHome>;
+  let prevCwd: string;
+  let cwdDir: string;
+
+  beforeEach(() => {
+    fixture = makeHome();
+    prevCwd = process.cwd();
+    cwdDir = mkdtempSync(join(tmpdir(), 'mosaic-cwd-'));
+    process.chdir(cwdDir); // neutralize cwd-relative mission/PRD blocks
+  });
+
+  afterEach(() => {
+    process.chdir(prevCwd);
+    rmSync(fixture.root, { recursive: true, force: true });
+    rmSync(cwdDir, { recursive: true, force: true });
+  });
+
+  it('includes the per-tier anchors and the selected harness runtime', () => {
+    const out = composeContract('claude', fixture.home);
+    expect(out).toContain('GATE-1: the non-negotiable law.'); // L0
+    expect(out).toContain('Mosaic Agent Dispatcher'); // AGENTS
+    expect(out).toContain('# User Profile'); // USER header
+    expect(out).toContain('Name: Test Operator'); // USER body
+    expect(out).toContain('# Runtime-Specific Contract');
+    expect(out).toContain('# claude runtime contract');
+  });
+
+  it('keeps the CONSTITUTION block byte-equal to the on-disk file (Tier-3)', () => {
+    const out = composeContract('pi', fixture.home);
+    const onDisk = readFileSync(join(fixture.home, 'CONSTITUTION.md'), 'utf-8');
+    // The injected L0 must be a byte-equal substring of the composed blob, so a
+    // bare-launch fallback read of CONSTITUTION.md matches what was injected.
+    expect(out.includes(onDisk)).toBe(true);
+  });
+
+  it('is base-only when no *.local overlays exist', () => {
+    const out = composeContract('claude', fixture.home);
+    expect(out).not.toContain('# Operator Overlays');
+    expect(out).not.toContain('Operator Overlay (USER.local.md)');
+    expect(out).not.toContain('Persona Overlay');
+    expect(out).not.toContain('Standards Overlay');
+  });
+
+  it('merges USER.local.md directly under the operator profile', () => {
+    writeFileSync(join(fixture.home, 'USER.local.md'), 'Prefer terse status updates.\n');
+    const out = composeContract('claude', fixture.home);
+    expect(out).toContain('## Operator Overlay (USER.local.md)');
+    expect(out).toContain('Prefer terse status updates.');
+    // Overlay appears AFTER its base profile.
+    expect(out.indexOf('# User Profile')).toBeLessThan(
+      out.indexOf('## Operator Overlay (USER.local.md)'),
+    );
+  });
+
+  it('merges SOUL.local.md + STANDARDS.local.md as deltas in the Operator Overlays block', () => {
+    writeFileSync(join(fixture.home, 'SOUL.local.md'), 'Tone: dry and direct.\n');
+    writeFileSync(join(fixture.home, 'STANDARDS.local.md'), 'Require 90% coverage on auth code.\n');
+    const out = composeContract('claude', fixture.home);
+    expect(out).toContain('# Operator Overlays');
+    expect(out).toContain('## Persona Overlay (SOUL.local.md)');
+    expect(out).toContain('Tone: dry and direct.');
+    expect(out).toContain('## Standards Overlay (STANDARDS.local.md)');
+    expect(out).toContain('Require 90% coverage on auth code.');
+  });
+
+  it('ignores whitespace-only *.local overlays (no empty overlay section)', () => {
+    writeFileSync(join(fixture.home, 'SOUL.local.md'), '   \n\n');
+    const out = composeContract('claude', fixture.home);
+    expect(out).not.toContain('# Operator Overlays');
+  });
+
+  it('selects a different RUNTIME.md per harness', () => {
+    expect(composeContract('codex', fixture.home)).toContain('# codex runtime contract');
+    expect(composeContract('pi', fixture.home)).toContain('# pi runtime contract');
+    expect(composeContract('codex', fixture.home)).not.toContain('# pi runtime contract');
+  });
+});

packages/mosaic/src/commands/launch.ts

@@ -291,12 +291,23 @@ function buildPrdBlock(): string {
 
 // ─── Runtime prompt builder ──────────────────────────────────────────────────
 
-function buildRuntimePrompt(runtime: RuntimeName): string {
+/**
+ * Compose the full runtime contract for a harness: the resident-by-value core
+ * (CONSTITUTION + AGENTS + USER + TOOLS + runtime) plus operator overlays
+ * (`*.local.md` deltas), merged in precedence order so the model gets one
+ * pre-merged blob (DESIGN §3.2 / R7). Overlays are injected as deltas by value;
+ * base files keep their existing residency (USER injected; SOUL/STANDARDS are
+ * load-on-demand, so only their small `.local` deltas are injected here).
+ *
+ * `mosaicHome` is parameterized for testability; production callers use the
+ * module-level default.
+ */
+export function composeContract(runtime: RuntimeName, mosaicHome: string = MOSAIC_HOME): string {
   const runtimeContractPaths: Record<RuntimeName, string> = {
-    claude: join(MOSAIC_HOME, 'runtime', 'claude', 'RUNTIME.md'),
+    claude: join(mosaicHome, 'runtime', 'claude', 'RUNTIME.md'),
-    codex: join(MOSAIC_HOME, 'runtime', 'codex', 'RUNTIME.md'),
+    codex: join(mosaicHome, 'runtime', 'codex', 'RUNTIME.md'),
-    opencode: join(MOSAIC_HOME, 'runtime', 'opencode', 'RUNTIME.md'),
+    opencode: join(mosaicHome, 'runtime', 'opencode', 'RUNTIME.md'),
-    pi: join(MOSAIC_HOME, 'runtime', 'pi', 'RUNTIME.md'),
+    pi: join(mosaicHome, 'runtime', 'pi', 'RUNTIME.md'),
   };
 
   const runtimeFile = runtimeContractPaths[runtime];
@@ -331,27 +342,55 @@ For required push/merge/issue-close/release actions, execute without routine con
 `);
 
   // CONSTITUTION.md (L0 — the non-negotiable law; lead with it). Tolerant of
-  // pre-constitution installs that have not been re-seeded yet.
+  // pre-constitution installs that have not been re-seeded yet. Injected by
-  const constitution = readOptional(join(MOSAIC_HOME, 'CONSTITUTION.md'));
+  // value verbatim so the bare-launch fallback read is byte-equal (R8).
+  const constitution = readOptional(join(mosaicHome, 'CONSTITUTION.md'));
   if (constitution) parts.push(constitution);
 
   // AGENTS.md
-  parts.push(readFileSync(join(MOSAIC_HOME, 'AGENTS.md'), 'utf-8'));
+  parts.push(readFileSync(join(mosaicHome, 'AGENTS.md'), 'utf-8'));
 
-  // USER.md
+  // USER.md (+ USER.local.md operator overlay, appended directly under the
-  const user = readOptional(join(MOSAIC_HOME, 'USER.md'));
+  // profile its base owns).
+  const user = readOptional(join(mosaicHome, 'USER.md'));
   if (user) parts.push('\n\n# User Profile\n\n' + user);
+  const userLocal = readOptional(join(mosaicHome, 'USER.local.md'));
+  if (userLocal.trim()) {
+    parts.push('\n\n## Operator Overlay (USER.local.md)\n\n' + userLocal);
+  }
 
   // TOOLS.md
-  const tools = readOptional(join(MOSAIC_HOME, 'TOOLS.md'));
+  const tools = readOptional(join(mosaicHome, 'TOOLS.md'));
   if (tools) parts.push('\n\n# Machine Tools\n\n' + tools);
 
+  // Operator overlays whose base layers are load-on-demand (SOUL, STANDARDS):
+  // inject only the small `.local` delta by value so the customization reaches
+  // the model without re-injecting the full base prose (preserves the byte
+  // budget). Absent `.local` files → base-only, automatically (R7 §3.2).
+  const overlayBlocks: string[] = [];
+  const soulLocal = readOptional(join(mosaicHome, 'SOUL.local.md'));
+  if (soulLocal.trim()) {
+    overlayBlocks.push('## Persona Overlay (SOUL.local.md)\n\n' + soulLocal.trim());
+  }
+  const standardsLocal = readOptional(join(mosaicHome, 'STANDARDS.local.md'));
+  if (standardsLocal.trim()) {
+    overlayBlocks.push('## Standards Overlay (STANDARDS.local.md)\n\n' + standardsLocal.trim());
+  }
+  if (overlayBlocks.length > 0) {
+    parts.push('\n\n# Operator Overlays\n\n' + overlayBlocks.join('\n\n'));
+  }
+
   // Runtime-specific contract
   parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
 
   return parts.join('\n');
 }
 
+/** @deprecated internal alias — use composeContract. Retained for call-site clarity. */
+function buildRuntimePrompt(runtime: RuntimeName): string {
+  return composeContract(runtime);
+}
+
 // ─── Session lock ────────────────────────────────────────────────────────────
 
 function writeSessionLock(runtime: string): void {
@@ -976,6 +1015,22 @@ export function registerLaunchCommands(program: Command): void {
     launchRuntime(runtime, extraArgs, yolo);
   });
 
+  // compose-contract — emit the composed runtime contract (base + operator
+  // overlays) for a harness to stdout, without launching. For inspection,
+  // `mosaic doctor`, diffing, and the composer test (R7).
+  program
+    .command('compose-contract <harness>')
+    .description('Print the composed runtime contract (base + *.local overlays) for a harness')
+    .action((harness: string) => {
+      const valid: RuntimeName[] = ['claude', 'codex', 'opencode', 'pi'];
+      if (!valid.includes(harness as RuntimeName)) {
+        console.error(`Unknown harness '${harness}'. Expected one of: ${valid.join(', ')}.`);
+        process.exitCode = 64;
+        return;
+      }
+      process.stdout.write(composeContract(harness as RuntimeName));
+    });
+
   // Coord (mission orchestrator)
   program
     .command('coord')

packages/mosaic/src/runtime/update-checker.reseed.spec.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  buildReseedCommand,
+  buildRelaunchCommands,
+  readRosterAgentNames,
+  runFrameworkReseed,
+} from './update-checker.js';
+
+/**
+ * F3-m3 / R13: `mosaic update` re-seeds the framework + (opt-in) relaunches
+ * durable agents so shipped launcher/runtime changes activate. These cover the
+ * pure builders + the missing-installer guard (the exec path is integration).
+ */
+
+describe('buildReseedCommand', () => {
+  it('invokes the package install.sh in data-safe sync-only keep mode', () => {
+    const out = buildReseedCommand('/pkg/framework', '/home/u/.config/mosaic');
+    expect(out.installer).toBe('/pkg/framework/install.sh');
+    expect(out.command).toBe('bash /pkg/framework/install.sh');
+    expect(out.env).toEqual({
+      MOSAIC_SYNC_ONLY: '1',
+      MOSAIC_INSTALL_MODE: 'keep',
+      MOSAIC_HOME: '/home/u/.config/mosaic',
+    });
+  });
+});
+
+describe('buildRelaunchCommands', () => {
+  it('builds a systemctl --user restart per agent unit', () => {
+    expect(buildRelaunchCommands(['orchestrator', 'coder0'])).toEqual([
+      ['systemctl', '--user', 'restart', 'mosaic-agent@orchestrator.service'],
+      ['systemctl', '--user', 'restart', 'mosaic-agent@coder0.service'],
+    ]);
+  });
+
+  it('is empty for an empty roster', () => {
+    expect(buildRelaunchCommands([])).toEqual([]);
+  });
+});
+
+describe('readRosterAgentNames', () => {
+  let home: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'mosaic-roster-'));
+  });
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  it('returns [] when no roster exists', () => {
+    expect(readRosterAgentNames(home)).toEqual([]);
+  });
+
+  it('extracts agent names from roster.yaml', () => {
+    mkdirSync(join(home, 'fleet'), { recursive: true });
+    writeFileSync(
+      join(home, 'fleet', 'roster.yaml'),
+      [
+        'version: 1',
+        'agents:',
+        '  - name: orchestrator',
+        '    runtime: pi',
+        '  - name: coder0',
+        '    runtime: claude',
+        '  - name: "reviewer-1"',
+        '    runtime: codex',
+      ].join('\n') + '\n',
+    );
+    expect(readRosterAgentNames(home)).toEqual(['orchestrator', 'coder0', 'reviewer-1']);
+  });
+});
+
+describe('runFrameworkReseed', () => {
+  it('reports not-ok (not throw) when the installer is absent', () => {
+    const missing = mkdtempSync(join(tmpdir(), 'mosaic-noinstaller-'));
+    const res = runFrameworkReseed(missing, join(missing, 'home'));
+    expect(res.ok).toBe(false);
+    expect(res.reason).toContain('installer not found');
+    rmSync(missing, { recursive: true, force: true });
+  });
+});

packages/mosaic/src/runtime/update-checker.ts

@@ -16,7 +16,8 @@
 import { execSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -453,6 +454,98 @@ export function getInstallAllCommand(outdated: PackageUpdateResult[]): string {
   return `npm i -g ${pkgs.join(' ')}`;
 }
 
+// ─── Post-update framework re-seed + agent relaunch (F3-m3 / R13) ─────────────
+//
+// `mosaic update` installs the new npm CLI but, on its own, leaves the framework
+// files in ~/.config/mosaic/ stale — so shipped launcher/runtime changes (e.g.
+// the agent-name export + native heartbeat) never ACTIVATE until a re-seed.
+// These helpers run the package's own install.sh in sync-only mode (the P4
+// data-safe reconcile: framework-owned overwrite + backup-once; SOUL/USER/
+// *.local/credentials preserved) and, opt-in, relaunch durable agents.
+
+/** Resolve the framework/ directory bundled in the installed package. */
+export function resolveBundledFrameworkRoot(): string {
+  // dist/runtime/update-checker.js → ../../framework (package files: dist + framework)
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'framework');
+}
+
+export const FRAMEWORK_RESEED_PACKAGE = PKG;
+
+/**
+ * Build the framework re-seed invocation: the package's install.sh in
+ * sync-only mode (file phase only — no environment-touching post-install),
+ * keep mode (never overwrite user files). Returned as data so it is unit
+ * testable; `runFrameworkReseed` executes it.
+ */
+export function buildReseedCommand(
+  frameworkRoot: string,
+  mosaicHome: string,
+): { installer: string; command: string; env: Record<string, string> } {
+  const installer = join(frameworkRoot, 'install.sh');
+  return {
+    installer,
+    command: `bash ${installer}`,
+    env: {
+      MOSAIC_SYNC_ONLY: '1',
+      MOSAIC_INSTALL_MODE: 'keep',
+      MOSAIC_HOME: mosaicHome,
+    },
+  };
+}
+
+/**
+ * Re-seed the framework from the freshly-installed package. Returns a result
+ * describing what happened (so callers can message + decide on relaunch).
+ * Best-effort: a missing installer or a non-zero exit is reported, not thrown.
+ */
+export function runFrameworkReseed(
+  frameworkRoot = resolveBundledFrameworkRoot(),
+  mosaicHome = join(homedir(), '.config', 'mosaic'),
+): { ok: boolean; reason?: string } {
+  const { installer, command, env } = buildReseedCommand(frameworkRoot, mosaicHome);
+  if (!existsSync(installer)) {
+    return { ok: false, reason: `installer not found: ${installer}` };
+  }
+  try {
+    execSync(command, { stdio: 'inherit', env: { ...process.env, ...env }, timeout: 120_000 });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Best-effort parse of the fleet roster for agent names (used to relaunch
+ * durable agents after a re-seed). Returns [] when no roster exists.
+ */
+export function readRosterAgentNames(mosaicHome = join(homedir(), '.config', 'mosaic')): string[] {
+  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
+  if (!existsSync(rosterPath)) return [];
+  let text: string;
+  try {
+    text = readFileSync(rosterPath, 'utf-8');
+  } catch {
+    return [];
+  }
+  // Roster agents are listed as `- name: <id>` entries under `agents:`.
+  const names: string[] = [];
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\s*-?\s*name:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/);
+    if (m && m[1]) names.push(m[1]);
+  }
+  return names;
+}
+
+/** Build the per-agent systemd relaunch commands (drain+relaunch via restart). */
+export function buildRelaunchCommands(agentNames: string[]): string[][] {
+  return agentNames.map((name) => [
+    'systemctl',
+    '--user',
+    'restart',
+    `mosaic-agent@${name}.service`,
+  ]);
+}
+
 /**
  * Format a table showing all packages with their current/latest versions.
  */