@vodmal/vdx-cli 0.17.0 → 0.19.0

package/README.md

@@ -48,7 +48,8 @@ vdx publish <patch|minor|major> [--dry-run] [--force]
 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)
 vdx <command> --help
@@ -73,7 +74,8 @@ vdx test            # → mise run test (which calls `vitest run` or whatever wa
 # 3. Ship a new minor release of a Node lib
 vdx publish minor   # bump → npm publish (OTP prompt) → git commit + tag (no push)
 
-# 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
 
@@ -90,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.17.0",
+  "version": "0.19.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,28 +922,176 @@ 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;
 }
 
-export function runAi(opts: AiOptions, deps: AiDeps): number {
-  const { log, tmux } = deps;
+/**
+ * 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 {
+  projectRoot: string;
+  environment: Environment;
+  profilePath: string | null;
+  profileDir: string;
+  plan: LaunchPlan;
+}
 
-  const projectRoot = resolveProjectRoot(opts.path);
+/** The project, the profile and the launch plan for `pathArg`; an exit code when there is none. */
+function prepare(pathArg: string, deps: AiDeps): Prepared | number {
+  const { log } = deps;
+
+  const projectRoot = resolveProjectRoot(pathArg);
   if (!projectRoot) {
-    log(`vdx ai: ${path.resolve(opts.path)} is not a directory`);
+    log(`vdx ai: ${path.resolve(pathArg)} is not a directory`);
     return EXIT_USAGE;
   }
 
@@ -959,6 +1139,75 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     log(`vdx ai: ${profilePath ?? 'profile'}: ${e?.message ?? e}`);
     return EXIT_USAGE;
   }
+  return { projectRoot, environment, profilePath, profileDir, plan };
+}
+
+/** The nearest ancestor of `pid` that is the agent: the session a hook or a shell tool runs in. */
+export function findOwnAgent(procs: ProcInfo[], pid: number, command: string): ProcInfo | null {
+  const byPid = new Map(procs.map((p) => [p.pid, p]));
+  let cur = byPid.get(pid);
+  for (let hops = 0; cur && cur.ppid > 1 && hops < 64; hops++) {
+    cur = byPid.get(cur.ppid);
+    if (cur && isAgentProcess(cur, command)) return cur;
+  }
+  return null;
+}
+
+/**
+ * `vdx ai --check`: what an agent should know about how it is launched here,
+ * and whether the session it runs in carries the profile's flags. Prints
+ * nothing without a profile — on such a machine `vdx ai` decides nothing.
+ */
+export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = process.pid): number {
+  if (!resolveEnvironmentPath(deps.env, deps.home)) return EXIT_OK;
+  const prepared = prepare(pathArg, deps);
+  if (typeof prepared === 'number') return prepared;
+  const { projectRoot, profilePath, plan } = prepared;
+
+  const lines = [
+    `${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. A project's agent on another machine: ` +
+      `\`vdx ai@<machine>\`. More: \`vdx ai --help\`.`,
+  ];
+  const own = findOwnAgent(deps.processes(), selfPid, plan.command);
+  if (!own) {
+    lines.push(`· no ${plan.command} among the ancestors of this process — no session to compare with the profile.`);
+    deps.out(lines.join('\n') + '\n');
+    return EXIT_OK;
+  }
+  const missing = missingArgs(own.args, plan.args);
+  const why = plan.matched.length ? ` (profile conditions met here: ${plan.matched.join(', ')})` : '';
+  if (missing.length === 0) {
+    lines.push(`✓ this session carries the profile's flags${why}.`);
+    deps.out(lines.join('\n') + '\n');
+    return EXIT_OK;
+  }
+  const root = shellQuote(projectRoot);
+  lines.push(
+    `✗ this session runs without ${missing.join(' ')}${why}. Hand the user the fix — ` +
+      (deps.env['TMUX']
+        ? `\`vdx ai --restart ${root}\`: it stops this session and starts it again with the profile's flags` +
+          (plan.resumeArgs.length ? `, resuming the conversation (${plan.resumeArgs.join(' ')})` : '') +
+          `. Do not run it yourself: it ends this session.`
+        : `this session runs outside tmux, so vdx cannot restart it: the user exits it and runs \`vdx ai ${root}\`.`),
+  );
+  deps.out(lines.join('\n') + '\n');
+  return EXIT_DRIFT;
+}
+
+export function runAi(opts: AiOptions, deps: AiDeps): number {
+  const { log, tmux } = deps;
+
+  const prepared = prepare(opts.path, deps);
+  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: [] };
 
@@ -972,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') {
@@ -1005,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: ` +
@@ -1015,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/doctor.ts

@@ -339,42 +339,45 @@ function checkClaudeCode(): CheckResult {
   };
 }
 
-function checkClaudeCodePlugin(): CheckResult {
-  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
-  if (!fs.existsSync(settingsPath)) {
-    return {
-      id: 'claude-plugin',
-      label: 'Claude Code vdx plugin',
-      status: 'warning',
-      message: '~/.claude/settings.json not found',
-      remedy: 'Install Claude Code, then add vdx marketplace (see README)',
-    };
-  }
-  try {
-    const raw = fs.readFileSync(settingsPath, 'utf8');
-    if (raw.includes('VoDmAl/vdx') || raw.includes('vdx/marketplace')) {
-      return {
-        id: 'claude-plugin',
-        label: 'Claude Code vdx plugin',
-        status: 'ok',
-        message: 'vdx marketplace registered',
-      };
+const PLUGIN_INSTALL_HINT =
+  'in Claude Code: /plugin marketplace add VoDmAl/ai-dev-plugins, then /plugin install vdx from it';
+
+/**
+ * The vdx plugin as Claude Code records it: `vdx@<marketplace>` in
+ * plugins/installed_plugins.json, and not switched off in settings.json
+ * enabledPlugins. Whichever marketplace brought it — the plugin ships through
+ * the owner's marketplace (VoDmAl/ai-dev-plugins), not a vdx one of its own.
+ */
+export function checkClaudeCodePlugin(
+  claudeDir: string = process.env['CLAUDE_CONFIG_DIR'] || path.join(os.homedir(), '.claude'),
+): CheckResult {
+  const base = { id: 'claude-plugin', label: 'Claude Code vdx plugin' };
+  const readJson = (file: string): any => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(claudeDir, file), 'utf8'));
+    } catch {
+      return null;
     }
+  };
+  const installed = readJson(path.join('plugins', 'installed_plugins.json'));
+  if (!installed) {
     return {
-      id: 'claude-plugin',
-      label: 'Claude Code vdx plugin',
-      status: 'warning',
-      message: 'vdx marketplace not registered',
-      remedy: 'Add github.com/VoDmAl/vdx/marketplace to extraKnownMarketplaces',
-    };
-  } catch (e: any) {
-    return {
-      id: 'claude-plugin',
-      label: 'Claude Code vdx plugin',
+      ...base,
       status: 'warning',
-      message: `cannot read settings.json: ${e?.message ?? e}`,
+      message: `no plugin records in ${claudeDir}/plugins/installed_plugins.json`,
+      remedy: PLUGIN_INSTALL_HINT,
     };
   }
+  const key = Object.keys(installed.plugins ?? {}).find((k) => k.startsWith('vdx@'));
+  if (!key) {
+    return { ...base, status: 'warning', message: 'not installed', remedy: PLUGIN_INSTALL_HINT };
+  }
+  const version = installed.plugins[key]?.[0]?.version;
+  const label = `${key}${typeof version === 'string' ? ` ${version}` : ''}`;
+  if (readJson('settings.json')?.enabledPlugins?.[key] === false) {
+    return { ...base, status: 'warning', message: `${label} installed but disabled`, remedy: `/plugin enable ${key}` };
+  }
+  return { ...base, status: 'ok', message: label };
 }
 
 /**
@@ -543,7 +546,7 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkVdxVersion,
   checkVdx,
   checkClaudeCode,
-  checkClaudeCodePlugin,
+  () => checkClaudeCodePlugin(),
   checkNode,
   checkGit,
   checkMise,

package/src/index.ts

@@ -29,7 +29,8 @@ import {
   type PublishOptions,
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
-import { runAi, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
+import { runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
+import { isConversationId } from './conversations.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
 
@@ -39,7 +40,7 @@ const USAGE = `Usage:
   vdx init    [project_path]  [--stack <id>] [--baseline <ref>] [--dry-run] [--force]                     (default: cwd)
   vdx publish <patch|minor|major> [--dry-run] [--force]
   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,11 +74,24 @@ 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
+  --check       for the agent's own session: how the agent here is launched, and
+                whether this session carries the profile's flags (the vdx plugin's
+                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.
@@ -124,10 +138,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'],
+    bools: ['new', 'restart', 'resume', 'detach', 'dry-run', 'check'],
+    values: ['conversation'],
     positionals: 1,
   },
   ...Object.fromEntries(
@@ -401,13 +416,35 @@ function cmdDoctor(opts: ParsedArgs): void {
 }
 
 function cmdAi(opts: ParsedArgs): void {
+  if (opts.flags.check === true) {
+    // About the session this runs in — there is nothing to start, and no other machine.
+    const others = Object.keys(opts.flags).filter((f) => f !== 'check');
+    if (others.length > 0 || opts.cmd !== 'ai') {
+      process.stderr.write(
+        `vdx ai: --check takes only the project path (not ${opts.cmd !== 'ai' ? opts.cmd : `--${others.join(', --')}`})\n`,
+      );
+      process.exit(2);
+    }
+    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) {
@@ -416,10 +453,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);