@dashclaw/cli 0.6.1 → 0.7.0

package/README.md

@@ -56,6 +56,8 @@ npx dashclaw up --source-dir <path> # use a local repo checkout instead of the p
 
 Re-running `npx dashclaw up` on an existing install boots the server without re-provisioning. Failures checkpoint and resume from where they stopped.
 
+Postgres prefers host port 5433; when something else already holds it, provisioning scans forward to the first free port and says so (an existing `dashclaw-pg` container keeps whatever port it was created with — data lives in the `dashclaw_pgdata` volume and survives container recreation).
+
 ### `dashclaw down`
 
 Stop the local server (and the Docker DB if `up` started it).
@@ -64,6 +66,15 @@ Stop the local server (and the Docker DB if `up` started it).
 npx dashclaw down
 ```
 
+### `dashclaw import <bundle.json>`
+
+Load a workspace carry-out bundle — the file **Export workspace** downloads on a trial's `/connect` card (or `GET /api/workspace/export` on any instance) — into the configured instance. Policies, guard decisions, action records, open loops, assumptions, and agent identities carry over; API keys, OAuth tokens, and secret values never ride a bundle. Idempotent: re-running skips rows that already exist.
+
+```bash
+DASHCLAW_BASE_URL=http://localhost:3000 DASHCLAW_API_KEY=oc_live_... \
+  dashclaw import dashclaw-workspace-*.json
+```
+
 ### `dashclaw approvals`
 
 Interactive inbox for all pending approval requests. Use arrow keys to navigate, `A` to approve, `D` to deny, `O` to open the replay link, `Q` to quit.
@@ -84,6 +95,18 @@ Deny a single action by ID.
 dashclaw deny act_01h... --reason "Outside change window"
 ```
 
+### `dashclaw halt`
+
+The org kill switch, from the terminal. Requires an admin API key.
+
+```bash
+dashclaw halt on --reason "runaway deploy loop"   # every guard evaluation for the org returns block
+dashclaw halt status                              # who halted, why, since when
+dashclaw halt off                                 # resume normal guard evaluation
+```
+
+The halt is absolute at the decision layer (propagates across instances in ~3 s); whether a blocked action is mechanically stopped depends on the surface — see `docs/architecture/enforcement-boundary.md` in the repo.
+
 ### `dashclaw install claude`
 
 Provision DashClaw governance into Claude Code without cloning the repo.

package/bin/dashclaw.js

@@ -86,6 +86,8 @@ ${bold('Usage:')}
     --port <n>                           Server port (default: 3000)
     --no-browser                         Do not open the browser when ready
   dashclaw down                          Stop the local DashClaw server (and Docker DB if we started it)
+  dashclaw import <bundle.json>          Import a workspace carry-out bundle (from /api/workspace/export)
+                                         into this instance — idempotent; keys/secrets never ride a bundle
   dashclaw approvals                     Interactive approval inbox
   dashclaw approve <actionId> [--reason]  Approve an action
   dashclaw deny <actionId> [--reason]     Deny an action
@@ -565,6 +567,38 @@ async function cmdInstall() {
   }
 }
 
+// -- import (v7.2 graduation path) --------------------------------------------
+
+/*
+ * Ingest a workspace carry-out bundle (the file /api/workspace/export
+ * downloads) into the configured instance. HTTP like every other post-up
+ * command; the route is idempotent so re-running is safe.
+ */
+async function cmdImport() {
+  const file = args[1];
+  if (!file || file.startsWith('--')) {
+    console.error('Usage: dashclaw import <bundle.json>   (the file downloaded from your trial\'s "Export workspace")');
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    let bundle;
+    try {
+      bundle = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (err) {
+      throw new Error(err.code === 'ENOENT' ? `File not found: ${file}` : `${file} is not valid JSON`);
+    }
+    const data = await apiRequest({ baseUrl, apiKey }, 'POST', '/api/workspace/import', { body: bundle });
+    console.log(green(`Imported ${data.imported} rows (${data.skipped} skipped — already present or missing their id).`));
+    for (const [table, c] of Object.entries(data.counts || {})) {
+      console.log(`  ${table}: +${c.imported}${c.skipped ? ` (${c.skipped} skipped)` : ''}`);
+    }
+  } catch (err) {
+    console.error(red(`Error: ${err.message}`));
+    process.exitCode = 1;
+  }
+}
+
 // -- up / down (one-command local install) -----------------------------------
 
 async function cmdUp() {
@@ -1298,7 +1332,7 @@ async function cmdEnv() {
 
 // -- Router -------------------------------------------------------------------
 
-const COMMANDS_NEEDING_CONFIG = new Set(['approvals', 'approve', 'deny', 'doctor', 'code', 'prompts', 'inbox', 'behavior', 'posture', 'next', 'env', 'halt']);
+const COMMANDS_NEEDING_CONFIG = new Set(['approvals', 'approve', 'deny', 'doctor', 'code', 'prompts', 'inbox', 'behavior', 'posture', 'next', 'env', 'halt', 'import']);
 // `install` deliberately omitted: provisioning hooks and AGENTS.md shouldn't
 // require the user to have already configured API keys. If config happens to
 // be present, install will pick up baseUrl for the AGENTS.md instance link.
@@ -1344,6 +1378,7 @@ const COMMAND_HANDLERS = {
   code: cmdCode,
   up: cmdUp,
   down: cmdDown,
+  import: cmdImport,
   install: cmdInstall,
   codex: cmdCodex,
   prompts: cmdPrompts,

package/lib/up/db.js

@@ -1,163 +1,318 @@
-// cli/lib/up/db.js
-//
-// Database mode selection and provisioning for `dashclaw up`.
-//
-// Three modes:
-//   docker   — starts/reuses a `dashclaw-pg` Docker container (port 5433)
-//   embedded — downloads and runs embedded Postgres via embedded-postgres (~40 MB, first run)
-//   url      — prompts for a postgresql:// connection string from the user
-
-import { join } from 'node:path';
-import { existsSync, rmSync } from 'node:fs';
-import { execFileSync, spawnSync } from 'node:child_process';
-
-// Keep this in sync with the "embedded-postgres" version in cli/package.json.
-const EMBEDDED_PG_VERSION = 'embedded-postgres@18.4.0-beta.17';
-
-export const LOCAL_DB_URL = 'postgresql://dashclaw:dashclaw@localhost:5433/dashclaw';
-
-const CONTAINER = 'dashclaw-pg';
-
-/** Returns true when the `docker` binary is available and responsive. */
-export function dockerAvailableSync() {
-  return spawnSync('docker', ['--version'], { stdio: 'ignore' }).status === 0;
-}
-
-/**
- * Determines which database mode to use.
- *
- * Priority:
- *   1. Explicit --db flag
- *   2. Non-interactive (--yes): docker if available, otherwise embedded
- *   3. Interactive prompt
- *
- * @param {object} opts
- * @param {string|null} opts.flagDb   - explicit --db value or null
- * @param {boolean}     opts.dockerAvailable
- * @param {boolean}     [opts.yes]    - non-interactive mode
- * @param {Function}    [opts.promptFn] - async (message) => string
- * @returns {Promise<'docker'|'embedded'|'url'>}
- */
-export async function chooseDbMode({ flagDb, dockerAvailable, yes = false, promptFn }) {
-  if (flagDb) return flagDb;
-  if (yes) return dockerAvailable ? 'docker' : 'embedded';
-
-  const lines = [
-    'Database — pick one:',
-    dockerAvailable
-      ? '  1. Docker Postgres (Docker detected)   [default]'
-      : '  1. Docker Postgres (Docker NOT detected)',
-    `  2. Embedded Postgres (no Docker needed, ~40 MB download)${dockerAvailable ? '' : '   [default]'}`,
-    '  3. I have a postgresql:// URL',
-  ];
-  const def = dockerAvailable ? '1' : '2';
-  const answer = (await promptFn(`${lines.join('\n')}\nChoice [${def}]: `)).trim() || def;
-  return { 1: 'docker', 2: 'embedded', 3: 'url' }[answer] ?? (dockerAvailable ? 'docker' : 'embedded');
-}
-
-/**
- * Returns the docker run command that starts a local Postgres container.
- * Mirrors the repo's docker-compose.yml: postgres:16-alpine, host port 5433,
- * dashclaw/dashclaw/dashclaw credentials, named volume dashclaw_pgdata.
- */
-export function dockerCommandFor() {
-  return {
-    cmd: 'docker',
-    args: [
-      'run', '-d', '--name', CONTAINER,
-      '-e', 'POSTGRES_USER=dashclaw',
-      '-e', 'POSTGRES_PASSWORD=dashclaw',
-      '-e', 'POSTGRES_DB=dashclaw',
-      '-p', '5433:5432',
-      '-v', 'dashclaw_pgdata:/var/lib/postgresql/data',
-      'postgres:16-alpine',
-    ],
-  };
-}
-
-/** Starts the dashclaw-pg container, reusing it if it already exists. */
-function dockerStartOrRun(logger) {
-  const ps = spawnSync(
-    'docker', ['ps', '-aq', '--filter', `name=^${CONTAINER}$`],
-    { encoding: 'utf8' },
-  );
-  if ((ps.stdout || '').trim()) {
-    execFileSync('docker', ['start', CONTAINER], { stdio: 'ignore' });
-  } else {
-    const { cmd, args } = dockerCommandFor();
-    execFileSync(cmd, args, { stdio: 'ignore' });
-  }
-  logger.error('[ok] Docker Postgres running (container dashclaw-pg, port 5433)');
-}
-
-/**
- * Provisions the database according to `mode` and returns { databaseUrl, stop }.
- *
- * @param {object}   opts
- * @param {'docker'|'embedded'|'url'} opts.mode
- * @param {string}   opts.baseDir   - base dir for embedded data (e.g. ~/.dashclaw)
- * @param {Function} [opts.promptFn] - async (message) => string (required for mode=url)
- * @param {object}   [opts.logger]  - object with .error(); defaults to console
- * @returns {Promise<{ databaseUrl: string, stop: () => Promise<void> }>}
- */
-export async function provisionDatabase({ mode, baseDir, promptFn, logger = console }) {
-  if (mode === 'url') {
-    const url = (await promptFn('postgresql:// connection string: ')).trim();
-    if (!url.startsWith('postgresql://')) throw new Error('That is not a postgresql:// URL.');
-    return { databaseUrl: url, stop: async () => {} };
-  }
-
-  if (mode === 'docker') {
-    dockerStartOrRun(logger);
-    await waitForPort(5433, 30_000);
-    return { databaseUrl: LOCAL_DB_URL, stop: async () => {} };
-  }
-
-  // mode === 'embedded'
-  const { default: EmbeddedPostgres } = await import('embedded-postgres');
-  const pgDir = join(baseDir, 'pg');
-  // Record whether the data dir existed BEFORE this run.
-  // Only clean up on failure when WE created it (a pre-existing dir means
-  // a working prior install whose data we must not delete).
-  const dirPreExisted = existsSync(pgDir);
-  // Derive credentials from LOCAL_DB_URL so the local dev creds live in
-  // exactly one place rather than being duplicated as bare literals here.
-  const localDb = new URL(LOCAL_DB_URL);
-  const pg = new EmbeddedPostgres({
-    databaseDir: pgDir,
-    user: localDb.username,
-    password: localDb.password,
-    port: Number(localDb.port),
-    persistent: true,
-  });
-  try {
-    await pg.initialise();
-    await pg.start();
-  } catch (e) {
-    if (!dirPreExisted) {
-      rmSync(pgDir, { recursive: true, force: true });
-    }
-    throw new Error(
-      `Embedded Postgres (${EMBEDDED_PG_VERSION}) failed: ${e.message}. Retry with --db docker or --db url.`,
-    );
-  }
-  try { await pg.createDatabase('dashclaw'); } catch { /* already exists on resume — fine */ }
-  logger.error('[ok] Embedded Postgres running (port 5433, data in ~/.dashclaw/pg)');
-  return { databaseUrl: LOCAL_DB_URL, stop: () => pg.stop() };
-}
-
-/** Polls :port until it accepts TCP connections, or throws on timeout. */
-async function waitForPort(port, timeoutMs) {
-  const net = await import('node:net');
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const ok = await new Promise((resolve) => {
-      const s = net.connect(port, '127.0.0.1');
-      s.once('connect', () => { s.destroy(); resolve(true); });
-      s.once('error', () => resolve(false));
-    });
-    if (ok) return;
-    await new Promise((r) => setTimeout(r, 500));
-  }
-  throw new Error(`Postgres did not accept connections on :${port} within ${timeoutMs / 1000}s.`);
-}
+// cli/lib/up/db.js
+//
+// Database mode selection and provisioning for `dashclaw up`.
+//
+// Three modes:
+//   docker   — starts/reuses a `dashclaw-pg` Docker container (host port 5433,
+//              or the next free port when 5433 is taken by something else)
+//   embedded — downloads and runs embedded Postgres via embedded-postgres (~40 MB, first run)
+//   url      — prompts for a postgresql:// connection string from the user
+//
+// Port policy: prefer DEFAULT_DB_PORT (5433, mirroring the repo's
+// docker-compose.yml). Dev machines often already have a Postgres on 5433 —
+// hard-failing there with a raw `docker run` error was a real first-run
+// killer, so provisioning scans forward to the first free port instead and
+// says so. Continuity beats novelty: an existing container keeps whatever
+// host port it was created with, and a saved databaseUrl's port is preferred
+// on resume so a working install never silently moves.
+
+import { join } from 'node:path';
+import { existsSync, rmSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+// Keep this in sync with the "embedded-postgres" version in cli/package.json.
+const EMBEDDED_PG_VERSION = 'embedded-postgres@18.4.0-beta.17';
+
+export const DEFAULT_DB_PORT = 5433;
+// Scan window when the preferred port is taken: preferred+1 .. preferred+10.
+const PORT_SCAN_SPAN = 10;
+
+export function localDbUrlFor(port) {
+  return `postgresql://dashclaw:dashclaw@localhost:${port}/dashclaw`;
+}
+
+// Back-compat export (the default-port URL).
+export const LOCAL_DB_URL = localDbUrlFor(DEFAULT_DB_PORT);
+
+const CONTAINER = 'dashclaw-pg';
+
+/** Returns true when the `docker` binary is available and responsive. */
+export function dockerAvailableSync() {
+  return spawnSync('docker', ['--version'], { stdio: 'ignore' }).status === 0;
+}
+
+/**
+ * Determines which database mode to use.
+ *
+ * Priority:
+ *   1. Explicit --db flag
+ *   2. Non-interactive (--yes): docker if available, otherwise embedded
+ *   3. Interactive prompt
+ *
+ * @param {object} opts
+ * @param {string|null} opts.flagDb   - explicit --db value or null
+ * @param {boolean}     opts.dockerAvailable
+ * @param {boolean}     [opts.yes]    - non-interactive mode
+ * @param {Function}    [opts.promptFn] - async (message) => string
+ * @returns {Promise<'docker'|'embedded'|'url'>}
+ */
+export async function chooseDbMode({ flagDb, dockerAvailable, yes = false, promptFn }) {
+  if (flagDb) return flagDb;
+  if (yes) return dockerAvailable ? 'docker' : 'embedded';
+
+  const lines = [
+    'Database — pick one:',
+    dockerAvailable
+      ? '  1. Docker Postgres (Docker detected)   [default]'
+      : '  1. Docker Postgres (Docker NOT detected)',
+    `  2. Embedded Postgres (no Docker needed, ~40 MB download)${dockerAvailable ? '' : '   [default]'}`,
+    '  3. I have a postgresql:// URL',
+  ];
+  const def = dockerAvailable ? '1' : '2';
+  const answer = (await promptFn(`${lines.join('\n')}\nChoice [${def}]: `)).trim() || def;
+  return { 1: 'docker', 2: 'embedded', 3: 'url' }[answer] ?? (dockerAvailable ? 'docker' : 'embedded');
+}
+
+/**
+ * True when nothing on this machine is serving :port.
+ *
+ * Two probes, both required — a single one lies on Windows, where binding
+ * 127.0.0.1:port SUCCEEDS while another process holds 0.0.0.0:port (observed
+ * live: the probe said 5433 was free while a Docker proxy held it):
+ *   1. connect() to 127.0.0.1:port — an accepted connection means a live
+ *      listener regardless of which address it bound.
+ *   2. listen() on the wildcard address — fails when the port is held at
+ *      0.0.0.0/[::] even if nothing accepts on loopback.
+ */
+export async function isPortFree(port) {
+  const net = await import('node:net');
+  const accepts = await new Promise((resolve) => {
+    const s = net.connect({ port, host: '127.0.0.1' });
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.once('connect', () => done(true));
+    s.once('error', () => done(false));
+    s.setTimeout(1000, () => done(false));
+  });
+  if (accepts) return false;
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once('error', () => resolve(false));
+    srv.once('listening', () => srv.close(() => resolve(true)));
+    srv.listen(port); // wildcard bind on purpose — see above
+  });
+}
+
+/**
+ * Picks the host port for a locally provisioned Postgres: the preferred port
+ * if free, otherwise the first free port in the scan window (logged, so the
+ * deviation is never silent). Throws when the whole window is occupied.
+ *
+ * @param {object}   [opts]
+ * @param {number}   [opts.preferred=DEFAULT_DB_PORT]
+ * @param {Function} [opts.isFree=isPortFree]  injectable for tests
+ * @param {object}   [opts.logger]
+ * @returns {Promise<number>}
+ */
+export async function pickDbPort({ preferred = DEFAULT_DB_PORT, isFree = isPortFree, logger = console } = {}) {
+  if (await isFree(preferred)) return preferred;
+  for (let p = preferred + 1; p <= preferred + PORT_SCAN_SPAN; p++) {
+    if (await isFree(p)) {
+      logger.error(`[warn] Port ${preferred} is already in use — using free port ${p} for Postgres instead.`);
+      return p;
+    }
+  }
+  throw new Error(
+    `No free port for Postgres: ${preferred}-${preferred + PORT_SCAN_SPAN} are all in use. `
+    + 'Free one up, or re-run with --db url and your own postgresql:// connection string.',
+  );
+}
+
+/**
+ * Returns the docker run command that starts a local Postgres container.
+ * Mirrors the repo's docker-compose.yml: postgres:16-alpine, dashclaw/dashclaw/
+ * dashclaw credentials, named volume dashclaw_pgdata. Host port is a parameter
+ * (default 5433) so provisioning can route around an occupied port.
+ */
+export function dockerCommandFor(port = DEFAULT_DB_PORT) {
+  return {
+    cmd: 'docker',
+    args: [
+      'run', '-d', '--name', CONTAINER,
+      '-e', 'POSTGRES_USER=dashclaw',
+      '-e', 'POSTGRES_PASSWORD=dashclaw',
+      '-e', 'POSTGRES_DB=dashclaw',
+      '-p', `${port}:5432`,
+      '-v', 'dashclaw_pgdata:/var/lib/postgresql/data',
+      'postgres:16-alpine',
+    ],
+  };
+}
+
+/** Runs a docker CLI call, capturing stderr so failures are explainable. */
+function dockerExec(args) {
+  try {
+    return execFileSync('docker', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (e) {
+    const stderr = (e.stderr || '').toString().trim();
+    throw new Error(`docker ${args[0]} failed${stderr ? `: ${stderr}` : `: ${e.message}`}`);
+  }
+}
+
+/** The real docker effects — injectable in provisionDatabase for tests. */
+export const realDockerOps = {
+  /** Container id (any state), or '' when it does not exist. */
+  containerId: () => (spawnSync(
+    'docker', ['ps', '-aq', '--filter', `name=^${CONTAINER}$`],
+    { encoding: 'utf8' },
+  ).stdout || '').trim(),
+  /** Container id when RUNNING, or ''. */
+  runningId: () => (spawnSync(
+    'docker', ['ps', '-q', '--filter', `name=^${CONTAINER}$`],
+    { encoding: 'utf8' },
+  ).stdout || '').trim(),
+  /**
+   * Host port the existing container maps to 5432, or null. Reads the
+   * configured binding via `docker inspect` because `docker port` reports
+   * nothing for containers that are created/stopped rather than running.
+   */
+  mappedPort: () => {
+    const out = spawnSync('docker', [
+      'inspect', CONTAINER,
+      '--format', '{{(index (index .HostConfig.PortBindings "5432/tcp") 0).HostPort}}',
+    ], { encoding: 'utf8' }).stdout || '';
+    const m = /^(\d+)$/.exec(out.trim());
+    return m ? Number(m[1]) : null;
+  },
+  start: () => dockerExec(['start', CONTAINER]),
+  remove: () => dockerExec(['rm', CONTAINER]),
+  run: (port) => {
+    try {
+      dockerExec(dockerCommandFor(port).args);
+    } catch (e) {
+      // A failed `docker run` can leave a half-created container behind,
+      // which would poison every retry with "name already in use" — clean
+      // it up best-effort before surfacing the real error.
+      try { execFileSync('docker', ['rm', '-f', CONTAINER], { stdio: 'ignore' }); } catch { /* nothing to clean */ }
+      throw e;
+    }
+  },
+};
+
+/**
+ * Starts (or creates) the dashclaw-pg container and returns the host port it
+ * serves on. Continuity first: a running container is used as-is on whatever
+ * port it maps; a stopped container is restarted on its recorded port. Only
+ * when that recorded port has been taken by some OTHER process is the
+ * container recreated on a fresh free port — safe by construction, because
+ * all data lives in the named volume `dashclaw_pgdata`, not the container.
+ */
+async function dockerProvision({ preferredPort, ops, isFree, logger }) {
+  if (ops.containerId()) {
+    const mapped = ops.mappedPort();
+    if (ops.runningId() && mapped) {
+      logger.error(`[ok] Docker Postgres already running (container ${CONTAINER}, port ${mapped})`);
+      return mapped;
+    }
+    if (mapped && await isFree(mapped)) {
+      ops.start();
+      logger.error(`[ok] Docker Postgres running (container ${CONTAINER}, port ${mapped})`);
+      return mapped;
+    }
+    // The container's port is now held by something else (or the mapping is
+    // unreadable) — recreate it on a free port. Data survives in the volume.
+    logger.error(
+      `[warn] Container ${CONTAINER} maps port ${mapped ?? '?'} which is now in use by another process — `
+      + 'recreating the container on a free port (data volume dashclaw_pgdata is preserved).',
+    );
+    ops.remove();
+  }
+  const port = await pickDbPort({ preferred: preferredPort, isFree, logger });
+  ops.run(port);
+  logger.error(`[ok] Docker Postgres running (container ${CONTAINER}, port ${port})`);
+  return port;
+}
+
+/**
+ * Provisions the database according to `mode` and returns { databaseUrl, stop }.
+ *
+ * @param {object}   opts
+ * @param {'docker'|'embedded'|'url'} opts.mode
+ * @param {string}   opts.baseDir   - base dir for embedded data (e.g. ~/.dashclaw)
+ * @param {Function} [opts.promptFn] - async (message) => string (required for mode=url)
+ * @param {string}   [opts.savedDatabaseUrl] - databaseUrl from a prior run (port continuity)
+ * @param {object}   [opts.dockerOps] - injectable docker effects (default realDockerOps)
+ * @param {Function} [opts.isFree]    - injectable port probe (default isPortFree)
+ * @param {Function} [opts.waitForDbPort] - injectable readiness wait (default waitForPort)
+ * @param {object}   [opts.logger]  - object with .error(); defaults to console
+ * @returns {Promise<{ databaseUrl: string, stop: () => Promise<void> }>}
+ */
+export async function provisionDatabase({
+  mode, baseDir, promptFn, savedDatabaseUrl,
+  dockerOps = realDockerOps, isFree = isPortFree, waitForDbPort = waitForPort, logger = console,
+}) {
+  let preferredPort = DEFAULT_DB_PORT;
+  if (savedDatabaseUrl) {
+    try { preferredPort = Number(new URL(savedDatabaseUrl).port) || DEFAULT_DB_PORT; } catch { /* keep default */ }
+  }
+
+  if (mode === 'url') {
+    const url = (await promptFn('postgresql:// connection string: ')).trim();
+    if (!url.startsWith('postgresql://')) throw new Error('That is not a postgresql:// URL.');
+    return { databaseUrl: url, stop: async () => {} };
+  }
+
+  if (mode === 'docker') {
+    const port = await dockerProvision({ preferredPort, ops: dockerOps, isFree, logger });
+    await waitForDbPort(port, 30_000);
+    return { databaseUrl: localDbUrlFor(port), stop: async () => {} };
+  }
+
+  // mode === 'embedded'
+  const port = await pickDbPort({ preferred: preferredPort, isFree, logger });
+  const { default: EmbeddedPostgres } = await import('embedded-postgres');
+  const pgDir = join(baseDir, 'pg');
+  // Record whether the data dir existed BEFORE this run.
+  // Only clean up on failure when WE created it (a pre-existing dir means
+  // a working prior install whose data we must not delete).
+  const dirPreExisted = existsSync(pgDir);
+  // Derive credentials from LOCAL_DB_URL so the local dev creds live in
+  // exactly one place rather than being duplicated as bare literals here.
+  const localDb = new URL(LOCAL_DB_URL);
+  const pg = new EmbeddedPostgres({
+    databaseDir: pgDir,
+    user: localDb.username,
+    password: localDb.password,
+    port,
+    persistent: true,
+  });
+  try {
+    await pg.initialise();
+    await pg.start();
+  } catch (e) {
+    if (!dirPreExisted) {
+      rmSync(pgDir, { recursive: true, force: true });
+    }
+    throw new Error(
+      `Embedded Postgres (${EMBEDDED_PG_VERSION}) failed: ${e.message}. Retry with --db docker or --db url.`,
+    );
+  }
+  try { await pg.createDatabase('dashclaw'); } catch { /* already exists on resume — fine */ }
+  logger.error(`[ok] Embedded Postgres running (port ${port}, data in ${pgDir})`);
+  return { databaseUrl: localDbUrlFor(port), stop: () => pg.stop() };
+}
+
+/** Polls :port until it accepts TCP connections, or throws on timeout. */
+async function waitForPort(port, timeoutMs) {
+  const net = await import('node:net');
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const ok = await new Promise((resolve) => {
+      const s = net.connect(port, '127.0.0.1');
+      s.once('connect', () => { s.destroy(); resolve(true); });
+      s.once('error', () => resolve(false));
+    });
+    if (ok) return;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error(`Postgres did not accept connections on :${port} within ${timeoutMs / 1000}s.`);
+}

package/lib/up/index.js

@@ -13,6 +13,7 @@
 // without touching the network, Docker, or a real Next server.
 
 import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -90,6 +91,24 @@ export function runSetupScriptReal({ appDir, databaseUrl, logger = console, spaw
   return parsed;
 }
 
+/**
+ * Rewrites the DATABASE_URL line in the app's .env.local after the local DB
+ * legitimately moved ports. Best-effort: a missing file or line is left alone
+ * (setup will write it on its next run).
+ */
+export function rewriteEnvDatabaseUrl(appDir, databaseUrl, logger = console) {
+  const envPath = join(appDir, '.env.local');
+  try {
+    if (!existsSync(envPath)) return;
+    const src = readFileSync(envPath, 'utf8');
+    if (!/^DATABASE_URL=.*$/m.test(src)) return;
+    writeFileSync(envPath, src.replace(/^DATABASE_URL=.*$/m, `DATABASE_URL=${databaseUrl}`));
+    logger.error(`[ok] Updated DATABASE_URL in ${envPath}`);
+  } catch (e) {
+    logger.error(`[warn] Could not update ${envPath}: ${e.message} — update DATABASE_URL manually.`);
+  }
+}
+
 /** Default process-liveness probe: signal 0 succeeds iff the pid exists. */
 export function defaultProcessAlive(pid) {
   try { process.kill(pid, 0); return true; } catch { return false; }
@@ -163,12 +182,24 @@ export async function runUp({ args, baseDir = join(homedir(), '.dashclaw'), deps
   });
   const db = (dbMode === 'url' && done('db_ready') && inst.databaseUrl)
     ? { databaseUrl: inst.databaseUrl, stop: async () => {} }
-    : await deps.provisionDatabase({ mode: dbMode, baseDir, promptFn: deps.promptFn, logger });
+    : await deps.provisionDatabase({
+        mode: dbMode, baseDir, promptFn: deps.promptFn, logger,
+        savedDatabaseUrl: inst.databaseUrl,
+      });
   if (!done('db_ready')) {
     inst = saveInstance(baseDir, { dbMode, databaseUrl: db.databaseUrl });
     inst = checkpoint(baseDir, 'db_ready');
   }
-  const databaseUrl = inst.databaseUrl ?? db.databaseUrl;
+  // Provisioning is authoritative: if the DB legitimately moved ports (its old
+  // port got taken and the container was recreated), chase the move — update
+  // the saved URL and the app's .env.local so the server doesn't point at a
+  // stranger's Postgres.
+  if (db.databaseUrl && inst.databaseUrl && db.databaseUrl !== inst.databaseUrl) {
+    logger.error(`[warn] Database URL changed (${inst.databaseUrl} -> ${db.databaseUrl}) — updating saved config.`);
+    inst = saveInstance(baseDir, { databaseUrl: db.databaseUrl });
+    if (done('setup_done') && appDir) rewriteEnvDatabaseUrl(appDir, db.databaseUrl, logger);
+  }
+  const databaseUrl = db.databaseUrl ?? inst.databaseUrl;
 
   // 4. setup_done -----------------------------------------------------------
   let apiKey = inst.apiKey;

package/package.json

@@ -1,36 +1,36 @@
-{
-  "name": "@dashclaw/cli",
-  "version": "0.6.1",
-  "description": "DashClaw terminal client — approve agent actions and diagnose your instance",
-  "type": "module",
-  "keywords": [
-    "dashclaw",
-    "cli",
-    "claude-code",
-    "ai-governance",
-    "agent-governance"
-  ],
-  "bin": {
-    "dashclaw": "./bin/dashclaw.js"
-  },
-  "files": [
-    "bin/",
-    "lib/",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "test": "node --test test/**/*.test.js"
-  },
-  "dependencies": {
-    "dashclaw": "^2.2.1",
-    "embedded-postgres": "18.4.0-beta.17",
-    "tar": "^7.4.0"
-  },
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@dashclaw/cli",
+  "version": "0.7.0",
+  "description": "DashClaw terminal client — approve agent actions and diagnose your instance",
+  "type": "module",
+  "keywords": [
+    "dashclaw",
+    "cli",
+    "claude-code",
+    "ai-governance",
+    "agent-governance"
+  ],
+  "bin": {
+    "dashclaw": "./bin/dashclaw.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "dependencies": {
+    "dashclaw": "^2.2.1",
+    "embedded-postgres": "18.4.0-beta.17",
+    "tar": "^7.4.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}