@vodmal/vdx-cli 0.18.0 → 0.20.0

package/README.md

@@ -42,13 +42,13 @@ vdx audit [project-path] [--format=ansi|markdown|json] [--rubric <path>] [--stac
 vdx init  [project-path] [--baseline github.com/org/repo@vX.Y] [--stack <id>] [--dry-run] [--force]   # default: cwd
 
 # Publish a library (Node MVP; PHP/Python coming in Y.3)
-vdx publish <patch|minor|major> [--dry-run] [--force]
+vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
 
 # Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin)
 vdx doctor [--format=ansi|markdown|json]
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
-vdx ai[@host] [project-path] [--new] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there
+vdx ai[@host] [project-path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there
 vdx ai --check [project-path]   # this session against the profile — what the plugin's SessionStart hook tells the agent
 
 # What a command does and takes; nothing runs (ai: also where launch flags live)
@@ -72,9 +72,10 @@ vdx init --stack node
 vdx test            # → mise run test (which calls `vitest run` or whatever was detected)
 
 # 3. Ship a new minor release of a Node lib
-vdx publish minor   # bump → npm publish (OTP prompt) → git commit + tag (no push)
+vdx publish minor   # npm login if expired → bump package.json + lock → npm publish (OTP) → commit + tag → push → wait for the registry
 
-# 4. Start the agent here, continuing its last conversation (--new: a new one);
+# 4. Start the agent here, continuing its last conversation (--new: a new one;
+#    another machine's conversation is continued on that machine);
 #    re-run to attach, --restart to apply a changed profile
 vdx ai
 
@@ -91,6 +92,11 @@ name. `vdx ai@<host>` runs the same command on `<host>` over ssh — that machin
 profile and tmux, the path taken under its home directory; `--detach` only
 starts it. The machine's own label (`$VDX_HOST`) runs here. Where git knows no
 commit author, `vdx ai` proposes one (Enter writes it into `.git/config`).
+For Claude Code `vdx ai` picks the conversation: each one is marked with the
+machine it was last started on (`vdx ai --check`, run by the plugin's hook, writes
+the label in), the running ones are asked of the other machines over ssh, and
+another machine's conversation is continued there. When the choice is not plain
+it lists them — Enter takes the newest; without a terminal, this machine's.
 
 Every command takes `--help` (`-h`) and runs nothing with it. An unknown option,
 a stray argument or a value flag without its value is refused with exit 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/src/ai.ts

@@ -8,6 +8,20 @@ import { autoDetectStack, readStructured, resolveConfigPath, type Ctx } from './
 import { loadManifest } from './manifest.ts';
 import { type Author, effectiveAuthor, isGitRepo, rankAuthors, scanPool, writeAuthor } from './author.ts';
 import type { Predicate } from './rubric.ts';
+import {
+  type Conversation,
+  describeConversation,
+  describeLive,
+  LIVE_SESSIONS_SCRIPT,
+  type LiveSession,
+  latestPerMachine,
+  listConversations,
+  liveConversationId,
+  liveSessionsHere,
+  machineLine,
+  machineOf,
+  parseLiveSessions,
+} from './conversations.ts';
 
 /**
  * `vdx ai` — start the person's agent in a project, with the flags their
@@ -17,7 +31,9 @@ import type { Predicate } from './rubric.ts';
  *
  * A start continues the project's last conversation (the profile's
  * `resume_args`) — after a reboot `vdx ai` brings the agent back where it was;
- * `--new` starts a new conversation.
+ * `--new` starts a new conversation. For Claude Code vdx picks the
+ * conversation itself, and continues another machine's on that machine
+ * (see chooseConversation).
  *
  * The profile is personal (which agent, which permissions), so it is never
  * bundled into the CLI: it is read from `$VDX_ENVIRONMENT` or
@@ -581,6 +597,8 @@ export interface AiOptions {
   restart: boolean;
   /** `--new`: start a new conversation — leave out the profile's resume args. */
   fresh: boolean;
+  /** `--conversation <id>`: continue this Claude Code conversation. */
+  conversation?: string;
   detach: boolean;
   dryRun: boolean;
 }
@@ -600,6 +618,18 @@ export interface AiDeps {
   confirmTimeoutMs: number;
   /** One line from the person at the terminal, or null when there is none. */
   ask: (prompt: string) => string | null;
+  /** This vdx's version, named to the vdx on another machine. */
+  version?: string;
+  /** Run ssh — capturing its output, or on this terminal; null when ssh is not on PATH. */
+  ssh?: (args: string[], capture: boolean) => { status: number; stdout: string } | null;
+  /** Claude Code processes alive on this machine; read from its session files when not given. */
+  liveHere?: () => LiveSession[];
+}
+
+export function runSsh(args: string[], capture: boolean): { status: number; stdout: string } | null {
+  const res = spawnSync('ssh', args, { stdio: capture ? ['ignore', 'pipe', 'ignore'] : 'inherit', encoding: 'utf8' });
+  if ((res.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') return null;
+  return { status: res.status ?? 1, stdout: res.stdout ?? '' };
 }
 
 export function sleepSync(ms: number): void {
@@ -643,6 +673,7 @@ export function defaultDeps(): AiDeps {
     sleep: sleepSync,
     confirmTimeoutMs: 30_000,
     ask: askLine,
+    ssh: runSsh,
   };
 }
 
@@ -826,6 +857,7 @@ export function remoteAiArgs(input: {
     opts.restart && '--restart',
     opts.detach && '--detach',
     opts.dryRun && '--dry-run',
+    opts.conversation && `--conversation ${shellQuote(opts.conversation)}`,
   ].filter((f): f is string => Boolean(f));
   const v = shellQuote(version);
   const script =
@@ -890,20 +922,159 @@ export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDe
   }
 }
 
-export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, version: string): number {
+export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, version: string = deps.version ?? ''): number {
   const projectPath = resolveProjectRoot(opts.path) ?? path.resolve(opts.path);
   const tty = deps.interactive && !opts.detach && !opts.dryRun;
   const args = remoteAiArgs({ host, projectPath, home: deps.home, version, opts, tty });
-  deps.log(`→ ${host}: vdx ai ${shellQuote(projectPath)}`);
-  const res = spawnSync('ssh', args, { stdio: 'inherit' });
-  if ((res.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+  deps.log(`→ ${host}: vdx ai ${shellQuote(projectPath)}${opts.conversation ? ` --conversation ${opts.conversation}` : ''}`);
+  const res = (deps.ssh ?? runSsh)(args, false);
+  if (res === null) {
     deps.log('vdx ai: `ssh` not found on PATH');
     return 127;
   }
   if (opts.detach && res.status === EXIT_OK) {
     deps.log(`attach from here: vdx ai@${host} ${shellQuote(projectPath)}`);
   }
-  return res.status ?? 1;
+  return res.status;
+}
+
+/**
+ * The Claude Code sessions alive on `host` right now; null when it does not
+ * answer over ssh (BatchMode: a password prompt counts as no answer).
+ */
+export function askMachine(host: string, deps: AiDeps): LiveSession[] | null {
+  const res = (deps.ssh ?? runSsh)(
+    ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', host, `sh -c ${shellQuote(LIVE_SESSIONS_SCRIPT)}`],
+    true,
+  );
+  return res && res.status === 0 ? parseLiveSessions(res.stdout) : null;
+}
+
+/** What a start continues: resume args here, or a conversation on another machine. */
+export interface ConversationChoice {
+  args: string[];
+  /** Continue it on that machine (`vdx ai@<host>`); `reachable` — it answered over ssh just now. */
+  remote?: { host: string; id: string; reachable: boolean };
+  /** Continue it here only after a yes: another machine's that cannot be asked, or one running here already. */
+  askHere?: { id: string; why: string };
+  /** For the person: what was found and what is taken. */
+  lines: string[];
+}
+
+export function isClaude(command: string): boolean {
+  return path.basename(command) === 'claude';
+}
+
+const resumeId = (id: string) => ['--resume', id];
+
+/**
+ * Which conversation a start continues. Other agents keep the profile's
+ * resume_args. For Claude Code vdx reads the project's conversations and the
+ * machine each belongs to (conversations.ts): `--continue` would take the
+ * newest one in the folder, and with the folder synced between machines that
+ * can be a conversation another machine is still writing to.
+ *
+ * Every other machine this project's conversations name is asked over ssh
+ * which of them run there right now; this machine's running ones come from
+ * its own session files. A running conversation is listed even when it is not
+ * its machine's newest.
+ *
+ * Another machine's conversation is continued on that machine, so two
+ * machines never write to one conversation; one whose machine is unknown, or
+ * cannot be reached, or that already runs here, is continued here only after a
+ * yes. When the choice is not plain, a person at a terminal picks — Enter
+ * takes the newest overall; without a terminal it is this machine's newest
+ * idle one, never another's.
+ */
+export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boolean): ConversationChoice {
+  if (plan.resumeArgs.length === 0 || !isClaude(plan.command)) return { args: plan.resumeArgs, lines: [] };
+  const host = plan.host;
+  const same = (a: string | null, b: string | null) => (a ?? '').toLowerCase() === (b ?? '').toLowerCase();
+  const all = listConversations({ env: deps.env, home: deps.home, projectRoot: plan.projectRoot });
+  if (all.length === 0) return { args: [], lines: ['no conversation of this project yet — starting a new one'] };
+
+  // Who runs what right now: this machine from its session files, the others over ssh.
+  const reach = new Map<string, LiveSession[] | null>();
+  for (const c of all) {
+    if (c.machine && !same(c.machine, host) && ![...reach.keys()].some((m) => same(m, c.machine))) {
+      reach.set(c.machine, askMachine(c.machine, deps));
+    }
+  }
+  const live = new Map<string, { machine: string; session: LiveSession; here: boolean }[]>();
+  const addLive = (machine: string, session: LiveSession, here: boolean) =>
+    live.set(session.conversation, [...(live.get(session.conversation) ?? []), { machine, session, here }]);
+  for (const l of (deps.liveHere ?? (() => liveSessionsHere(deps.env, deps.home)))()) addLive(host, l, true);
+  for (const [m, sessions] of reach) for (const l of sessions ?? []) addLive(m, l, false);
+
+  const machine = (c: Conversation) => live.get(c.id)?.find((l) => !l.here)?.machine ?? machineOf(c, host);
+  const runsHere = (c: Conversation) => live.get(c.id)?.find((l) => l.here);
+  const isOurs = (c: Conversation) => same(machine(c), host);
+  const idleHere = (c: Conversation) => isOurs(c) && !runsHere(c);
+  const found = [...new Set([...latestPerMachine(all, machine), ...all.filter((c) => live.has(c.id))])].sort(
+    (a, b) => b.updated.getTime() - a.updated.getTime(),
+  );
+  const show = (c: Conversation) => describeConversation(c, machine(c));
+  const running = (c: Conversation) => (live.get(c.id) ?? []).map((l) => describeLive(l.machine, l.session, l.here));
+
+  const take = (c: Conversation): ConversationChoice => {
+    const m = machine(c);
+    const here = runsHere(c);
+    if (here) {
+      return {
+        args: [],
+        askHere: { id: c.id, why: `It runs here right now (${here.session.tmux ?? `pid ${here.session.pid}`}); two sessions would write to it` },
+        lines: [`chosen: ${show(c)}`],
+      };
+    }
+    if (isOurs(c)) return { args: resumeId(c.id), lines: [`continuing ${show(c)}`] };
+    if (m) return { args: [], remote: { host: m, id: c.id, reachable: reach.get(m) != null }, lines: [`continuing on ${m}: ${show(c)}`] };
+    return {
+      args: [],
+      askHere: { id: c.id, why: 'Its machine is unknown (never typed in here); if it runs there, both machines will write to it' },
+      lines: [`chosen: ${show(c)}`],
+    };
+  };
+  if (found.every(idleHere)) return take(found[0]!);
+
+  const firstIdle = found.find(idleHere);
+  if (canAsk && deps.interactive) {
+    deps.log('conversations of this project:');
+    found.forEach((c, i) => {
+      const marks = [i === 0 && 'newest', c === firstIdle && 'this machine', !machine(c) && 'machine unknown', ...running(c)];
+      const m = marks.filter(Boolean);
+      deps.log(`  ${i + 1}) ${show(c)}${m.length ? `   ← ${m.join(', ')}` : ''}`);
+    });
+    deps.log('  n) a new conversation');
+    for (let tries = 0; tries < 2; tries++) {
+      const answer = deps.ask(`Which one to continue? [1]: `);
+      if (answer === null) break;
+      const a = answer.trim();
+      if (/^n(ew)?$/i.test(a)) return { args: [], lines: ['a new conversation'] };
+      const c = a === '' ? found[0] : /^\d+$/.test(a) ? found[Number(a) - 1] : undefined;
+      if (c) return take(c);
+      deps.log(`  1–${found.length}, or n`);
+    }
+  }
+  const root = shellQuote(plan.projectRoot);
+  const notes = found
+    .filter((c) => !idleHere(c))
+    .map((c) => {
+      const m = machine(c);
+      const now = running(c);
+      const which =
+        `${c.updated > (firstIdle?.updated ?? new Date(0)) ? 'a newer' : 'another'} conversation ${c.id.slice(0, 8)}` +
+        (now.length ? `, ${now.join(', ')}` : '');
+      if (runsHere(c)) return `note: ${which} — not taken: it would have two sessions`;
+      return m
+        ? `note: ${m} has ${which} — continue it there: vdx ai@${m} ${root} --conversation ${c.id}`
+        : `note: ${which} is of an unknown machine (never typed in here) — on its machine: vdx ai@<machine> ${root} --conversation ${c.id}`;
+    });
+  for (const [m, sessions] of reach) if (sessions === null) notes.push(`note: ${m} does not answer over ssh — what runs there is not known`);
+  if (firstIdle) {
+    const chosen = take(firstIdle);
+    return { ...chosen, lines: [...chosen.lines, ...notes] };
+  }
+  return { args: [], lines: ['no idle conversation of this machine — starting a new one', ...notes] };
 }
 
 interface Prepared {
@@ -994,10 +1165,11 @@ export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = proc
   const { projectRoot, profilePath, plan } = prepared;
 
   const lines = [
-    `vdx ai: the agent in this project is started with \`vdx ai\`, and its flags come from the profile ` +
+    `${machineLine(plan.host)}; the agent in this project is started with \`vdx ai\`, and its flags come from the profile ` +
       `${profilePath} — agent.args for every project, agent.when[] for a class of projects. ` +
       `Hand the user \`vdx ai\`, not \`${plan.command} --<flag>\`; a flag a class of projects needs is a ` +
-      `condition in the profile, not an instruction to type. More: \`vdx ai --help\`.`,
+      `condition in the profile, not an instruction to type. A project's agent on another machine: ` +
+      `\`vdx ai@<machine>\`. More: \`vdx ai --help\`.`,
   ];
   const own = findOwnAgent(deps.processes(), selfPid, plan.command);
   if (!own) {
@@ -1032,6 +1204,10 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   if (typeof prepared === 'number') return prepared;
   const { projectRoot, environment, profileDir } = prepared;
   let { plan } = prepared;
+  if (opts.conversation && !isClaude(plan.command)) {
+    log(`vdx ai: --conversation names a Claude Code conversation; the agent here is ${plan.command}`);
+    return EXIT_USAGE;
+  }
   // A start continues the last conversation unless asked for a new one.
   if (opts.fresh) plan = { ...plan, resumeArgs: [] };
 
@@ -1045,13 +1221,49 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     multiplexer === 'tmux'
       ? findAgentPanes(tmux.panes(), deps.processes(), projectRoot, plan.command)
       : [];
+  const current = running[0];
+
+  // What a start continues. A restart keeps the conversation the agent is in.
+  let choice: ConversationChoice | null = null;
+  if (!current || opts.restart) {
+    if (opts.conversation) choice = { args: resumeId(opts.conversation), lines: [] };
+    else if (current && plan.resumeArgs.length > 0 && isClaude(plan.command)) {
+      const live = liveConversationId(deps.env, deps.home, current.proc.pid);
+      choice = live
+        ? { args: resumeId(live), lines: [`the agent is in conversation ${live.slice(0, 8)} — resuming it`] }
+        : chooseConversation(plan, deps, false);
+    } else choice = chooseConversation(plan, deps, !opts.dryRun);
+    plan = { ...plan, resumeArgs: choice.args };
+  }
 
   const poolDirs = authorPoolDirs(environment, projectRoot, deps.home, profileDir);
   if (opts.dryRun) {
     deps.out(renderPlan(plan, multiplexer, running));
+    for (const l of choice?.lines ?? []) deps.out(`  conversation: ${l}\n`);
     ensureAuthor(projectRoot, poolDirs, deps, true);
     return EXIT_OK;
   }
+  for (const l of choice?.lines ?? []) log(l);
+
+  let askHere = choice?.askHere;
+  if (choice?.remote) {
+    const { host, id, reachable } = choice.remote;
+    if (reachable) return runAiRemote({ ...opts, path: projectRoot, conversation: id }, host, deps);
+    log(`✗ ${host} does not answer over ssh — its conversation ${id.slice(0, 8)} cannot be continued there`);
+    askHere = { id, why: `If it still runs on ${host}, both machines will write to it` };
+  }
+  if (askHere) {
+    const { id, why } = askHere;
+    const answer = deps.interactive ? deps.ask(`Continue ${id.slice(0, 8)} here, on ${plan.host}? ${why}. [y/N]: `) : null;
+    if (!/^y(es)?$/i.test(answer?.trim() ?? '')) {
+      log(
+        `nothing started. Here: vdx ai ${shellQuote(projectRoot)} --conversation ${id}` +
+          ` · a new conversation: vdx ai --new ${shellQuote(projectRoot)}`,
+      );
+      return EXIT_LAUNCH_FAILED;
+    }
+    plan = { ...plan, resumeArgs: resumeId(id) };
+  }
   ensureAuthor(projectRoot, poolDirs, deps, false);
 
   if (multiplexer === 'none') {
@@ -1078,7 +1290,6 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     return res.status ?? 1;
   }
 
-  const current = running[0];
   if (running.length > 1) {
     log(
       `note: ${running.length} panes run ${plan.command} in this project: ` +
@@ -1088,13 +1299,22 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
 
   if (current && !opts.restart) {
     if (opts.fresh) log(`note: ${current.pane.session} already runs ${plan.command} — --new replaces it only with --restart`);
+    if (opts.conversation) {
+      const live = liveConversationId(deps.env, deps.home, current.proc.pid);
+      if (live !== opts.conversation) {
+        log(
+          `note: ${current.pane.session} is in ${live ? `conversation ${live.slice(0, 8)}` : 'another conversation'} — ` +
+            `to switch it: vdx ai --restart ${shellQuote(projectRoot)} --conversation ${opts.conversation}`,
+        );
+      }
+    }
     const missing = missingArgs(current.proc.args, plan.args);
     if (missing.length > 0) {
       log(`✗ ${current.pane.session}: ${plan.command} is running without ${missing.join(' ')}`);
       log(
         `  to apply the profile: vdx ai --restart${opts.fresh ? ' --new' : ''} ${shellQuote(projectRoot)}` +
           (plan.resumeArgs.length
-            ? ` (stops the running agent, then resumes the conversation with ${plan.resumeArgs.join(' ')})`
+            ? ` (stops the running agent, then resumes its conversation)`
             : opts.fresh
               ? ' (stops the running agent and starts a new conversation)'
               : ' (stops the running agent; the conversation is not resumed — the profile has no resume_args)'),

package/src/conversations.ts

@@ -0,0 +1,299 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Claude Code conversations of a project, and the machine each one was last
+ * started on.
+ *
+ * Claude Code keeps a conversation as `<config>/projects/<dir>/<id>.jsonl`,
+ * where `<dir>` is the working directory with every character other than a
+ * letter or a digit turned into `-`. That folder may be synced between
+ * machines (it is on the owner's: Syncthing), so the newest conversation of a
+ * project can be another machine's — and `claude --continue` would take it
+ * there, while that machine still writes to it.
+ *
+ * The transcript has no field for the machine. The machine comes from vdx
+ * itself: `vdx ai --check`, run by the vdx plugin's SessionStart hook, names
+ * it, and Claude Code keeps the hook's text in the transcript — on every
+ * start, resume, /clear and compact. The last such line is where the
+ * conversation was last started. Derived from the synced transcript, never
+ * stored apart from it.
+ *
+ * A conversation from before vdx named the machine has no such line. For it
+ * the machine's own `<config>/history.jsonl` answers half the question: it
+ * records the conversation of every prompt typed here, and it is not synced
+ * (the owner's Syncthing ignores it; unsynced setups have nothing to sync). A
+ * conversation typed in here is this machine's; one never typed in here is
+ * another machine's — which one, nothing says.
+ */
+
+/** The opening of `vdx ai --check`'s text; the label is an ssh destination from the other machines. */
+export const MACHINE_LINE_PREFIX = 'vdx ai: this machine is';
+const MACHINE_LINE_RE = /^vdx ai: this machine is `([^`]+)`/m;
+/** A label read from a synced file goes to ssh: it must not be able to read as an option. */
+const LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function machineLine(label: string): string {
+  return `${MACHINE_LINE_PREFIX} \`${label}\``;
+}
+
+export function isConversationId(s: string): boolean {
+  return ID_RE.test(s);
+}
+
+export interface Conversation {
+  id: string;
+  /** Last write — the file's mtime, which Syncthing carries over from the writer. */
+  updated: Date;
+  /** Where it was last started; null for a conversation from before vdx named the machine. */
+  machine: string | null;
+  /** A prompt was typed in it on this machine (history.jsonl). */
+  typedHere: boolean;
+  /** Claude's title for it, else the last prompt. */
+  title: string | null;
+}
+
+export function claudeConfigDir(env: NodeJS.ProcessEnv, home: string): string {
+  const dir = env['CLAUDE_CONFIG_DIR']?.trim();
+  return dir ? path.resolve(dir.replace(/^~(?=$|\/)/, home)) : path.join(home, '.claude');
+}
+
+export function projectDirName(projectRoot: string): string {
+  return projectRoot.replace(/[^A-Za-z0-9]/g, '-');
+}
+
+/** Read one transcript; null when nobody ever wrote in it — there is nothing to continue. */
+export function readConversation(file: string, updated: Date): Conversation | null {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let machine: string | null = null;
+  let aiTitle: string | null = null;
+  let lastPrompt: string | null = null;
+  let turns = false;
+  for (const line of text.split('\n')) {
+    // Cheap filters first: transcripts run to megabytes, and only these lines matter.
+    const isHook = line.includes('"hook_additional_context"') && line.includes(MACHINE_LINE_PREFIX);
+    const isTitle = line.includes('"ai-title"') || line.includes('"last-prompt"');
+    if (!turns && line.includes('"type":"user"')) turns = true;
+    if (!isHook && !isTitle) continue;
+    let entry: any;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry?.type === 'ai-title' && typeof entry.aiTitle === 'string') aiTitle = entry.aiTitle;
+    else if (entry?.type === 'last-prompt' && typeof entry.lastPrompt === 'string') lastPrompt = entry.lastPrompt;
+    else if (entry?.type === 'attachment' && entry.attachment?.type === 'hook_additional_context') {
+      const content = entry.attachment.content;
+      for (const part of Array.isArray(content) ? content : [content]) {
+        const label = typeof part === 'string' ? part.match(MACHINE_LINE_RE)?.[1] : undefined;
+        if (label && LABEL_RE.test(label)) machine = label;
+      }
+    }
+  }
+  if (!turns) return null;
+  const id = path.basename(file, '.jsonl');
+  return { id, updated, machine, typedHere: false, title: aiTitle ?? lastPrompt };
+}
+
+/** Which of `ids` had a prompt typed in them on this machine. */
+export function typedHere(env: NodeJS.ProcessEnv, home: string, ids: Set<string>): Set<string> {
+  const found = new Set<string>();
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(claudeConfigDir(env, home), 'history.jsonl'), 'utf8');
+  } catch {
+    return found;
+  }
+  for (const m of text.matchAll(/"sessionId":"([0-9a-f-]{36})"/g)) {
+    if (ids.has(m[1]!)) found.add(m[1]!);
+  }
+  return found;
+}
+
+/** The project's conversations, newest first; at most `limit` files are read. */
+export function listConversations(input: {
+  env: NodeJS.ProcessEnv;
+  home: string;
+  projectRoot: string;
+  limit?: number;
+}): Conversation[] {
+  const roots = new Set([input.projectRoot]);
+  try {
+    roots.add(fs.realpathSync(input.projectRoot));
+  } catch {
+    /* the plain path is enough */
+  }
+  const files: { file: string; updated: Date }[] = [];
+  for (const root of roots) {
+    const dir = path.join(claudeConfigDir(input.env, input.home), 'projects', projectDirName(root));
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      // `<id>.sync-conflict-….jsonl` is Syncthing's copy of a losing side, not a conversation.
+      if (!name.endsWith('.jsonl') || !isConversationId(name.slice(0, -'.jsonl'.length))) continue;
+      const file = path.join(dir, name);
+      try {
+        files.push({ file, updated: fs.statSync(file).mtime });
+      } catch {
+        /* gone since the listing */
+      }
+    }
+  }
+  files.sort((a, b) => b.updated.getTime() - a.updated.getTime());
+  const seen = new Set<string>();
+  const out: Conversation[] = [];
+  for (const f of files.slice(0, input.limit ?? 30)) {
+    const c = readConversation(f.file, f.updated);
+    if (c && !seen.has(c.id)) {
+      seen.add(c.id);
+      out.push(c);
+    }
+  }
+  const typed = typedHere(input.env, input.home, seen);
+  return out.map((c) => ({ ...c, typedHere: typed.has(c.id) }));
+}
+
+function sameMachine(a: string | null, b: string | null): boolean {
+  return (a ?? '').toLowerCase() === (b ?? '').toLowerCase();
+}
+
+/** The machine a conversation belongs to: its last start, else this one if typed in here; null — unknown. */
+export function machineOf(c: Conversation, host: string): string | null {
+  return c.machine ?? (c.typedHere ? host : null);
+}
+
+/** The newest conversation of each machine (unknown counts as one), newest first. */
+export function latestPerMachine(conversations: Conversation[], machine: (c: Conversation) => string | null): Conversation[] {
+  const out: Conversation[] = [];
+  for (const c of [...conversations].sort((a, b) => b.updated.getTime() - a.updated.getTime())) {
+    if (!out.some((o) => sameMachine(machine(o), machine(c)))) out.push(c);
+  }
+  return out;
+}
+
+
+/**
+ * The conversation a running Claude Code process is in, from its session file
+ * `<config>/sessions/<pid>.json` — it follows /clear. That folder is per
+ * machine, so the pid is this machine's.
+ */
+export function liveConversationId(env: NodeJS.ProcessEnv, home: string, pid: number): string | null {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(claudeConfigDir(env, home), 'sessions', `${pid}.json`), 'utf8'));
+    const id = data?.sessionId;
+    return typeof id === 'string' && isConversationId(id) ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A Claude Code process running right now, and the conversation it is in. */
+export interface LiveSession {
+  pid: number;
+  conversation: string;
+  /** `session:@window.%pane`, when it runs in tmux. */
+  tmux: string | null;
+  /** Claude Code's own word for it: `busy`, `waiting`, … */
+  status: string | null;
+}
+
+/** Session files, one JSON object per line — a file read here, or the output of LIVE_SESSIONS_SCRIPT. */
+export function parseLiveSessions(text: string): LiveSession[] {
+  const out: LiveSession[] = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim().startsWith('{')) continue;
+    let data: any;
+    try {
+      data = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!Number.isInteger(data?.pid) || typeof data?.sessionId !== 'string' || !isConversationId(data.sessionId)) continue;
+    out.push({
+      pid: data.pid,
+      conversation: data.sessionId,
+      tmux: typeof data.tmux === 'string' ? data.tmux : null,
+      status: typeof data.status === 'string' ? data.status : null,
+    });
+  }
+  return out;
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e: any) {
+    return e?.code === 'EPERM';
+  }
+}
+
+/**
+ * Prints the session file of every Claude Code process alive on the machine it
+ * runs on, one per line — what `vdx ai` asks another machine over ssh. Claude
+ * removes the file of a process that ended, but not after a crash or a reboot:
+ * the pid is checked. `<pid>.sync-conflict-….json` is not a session file.
+ */
+export const LIVE_SESSIONS_SCRIPT =
+  'd="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/sessions"; for f in "$d"/*.json; do ' +
+  'p=${f##*/}; p=${p%.json}; case $p in ""|*[!0-9]*) continue;; esac; ' +
+  'kill -0 "$p" 2>/dev/null && tr -d "\\n" < "$f" && echo; done; exit 0';
+
+/** Claude Code processes alive on this machine. */
+export function liveSessionsHere(env: NodeJS.ProcessEnv, home: string, alive: (pid: number) => boolean = pidAlive): LiveSession[] {
+  const dir = path.join(claudeConfigDir(env, home), 'sessions');
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const lines: string[] = [];
+  for (const name of names) {
+    const pid = name.match(/^(\d+)\.json$/)?.[1];
+    if (!pid || !alive(Number(pid))) continue;
+    try {
+      lines.push(fs.readFileSync(path.join(dir, name), 'utf8').replace(/\n/g, ''));
+    } catch {
+      /* ended since the listing */
+    }
+  }
+  return parseLiveSessions(lines.join('\n'));
+}
+
+/** "running on m3 now (t23b-program@m3, waiting)" — where a live session is, for a person choosing. */
+export function describeLive(machine: string, live: LiveSession, here: boolean): string {
+  const where = live.tmux ? live.tmux.replace(/:.*$/, '') : `pid ${live.pid}`;
+  return `running ${here ? 'here' : `on ${machine}`} now (${where}${live.status ? `, ${live.status}` : ''})`;
+}
+
+/** "3 min ago", "yesterday 14:05", "2026-09-30 14:05" — for a person choosing. */
+export function describeAge(when: Date, now: Date = new Date()): string {
+  const min = Math.round((now.getTime() - when.getTime()) / 60_000);
+  if (min < 1) return 'just now';
+  if (min < 60) return `${min} min ago`;
+  const hh = String(when.getHours()).padStart(2, '0');
+  const mm = String(when.getMinutes()).padStart(2, '0');
+  const day = (d: Date) => new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+  const days = Math.round((day(now) - day(when)) / 86_400_000);
+  if (days === 0) return `today ${hh}:${mm}`;
+  if (days === 1) return `yesterday ${hh}:${mm}`;
+  const date = `${when.getFullYear()}-${String(when.getMonth() + 1).padStart(2, '0')}-${String(when.getDate()).padStart(2, '0')}`;
+  return `${date} ${hh}:${mm}`;
+}
+
+export function describeConversation(c: Conversation, machine: string | null, now: Date = new Date()): string {
+  const title = c.title ? ` «${c.title.replace(/\s+/g, ' ').trim().slice(0, 60)}»` : '';
+  return `${machine ?? '?'}  ${describeAge(c.updated, now)}  ${c.id.slice(0, 8)}${title}`;
+}

package/src/index.ts

@@ -23,13 +23,16 @@ import { runDoctor, looksLikeProject, readCliVersion } from './doctor.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
 import {
   planPublish,
+  preflightFixable,
   renderPublishPlan,
   executePublish,
+  defaultPublishDeps,
   type BumpKind,
   type PublishOptions,
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
 import { runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
+import { isConversationId } from './conversations.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
 
@@ -37,9 +40,9 @@ const USAGE = `Usage:
   vdx <up|down|build|test|check|fix>     run lifecycle verb (via mise run <verb>)
   vdx audit   [project_path]  [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]   (default: cwd)
   vdx init    [project_path]  [--stack <id>] [--baseline <ref>] [--dry-run] [--force]                     (default: cwd)
-  vdx publish <patch|minor|major> [--dry-run] [--force]
+  vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
   vdx doctor  [--format=ansi|markdown|json] [--json]
-  vdx ai[@host] [project_path] [--new] [--restart] [--detach] [--dry-run]         (default: cwd; @host: over ssh, in tmux there)
+  vdx ai[@host] [project_path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]   (default: cwd; @host: over ssh, in tmux there)
   vdx <command> --help                   what the command does; an unknown option is refused (exit 2)
   vdx --version
 `;
@@ -73,6 +76,8 @@ the project's files). Hand a person \`vdx ai\`, not \`<agent> --<flag>\`.
   project_path  the project (default: cwd); its git toplevel is used
   @host         the same command on <host> over ssh: its vdx, profile and tmux
   --new         a new conversation instead of continuing the last one
+  --conversation <id>
+                continue this Claude Code conversation
   --restart     restart the running agent in its pane — applies a changed profile
   --detach      start without attaching; print the command that attaches
   --dry-run     print the plan and the project's running agents; start nothing
@@ -81,6 +86,14 @@ the project's files). Hand a person \`vdx ai\`, not \`<agent> --<flag>\`.
                 SessionStart hook); prints nothing without a profile; exit 3 on drift
   -h, --help    this help
 
+Which conversation a start continues (Claude Code): each one is marked with the
+machine it was last started on (the vdx plugin's hook writes it in), and the
+other machines are asked over ssh which ones run there now. Another machine's
+conversation is continued on that machine; if it does not answer, vdx asks
+before continuing it here. When the choice is not plain, vdx lists them, the
+running ones marked — Enter takes the newest; without a terminal it takes this
+machine's.
+
 Exit codes: 0 the agent runs per the profile; 2 profile or usage error;
 3 the running agent lacks profile flags (rerun with --restart); 4 the start
 was not confirmed.
@@ -108,12 +121,18 @@ mise.toml is overwritten only with --force.
     positionals: 1,
   },
   publish: {
-    usage: 'vdx publish <patch|minor|major> [--dry-run] [--force]',
-    help: `Releases the library in the current directory: pre-flight checks, version bump,
-npm publish (npm asks for an OTP), git commit and tag. Does not push.
---dry-run runs the pre-flight and prints the plan; --force goes on past a failed pre-flight.
+    usage: 'vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]',
+    help: `Releases the library in the current directory, start to finish:
+  pre-flight checks — at a terminal an expired npm login is renewed (\`npm login\`)
+  and the checks run again;
+  the version bump in package.json and package-lock.json;
+  npm publish (npm asks for an OTP);
+  git commit and tag, then \`git push --follow-tags\` to the branch's upstream;
+  a wait until the registry shows the new version (up to 3 min).
+--dry-run runs the pre-flight and prints the plan; --force goes on past a failed
+pre-flight; --no-push leaves the commit and the tag local.
 `,
-    bools: ['dry-run', 'force'],
+    bools: ['dry-run', 'force', 'no-push'],
     positionals: 1,
   },
   doctor: {
@@ -127,10 +146,11 @@ Exit 2 when something is missing.
     positionals: 0,
   },
   ai: {
-    usage: 'vdx ai[@host] [project_path] [--new] [--restart] [--detach] [--dry-run]',
+    usage: 'vdx ai[@host] [project_path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]',
     help: AI_HELP,
     // `--resume` asked to continue in 0.12; continuing is the default now.
     bools: ['new', 'restart', 'resume', 'detach', 'dry-run', 'check'],
+    values: ['conversation'],
     positionals: 1,
   },
   ...Object.fromEntries(
@@ -308,7 +328,7 @@ function cmdPublish(opts: ParsedArgs): void {
   const bumpArg = opts.positionals[0];
   if (!bumpArg || !['patch', 'minor', 'major'].includes(bumpArg)) {
     process.stderr.write(
-      'Usage: vdx publish <patch|minor|major> [--dry-run] [--force]\n',
+      'Usage: vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]\n',
     );
     process.exit(1);
   }
@@ -328,15 +348,18 @@ function cmdPublish(opts: ParsedArgs): void {
     bump,
     dryRun: Boolean(opts.flags['dry-run']),
     force: Boolean(opts.flags.force),
+    push: !opts.flags['no-push'],
   };
 
-  let plan;
-  try {
-    plan = planPublish(planOpts, auditResult, ctx);
-  } catch (e: any) {
-    process.stderr.write(`error: ${e?.message ?? String(e)}\n`);
-    process.exit(2);
-  }
+  const replan = () => {
+    try {
+      return planPublish(planOpts, auditResult, ctx);
+    } catch (e: any) {
+      process.stderr.write(`error: ${e?.message ?? String(e)}\n`);
+      process.exit(2);
+    }
+  };
+  let plan = replan();
 
   process.stdout.write(renderPublishPlan(plan));
 
@@ -345,13 +368,30 @@ function cmdPublish(opts: ParsedArgs): void {
     return;
   }
 
+  // A failure a command fixes (an expired npm login): run it here, then check again.
+  const deps = defaultPublishDeps();
+  const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+  if (!plan.preflightPassed && !planOpts.force && interactive && preflightFixable(plan)) {
+    for (const c of plan.preflight.filter((c) => !c.ok && c.fix)) {
+      process.stderr.write(`\n→ ${c.name}: ${c.fix!.cmd} ${c.fix!.args.join(' ')}\n`);
+      try {
+        deps.run(c.fix!.cmd, c.fix!.args, projectRoot);
+      } catch {
+        process.stderr.write(`error: \`${c.fix!.cmd} ${c.fix!.args.join(' ')}\` failed\n`);
+        process.exit(2);
+      }
+    }
+    plan = replan();
+    process.stdout.write('\n' + renderPublishPlan(plan));
+  }
+
   if (!plan.preflightPassed && !planOpts.force) {
     process.stderr.write('\nerror: pre-flight failed (use --force to bypass)\n');
     process.exit(2);
   }
 
   try {
-    executePublish(plan);
+    executePublish(plan, deps);
   } catch (e: any) {
     process.stderr.write(`\nerror: ${e?.message ?? String(e)}\n`);
     process.exit(3);
@@ -415,13 +455,24 @@ function cmdAi(opts: ParsedArgs): void {
     }
     process.exit(runAiCheck(opts.positionals[0] ?? '.', defaultDeps()));
   }
+  const conversation = typeof opts.flags.conversation === 'string' ? opts.flags.conversation : undefined;
+  if (conversation !== undefined && !isConversationId(conversation)) {
+    process.stderr.write(`vdx ai: --conversation takes a conversation id (a UUID), not "${conversation}"\n`);
+    process.exit(2);
+  }
+  if (conversation !== undefined && opts.flags.new === true) {
+    process.stderr.write('vdx ai: --new and --conversation ask for different conversations — pick one\n');
+    process.exit(2);
+  }
   const options = {
     path: opts.positionals[0] ?? '.',
     restart: opts.flags.restart === true,
     fresh: opts.flags.new === true,
+    conversation,
     detach: opts.flags.detach === true,
     dryRun: opts.flags['dry-run'] === true,
   };
+  const deps = { ...defaultDeps(), version: readCliVersion() };
   // `ai@m3`: the same command on another machine. Its own label runs here.
   const host = opts.cmd.startsWith('ai@') ? opts.cmd.slice(3) : null;
   if (host !== null) {
@@ -430,10 +481,10 @@ function cmdAi(opts: ParsedArgs): void {
       process.exit(2);
     }
     if (host.toLowerCase() !== hostLabel().toLowerCase()) {
-      process.exit(runAiRemote(options, host, defaultDeps(), readCliVersion()));
+      process.exit(runAiRemote(options, host, deps));
     }
   }
-  process.exit(runAi(options, defaultDeps()));
+  process.exit(runAi(options, deps));
 }
 
 const parsed = parseArgs(process.argv);

package/src/publish.ts

@@ -11,12 +11,28 @@ export interface PublishOptions {
   bump: BumpKind;
   dryRun: boolean;
   force: boolean;
+  /** `git push --follow-tags` after the tag; `--no-push` turns it off. */
+  push?: boolean;
 }
 
 export interface PreflightCheck {
   name: string;
   ok: boolean;
   message: string;
+  /** A failed check a command at the terminal can fix — `npm login` for an expired session. */
+  fix?: { cmd: string; args: string[] };
+}
+
+/** Where the release goes after the tag. */
+export interface PushPlan {
+  /** Asked for (not `--no-push`). */
+  enabled: boolean;
+  /** `origin/main`; null — the branch has none, nothing to push to. */
+  upstream: string | null;
+  /** Local commits not on the upstream yet — they go with the release. */
+  ahead: number;
+  /** Upstream commits not here: the push would be refused. */
+  behind: number;
 }
 
 export interface PublishPlan {
@@ -27,6 +43,9 @@ export interface PublishPlan {
   newVersion: string;
   bump: BumpKind;
   packageJsonPath: string;
+  /** package-lock.json beside package.json, when there is one: its version goes into the same commit. */
+  lockPath?: string | null;
+  push?: PushPlan;
   preflight: PreflightCheck[];
   preflightPassed: boolean;
   delegatedToMise: boolean;
@@ -82,6 +101,33 @@ function isGitWorkingTreeClean(projectRoot: string): { ok: boolean; detail: stri
 /** Runs npm with these args and returns stdout; throws with `stderr` on a non-zero exit. */
 export type NpmRunner = (args: string[]) => string;
 
+/** Runs git with these args in `cwd` and returns stdout; throws on a non-zero exit. */
+export type GitRunner = (args: string[], cwd: string) => string;
+
+const runGit: GitRunner = (args, cwd) =>
+  execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+/**
+ * The branch's upstream and how far apart they are — from what git knows
+ * since the last fetch; nothing is fetched.
+ */
+export function planPush(projectRoot: string, enabled: boolean, git: GitRunner = runGit): PushPlan {
+  let upstream: string | null = null;
+  try {
+    upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], projectRoot).trim() || null;
+  } catch {
+    return { enabled, upstream: null, ahead: 0, behind: 0 };
+  }
+  const count = (range: string) => {
+    try {
+      return parseInt(git(['rev-list', '--count', range], projectRoot).trim(), 10) || 0;
+    } catch {
+      return 0;
+    }
+  };
+  return { enabled, upstream, ahead: count('@{u}..HEAD'), behind: count('HEAD..@{u}') };
+}
+
 // A caller's `npm run -s` passes `npm_config_loglevel=silent` down, and npm then
 // fails with an empty stderr — no E401 or E404 left to tell the cases apart.
 const runNpm: NpmRunner = (args) =>
@@ -128,11 +174,13 @@ export function publishRegistry(
  */
 export function checkNpmAuth(registry: string | null, npm: NpmRunner): PreflightCheck {
   const where = registry ?? 'npm';
-  const login = registry ? `npm login --registry ${registry}` : 'npm login';
+  const loginArgs = registry ? ['login', '--registry', registry] : ['login'];
+  const login = `npm ${loginArgs.join(' ')}`;
+  const fix = { cmd: 'npm', args: loginArgs };
   try {
     const who = npm(registry ? ['whoami', '--registry', registry] : ['whoami']).trim();
     if (who) return { name: 'npm-auth', ok: true, message: `OK (logged in to ${where} as ${who})` };
-    return { name: 'npm-auth', ok: false, message: `npm whoami answered nothing for ${where}. Run: ${login}` };
+    return { name: 'npm-auth', ok: false, message: `npm whoami answered nothing for ${where}. Run: ${login}`, fix };
   } catch (e: any) {
     const stderr = String(e?.stderr ?? e?.message ?? '');
     if (/E401|ENEEDAUTH/.test(stderr)) {
@@ -140,6 +188,7 @@ export function checkNpmAuth(registry: string | null, npm: NpmRunner): Preflight
         name: 'npm-auth',
         ok: false,
         message: `not logged in to ${where} (the npm session may have expired). Run: ${login}`,
+        fix,
       };
     }
     return {
@@ -174,6 +223,7 @@ export function planPublish(
   audit: AuditResult,
   ctx: Ctx,
   npm: NpmRunner = runNpm,
+  git: GitRunner = runGit,
 ): PublishPlan {
   if (checkMiseOverride(opts.projectRoot)) {
     return {
@@ -288,6 +338,26 @@ export function planPublish(
     });
   }
 
+  const push = planPush(opts.projectRoot, opts.push ?? true, git);
+  if (push.enabled && push.upstream && push.behind > 0) {
+    preflight.push({
+      name: 'push-target',
+      ok: false,
+      message:
+        `${push.upstream} has ${push.behind} commit(s) this branch lacks — the push after npm publish ` +
+        `would be refused. Pull first (or --no-push)`,
+    });
+  } else if (push.enabled) {
+    preflight.push({
+      name: 'push-target',
+      ok: true,
+      message: push.upstream
+        ? `OK (${push.upstream}${push.ahead ? `, ${push.ahead} local commit(s) go with the release` : ''})`
+        : 'no upstream for this branch — the release commit and tag stay local',
+    });
+  }
+
+  const lockPath = path.join(path.dirname(pkgJsonPath), 'package-lock.json');
   const preflightPassed = preflight.every((c) => c.ok);
 
   return {
@@ -298,82 +368,165 @@ export function planPublish(
     newVersion,
     bump: opts.bump,
     packageJsonPath: pkgJsonPath,
+    lockPath: fs.existsSync(lockPath) ? lockPath : null,
+    push,
     preflight,
     preflightPassed,
     delegatedToMise: false,
   };
 }
 
+/** Every failed check has a command that fixes it — run at a terminal, then plan again. */
+export function preflightFixable(plan: PublishPlan): boolean {
+  const failed = plan.preflight.filter((c) => !c.ok);
+  return failed.length > 0 && failed.every((c) => c.fix);
+}
+
+/** Runs a command on this terminal (stdio inherited); throws on a non-zero exit. */
+export type CommandRunner = (cmd: string, args: string[], cwd: string) => void;
+
+export interface PublishDeps {
+  run: CommandRunner;
+  npm: NpmRunner;
+  log: (line: string) => void;
+  sleep: (ms: number) => void;
+  /** How long to wait for the registry to show the new version. */
+  registryWaitMs: number;
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function defaultPublishDeps(): PublishDeps {
+  return {
+    run: (cmd, args, cwd) => {
+      execFileSync(cmd, args, { cwd, stdio: 'inherit' });
+    },
+    npm: runNpm,
+    log: (line) => process.stderr.write(line + '\n'),
+    sleep: sleepSync,
+    registryWaitMs: 180_000,
+  };
+}
+
+/** Set `version` in package-lock.json — the root and its own entry under `packages`. */
+export function bumpLockText(text: string, version: string): string {
+  const lock = JSON.parse(text);
+  lock.version = version;
+  if (lock.packages?.['']) lock.packages[''].version = version;
+  return JSON.stringify(lock, null, 2) + '\n';
+}
+
+/**
+ * npm answers `202 Accepted` and the version shows up a minute or two later;
+ * until then `npm view` and `npx` still see the previous one. Waiting here
+ * turns "is it out?" into an answer. A version that does not show up in time
+ * is not a failure: npm took it.
+ */
+export function waitForRegistry(name: string, version: string, deps: PublishDeps): boolean {
+  const started = Date.now();
+  const deadline = started + deps.registryWaitMs;
+  deps.log(`→ waiting for the registry to show ${name}@${version}...`);
+  for (;;) {
+    try {
+      if (deps.npm(['view', `${name}@${version}`, 'version', '--prefer-online']).trim() === version) {
+        deps.log(`✓ ${name}@${version} is on the registry (${Math.round((Date.now() - started) / 1000)} s after publish)`);
+        return true;
+      }
+    } catch {
+      /* E404 until it is processed */
+    }
+    if (Date.now() >= deadline) break;
+    deps.sleep(10_000);
+  }
+  deps.log(
+    `! ${name}@${version} not visible on the registry after ${Math.round(deps.registryWaitMs / 60_000)} min — ` +
+      `npm accepted it; check later: npm view ${name}@${version} version`,
+  );
+  return false;
+}
+
 /**
  * Execute the publish pipeline. Order is transactional:
- *   1. bump package.json in-place (reversible by file restore).
+ *   1. bump package.json and package-lock.json in place (reversible by file restore).
  *   2. `npm publish` (irreversible — first because npm errors are easier
  *      to recover from than a published-but-uncommitted state).
  *   3. git add + commit + tag (reversible by reset/tag delete, but only
  *      a problem if step 2 succeeded — uncommitted bump after success
  *      is recoverable manually).
- *   4. NOT pushed — that's the user's call.
+ *   4. `git push --follow-tags` to the branch's upstream, unless `--no-push`
+ *      or there is none. The pre-flight refused a branch behind its upstream.
+ *   5. Wait until the registry shows the version.
  *
- * On npm publish failure → restore original package.json contents.
+ * On npm publish failure → restore the original files.
  * Git failures after a successful npm publish leave the user in a
- * partially-released state; they fix it manually (commit/tag what's
+ * partially-released state; they fix it manually (commit/tag/push what's
  * needed) — we don't try to unpublish.
  */
-export function executePublish(plan: PublishPlan): void {
+export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPublishDeps()): void {
   if (plan.delegatedToMise) {
-    process.stderr.write('→ delegating to `mise run publish`...\n');
-    execFileSync('mise', ['run', 'publish'], {
-      cwd: plan.projectRoot,
-      stdio: 'inherit',
-    });
+    deps.log('→ delegating to `mise run publish`...');
+    deps.run('mise', ['run', 'publish'], plan.projectRoot);
     return;
   }
 
-  // 1. Bump package.json in-place (keep original text for revert)
-  const originalText = fs.readFileSync(plan.packageJsonPath, 'utf8');
-  const pkg = JSON.parse(originalText);
-  pkg.version = plan.newVersion;
-  fs.writeFileSync(
-    plan.packageJsonPath,
-    JSON.stringify(pkg, null, 2) + '\n',
-    'utf8',
-  );
-  process.stderr.write(
-    `✓ bumped ${path.relative(plan.projectRoot, plan.packageJsonPath)}: ${plan.currentVersion} → ${plan.newVersion}\n`,
+  // 1. Bump package.json (and the lock) in place, keeping the original text for revert.
+  const originals = new Map<string, string>();
+  const rewrite = (file: string, next: (text: string) => string) => {
+    const text = fs.readFileSync(file, 'utf8');
+    originals.set(file, text);
+    fs.writeFileSync(file, next(text), 'utf8');
+  };
+  rewrite(plan.packageJsonPath, (text) => {
+    const pkg = JSON.parse(text);
+    pkg.version = plan.newVersion;
+    return JSON.stringify(pkg, null, 2) + '\n';
+  });
+  if (plan.lockPath) rewrite(plan.lockPath, (text) => bumpLockText(text, plan.newVersion));
+  const bumped = [...originals.keys()];
+  deps.log(
+    `✓ bumped ${bumped.map((f) => path.relative(plan.projectRoot, f)).join(' and ')}: ${plan.currentVersion} → ${plan.newVersion}`,
   );
 
   // 2. npm publish (interactive — OTP prompt may appear)
-  process.stderr.write(`→ running \`npm publish\` (OTP prompt may appear)...\n`);
-  const pkgDir = path.dirname(plan.packageJsonPath);
+  deps.log('→ running `npm publish` (OTP prompt may appear)...');
   try {
-    execFileSync('npm', ['publish'], { cwd: pkgDir, stdio: 'inherit' });
+    deps.run('npm', ['publish'], path.dirname(plan.packageJsonPath));
   } catch (e: any) {
-    fs.writeFileSync(plan.packageJsonPath, originalText, 'utf8');
-    process.stderr.write(
-      `✗ npm publish failed (exit ${e?.status ?? '?'}); reverted package.json\n`,
-    );
+    for (const [file, text] of originals) fs.writeFileSync(file, text, 'utf8');
+    deps.log(`✗ npm publish failed (exit ${e?.status ?? '?'}); reverted ${bumped.map((f) => path.basename(f)).join(' and ')}`);
     throw new Error('npm publish failed');
   }
-  process.stderr.write(`✓ published ${plan.packageName}@${plan.newVersion}\n`);
+  deps.log(`✓ published ${plan.packageName}@${plan.newVersion}`);
 
   // 3. git add + commit + tag (at project root)
-  execFileSync('git', ['add', plan.packageJsonPath], {
-    cwd: plan.projectRoot,
-    stdio: 'inherit',
-  });
-  execFileSync('git', ['commit', '-m', `release: v${plan.newVersion}`], {
-    cwd: plan.projectRoot,
-    stdio: 'inherit',
-  });
-  execFileSync(
-    'git',
-    ['tag', '-a', `v${plan.newVersion}`, '-m', `v${plan.newVersion}`],
-    { cwd: plan.projectRoot, stdio: 'inherit' },
-  );
-  process.stderr.write(`✓ committed + tagged v${plan.newVersion}\n`);
-  process.stderr.write(
-    `\n! NOT pushed — your call: \`git push --follow-tags\`\n`,
-  );
+  deps.run('git', ['add', '--', ...bumped], plan.projectRoot);
+  deps.run('git', ['commit', '-m', `release: v${plan.newVersion}`, '--', ...bumped], plan.projectRoot);
+  deps.run('git', ['tag', '-a', `v${plan.newVersion}`, '-m', `v${plan.newVersion}`], plan.projectRoot);
+  deps.log(`✓ committed + tagged v${plan.newVersion}`);
+
+  // 4. push
+  const push = plan.push;
+  if (push?.enabled && push.upstream) {
+    deps.log(`→ git push --follow-tags (${push.upstream})...`);
+    try {
+      deps.run('git', ['push', '--follow-tags'], plan.projectRoot);
+    } catch {
+      deps.log(`✗ git push failed — ${plan.packageName}@${plan.newVersion} is published and tagged here; push it: git push --follow-tags`);
+      throw new Error('git push failed');
+    }
+    deps.log(`✓ pushed to ${push.upstream} with tag v${plan.newVersion}`);
+  } else {
+    deps.log(
+      push?.enabled === false
+        ? '! not pushed (--no-push): git push --follow-tags'
+        : '! not pushed — the branch has no upstream: git push --follow-tags -u <remote> <branch>',
+    );
+  }
+
+  // 5. registry
+  waitForRegistry(plan.packageName, plan.newVersion, deps);
 }
 
 export function renderPublishPlan(plan: PublishPlan): string {
@@ -409,14 +562,28 @@ export function renderPublishPlan(plan: PublishPlan): string {
     lines.push(`| ${c.name} | ${c.ok ? 'OK' : 'FAIL'} | ${c.message} |`);
   }
   lines.push('');
-  if (plan.preflightPassed) {
+  const fixable = !plan.preflightPassed && preflightFixable(plan);
+  if (plan.preflightPassed || fixable) {
+    const files = plan.lockPath ? 'package.json and package-lock.json' : 'package.json';
+    const push = plan.push;
     lines.push('## Pipeline (would execute on `vdx publish`)');
     lines.push('');
-    lines.push(`1. Set \`version\` in package.json → \`${plan.newVersion}\``);
+    if (fixable) {
+      const fixes = plan.preflight.filter((c) => !c.ok && c.fix).map((c) => `\`${c.fix!.cmd} ${c.fix!.args.join(' ')}\``);
+      lines.push(`0. ${fixes.join(', ')} — at a terminal, then the pre-flight again`);
+    }
+    lines.push(`1. Set \`version\` in ${files} → \`${plan.newVersion}\``);
     lines.push(`2. \`npm publish\` (cwd = directory containing package.json)`);
-    lines.push(`3. \`git add package.json && git commit -m "release: v${plan.newVersion}"\``);
+    lines.push(`3. \`git commit -m "release: v${plan.newVersion}"\` (${files})`);
     lines.push(`4. \`git tag -a v${plan.newVersion} -m "v${plan.newVersion}"\``);
-    lines.push(`5. (NOT pushed — your call: \`git push --follow-tags\`)`);
+    lines.push(
+      !push?.enabled
+        ? '5. Not pushed (`--no-push`): `git push --follow-tags` is yours'
+        : push.upstream
+          ? `5. \`git push --follow-tags\` → ${push.upstream}${push.ahead ? ` (with ${push.ahead} local commit(s) not pushed yet)` : ''}`
+          : '5. Not pushed: the branch has no upstream',
+    );
+    lines.push(`6. Wait until the registry shows ${plan.newVersion} (up to 3 min)`);
   } else {
     lines.push('> Pre-flight failed. Use `--force` to bypass at your own risk.');
   }