@vodmal/vdx-cli 0.24.0 → 0.25.0

package/src/audit.ts

@@ -28,12 +28,11 @@ export interface AuditResult {
  *   3. fallback на root ctx.
  *
  * Возвращает `{ ctx, relPath }` где relPath — относительный путь либо null
- * (если subpackage не разрезолвился — будем использовать root).
+ * (если subpackage не разрезолвился — будем использовать root). Файл, которого
+ * нет в subpackage, ищется в корне (`fallbackRoot`): `.github/` и `.gitignore`
+ * у репо одни.
  */
-function resolveSubpackageCtx(
-  ctx: Ctx,
-  manifest: VdxManifest | null,
-): { ctx: Ctx; relPath: string | null } {
+function resolveSubpackageCtx(ctx: Ctx, manifest: VdxManifest | null): { ctx: Ctx; relPath: string | null } {
   let relPath: string | null = null;
   let subpackageStack: string | null = null;
 
@@ -44,9 +43,7 @@ function resolveSubpackageCtx(
       relPath = p;
       subpackageStack = stackForDir(abs);
     } else {
-      process.stderr.write(
-        `warning: primary_subpackage "${p}" does not exist — falling back to root\n`,
-      );
+      process.stderr.write(`warning: primary_subpackage "${p}" does not exist — falling back to root\n`);
     }
   } else {
     const subs = findSubPackages(ctx.projectRoot);
@@ -68,11 +65,23 @@ function resolveSubpackageCtx(
       projectRoot: path.join(ctx.projectRoot, relPath),
       stack: subpackageStack ?? ctx.stack,
       cache: new Map(),
+      fallbackRoot: ctx.projectRoot,
     },
     relPath,
   };
 }
 
+/**
+ * Ctx осей без `applies_to`. Корень мета-репо (без своего манифеста стека)
+ * дочитывает недостающие файлы из subpackage: `engines` в `cli/package.json`
+ * — тоже про воспроизводимость всего репо. У корня со своим манифестом
+ * подстановки нет.
+ */
+function rootAxisCtx(ctx: Ctx, subpackage: Ctx, relPath: string | null): Ctx {
+  if (!relPath || stackForDir(ctx.projectRoot) !== null) return ctx;
+  return { ...ctx, cache: new Map(), fallbackRoot: subpackage.projectRoot };
+}
+
 export function audit(
   rubric: Rubric,
   ctx: Ctx,
@@ -92,6 +101,7 @@ export function audit(
   }
 
   const { ctx: subpackageCtx, relPath: subpackagePath } = resolveSubpackageCtx(ctx, manifest);
+  const rootCtx = rootAxisCtx(ctx, subpackageCtx, subpackagePath);
 
   const perAxis: AuditResult['per_axis'] = [];
   for (const axis of rubric.axes) {
@@ -106,7 +116,7 @@ export function audit(
       });
       continue;
     }
-    const evalCtx = axis.applies_to ? subpackageCtx : ctx;
+    const evalCtx = axis.applies_to ? subpackageCtx : rootCtx;
     if (axis.applies_to && !axis.applies_to.includes(evalCtx.stack)) {
       perAxis.push({
         axis_id: axis.id,

package/src/author.ts

@@ -61,8 +61,24 @@ export function remoteParts(url: string): { host: string; group: string; path: s
 
 /** Words that say nothing about whose repo it is. */
 const GENERIC = new Set([
-  'git', 'com', 'org', 'name', 'www', 'ssh', 'http', 'https', 'the', 'app', 'mcp',
-  'github', 'gitlab', 'dev', 'net', 'vorobyev', 'vodmal', 'dmitry',
+  'git',
+  'com',
+  'org',
+  'name',
+  'www',
+  'ssh',
+  'http',
+  'https',
+  'the',
+  'app',
+  'mcp',
+  'github',
+  'gitlab',
+  'dev',
+  'net',
+  'vorobyev',
+  'vodmal',
+  'dmitry',
 ]);
 
 export function nameTokens(dir: string, remotePath: string): Set<string> {
@@ -77,7 +93,11 @@ export function nameTokens(dir: string, remotePath: string): Set<string> {
 function describe(dir: string): PoolRepo {
   const cfg = git(dir, ['config', '--local', '--get-regexp', '^(user\\.(name|email)|remote\\.origin\\.url)$']) ?? '';
   const val = (key: string) =>
-    cfg.split('\n').find((l) => l.toLowerCase().startsWith(`${key} `))?.slice(key.length + 1).trim() ?? '';
+    cfg
+      .split('\n')
+      .find((l) => l.toLowerCase().startsWith(`${key} `))
+      ?.slice(key.length + 1)
+      .trim() ?? '';
   const email = val('user.email');
   const remote = remoteParts(val('remote.origin.url'));
   return {
@@ -177,11 +197,10 @@ export function rankAuthors(dir: string, pool: PoolRepo[]): AuthorCandidate[] {
   }
 
   const fallbackName = [...names.values()].flatMap((m) => [...m.entries()]).sort((a, b) => b[1] - a[1])[0]?.[0] ?? '';
-  return ranked
-    .map(([email, s]) => {
-      const byName = [...(names.get(email)?.entries() ?? [])].sort((a, b) => b[1] - a[1]);
-      return { email, name: byName[0]?.[0] ?? fallbackName, score: s, why: why.get(email) ?? [] };
-    });
+  return ranked.map(([email, s]) => {
+    const byName = [...(names.get(email)?.entries() ?? [])].sort((a, b) => b[1] - a[1]);
+    return { email, name: byName[0]?.[0] ?? fallbackName, score: s, why: why.get(email) ?? [] };
+  });
 }
 
 export function writeAuthor(dir: string, author: Author): boolean {

package/src/clone-checks.ts

@@ -95,12 +95,14 @@ export function checkRepoHooks(root: string | null): CheckResult | null {
         remedy: `chmod +x ${hooksPath}/*`,
       };
     }
-    return bodyProblems(id, label, [...hooks.values()]) ?? {
-      id,
-      label,
-      status: 'ok',
-      message: `${hooks.size} hook(s) active via ${hooksPath}`,
-    };
+    return (
+      bodyProblems(id, label, [...hooks.values()]) ?? {
+        id,
+        label,
+        status: 'ok',
+        message: `${hooks.size} hook(s) active via ${hooksPath}`,
+      }
+    );
   }
 
   const states = cloneHookStates(root, ctx, frameworks);
@@ -110,7 +112,9 @@ export function checkRepoHooks(root: string | null): CheckResult | null {
       id,
       label,
       status: 'warning',
-      message: off.map((s) => `${s.framework.id} (${s.framework.declaredIn}): ${s.problem} — those hooks never run`).join('; '),
+      message: off
+        .map((s) => `${s.framework.id} (${s.framework.declaredIn}): ${s.problem} — those hooks never run`)
+        .join('; '),
       ...(off[0]!.remedy ? { remedy: off[0]!.remedy } : {}),
     };
   }
@@ -149,7 +153,8 @@ function bodyProblems(id: string, label: string, bodies: string[]): CheckResult
       label,
       status: 'warning',
       message: `hooks call ${missing.join(', ')} — not on this machine, the commit fails or the gate is skipped`,
-      remedy: 'install what the hook calls here, or move the hook out of the repository (a personal hook in git config)',
+      remedy:
+        'install what the hook calls here, or move the hook out of the repository (a personal hook in git config)',
     };
   }
   return null;

package/src/conversations.ts

@@ -179,7 +179,10 @@ export function machineOf(c: Conversation, host: string): string | null {
 }
 
 /** The newest conversation of each machine (unknown counts as one), newest first. */
-export function latestPerMachine(conversations: Conversation[], machine: (c: Conversation) => string | null): Conversation[] {
+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);
@@ -187,7 +190,6 @@ export function latestPerMachine(conversations: Conversation[], machine: (c: Con
   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
@@ -203,6 +205,18 @@ export function liveConversationId(env: NodeJS.ProcessEnv, home: string, pid: nu
   }
 }
 
+/** When a running Claude Code process started (ms), from the same session file; null — not known. */
+export function liveStartedAt(env: NodeJS.ProcessEnv, home: string, pid: number): number | null {
+  try {
+    const file = path.join(claudeConfigDir(env, home), 'sessions', `${pid}.json`);
+    const data: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const at = typeof data === 'object' && data !== null ? (data as { startedAt?: unknown }).startedAt : undefined;
+    return typeof at === 'number' ? at : null;
+  } catch {
+    return null;
+  }
+}
+
 /** A Claude Code process running right now, and the conversation it is in. */
 export interface LiveSession {
   pid: number;
@@ -226,7 +240,8 @@ export function parseLiveSessions(text: string): LiveSession[] {
     } catch {
       continue;
     }
-    if (!Number.isInteger(data?.pid) || typeof data?.sessionId !== 'string' || !isConversationId(data.sessionId)) continue;
+    if (!Number.isInteger(data?.pid) || typeof data?.sessionId !== 'string' || !isConversationId(data.sessionId))
+      continue;
     out.push({
       pid: data.pid,
       conversation: data.sessionId,
@@ -282,7 +297,11 @@ export const LIVE_SESSIONS_SCRIPT =
   '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[] {
+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 {

package/src/doctor.ts

@@ -6,7 +6,12 @@ import { execFileSync } from 'node:child_process';
 import { effectiveAuthor, isGitRepo, rankAuthors, scanPool } from './author.ts';
 import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
 import { checkRepoHooks } from './clone-checks.ts';
-import { checkPersonalHooks, defaultPersonalHookDeps, fixPersonalHooks, type PersonalHookDeps } from './personal-hooks.ts';
+import {
+  checkPersonalHooks,
+  defaultPersonalHookDeps,
+  fixPersonalHooks,
+  type PersonalHookDeps,
+} from './personal-hooks.ts';
 
 export type CheckStatus = 'ok' | 'warning' | 'missing';
 
@@ -39,11 +44,7 @@ export interface DoctorReport {
 
 export function readCliVersion(): string {
   try {
-    const pkgPath = path.resolve(
-      path.dirname(fileURLToPath(import.meta.url)),
-      '..',
-      'package.json',
-    );
+    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
     const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
     return raw.version ?? 'unknown';
   } catch {
@@ -315,8 +316,7 @@ function checkVdx(): CheckResult {
     status: 'ok',
     level,
     message: `${tag} — works inside this project only (${found})`,
-    remedy:
-      'npm i -g @vodmal/vdx-cli  OR  add `alias vdx="npx -y -p @vodmal/vdx-cli vdx"` to your shell rc',
+    remedy: 'npm i -g @vodmal/vdx-cli  OR  add `alias vdx="npx -y -p @vodmal/vdx-cli vdx"` to your shell rc',
   };
 }
 
@@ -458,9 +458,7 @@ export function runDoctorCheck(
   );
   return rows
     .map(
-      (c) =>
-        `vdx doctor: ${c.label} — ${c.message}.` +
-        (c.remedy ? ` Fix, on the user's word: \`${c.remedy}\`.` : ''),
+      (c) => `vdx doctor: ${c.label} — ${c.message}.` + (c.remedy ? ` Fix, on the user's word: \`${c.remedy}\`.` : ''),
     )
     .join('\n');
 }

package/src/evaluator.ts

@@ -108,7 +108,7 @@ export function predicateNames(p: Predicate): string[] {
     const obj = q as Record<string, any>;
     if ('all_of' in obj) return (obj.all_of as Predicate[]).forEach(walk);
     if ('any_of' in obj) return (obj.any_of as Predicate[]).forEach(walk);
-    if ('at_least_n_of' in obj) return (obj.at_least_n_of?.predicates as Predicate[] ?? []).forEach(walk);
+    if ('at_least_n_of' in obj) return ((obj.at_least_n_of?.predicates as Predicate[]) ?? []).forEach(walk);
     if ('not' in obj) return walk(obj.not);
     if ('fn' in obj) {
       out.push(String(obj.fn));

package/src/facts.ts

@@ -7,16 +7,41 @@ export interface Ctx {
   projectRoot: string;
   stack: string;
   cache: Map<string, unknown>;
+  /**
+   * Meta repo: the other half, where a file missing here is looked for — the repo root
+   * for an axis evaluated in the primary subpackage (`.github/` lives there), the
+   * subpackage for an axis evaluated in a root without a stack manifest of its own.
+   */
+  fallbackRoot?: string;
+}
+
+/** Absolute path of `rel`: here, else in `fallbackRoot` when it is there. */
+function locate(ctx: Ctx, rel: string): string {
+  const here = path.join(ctx.projectRoot, rel);
+  if (ctx.fallbackRoot === undefined || fs.existsSync(here)) return here;
+  const there = path.join(ctx.fallbackRoot, rel);
+  return fs.existsSync(there) ? there : here;
+}
+
+/** The same directory without the fallback: a project's tasks are the ones its own runner sees. */
+function ownCtx(ctx: Ctx): Ctx {
+  if (ctx.fallbackRoot === undefined) return ctx;
+  let own = ctx.cache.get('ctx:own') as Ctx | undefined;
+  if (!own) {
+    own = { projectRoot: ctx.projectRoot, stack: ctx.stack, cache: new Map() };
+    ctx.cache.set('ctx:own', own);
+  }
+  return own;
 }
 
 export function fileExists(ctx: Ctx, rel: string): boolean {
-  return fs.existsSync(path.join(ctx.projectRoot, rel));
+  return fs.existsSync(locate(ctx, rel));
 }
 
 export function readText(ctx: Ctx, rel: string): string | null {
   const key = `file:${rel}`;
   if (ctx.cache.has(key)) return ctx.cache.get(key) as string | null;
-  const abs = path.join(ctx.projectRoot, rel);
+  const abs = locate(ctx, rel);
   try {
     const t = fs.readFileSync(abs, 'utf8');
     ctx.cache.set(key, t);
@@ -107,34 +132,38 @@ export function resolveConfigPath(root: unknown, jsonpath: string): unknown {
   return cur;
 }
 
-/** Aggregated task names from mise.toml, composer scripts, npm scripts, Makefile. */
+/**
+ * Aggregated task names from mise.toml, composer scripts, npm scripts, Makefile.
+ * Without the fallback: `vdx test` here runs this directory's tasks, not the other half's.
+ */
 export function listAllTasks(ctx: Ctx): Set<string> {
   const key = 'tasks:all';
   if (ctx.cache.has(key)) return ctx.cache.get(key) as Set<string>;
   const tasks = new Set<string>();
+  const own = ownCtx(ctx);
 
-  const miseT = readToml(ctx, 'mise.toml');
+  const miseT = readToml(own, 'mise.toml');
   if (miseT?.tasks && typeof miseT.tasks === 'object') {
     for (const k of Object.keys(miseT.tasks as object)) tasks.add(k);
   }
 
-  const composer = readJson(ctx, 'composer.json');
+  const composer = readJson(own, 'composer.json');
   if (composer?.scripts && typeof composer.scripts === 'object') {
     for (const k of Object.keys(composer.scripts)) tasks.add(k);
   }
 
-  const pkg = readJson(ctx, 'package.json');
+  const pkg = readJson(own, 'package.json');
   if (pkg?.scripts && typeof pkg.scripts === 'object') {
     for (const k of Object.keys(pkg.scripts)) tasks.add(k);
   }
 
   // monorepo-ish fallback: server/package.json (см. bookmap)
-  const serverPkg = readJson(ctx, 'server/package.json');
+  const serverPkg = readJson(own, 'server/package.json');
   if (serverPkg?.scripts && typeof serverPkg.scripts === 'object') {
     for (const k of Object.keys(serverPkg.scripts)) tasks.add(`server:${k}`);
   }
 
-  const make = readText(ctx, 'Makefile');
+  const make = readText(own, 'Makefile');
   if (make) {
     const lines = make.split('\n');
     for (const line of lines) {
@@ -176,7 +205,7 @@ export function expandPaths(paths: string[], ctx: Ctx): string[] {
       if (m && m[1] && m[2]) {
         const dir = m[1];
         const ext = m[2];
-        const abs = path.join(ctx.projectRoot, dir);
+        const abs = locate(ctx, dir);
         try {
           const files = fs.readdirSync(abs);
           for (const f of files) {
@@ -224,8 +253,19 @@ export function stackForDir(dir: string): string | null {
 }
 
 const SUBPACKAGE_SCAN_IGNORE = new Set([
-  'node_modules', 'vendor', 'dist', 'build', 'out', 'target',
-  '.git', '.next', '__pycache__', '.venv', 'venv', '.cache', 'coverage',
+  'node_modules',
+  'vendor',
+  'dist',
+  'build',
+  'out',
+  'target',
+  '.git',
+  '.next',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.cache',
+  'coverage',
 ]);
 
 export interface SubPackage {

package/src/gha.ts

@@ -120,7 +120,10 @@ export function readWorkflows(ctx: Ctx): GhaWorkflow[] {
   const out: GhaWorkflow[] = [];
   let files: string[] = [];
   try {
-    files = fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)).sort();
+    files = fs
+      .readdirSync(dir)
+      .filter((f) => /\.ya?ml$/.test(f))
+      .sort();
   } catch {
     files = [];
   }

package/src/hooks.ts

@@ -36,11 +36,29 @@ export interface HookFramework {
 }
 
 export const GIT_HOOK_EVENTS = new Set([
-  'applypatch-msg', 'pre-applypatch', 'post-applypatch', 'pre-commit', 'pre-merge-commit',
-  'prepare-commit-msg', 'commit-msg', 'post-commit', 'pre-rebase', 'post-checkout', 'post-merge',
-  'pre-push', 'pre-auto-gc', 'post-rewrite', 'reference-transaction', 'push-to-checkout',
-  'post-index-change', 'sendemail-validate', 'fsmonitor-watchman', 'p4-changelist',
-  'p4-prepare-changelist', 'p4-post-changelist', 'p4-pre-submit',
+  'applypatch-msg',
+  'pre-applypatch',
+  'post-applypatch',
+  'pre-commit',
+  'pre-merge-commit',
+  'prepare-commit-msg',
+  'commit-msg',
+  'post-commit',
+  'pre-rebase',
+  'post-checkout',
+  'post-merge',
+  'pre-push',
+  'pre-auto-gc',
+  'post-rewrite',
+  'reference-transaction',
+  'push-to-checkout',
+  'post-index-change',
+  'sendemail-validate',
+  'fsmonitor-watchman',
+  'p4-changelist',
+  'p4-prepare-changelist',
+  'p4-post-changelist',
+  'p4-pre-submit',
 ]);
 
 /** Install steps a clone runs anyway: npm-family lifecycle scripts, composer's, the vdx `up` task. */
@@ -173,7 +191,10 @@ export function detectHookFrameworks(ctx: Ctx): HookFramework[] {
       id: 'husky',
       declaredIn: '.husky/',
       hooks: husky,
-      installedBy: findStep(steps.filter((s) => s.where.startsWith('package.json') || s.where === 'mise task up'), /(^|[\s;&|(])husky(\s+install)?(?=$|[\s;&|)])/m),
+      installedBy: findStep(
+        steps.filter((s) => s.where.startsWith('package.json') || s.where === 'mise task up'),
+        /(^|[\s;&|(])husky(\s+install)?(?=$|[\s;&|)])/m,
+      ),
       manualInstall: 'npx husky',
       hooksPath: '.husky/_',
       copies: false,
@@ -247,7 +268,10 @@ export function detectHookFrameworks(ctx: Ctx): HookFramework[] {
         id: 'cghooks',
         declaredIn: 'composer.json extra.hooks',
         hooks,
-        installedBy: findStep(steps.filter((s) => s.where.startsWith('composer') || s.where === 'mise task up'), /\bcghooks\s+(add|update)\b/),
+        installedBy: findStep(
+          steps.filter((s) => s.where.startsWith('composer') || s.where === 'mise task up'),
+          /\bcghooks\s+(add|update)\b/,
+        ),
         manualInstall: 'vendor/bin/cghooks update',
         hooksPath: null,
         copies: true,
@@ -353,7 +377,13 @@ export function cloneHookStates(root: string, ctx: Ctx, frameworks: HookFramewor
     }
     if (fw.id === 'lefthook') {
       const foreign = events.filter((e) => !/lefthook/.test(readFile(path.join(dir, e))));
-      if (foreign.length > 0) return { framework: fw, enabled: false, problem: `${foreign.join(', ')} in ${path.relative(root, dir)} is not lefthook's`, remedy };
+      if (foreign.length > 0)
+        return {
+          framework: fw,
+          enabled: false,
+          problem: `${foreign.join(', ')} in ${path.relative(root, dir)} is not lefthook's`,
+          remedy,
+        };
     }
     if (fw.copies) {
       const stale = events.filter((e) => {
@@ -361,7 +391,12 @@ export function cloneHookStates(root: string, ctx: Ctx, frameworks: HookFramewor
         return fw.hooks.get(e)!.some((cmd) => !body.includes(cmd.trim()));
       });
       if (stale.length > 0) {
-        return { framework: fw, enabled: false, problem: `installed ${stale.join(', ')} older than ${fw.declaredIn}`, remedy };
+        return {
+          framework: fw,
+          enabled: false,
+          problem: `installed ${stale.join(', ')} older than ${fw.declaredIn}`,
+          remedy,
+        };
       }
     }
     return { framework: fw, enabled: true };
@@ -386,8 +421,7 @@ function readFile(file: string): string {
  * anywhere in a script says nothing about whether the hook still does its job,
  * while an unset variable inside the guard means the guarded block never runs.
  */
-const GATING_VAR_RE =
-  /\[\s+-[nxfse]\s+"\$\{([A-Z][A-Z0-9_]*)(?::-[^}]*)?\}"|\[\s+-[nxfse]\s+"\$([A-Z][A-Z0-9_]*)"/g;
+const GATING_VAR_RE = /\[\s+-[nxfse]\s+"\$\{([A-Z][A-Z0-9_]*)(?::-[^}]*)?\}"|\[\s+-[nxfse]\s+"\$([A-Z][A-Z0-9_]*)"/g;
 
 export function unsetGatingVars(commands: string[], env: NodeJS.ProcessEnv = process.env): string[] {
   const out = new Set<string>();
@@ -406,7 +440,8 @@ export function unsetGatingVars(commands: string[], env: NodeJS.ProcessEnv = pro
  * Only what is run: a path in an argument or an `echo` says nothing about
  * whether the hook works here.
  */
-const MACHINE_PROGRAM_RE = /^(?:"((?:\$HOME|\$\{HOME\}|~|\/Users|\/home|\/Volumes)\/[^"]+)"|((?:\$HOME|\$\{HOME\}|~|\/Users|\/home|\/Volumes)\/[^\s"';|&)]+))/;
+const MACHINE_PROGRAM_RE =
+  /^(?:"((?:\$HOME|\$\{HOME\}|~|\/Users|\/home|\/Volumes)\/[^"]+)"|((?:\$HOME|\$\{HOME\}|~|\/Users|\/home|\/Volumes)\/[^\s"';|&)]+))/;
 
 export function missingMachinePaths(commands: string[], home: string = os.homedir()): string[] {
   const out = new Set<string>();

package/src/index.ts

@@ -4,12 +4,7 @@ import { execFileSync } from 'node:child_process';
 import { loadRubric } from './rubric.ts';
 import { loadManifest, loadOverrides } from './manifest.ts';
 import { autoDetectStack, type Ctx } from './facts.ts';
-import {
-  LIFECYCLE_VERBS,
-  type LifecycleVerb,
-  resolveLifecycleVerb,
-  renderResolveError,
-} from './run.ts';
+import { LIFECYCLE_VERBS, type LifecycleVerb, resolveLifecycleVerb, renderResolveError } from './run.ts';
 import { audit } from './audit.ts';
 import {
   reportMarkdown,
@@ -19,7 +14,14 @@ import {
   reportDoctorJson,
   reportDoctorAnsi,
 } from './report.ts';
-import { runDoctor, runDoctorCheck, runDoctorFix, resolveDoctorCtx, looksLikeProject, readCliVersion } from './doctor.ts';
+import {
+  runDoctor,
+  runDoctorCheck,
+  runDoctorFix,
+  resolveDoctorCtx,
+  looksLikeProject,
+  readCliVersion,
+} from './doctor.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
 import {
   planPublish,
@@ -66,6 +68,7 @@ interface CommandSpec {
 }
 
 const AI_HELP = `Starts your agent in the project, or attaches to the one already running there.
+Several running there: a list to pick from — Enter takes the newest.
 Which agent, its flags and whether it runs in tmux come from your profile:
 $VDX_ENVIRONMENT, else ~/.vdx-environment.yaml, else a plain claude/codex.
 
@@ -75,15 +78,20 @@ 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
-  --focused     a session nothing wakes: the agent, its hooks and MCP servers get
-                VDX_FOCUSED=1 — for the plugins that wake sessions to leave it
-                alone — and the profile's rules marked \`wakes: true\` (a channel
-                flag) are left out. A running agent keeps its mode; --restart
-                applies this one
+  --new         a new conversation instead of continuing the last one; an agent
+                already running here keeps running, the new one starts next to
+                it (a new tmux window)
+  --focused     a new conversation, as --new, in a session nothing wakes: the
+                agent, its hooks and MCP servers get VDX_FOCUSED=1 — for the
+                plugins that wake sessions to leave it alone — and the profile's
+                rules marked \`wakes: true\` (a channel flag) are left out. Back
+                to it: --focused --conversation <id>. A running agent keeps its
+                mode: plain vdx ai attaches to it as it is
   --conversation <id>
-                continue this Claude Code conversation
-  --restart     restart the running agent in its pane — applies a changed profile.
+                continue this Claude Code conversation: attach to the agent in
+                it, or start one next to the agents running here
+  --restart     restart the running agent in its pane — applies a changed profile;
+                with --new, --focused or --conversation, it is replaced by that.
                 Without it, an agent running without the profile's flags is
                 a question in a terminal: Enter attaches to it as is, r
                 restarts it, q leaves it
@@ -251,7 +259,9 @@ function checkArgs(name: string, opts: ParsedArgs): ParsedArgs {
     process.exit(2);
   };
   const unknown = [
-    ...Object.keys(flags).filter((f) => !bools.includes(f) && !values.includes(f)).map((f) => `--${f}`),
+    ...Object.keys(flags)
+      .filter((f) => !bools.includes(f) && !values.includes(f))
+      .map((f) => `--${f}`),
     ...positionals.filter((p) => p.startsWith('-')),
   ];
   if (unknown.length > 0) fail(`unknown option ${unknown.join(', ')}`);
@@ -281,8 +291,7 @@ function cmdAudit(opts: ParsedArgs): void {
   const rubricPath = (opts.flags.rubric as string) || DEFAULT_RUBRIC;
   const rubric = loadRubric(rubricPath);
 
-  const stack =
-    (opts.flags.stack as string) || manifest?.stack || autoDetectStack(projectRoot);
+  const stack = (opts.flags.stack as string) || manifest?.stack || autoDetectStack(projectRoot);
 
   const ctx: Ctx = {
     projectRoot,
@@ -293,8 +302,7 @@ function cmdAudit(opts: ParsedArgs): void {
   const baselineRef = manifest?.baseline ?? `file://${rubricPath}`;
   const result = audit(rubric, ctx, overrides, baselineRef, manifest);
 
-  const formatFlag =
-    typeof opts.flags.format === 'string' ? opts.flags.format : undefined;
+  const formatFlag = typeof opts.flags.format === 'string' ? opts.flags.format : undefined;
   const wantJson = opts.flags.json === true || formatFlag === 'json';
   const wantMarkdown = formatFlag === 'markdown' || formatFlag === 'md';
   const wantAnsi = formatFlag === 'ansi';
@@ -347,9 +355,7 @@ function cmdInit(opts: ParsedArgs): void {
 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] [--no-push]\n',
-    );
+    process.stderr.write('Usage: vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]\n');
     process.exit(1);
   }
   const bump = bumpArg as BumpKind;
@@ -431,8 +437,7 @@ function cmdRun(verb: LifecycleVerb): void {
   } catch (e: any) {
     if (e?.code === 'ENOENT') {
       process.stderr.write(
-        `vdx: \`mise\` binary not found on PATH\n` +
-          `hint: install mise — https://mise.jdx.dev/getting-started.html\n`,
+        `vdx: \`mise\` binary not found on PATH\n` + `hint: install mise — https://mise.jdx.dev/getting-started.html\n`,
       );
       process.exit(127);
     }
@@ -454,7 +459,9 @@ function cmdDoctor(opts: ParsedArgs): void {
   if (opts.flags.fix === true) {
     try {
       const done = runDoctorFix();
-      process.stderr.write(done.length > 0 ? done.map((d) => `✓ ${d}`).join('\n') + '\n' : 'nothing to fix in ~/.gitconfig\n');
+      process.stderr.write(
+        done.length > 0 ? done.map((d) => `✓ ${d}`).join('\n') + '\n' : 'nothing to fix in ~/.gitconfig\n',
+      );
     } catch (e: any) {
       process.stderr.write(`vdx doctor --fix: ${e?.message ?? String(e)}\n`);
       process.exit(2);
@@ -462,8 +469,7 @@ function cmdDoctor(opts: ParsedArgs): void {
   }
   const report = runDoctor(ctx);
 
-  const formatFlag =
-    typeof opts.flags.format === 'string' ? opts.flags.format : undefined;
+  const formatFlag = typeof opts.flags.format === 'string' ? opts.flags.format : undefined;
   const wantJson = opts.flags.json === true || formatFlag === 'json';
   const wantMarkdown = formatFlag === 'markdown' || formatFlag === 'md';
   const wantAnsi = formatFlag === 'ansi';