@vodmal/vdx-cli 0.23.0 → 0.25.0

package/src/ai.ts

@@ -12,6 +12,7 @@ import type { Predicate } from './rubric.ts';
 import {
   type Conversation,
   describeConversation,
+  describeAge,
   describeLive,
   isMachineLabel,
   LIVE_SESSIONS_SCRIPT,
@@ -20,6 +21,7 @@ import {
   listConversations,
   liveConversationId,
   liveSessionsHere,
+  liveStartedAt,
   machineLine,
   type MachineReport,
   machineOf,
@@ -84,6 +86,8 @@ export interface SessionProfile {
   project_names?: NameSource[];
   /** The machines a project's agent may run on, as ssh destinations; vdx asks the others what runs there. */
   machines?: string[];
+  /** What to do when a session cannot read ~/Downloads, ~/Desktop or ~/Documents (macOS): shown after the warning. */
+  folders_fix?: string;
 }
 
 /**
@@ -219,9 +223,16 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (session.machines !== undefined) {
       if (!isStringList(session.machines)) fail('session.machines', 'must be a list of machine names');
       session.machines.forEach((m, i) => {
-        if (!isMachineLabel(m)) fail(`session.machines[${i}]`, 'must be an ssh destination: letters, digits, . _ - and no leading -');
+        if (!isMachineLabel(m))
+          fail(`session.machines[${i}]`, 'must be an ssh destination: letters, digits, . _ - and no leading -');
       });
     }
+    if (
+      session.folders_fix !== undefined &&
+      (typeof session.folders_fix !== 'string' || session.folders_fix.trim() === '')
+    ) {
+      fail('session.folders_fix', 'must be a non-empty string');
+    }
   }
 
   const gitDoc = envDoc.git;
@@ -245,7 +256,8 @@ export function parseEnvironment(text: string, source: string): Environment {
         if (events.length === 0 || !events.every((e) => typeof e === 'string' && GIT_HOOK_EVENTS.has(e))) {
           fail(`${at}.event`, 'must be a git hook event (pre-commit, pre-push, …) or a list of them');
         }
-        if (typeof h.command !== 'string' || h.command.trim() === '') fail(`${at}.command`, 'must be a non-empty string');
+        if (typeof h.command !== 'string' || h.command.trim() === '')
+          fail(`${at}.command`, 'must be a non-empty string');
         if (h.when_exists !== undefined && (typeof h.when_exists !== 'string' || h.when_exists === '')) {
           fail(`${at}.when_exists`, 'must be a path');
         }
@@ -514,7 +526,11 @@ export function projectIdentity(projectRoot: string): string {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
-    const slug = url.replace(/\/+$/, '').replace(/\.git$/, '').split(/[/:]/).pop();
+    const slug = url
+      .replace(/\/+$/, '')
+      .replace(/\.git$/, '')
+      .split(/[/:]/)
+      .pop();
     if (slug) return slug.toLowerCase();
   } catch {
     /* no git or no origin */
@@ -547,7 +563,10 @@ export function resolveProjectName(input: {
       src.file.replace(/^~(?=$|\/)/, input.home).replace(/\{repo\}/g, input.repo),
     );
     // Readers take paths relative to a project root; from "/" an absolute path stays itself.
-    const value = resolveConfigPath(readStructured({ projectRoot: '/', stack: '', cache: new Map() }, file), src.jsonpath);
+    const value = resolveConfigPath(
+      readStructured({ projectRoot: '/', stack: '', cache: new Map() }, file),
+      src.jsonpath,
+    );
     if (typeof value === 'string' && value.trim()) {
       const shown = file.startsWith(input.home + path.sep) ? `~${file.slice(input.home.length)}` : file;
       return { name: value.trim(), source: `${shown} ${src.jsonpath}` };
@@ -670,9 +689,7 @@ export class Tmux {
   }
 
   attach(session: string, insideTmux: boolean): number {
-    const args = insideTmux
-      ? ['switch-client', '-t', `=${session}`]
-      : ['attach-session', '-t', `=${session}`];
+    const args = insideTmux ? ['switch-client', '-t', `=${session}`] : ['attach-session', '-t', `=${session}`];
     return spawnSync('tmux', this.argv(args), { stdio: 'inherit' }).status ?? 1;
   }
 
@@ -708,6 +725,8 @@ export interface AiDeps {
   processes: () => ProcInfo[];
   /** Was this agent process started focused; default: its environment (`processFocused`). */
   agentFocused?: (pid: number) => boolean;
+  /** Default `process.platform`: the folder check is for macOS. */
+  platform?: NodeJS.Platform;
   sleep: (ms: number) => void;
   confirmTimeoutMs: number;
   /** One line from the person at the terminal, or null when there is none. */
@@ -797,7 +816,8 @@ export function renderPlan(
     `  resume:   ${plan.resumeArgs.length ? plan.resumeArgs.join(' ') : '—'}`,
     `  matched:  ${plan.matched.length ? plan.matched.join(', ') : '—'}`,
   ];
-  if (plan.focused) lines.push(`  focused:  nothing wakes it; left out: ${plan.skipped.length ? plan.skipped.join(', ') : '—'}`);
+  if (plan.focused)
+    lines.push(`  focused:  nothing wakes it; left out: ${plan.skipped.length ? plan.skipped.join(', ') : '—'}`);
   for (const c of plan.confirm) lines.push(`  confirm:  "${c.screen}" → ${c.keys.join(' ')}`);
   lines.push(
     multiplexer === 'tmux'
@@ -821,7 +841,10 @@ export function renderPlan(
 
 function lastLines(screen: string | null, n: number): string {
   const lines = (screen ?? '').split('\n').filter((l) => l.trim() !== '');
-  return lines.slice(-n).map((l) => `    | ${l}`).join('\n');
+  return lines
+    .slice(-n)
+    .map((l) => `    | ${l}`)
+    .join('\n');
 }
 
 function findAgentInPane(plan: LaunchPlan, paneId: string, deps: AiDeps): ProcInfo | null {
@@ -974,7 +997,12 @@ export function remoteAiArgs(input: {
 }
 
 /** Where neighbour repos live: the profile's `git.author_pool`, else the project's parent directory. */
-export function authorPoolDirs(environment: Environment, projectRoot: string, home: string, profileDir: string): string[] {
+export function authorPoolDirs(
+  environment: Environment,
+  projectRoot: string,
+  home: string,
+  profileDir: string,
+): string[] {
   const listed = environment.git?.author_pool;
   if (!listed?.length) return [path.dirname(projectRoot)];
   return listed.map((d) => path.resolve(profileDir, d.replace(/^~(?=$|\/)/, home)));
@@ -1018,7 +1046,13 @@ export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDe
       return;
     }
     const pick: Author | undefined =
-      a === '' ? top[0] : /^\d+$/.test(a) ? top[Number(a) - 1] : a.includes('@') ? { name: top[0]!.name, email: a } : undefined;
+      a === ''
+        ? top[0]
+        : /^\d+$/.test(a)
+          ? top[Number(a) - 1]
+          : a.includes('@')
+            ? { name: top[0]!.name, email: a }
+            : undefined;
     if (pick) {
       if (writeAuthor(projectRoot, pick)) deps.log(`✓ ${pick.name} <${pick.email}> → .git/config`);
       else deps.log(`✗ could not write .git/config — ${command(pick)}`);
@@ -1033,7 +1067,9 @@ export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, from: s
   const projectPath = resolveProjectRoot(opts.path) ?? path.resolve(opts.path);
   const tty = deps.interactive && !opts.detach && !opts.dryRun;
   const args = remoteAiArgs({ host, from, projectPath, home: deps.home, version: deps.version ?? '', opts, tty });
-  deps.log(`→ ${host}: vdx ai ${shellQuote(projectPath)}${opts.conversation ? ` --conversation ${opts.conversation}` : ''}`);
+  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');
@@ -1106,7 +1142,10 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
   if (!isClaude(plan.command)) return { args: plan.resumeArgs, lines: [] };
   const host = plan.host;
   const same = sameMachine;
-  const all = plan.resumeArgs.length === 0 ? [] : listConversations({ env: deps.env, home: deps.home, projectRoot: plan.projectRoot });
+  const all =
+    plan.resumeArgs.length === 0
+      ? []
+      : listConversations({ env: deps.env, home: deps.home, projectRoot: plan.projectRoot });
   const root = shellQuote(plan.projectRoot);
   // Said from where the person sits: under `vdx ai@<host>` that is not this machine.
   const atSeat = same(plan.seat, host);
@@ -1117,7 +1156,9 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
   for (const m of [...plan.machines, ...all.map((c) => c.machine)]) {
     if (m && !same(m, host) && ![...reach.keys()].some((k) => same(k, m))) reach.set(m, askMachine(m, deps));
   }
-  const silent = [...reach].filter(([, r]) => r === null).map(([m]) => `note: ${m} does not answer over ssh — what runs there is not known`);
+  const silent = [...reach]
+    .filter(([, r]) => r === null)
+    .map(([m]) => `note: ${m} does not answer over ssh — what runs there is not known`);
   const elsewhere = [...reach].flatMap(([m, r]) =>
     (r?.sessions ?? []).filter((l) => runsInProject(l, r!.home, plan.projectRoot, deps.home)).map((l) => ({ m, l })),
   );
@@ -1132,7 +1173,9 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
     !l.tmux ? '' : same(m, plan.seat) ? ` — attach: vdx ai ${rootOn(m)}` : ` — there: vdx ai@${m} ${root}`;
   const fresh = (lines: string[]): ConversationChoice => {
     if (elsewhere.length === 0) return { args: [], lines };
-    const agents = elsewhere.map(({ m, l }) => `an agent of this project is ${describeLive(on(m), l)}${reachAgent(m, l)}`);
+    const agents = elsewhere.map(
+      ({ m, l }) => `an agent of this project is ${describeLive(on(m), l)}${reachAgent(m, l)}`,
+    );
     return { args: [], elsewhere: [...new Set(elsewhere.map(({ m }) => m))], lines: [...lines, ...agents] };
   };
   if (plan.resumeArgs.length === 0) return fresh(silent);
@@ -1160,15 +1203,26 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
     if (here) {
       return {
         args: [],
-        askHere: { id: c.id, why: `It runs ${on(host)} right now (${here.session.tmux ?? `pid ${here.session.pid}`}); two sessions would write to it` },
+        askHere: {
+          id: c.id,
+          why: `It runs ${on(host)} 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)}`] };
+    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 ${on(host)}); if it runs there, both machines will write to it` },
+      askHere: {
+        id: c.id,
+        why: `Its machine is unknown (never typed in ${on(host)}); if it runs there, both machines will write to it`,
+      },
       lines: [`chosen: ${show(c)}`],
     };
   };
@@ -1181,7 +1235,12 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
   if (canAsk && deps.interactive) {
     deps.log('conversations of this project:');
     found.forEach((c, i) => {
-      const marks = [i === 0 && 'newest', c === firstIdle && (atSeat ? 'this machine' : `idle on ${host}`), !machine(c) && 'machine unknown', ...running(c)];
+      const marks = [
+        i === 0 && 'newest',
+        c === firstIdle && (atSeat ? 'this machine' : `idle on ${host}`),
+        !machine(c) && 'machine unknown',
+        ...running(c),
+      ];
       const m = marks.filter(Boolean);
       deps.log(`  ${i + 1}) ${show(c)}${m.length ? `   ← ${m.join(', ')}` : ''}`);
     });
@@ -1208,7 +1267,8 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
         `${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`;
-      if (m && same(m, plan.seat)) return `note: ${m} has ${which} — continue it where you are: vdx ai ${rootOn(m)} --conversation ${c.id}`;
+      if (m && same(m, plan.seat))
+        return `note: ${m} has ${which} — continue it where you are: vdx ai ${rootOn(m)} --conversation ${c.id}`;
       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 ${on(host)}) — on its machine: vdx ai@<machine> ${root} --conversation ${c.id}`;
@@ -1221,6 +1281,51 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
   return fresh([`no idle conversation ${atSeat ? 'of this machine' : `on ${host}`} — starting a new one`, ...notes]);
 }
 
+/**
+ * Several agents of the project run here and the start is about one of them: a person
+ * picks — Enter takes the newest; without a terminal, or under --dry-run, it is the newest.
+ * null — the person left it.
+ */
+function pickAgent(
+  running: AgentPane[],
+  focusedOf: (pid: number) => boolean,
+  deps: AiDeps,
+  canAsk: boolean,
+): AgentPane | null {
+  if (running.length === 1) return running[0]!;
+  const startedAt = (a: AgentPane) => liveStartedAt(deps.env, deps.home, a.proc.pid);
+  const sorted = [...running].sort((a, b) => (startedAt(b) ?? 0) - (startedAt(a) ?? 0));
+  const show = (a: AgentPane) => {
+    const id = liveConversationId(deps.env, deps.home, a.proc.pid);
+    const at = startedAt(a);
+    const marks = [
+      id && `conversation ${id.slice(0, 8)}`,
+      focusedOf(a.proc.pid) && 'focused',
+      at !== null && `started ${describeAge(new Date(at))}`,
+    ].filter(Boolean);
+    return `${a.pane.session} ${a.pane.paneId}${marks.length ? ` — ${marks.join(', ')}` : ''}`;
+  };
+  // Start times come from Claude Code's session files; without them, tmux's order.
+  const newest = startedAt(sorted[0]!) !== null ? 'the newest' : 'the first';
+  if (!canAsk || !deps.interactive) {
+    deps.log(`note: ${sorted.length} agents of this project run here — taking ${newest}, ${show(sorted[0]!)}`);
+    return sorted[0]!;
+  }
+  deps.log('agents of this project running here:');
+  sorted.forEach((a, i) =>
+    deps.log(`  ${i + 1}) ${show(a)}${i === 0 && newest === 'the newest' ? '   ← newest' : ''}`),
+  );
+  for (let tries = 0; tries < 2; tries++) {
+    const answer = deps.ask('Which one? [1]: ');
+    if (answer === null) return null;
+    const a = answer.trim();
+    const agent = a === '' ? sorted[0] : /^\d+$/.test(a) ? sorted[Number(a) - 1] : undefined;
+    if (agent) return agent;
+    deps.log(`  1–${sorted.length}`);
+  }
+  return null;
+}
+
 interface Prepared {
   projectRoot: string;
   environment: Environment;
@@ -1308,6 +1413,59 @@ export function processFocused(pid: number): boolean {
   }
 }
 
+/** macOS guards these folders on their own; a tmux server can hold a denial for every session under it. */
+export const GUARDED_FOLDERS = ['Downloads', 'Desktop', 'Documents'];
+
+/**
+ * The guarded folders an agent started here could not read. Through the tmux server
+ * (`run-shell`): its sessions have the server's rights, not vdx's. Without a server, or
+ * without tmux, this process's own — the agent gets the rights of this terminal. A folder
+ * that does not exist is skipped.
+ */
+export function unreadableFolders(tmux: Tmux | null, home: string): string[] {
+  const dirs = GUARDED_FOLDERS.map((f) => path.join(home, f));
+  if (tmux) {
+    // `ls`, not `[ -d ]`: a denied folder still passes -d. The answer comes back in a
+    // file: tmux before 3.5 prints run-shell's output into a pane, not to the caller.
+    const file = path.join(os.tmpdir(), `vdx-folders-${process.pid}-${Date.now()}`);
+    const checks = dirs.map(
+      (d) => `{ [ ! -d ${shellQuote(d)} ] || ls ${shellQuote(d)} >/dev/null 2>&1 || echo ${shellQuote(d)}; }`,
+    );
+    try {
+      if (tmux.tryRun(['run-shell', `{ ${checks.join('; ')}; } > ${shellQuote(file)}`]) !== null) {
+        return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+      }
+    } catch {
+      // no answer from the server: this process's own check
+    } finally {
+      fs.rmSync(file, { force: true });
+    }
+  }
+  return dirs.filter((d) => {
+    try {
+      fs.readdirSync(d);
+      return false;
+    } catch (e: any) {
+      return e?.code === 'EPERM' || e?.code === 'EACCES';
+    }
+  });
+}
+
+/** One warning and its fix — the profile's `session.folders_fix`, else what works anywhere. */
+export function foldersWarning(denied: string[], viaTmux: boolean, fix: string | undefined, home: string): string[] {
+  const names = denied.map((d) => (d.startsWith(home + path.sep) ? `~${d.slice(home.length)}` : d)).join(', ');
+  return [
+    `⚠ this session cannot read ${names} — macOS holds the denial ${viaTmux ? 'in the tmux server' : 'for this terminal'}; ` +
+      `files there are out of the agent's reach`,
+    `  fix: ${
+      fix ??
+      (viaTmux
+        ? 'restart the tmux server (it closes every session)'
+        : 'allow this terminal app in System Settings → Privacy & Security → Files and Folders')
+    }`,
+  ];
+}
+
 /** The agent's command line; a focused one carries VDX_FOCUSED=1 in front, for the shell in its tmux pane. */
 function agentLine(plan: LaunchPlan, args: string[]): string {
   return `${plan.focused ? `${FOCUSED_ENV_VAR}=1 ` : ''}${commandLine(plan.command, args)}`;
@@ -1398,8 +1556,9 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     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: [] };
+  // A start continues the last conversation unless asked for a new one; a focused session is a new one.
+  const wantsNew = (opts.fresh || opts.focused === true) && !opts.conversation;
+  if (wantsNew) plan = { ...plan, resumeArgs: [] };
 
   let multiplexer = plan.multiplexer;
   if (multiplexer === 'tmux' && !tmux.available()) {
@@ -1408,13 +1567,27 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   }
 
   const running =
-    multiplexer === 'tmux'
-      ? findAgentPanes(tmux.panes(), deps.processes(), projectRoot, plan.command)
-      : [];
-  const current = running[0];
+    multiplexer === 'tmux' ? findAgentPanes(tmux.panes(), deps.processes(), projectRoot, plan.command) : [];
+  const focusedOf = deps.agentFocused ?? processFocused;
+  const conversationOf = (a: AgentPane) => liveConversationId(deps.env, deps.home, a.proc.pid);
+  // Which running agent the start is about. A new conversation, or one no agent here is in, starts
+  // next to them; --restart replaces one. An agent whose conversation vdx cannot read may be in the
+  // one asked for: no second agent in it blindly.
+  const inConversation = opts.conversation ? running.find((a) => conversationOf(a) === opts.conversation) : undefined;
+  const unreadable = opts.conversation && !inConversation ? running.find((a) => conversationOf(a) === null) : undefined;
+  const alongside =
+    running.length > 0 && !opts.restart && !inConversation && !unreadable && (wantsNew || !!opts.conversation);
+  let current = inConversation ?? unreadable;
+  if (!current && !alongside && running.length > 0) {
+    const picked = pickAgent(running, focusedOf, deps, !opts.dryRun);
+    if (picked === null) {
+      log('nothing done');
+      return EXIT_LAUNCH_FAILED;
+    }
+    current = picked;
+  }
   // A running agent keeps its mode: plain `vdx ai` takes a focused one as it is,
   // and the rules it leaves out are not missing from it.
-  const focusedOf = deps.agentFocused ?? processFocused;
   const runningFocused = current ? focusedOf(current.proc.pid) : false;
   if (current && !opts.restart && runningFocused && !plan.focused) {
     plan = { ...prepared.replan(true), resumeArgs: plan.resumeArgs };
@@ -1424,8 +1597,9 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   let choice: ConversationChoice | null = null;
   if (!current || opts.restart) {
     if (opts.conversation) choice = { args: resumeId(opts.conversation), lines: [] };
-    // A restart into a new conversation replaces the agent here: no second agent, nothing to ask.
-    else if (current && plan.resumeArgs.length === 0) choice = { args: [], lines: [] };
+    // A restart into a new conversation replaces the agent here, and a new one next to an agent here
+    // is what was asked for: the other machines are not asked.
+    else if ((current || alongside) && plan.resumeArgs.length === 0) choice = { args: [], lines: [] };
     else if (current && isClaude(plan.command)) {
       const live = liveConversationId(deps.env, deps.home, current.proc.pid);
       choice = live
@@ -1436,16 +1610,28 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   }
 
   const poolDirs = authorPoolDirs(environment, projectRoot, deps.home, profileDir);
+  // Said before a start or an attach, never in the way: the agent runs, without those files.
+  const denied =
+    (deps.platform ?? process.platform) === 'darwin'
+      ? unreadableFolders(multiplexer === 'tmux' ? tmux : null, deps.home)
+      : [];
+  const folders = denied.length
+    ? foldersWarning(denied, multiplexer === 'tmux', environment.session?.folders_fix, deps.home)
+    : [];
   if (opts.dryRun) {
     deps.out(renderPlan(plan, multiplexer, running, focusedOf));
     for (const l of choice?.lines ?? []) deps.out(`  conversation: ${l}\n`);
+    for (const l of folders) deps.out(`  ${l}\n`);
     ensureAuthor(projectRoot, poolDirs, deps, true);
     return EXIT_OK;
   }
   for (const l of choice?.lines ?? []) log(l);
+  for (const l of folders) log(l);
   if (choice?.abort) return EXIT_LAUNCH_FAILED;
   if (choice?.elsewhere && !current) {
-    const answer = deps.interactive ? deps.ask(`Start a new conversation ${here}${atSeat ? ',' : ''} anyway? [y/N]: `) : null;
+    const answer = deps.interactive
+      ? deps.ask(`Start a new conversation ${here}${atSeat ? ',' : ''} anyway? [y/N]: `)
+      : null;
     if (!/^y(es)?$/i.test(answer?.trim() ?? '')) {
       log('nothing started');
       return EXIT_LAUNCH_FAILED;
@@ -1498,54 +1684,76 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     return res.status ?? 1;
   }
 
-  if (running.length > 1) {
+  if (alongside) {
+    const others = running.map((r) => `${r.pane.session} ${r.pane.paneId}`).join(', ');
     log(
-      `note: ${running.length} panes run ${plan.command} in this project: ` +
-        `${running.map((r) => `${r.pane.session} ${r.pane.paneId}`).join(', ')} — using the first`,
+      `note: ${others} keep${running.length === 1 ? 's' : ''} running ${plan.command} — starting another one next to it, ` +
+        `in ${opts.conversation ? `conversation ${opts.conversation.slice(0, 8)}` : 'a new conversation'}`,
     );
   }
 
   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}`,
-        );
-      }
-    }
-    if (plan.focused && !runningFocused) {
-      log(`✗ ${current.pane.session}: ${plan.command} is running, not focused`);
+    if (current === unreadable) {
       log(
-        `  to focus it: vdx ai --restart --focused ${shellQuote(projectRoot)}` +
-          (plan.resumeArgs.length ? ' (stops the running agent, then resumes its conversation)' : ' (stops the running agent)'),
+        `note: ${current.pane.session} runs ${plan.command} in a conversation vdx cannot read — attaching to it; ` +
+          `to switch it: vdx ai --restart ${shellQuote(projectRoot)} --conversation ${opts.conversation}`,
       );
-      return EXIT_DRIFT;
     }
-    const missing = missingArgs(current.proc.args, plan.args);
-    if (missing.length > 0) {
-      log(`✗ ${current.pane.session}: ${plan.command} is running without ${missing.join(' ')}`);
+    const unfocused = plan.focused && !runningFocused;
+    const missing = unfocused ? [] : missingArgs(current.proc.args, plan.args);
+    if (!unfocused && missing.length === 0) {
       log(
-        `  to apply the profile: vdx ai --restart${plan.focused ? ' --focused' : ''}${opts.fresh ? ' --new' : ''} ${shellQuote(projectRoot)}` +
-          (plan.resumeArgs.length
-            ? ` (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)'),
+        `✓ ${current.pane.session}: already running with the profile${runningFocused ? ', focused' : ''} — ${current.proc.args}`,
       );
+      return finish(true, current.pane.session, current.pane.paneId, opts, deps);
+    }
+    // Drift. In a terminal the person picks: the agent as it runs, or a restart
+    // with the profile; without one nothing is touched, and the fix is named.
+    const drift = `${current.pane.session}: ${plan.command} is running${unfocused ? ', not focused' : ` without ${missing.join(' ')}`}`;
+    const fix =
+      `vdx ai --restart${plan.focused ? ' --focused' : ''}${opts.fresh ? ' --new' : ''} ${shellQuote(projectRoot)}` +
+      (opts.conversation ? ` --conversation ${opts.conversation}` : '');
+    const effect = plan.resumeArgs.length
+      ? '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';
+    if (!deps.interactive) {
+      log(`✗ ${drift}`);
+      log(`  ${unfocused ? 'to focus it' : 'to apply the profile'}: ${fix} (${effect})`);
       return EXIT_DRIFT;
     }
-    log(`✓ ${current.pane.session}: already running with the profile${runningFocused ? ', focused' : ''} — ${current.proc.args}`);
-    return finish(true, current.pane.session, current.pane.paneId, opts, deps);
+    log(`⚠ ${drift}`);
+    log(
+      `  Enter  ${opts.detach ? 'leave it running' : 'attach to it'} as is${unfocused ? '' : ' — the flags wait for a restart'}`,
+    );
+    log(`  r      restart it ${unfocused ? 'focused' : 'with the profile'}: ${effect}`);
+    log(`  q      leave it; later: ${fix}`);
+    const answer = deps.ask(`${opts.detach ? 'Leave it as is' : 'Attach as is'}? [Enter/r/q]: `);
+    if (answer === '') {
+      log(`→ ${current.pane.session}: as is — ${current.proc.args}`);
+      return finish(true, current.pane.session, current.pane.paneId, opts, deps);
+    }
+    if (answer?.toLowerCase() !== 'r') {
+      log('nothing done');
+      return EXIT_DRIFT;
+    }
+    // As --restart: the conversation the agent is in, not the folder's newest — another agent's, maybe.
+    const live = isClaude(plan.command) && plan.resumeArgs.length > 0 ? conversationOf(current) : null;
+    if (live) plan = { ...plan, resumeArgs: resumeId(live) };
   }
 
   if (current) {
     const line = agentLine(plan, [...plan.args, ...plan.resumeArgs]);
     log(`↻ ${current.pane.session} ${current.pane.paneId}: restarting — ${line}`);
     tmux.respawn(current.pane.paneId, projectRoot, tmuxShellCommand(line, deps.shell));
-    return finish(settleResumed(plan, current.pane.paneId, deps), current.pane.session, current.pane.paneId, opts, deps);
+    return finish(
+      settleResumed(plan, current.pane.paneId, deps),
+      current.pane.session,
+      current.pane.paneId,
+      opts,
+      deps,
+    );
   }
 
   if (opts.restart) log(`note: no running ${plan.command} in this project — starting one`);

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,