@automagik/genie 4.260503.5 → 4.260503.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automagik/genie",
-  "version": "4.260503.5",
+  "version": "4.260503.6",
   "description": "Collaborative terminal toolkit for human + AI workflows. NOTE: the npm distribution is being soft-deprecated — the canonical install is `curl -fsSL https://get.automagik.dev/genie | bash` (cosign + SLSA verified). See https://automagik.dev/genie/security/distribution-sovereignty",
   "type": "module",
   "bin": {
@@ -12,11 +12,13 @@
     "plugins/genie/",
     "scripts/postinstall-tmux.js",
     "scripts/postinstall-hook-binary.js",
+    "scripts/postinstall-migrations.js",
     "scripts/sec-scan.cjs",
     "scripts/sec-remediate.cjs",
     "scripts/sec-fix.cjs",
     "scripts/tmux/",
     "src/db/migrations/",
+    "src/migrations/",
     "templates/",
     "README.md",
     "LICENSE"

package/plugins/genie/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genie",
-  "version": "4.260503.5",
+  "version": "4.260503.6",
   "description": "Human-AI partnership for Claude Code. Share a terminal, orchestrate workers, evolve together. Brainstorm ideas, turn them into wishes, execute with /work, validate with /review, and ship as one team.",
   "author": {
     "name": "Namastex Labs"

package/plugins/genie/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genie-plugin",
-  "version": "4.260503.5",
+  "version": "4.260503.6",
   "private": true,
   "description": "Runtime dependencies for genie bundled CLIs",
   "type": "module",

package/scripts/postinstall-migrations.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * genie host-migrations postinstall hook.
+ *
+ * Runs `genie migrate --quiet` after `bun add -g @automagik/genie@<latest>`
+ * so users get host-state self-heal transparently.
+ *
+ * Behavior:
+ *   - GENIE_SKIP_MIGRATIONS=1 → exit 0 immediately (CI / containers)
+ *   - No ~/.genie/ directory → fresh install, exit 0 silently
+ *   - genie binary not callable yet → exit 0 (other postinstalls may run first)
+ *   - Otherwise: invoke `genie migrate --quiet` with timeout
+ *   - Soft-fail: any error logs warning, exits 0 (never breaks bun install)
+ *
+ * The escape hatch for forced re-runs is `genie migrate` (manual).
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function main() {
+  if (process.env.GENIE_SKIP_MIGRATIONS === '1') return;
+
+  const genieRoot = path.join(os.homedir(), '.genie');
+  if (!fs.existsSync(genieRoot)) return; // fresh install
+
+  // Try locating the genie binary in this package
+  const candidate = path.join(__dirname, '..', 'dist', 'genie.js');
+  if (!fs.existsSync(candidate)) {
+    process.stderr.write(`[genie-postinstall-migrations] dist not built yet at ${candidate}, skipping\n`);
+    return;
+  }
+
+  const result = spawnSync(process.execPath, [candidate, 'migrate', '--quiet'], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+    timeout: 60_000,
+  });
+
+  if (result.error) {
+    process.stderr.write(`[genie-postinstall-migrations] WARNING: invocation failed: ${result.error.message}\n`);
+    process.stderr.write('[genie-postinstall-migrations] Run `genie migrate` manually to retry.\n');
+    return;
+  }
+  if (result.status !== 0) {
+    process.stderr.write(`[genie-postinstall-migrations] WARNING: \`genie migrate\` exited ${result.status}\n`);
+    process.stderr.write('[genie-postinstall-migrations] Run `genie migrate` manually to investigate.\n');
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  process.stderr.write(`[genie-postinstall-migrations] WARNING: unexpected error: ${err.message}\n`);
+}
+process.exit(0);

package/src/migrations/README.md

@@ -0,0 +1,71 @@
+# genie host-migrations
+
+`genie migrate` applies versioned host-state migrations that fix drift
+between current code expectations and persisted host state (pm2 env
+blocks, embedded pgserve fantasmas, config drifts). Same pattern as DB
+migrations (drizzle, alembic) but for HOST state.
+
+## Lifecycle
+
+```
+bun add -g @automagik/genie
+  └─ postinstall hook → genie migrate --quiet
+                          └─ for each step:
+                              ├─ check(ctx)    — needs apply?
+                              ├─ apply(ctx)    — make it so
+                              ├─ validate(ctx) — confirm it stuck
+                              └─ record APPLIED in ~/.genie/migrations.json
+```
+
+## Subcommands
+
+| Command | Behavior |
+|---------|----------|
+| `genie migrate` | Apply all pending in alphabetical order |
+| `genie migrate --dry-run` | List pending without executing |
+| `genie migrate --quiet` | Suppress per-step OK lines (used by postinstall) |
+| `genie migrate --status` | Show applied / pending / failed table |
+
+## Tracking store
+
+`~/.genie/migrations.json` — atomic-write JSON. Override path via `GENIE_MIGRATIONS_STORE`.
+
+## Writing a new migration
+
+1. Pick the next 3-digit ID — alphabetical = apply order
+2. Create file `src/migrations/steps/<NNN>-<kebab-case-name>.ts`
+3. Export the contract:
+
+```typescript
+import type { MigrationContext } from '../discover.js';
+export const id = 'NNN-kebab-case-name';
+export const description = 'One-line operator-facing description';
+export async function check(ctx: MigrationContext): Promise<boolean> { /* return true if needs apply */ }
+export async function apply(ctx: MigrationContext): Promise<void> { /* write side */ }
+export async function validate(ctx: MigrationContext): Promise<void> { /* throw on fail */ }
+```
+
+## Idempotency requirement
+
+Every migration MUST be idempotent at the apply level. Prefer "set X to Y" over "increment X by 1". Re-runs after partial failure must never corrupt state.
+
+## Failure semantics
+
+- A migration that throws is recorded as `FAILED` with error message
+- Subsequent `genie migrate` runs RETRY the failed migration
+- `genie migrate --status` surfaces FAILED rows
+- Postinstall hook soft-fails (warn + exit 0) — `bun install` never breaks
+
+## Override / escape hatch
+
+| Env var | Effect |
+|---------|--------|
+| `GENIE_SKIP_MIGRATIONS=1` | Postinstall exits 0 without invoking migrate |
+| `GENIE_MIGRATIONS_STORE` | Override `~/.genie/migrations.json` path |
+| `GENIE_KEEP_LEGACY_PG=1` | Migration 002 will not stop the legacy embedded |
+
+## See also
+
+- Wish: `.genie/wishes/genie-host-migrations/WISH.md`
+- Sibling: `pgserve/autopg-upgrade-command` (same self-heal pattern, pgserve subsystem)
+- Drizzle DB migrations (separate concern): `src/db/migrations/`

package/src/migrations/__tests__/orchestrator.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Smoke tests for the migrations orchestrator.
+ *
+ * Validates: dry-run lists discoverable steps, status read works, store
+ * read/write atomic, no-op on already-applied. Does NOT exercise actual
+ * migration apply paths (that would touch pm2/processes — left for
+ * integration tests).
+ */
+
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+let tmpStore: string;
+const ORIGINAL_STORE = process.env.GENIE_MIGRATIONS_STORE;
+
+beforeEach(() => {
+  const dir = mkdtempSync(join(tmpdir(), 'genie-mig-test-'));
+  tmpStore = join(dir, 'migrations.json');
+  process.env.GENIE_MIGRATIONS_STORE = tmpStore;
+});
+
+afterEach(() => {
+  if (existsSync(tmpStore)) rmSync(tmpStore, { force: true });
+  if (ORIGINAL_STORE) process.env.GENIE_MIGRATIONS_STORE = ORIGINAL_STORE;
+  else process.env.GENIE_MIGRATIONS_STORE = undefined;
+});
+
+test('store: load empty when file missing', async () => {
+  const { loadStore } = await import('../store.js');
+  const s = loadStore();
+  expect(s.applied).toEqual([]);
+});
+
+test('store: recordApplied + load round-trip', async () => {
+  const { recordApplied, loadStore } = await import('../store.js');
+  recordApplied('999-test', '4.0.0', 'test detail');
+  const s = loadStore();
+  expect(s.applied.length).toBe(1);
+  expect(s.applied[0].id).toBe('999-test');
+  expect(s.applied[0].status).toBe('APPLIED');
+  expect(s.applied[0].appliedFrom).toBe('4.0.0');
+});
+
+test('store: recordFailed then recordApplied replaces FAILED', async () => {
+  const { recordFailed, recordApplied, loadStore } = await import('../store.js');
+  recordFailed('999-test', '4.0.0', 'first attempt err');
+  expect(loadStore().applied[0].status).toBe('FAILED');
+  recordApplied('999-test', '4.0.1', 'second attempt ok');
+  const s = loadStore();
+  expect(s.applied.length).toBe(1);
+  expect(s.applied[0].status).toBe('APPLIED');
+});
+
+test('store: atomic write prevents partial JSON', async () => {
+  const { recordApplied } = await import('../store.js');
+  recordApplied('999-atomic', '4.0.0');
+  const raw = readFileSync(tmpStore, 'utf8');
+  // file should be valid JSON in one piece
+  expect(() => JSON.parse(raw)).not.toThrow();
+});
+
+test('discover: returns sorted by id (lexical)', async () => {
+  const { discoverMigrations } = await import('../discover.js');
+  const list = discoverMigrations();
+  // current shipped: 001-* and 002-*
+  expect(list.length).toBeGreaterThanOrEqual(2);
+  for (let i = 1; i < list.length; i++) {
+    expect(list[i].id > list[i - 1].id).toBe(true);
+  }
+});
+
+test('orchestrator: dry-run does not write store for synthetic check=true mig', async () => {
+  // We can't easily inject a synthetic migration without filesystem ceremony;
+  // instead verify dry-run on the real shipped migrations doesn't record APPLIED.
+  const { migrate } = await import('../index.js');
+  const _before = existsSync(tmpStore);
+  const r = await migrate({ dryRun: true, quiet: true });
+  expect(r.results.length).toBeGreaterThanOrEqual(2);
+  // Each result should be DRY-RUN, NO-OP, or SKIP — never APPLIED on dry-run
+  for (const x of r.results) {
+    expect(['DRY-RUN', 'NO-OP', 'SKIP', 'FAIL'].includes(x.status)).toBe(true);
+  }
+  // If file exists, it should not contain entries from this dry-run
+  if (existsSync(tmpStore)) {
+    const s = JSON.parse(readFileSync(tmpStore, 'utf8'));
+    // dry-run never records APPLIED (NO-OP could record though, that's allowed for short-circuit)
+    expect(s.applied.every((r: any) => r.status !== 'APPLIED' || r.detail === 'no-op (check returned false)')).toBe(
+      true,
+    );
+  }
+});

package/src/migrations/discover.ts

@@ -0,0 +1,57 @@
+/**
+ * Discover migrations: scan src/migrations/steps/ for files matching
+ * `^\d{3}-.+\.(ts|js)$`. Filename = id (sans extension). Alphabetical
+ * sort = strict apply order.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const FILE_PATTERN = /^(\d{3}-[a-z0-9-]+)\.(ts|js)$/;
+
+export interface MigrationModule {
+  id: string;
+  description: string;
+  check: (ctx: MigrationContext) => Promise<boolean>;
+  apply: (ctx: MigrationContext) => Promise<void>;
+  validate: (ctx: MigrationContext) => Promise<void>;
+}
+
+export interface MigrationContext {
+  log: (msg: string) => void;
+  warn: (msg: string) => void;
+  dryRun: boolean;
+}
+
+export interface DiscoveredMigration {
+  id: string;
+  filePath: string;
+}
+
+export function discoverMigrations(): DiscoveredMigration[] {
+  const stepsDir = join(__dirname, 'steps');
+  if (!existsSync(stepsDir)) return [];
+  const files = readdirSync(stepsDir);
+  const matched: DiscoveredMigration[] = [];
+  for (const file of files) {
+    const m = file.match(FILE_PATTERN);
+    if (!m) continue;
+    matched.push({ id: m[1], filePath: join(stepsDir, file) });
+  }
+  matched.sort((a, b) => a.id.localeCompare(b.id));
+  return matched;
+}
+
+export async function loadMigrationModule(filePath: string): Promise<MigrationModule> {
+  const mod = await import(filePath);
+  if (typeof mod.id !== 'string' || typeof mod.description !== 'string') {
+    throw new Error(`migration ${filePath}: missing id/description exports`);
+  }
+  if (typeof mod.check !== 'function' || typeof mod.apply !== 'function' || typeof mod.validate !== 'function') {
+    throw new Error(`migration ${filePath}: missing check/apply/validate exports`);
+  }
+  return mod as MigrationModule;
+}

package/src/migrations/index.ts

@@ -0,0 +1,119 @@
+/**
+ * Genie host migrations — versioned, applied-once-per-host.
+ *
+ * Discover migrations in steps/ → filter pending vs already-applied →
+ * run check → apply → validate per step, record to store. Same pattern
+ * as DB migrations (drizzle, alembic) but for HOST state (pm2 env,
+ * embedded pgserve, config drifts).
+ *
+ * Auto-runs on `bun add -g @automagik/genie@latest` via postinstall hook
+ * (scripts/postinstall-migrations.js). Manual `genie migrate` is the
+ * explicit escape hatch.
+ *
+ * See: .genie/wishes/genie-host-migrations/WISH.md
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { type MigrationContext, type MigrationModule, discoverMigrations, loadMigrationModule } from './discover.js';
+import { type StepResult, runMigration } from './runner.js';
+import { type MigrationRecord, getApplied } from './store.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export interface MigrateOptions {
+  quiet?: boolean;
+  dryRun?: boolean;
+}
+
+export interface MigrateResult {
+  ok: boolean;
+  results: StepResult[];
+  summary: string;
+}
+
+function getGenieVersion(): string {
+  try {
+    // genie cli installed structure: <root>/dist/genie.js + <root>/package.json
+    const pkgPath = join(__dirname, '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+export async function migrate(options: MigrateOptions = {}): Promise<MigrateResult> {
+  const { quiet = false, dryRun = false } = options;
+  const log = (msg: string) => {
+    if (!quiet) process.stderr.write(`${msg}\n`);
+  };
+  const warn = (msg: string) => process.stderr.write(`${msg}\n`);
+  const ctx: MigrationContext = { log, warn, dryRun };
+
+  const version = getGenieVersion();
+  log(`genie host-migrations starting (version=${version}, dryRun=${dryRun})`);
+
+  const discovered = discoverMigrations();
+  if (discovered.length === 0) {
+    return { ok: true, results: [], summary: 'no migrations discovered' };
+  }
+
+  const results: StepResult[] = [];
+  for (const item of discovered) {
+    let mod: MigrationModule;
+    try {
+      mod = await loadMigrationModule(item.filePath);
+    } catch (err) {
+      const msg = (err as Error).message;
+      warn(`[${item.id}] FAIL during load: ${msg}`);
+      results.push({ id: item.id, status: 'FAIL', detail: `load threw: ${msg}` });
+      continue;
+    }
+    const r = await runMigration(mod, ctx, version);
+    results.push(r);
+  }
+
+  const failed = results.filter((r) => r.status === 'FAIL');
+  const summary = `genie host-migrations complete: ${results.length - failed.length}/${results.length} OK`;
+  log(summary);
+  if (failed.length > 0) {
+    warn(`Failed migrations: ${failed.map((r) => r.id).join(', ')}`);
+    warn('Re-run `genie migrate` after addressing the above.');
+    return { ok: false, results, summary };
+  }
+  return { ok: true, results, summary };
+}
+
+export interface StatusEntry {
+  id: string;
+  status: 'APPLIED' | 'PENDING' | 'FAILED';
+  appliedAt?: string;
+  appliedFrom?: string;
+  detail?: string;
+}
+
+export function status(): StatusEntry[] {
+  const discovered = discoverMigrations();
+  const applied = getApplied();
+  const out: StatusEntry[] = [];
+  for (const item of discovered) {
+    const rec: MigrationRecord | undefined = applied.get(item.id);
+    if (!rec) {
+      out.push({ id: item.id, status: 'PENDING' });
+    } else {
+      out.push({
+        id: item.id,
+        status: rec.status === 'APPLIED' ? 'APPLIED' : 'FAILED',
+        appliedAt: rec.appliedAt,
+        appliedFrom: rec.appliedFrom,
+        detail: rec.detail,
+      });
+    }
+  }
+  return out;
+}
+
+export { discoverMigrations, loadMigrationModule } from './discover.js';

package/src/migrations/runner.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-step runner — enforces the check → apply → validate contract,
+ * records outcome to the store, returns structured result.
+ */
+
+import type { MigrationContext, MigrationModule } from './discover.js';
+import { getApplied, recordApplied, recordFailed } from './store.js';
+
+export type StepStatus = 'APPLIED' | 'SKIP' | 'NO-OP' | 'FAIL' | 'DRY-RUN';
+
+export interface StepResult {
+  id: string;
+  status: StepStatus;
+  detail: string;
+}
+
+export async function runMigration(mod: MigrationModule, ctx: MigrationContext, version: string): Promise<StepResult> {
+  const applied = getApplied();
+  const prior = applied.get(mod.id);
+  if (prior?.status === 'APPLIED') {
+    ctx.log(`[${mod.id}] SKIP: already applied at ${prior.appliedAt}`);
+    return { id: mod.id, status: 'SKIP', detail: `already applied at ${prior.appliedAt}` };
+  }
+
+  let needsApply: boolean;
+  try {
+    needsApply = await mod.check(ctx);
+  } catch (err) {
+    const msg = (err as Error).message;
+    ctx.warn(`[${mod.id}] FAIL during check: ${msg}`);
+    recordFailed(mod.id, version, `check threw: ${msg}`);
+    return { id: mod.id, status: 'FAIL', detail: `check threw: ${msg}` };
+  }
+
+  if (!needsApply) {
+    ctx.log(`[${mod.id}] NO-OP: check returned false (host already in target state)`);
+    recordApplied(mod.id, version, 'no-op (check returned false)');
+    return { id: mod.id, status: 'NO-OP', detail: 'check returned false' };
+  }
+
+  if (ctx.dryRun) {
+    ctx.log(`[${mod.id}] DRY-RUN: would apply — ${mod.description}`);
+    return { id: mod.id, status: 'DRY-RUN', detail: mod.description };
+  }
+
+  try {
+    await mod.apply(ctx);
+  } catch (err) {
+    const msg = (err as Error).message;
+    ctx.warn(`[${mod.id}] FAIL during apply: ${msg}`);
+    recordFailed(mod.id, version, `apply threw: ${msg}`);
+    return { id: mod.id, status: 'FAIL', detail: `apply threw: ${msg}` };
+  }
+
+  try {
+    await mod.validate(ctx);
+  } catch (err) {
+    const msg = (err as Error).message;
+    ctx.warn(`[${mod.id}] FAIL during validate: ${msg}`);
+    recordFailed(mod.id, version, `validate threw: ${msg}`);
+    return { id: mod.id, status: 'FAIL', detail: `validate threw: ${msg}` };
+  }
+
+  recordApplied(mod.id, version, mod.description);
+  ctx.log(`[${mod.id}] APPLIED: ${mod.description}`);
+  return { id: mod.id, status: 'APPLIED', detail: mod.description };
+}

package/src/migrations/steps/001-pm2-env-databaseurl-bake.ts

@@ -0,0 +1,91 @@
+/**
+ * Migration 001 — bake DATABASE_URL into pm2 genie-serve env block.
+ *
+ * Closes the upgrade-path hole left by commit 5567e202 (`fix(install):
+ * bake DATABASE_URL env into ecosystem config when canonical pgserve is
+ * detected`). That fix only kicks in on fresh `genie install`. Hosts
+ * installed before the fix have a pm2 process `genie-serve` with no
+ * env block and silently spawn their own embedded pgserve instead of
+ * connecting to the canonical one.
+ *
+ * Detection: pm2 process `genie-serve` exists AND its env lacks
+ * `DATABASE_URL` AND canonical pgserve is registered (port 8432
+ * reachable).
+ *
+ * Fix: set DATABASE_URL via `pm2 set genie-serve:DATABASE_URL <url>` then
+ * `pm2 restart genie-serve --update-env`. Genie-serve at next boot
+ * connects to canonical and stops spawning the legacy embedded.
+ */
+
+import { execSync } from 'node:child_process';
+
+import type { MigrationContext } from '../discover.js';
+
+export const id = '001-pm2-env-databaseurl-bake';
+export const description = 'Bake DATABASE_URL into pm2 genie-serve env when canonical pgserve registered';
+
+const CANONICAL_PORT = 8432;
+
+interface Pm2Process {
+  pm_id: number;
+  name: string;
+  pm2_env?: { env?: Record<string, string> };
+}
+
+function pm2ListJson(): Pm2Process[] {
+  try {
+    const out = execSync('pm2 jlist', { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+    return JSON.parse(out) as Pm2Process[];
+  } catch {
+    return [];
+  }
+}
+
+function findGenieServe(): Pm2Process | undefined {
+  return pm2ListJson().find((p) => p.name === 'genie-serve');
+}
+
+function canonicalPgserveReachable(): boolean {
+  try {
+    execSync(`pg_isready -h 127.0.0.1 -p ${CANONICAL_PORT}`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildCanonicalUrl(): string {
+  // Mirrors the URL shape baked by `genie install` post-5567e202:
+  // postgresql://postgres:postgres@127.0.0.1:<port>/<db>
+  // The DB name is per-app fingerprint; genie defaults to 'postgres' when
+  // the host hasn't run autopg create-app — install sets the real name.
+  // For the migration we use the pgserve discovery URL.
+  return `postgresql://postgres:postgres@127.0.0.1:${CANONICAL_PORT}/postgres`;
+}
+
+export async function check(_ctx: MigrationContext): Promise<boolean> {
+  const proc = findGenieServe();
+  if (!proc) return false; // no genie-serve under pm2 → nothing to fix
+  const envHas = proc.pm2_env?.env?.DATABASE_URL;
+  if (envHas) return false; // already baked
+  if (!canonicalPgserveReachable()) return false; // canonical not up → can't safely set URL
+  return true;
+}
+
+export async function apply(ctx: MigrationContext): Promise<void> {
+  const url = buildCanonicalUrl();
+  ctx.log(`setting pm2 env genie-serve:DATABASE_URL = ${url}`);
+  execSync(`pm2 set genie-serve:DATABASE_URL ${JSON.stringify(url)}`, { stdio: 'pipe' });
+  ctx.log('restarting genie-serve --update-env');
+  execSync('pm2 restart genie-serve --update-env', { stdio: 'pipe' });
+}
+
+export async function validate(_ctx: MigrationContext): Promise<void> {
+  const proc = findGenieServe();
+  if (!proc) throw new Error('genie-serve missing from pm2 after restart');
+  const url = proc.pm2_env?.env?.DATABASE_URL;
+  if (!url) throw new Error('DATABASE_URL still not baked into pm2 env after apply');
+  if (!url.includes(`:${CANONICAL_PORT}/`)) {
+    throw new Error(`DATABASE_URL points to non-canonical port: ${url}`);
+  }
+}

package/src/migrations/steps/002-kill-embedded-pgserve-legacy.ts

@@ -0,0 +1,114 @@
+/**
+ * Migration 002 — kill legacy embedded pgserve listening on a non-canonical port.
+ *
+ * Detection: a postgres process owned by the current user is listening on
+ * a port other than canonical 8432, AND canonical pgserve responds on
+ * 8432, AND no obvious user-intent override (env var GENIE_KEEP_LEGACY_PG=1).
+ *
+ * Fix: send graceful pg_ctl stop to the legacy process; if that fails,
+ * SIGTERM. Migration 001 (must run first) ensures genie-serve no longer
+ * spawns it, so it stays dead.
+ */
+
+import { execSync } from 'node:child_process';
+
+import type { MigrationContext } from '../discover.js';
+
+export const id = '002-kill-embedded-pgserve-legacy';
+export const description = 'Stop legacy embedded pgserve on non-canonical ports when canonical is healthy';
+
+const CANONICAL_PORT = 8432;
+
+interface ListeningPg {
+  pid: number;
+  port: number;
+}
+
+function listListeningPgserve(): ListeningPg[] {
+  try {
+    const out = execSync('ss -tlnp', { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+    const out_lines = out.split('\n');
+    const found: ListeningPg[] = [];
+    const seen = new Set<number>();
+    for (const line of out_lines) {
+      // Match "127.0.0.1:<port>" with users:(("postgres",pid=<n>,...))
+      const portMatch = line.match(/127\.0\.0\.1:(\d+)\s/);
+      const procMatch = line.match(/users:\(\("postgres",pid=(\d+)/);
+      if (portMatch && procMatch) {
+        const pid = Number.parseInt(procMatch[1], 10);
+        const port = Number.parseInt(portMatch[1], 10);
+        if (!seen.has(pid)) {
+          seen.add(pid);
+          found.push({ pid, port });
+        }
+      }
+    }
+    return found;
+  } catch {
+    return [];
+  }
+}
+
+function canonicalReachable(): boolean {
+  try {
+    execSync(`pg_isready -h 127.0.0.1 -p ${CANONICAL_PORT}`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findLegacyEmbedded(): ListeningPg | undefined {
+  if (process.env.GENIE_KEEP_LEGACY_PG === '1') return undefined;
+  if (!canonicalReachable()) return undefined;
+  return listListeningPgserve().find((p) => p.port !== CANONICAL_PORT);
+}
+
+export async function check(_ctx: MigrationContext): Promise<boolean> {
+  return findLegacyEmbedded() !== undefined;
+}
+
+export async function apply(ctx: MigrationContext): Promise<void> {
+  const target = findLegacyEmbedded();
+  if (!target) {
+    ctx.log('no legacy embedded found at apply time (race resolved)');
+    return;
+  }
+  ctx.log(`stopping legacy embedded pgserve PID ${target.pid} (port ${target.port})`);
+  // Try pg_ctl stop via discovered data dir from the process
+  try {
+    // Process cmdline to find -D <dataDir>
+    const cmdline = execSync(`cat /proc/${target.pid}/cmdline | tr '\\0' ' '`, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+    const dataMatch = cmdline.match(/-D\s+(\S+)/);
+    if (dataMatch) {
+      execSync(`pg_ctl -D ${dataMatch[1]} -m fast stop`, { stdio: 'pipe' });
+      ctx.log(`pg_ctl stop OK (data dir: ${dataMatch[1]})`);
+      return;
+    }
+  } catch (err) {
+    ctx.warn(`pg_ctl stop failed: ${(err as Error).message} — falling back to SIGTERM`);
+  }
+  // Fallback: SIGTERM the master process
+  try {
+    process.kill(target.pid, 'SIGTERM');
+    ctx.log(`SIGTERM sent to PID ${target.pid}`);
+  } catch (err) {
+    throw new Error(`could not stop legacy embedded PID ${target.pid}: ${(err as Error).message}`);
+  }
+}
+
+export async function validate(_ctx: MigrationContext): Promise<void> {
+  // Allow up to 5s for shutdown
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    if (findLegacyEmbedded() === undefined) return;
+    // small sleep
+    Bun.sleepSync(200);
+  }
+  const remaining = findLegacyEmbedded();
+  if (remaining) {
+    throw new Error(`legacy embedded still listening on port ${remaining.port} (PID ${remaining.pid}) after 5s`);
+  }
+}

package/src/migrations/store.ts

@@ -0,0 +1,87 @@
+/**
+ * Migration tracking store — atomic read/write of ~/.genie/migrations.json.
+ *
+ * Records which migrations have been applied to this host, when, and from
+ * which genie cli version. Used by the orchestrator to filter pending vs
+ * already-applied. File-based (not PG) because migrations may need to RUN
+ * before genie-serve / canonical pgserve are healthy.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+
+export type MigrationStatus = 'APPLIED' | 'FAILED';
+
+export interface MigrationRecord {
+  id: string;
+  status: MigrationStatus;
+  appliedAt: string; // ISO timestamp
+  appliedFrom: string; // genie cli version at apply time
+  detail?: string; // FAILED reason or APPLIED note
+}
+
+interface StoreFile {
+  applied: MigrationRecord[];
+}
+
+export function getStorePath(): string {
+  return process.env.GENIE_MIGRATIONS_STORE || `${homedir()}/.genie/migrations.json`;
+}
+
+export function loadStore(): StoreFile {
+  const p = getStorePath();
+  if (!existsSync(p)) return { applied: [] };
+  try {
+    const raw = readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.applied)) return { applied: [] };
+    return parsed as StoreFile;
+  } catch {
+    return { applied: [] };
+  }
+}
+
+/**
+ * Atomic write: tmp file + rename so a crash mid-write never leaves
+ * partial JSON on disk.
+ */
+export function saveStore(store: StoreFile): void {
+  const p = getStorePath();
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o644 });
+  renameSync(tmp, p);
+}
+
+export function recordApplied(id: string, version: string, detail?: string): void {
+  const store = loadStore();
+  // Strip any prior FAILED record for this id; record APPLIED authoritatively.
+  store.applied = store.applied.filter((r) => r.id !== id);
+  store.applied.push({
+    id,
+    status: 'APPLIED',
+    appliedAt: new Date().toISOString(),
+    appliedFrom: version,
+    detail,
+  });
+  saveStore(store);
+}
+
+export function recordFailed(id: string, version: string, reason: string): void {
+  const store = loadStore();
+  store.applied = store.applied.filter((r) => r.id !== id);
+  store.applied.push({
+    id,
+    status: 'FAILED',
+    appliedAt: new Date().toISOString(),
+    appliedFrom: version,
+    detail: reason,
+  });
+  saveStore(store);
+}
+
+export function getApplied(): Map<string, MigrationRecord> {
+  const store = loadStore();
+  return new Map(store.applied.map((r) => [r.id, r]));
+}