@vodmal/vdx-cli 0.22.0 → 0.23.0

package/README.md

@@ -51,7 +51,7 @@ vdx doctor --check [project-path]   # one line per hook declared but not running
 vdx doctor --fix                    # write the profile's personal hooks (git.hooks) into ~/.gitconfig
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
-vdx ai[@host] [project-path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there
+vdx ai[@host] [project-path] [--new | --conversation <id>] [--focused] [--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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.22.0",
+  "version": "0.23.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/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.3"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "1.0.0"
+  version: "1.2.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"

package/src/ai.ts

@@ -57,6 +57,8 @@ export interface WhenRule {
   if: Predicate;
   args?: string[];
   confirm?: ConfirmRule[];
+  /** The rule is there to wake the agent: a focused session (`vdx ai --focused`) leaves it out. */
+  wakes?: boolean;
 }
 
 export interface AgentProfile {
@@ -116,6 +118,13 @@ export interface Environment {
 
 export const ENVIRONMENT_ENV_VAR = 'VDX_ENVIRONMENT';
 export const HOST_ENV_VAR = 'VDX_HOST';
+/** Set by `vdx ai@<host>` for the vdx it starts there: the machine the person sits at. */
+export const SEAT_ENV_VAR = 'VDX_AI_FROM';
+/**
+ * `1` in the environment of an agent started with `vdx ai --focused`, and so of
+ * its hooks and MCP servers: nothing wakes this session or reads its inbox for it.
+ */
+export const FOCUSED_ENV_VAR = 'VDX_FOCUSED';
 export const USER_ENVIRONMENT_FILE = '.vdx-environment.yaml';
 /** Tried in order when no profile names an agent. Started plain, with no flags. */
 export const FALLBACK_AGENTS = ['claude', 'codex'] as const;
@@ -168,6 +177,7 @@ export function parseEnvironment(text: string, source: string): Environment {
         if (rule.args !== undefined && !isStringList(rule.args)) {
           fail(`${at}.args`, 'must be a list of strings');
         }
+        if (rule.wakes !== undefined && typeof rule.wakes !== 'boolean') fail(`${at}.wakes`, 'must be true or false');
         if (rule.confirm !== undefined) {
           if (!Array.isArray(rule.confirm)) fail(`${at}.confirm`, 'must be a list');
           rule.confirm.forEach((c, j) => {
@@ -279,12 +289,18 @@ export interface LaunchPlan {
   /** Where `project` came from: mise.toml, a profile source, or the repository name. */
   projectSource: string;
   host: string;
+  /** The machine the person sits at: `host`, or the one that ran `vdx ai@<host>`. */
+  seat: string;
   profilePath: string | null;
   command: string;
   /** agent.args plus the args of every matched `when` rule — what a running agent must carry. */
   args: string[];
   resumeArgs: string[];
   matched: string[];
+  /** `vdx ai --focused`: the agent gets VDX_FOCUSED=1, and the rules that wake it are left out. */
+  focused: boolean;
+  /** Matched rules a focused session leaves out (`wakes: true`). */
+  skipped: string[];
   confirm: ConfirmRule[];
   multiplexer: Multiplexer;
   sessionName: string;
@@ -300,14 +316,22 @@ export function planLaunch(input: {
   project: string;
   projectSource?: string;
   host: string;
+  seat?: string;
+  focused?: boolean;
 }): LaunchPlan {
   const { environment, agent, projectRoot } = input;
+  const focused = input.focused === true;
   const ctx: Ctx = { projectRoot, stack: autoDetectStack(projectRoot), cache: new Map() };
   const args = [...(agent.args ?? [])];
   const matched: string[] = [];
+  const skipped: string[] = [];
   const confirm: ConfirmRule[] = [];
   for (const rule of agent.when ?? []) {
     if (!evalPredicate(rule.if, ctx)) continue;
+    if (focused && rule.wakes) {
+      skipped.push(rule.id);
+      continue;
+    }
     matched.push(rule.id);
     args.push(...(rule.args ?? []));
     confirm.push(...(rule.confirm ?? []));
@@ -317,11 +341,14 @@ export function planLaunch(input: {
     project: input.project,
     projectSource: input.projectSource ?? 'repository name',
     host: input.host,
+    seat: input.seat ?? input.host,
     profilePath: input.profilePath,
     command: agent.command,
     args,
     resumeArgs: [...(agent.resume_args ?? [])],
     matched,
+    focused,
+    skipped,
     confirm,
     multiplexer: environment.session?.multiplexer ?? 'none',
     sessionName: renderSessionName(environment.session?.name ?? DEFAULT_SESSION_NAME, {
@@ -535,6 +562,16 @@ export function hostLabel(env: NodeJS.ProcessEnv = process.env): string {
   return label || os.hostname().split('.')[0]!;
 }
 
+/** The machine the person sits at: the one whose `vdx ai@<host>` started this vdx, else this one. */
+export function seatLabel(env: NodeJS.ProcessEnv = process.env): string {
+  return env[SEAT_ENV_VAR]?.trim() || hostLabel(env);
+}
+
+/** Machine labels compare without case: `M3` in the profile is `m3` in a transcript. */
+export function sameMachine(a: string | null, b: string | null): boolean {
+  return (a ?? '').toLowerCase() === (b ?? '').toLowerCase();
+}
+
 export function onPath(bin: string, env: NodeJS.ProcessEnv = process.env): boolean {
   for (const dir of (env['PATH'] ?? '').split(path.delimiter)) {
     if (!dir) continue;
@@ -654,6 +691,8 @@ export interface AiOptions {
   conversation?: string;
   detach: boolean;
   dryRun: boolean;
+  /** `--focused`: a session nothing wakes — VDX_FOCUSED=1, the profile's `wakes` rules left out. */
+  focused?: boolean;
 }
 
 export interface AiDeps {
@@ -667,6 +706,8 @@ export interface AiDeps {
   out: (text: string) => void;
   onPath: (bin: string) => boolean;
   processes: () => ProcInfo[];
+  /** Was this agent process started focused; default: its environment (`processFocused`). */
+  agentFocused?: (pid: number) => boolean;
   sleep: (ms: number) => void;
   confirmTimeoutMs: number;
   /** One line from the person at the terminal, or null when there is none. */
@@ -742,15 +783,21 @@ export const EXIT_LAUNCH_FAILED = 4;
  */
 export const NOTHING_TO_RESUME_MS = 30_000;
 
-export function renderPlan(plan: LaunchPlan, multiplexer: Multiplexer, running: AgentPane[]): string {
+export function renderPlan(
+  plan: LaunchPlan,
+  multiplexer: Multiplexer,
+  running: AgentPane[],
+  focusedOf: (pid: number) => boolean = () => false,
+): string {
   const lines = [
     `vdx ai — ${plan.projectRoot}`,
     `  name:     ${plan.project} (${plan.projectSource})`,
     `  profile:  ${plan.profilePath ?? `none — built-in default (${FALLBACK_AGENTS.join(' or ')}, no flags, no tmux)`}`,
-    `  agent:    ${commandLine(plan.command, plan.args)}`,
+    `  agent:    ${agentLine(plan, plan.args)}`,
     `  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(', ') : '—'}`);
   for (const c of plan.confirm) lines.push(`  confirm:  "${c.screen}" → ${c.keys.join(' ')}`);
   lines.push(
     multiplexer === 'tmux'
@@ -761,10 +808,11 @@ export function renderPlan(plan: LaunchPlan, multiplexer: Multiplexer, running:
     if (running.length === 0) lines.push('  running:  —');
     for (const r of running) {
       const missing = missingArgs(r.proc.args, plan.args);
+      const focused = focusedOf(r.proc.pid);
       lines.push(
         `  running:  ${r.pane.session} ${r.pane.paneId} — ${
           missing.length ? `missing ${missing.join(' ')}` : 'matches the profile'
-        }`,
+        }${focused ? ', focused' : plan.focused ? ', not focused' : ''}`,
       );
     }
   }
@@ -864,7 +912,7 @@ function settle(plan: LaunchPlan, paneId: string, deps: AiDeps): SettleResult {
 function settleResumed(plan: LaunchPlan, paneId: string, deps: AiDeps): boolean {
   const result = settle(plan, paneId, deps);
   if (result !== 'not-running' || plan.resumeArgs.length === 0) return result === 'ok';
-  const line = commandLine(plan.command, plan.args);
+  const line = agentLine(plan, plan.args);
   deps.log(`↻ nothing to resume — starting without ${plan.resumeArgs.join(' ')}: ${line}`);
   deps.tmux.respawn(paneId, plan.projectRoot, tmuxShellCommand(line, deps.shell));
   return settle(plan, paneId, deps) === 'ok';
@@ -895,9 +943,12 @@ export function remotePathWord(abs: string, home: string): string {
  * The ssh argv for `vdx ai@<host>`: the same `vdx ai` on the host, in its own
  * tmux there. The path goes first: an older vdx hands the token after a flag it
  * does not know to that flag. A different vdx version there is named, not fatal.
+ * `from` — the machine the person sits at, so the vdx there speaks from it; an
+ * older vdx leaves the variable alone.
  */
 export function remoteAiArgs(input: {
   host: string;
+  from: string;
   projectPath: string;
   home: string;
   version: string;
@@ -907,6 +958,7 @@ export function remoteAiArgs(input: {
   const { host, opts, version } = input;
   const flags = [
     opts.fresh && '--new',
+    opts.focused && '--focused',
     opts.restart && '--restart',
     opts.detach && '--detach',
     opts.dryRun && '--dry-run',
@@ -916,6 +968,7 @@ export function remoteAiArgs(input: {
   const script =
     `v=$(vdx --version 2>/dev/null) || v='older than 0.13.1'; ` +
     `[ "$v" = ${v} ] || echo "note: vdx on ${host} is $v, here "${v} >&2; ` +
+    `export ${SEAT_ENV_VAR}=${shellQuote(input.from)}; ` +
     `exec vdx ai ${[remotePathWord(input.projectPath, input.home), ...flags].join(' ')}`;
   return [input.tty ? '-t' : '-T', host, script];
 }
@@ -975,10 +1028,11 @@ export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDe
   }
 }
 
-export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, version: string = deps.version ?? ''): number {
+/** `from` — where the person sits; a vdx that `vdx ai@<host>` started passes its own on. */
+export function runAiRemote(opts: AiOptions, host: string, deps: AiDeps, from: string = seatLabel(deps.env)): 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 });
+  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}` : ''}`);
   const res = (deps.ssh ?? runSsh)(args, false);
   if (res === null) {
@@ -1051,9 +1105,12 @@ const resumeId = (id: string) => ['--resume', id];
 export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boolean): ConversationChoice {
   if (!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 same = sameMachine;
   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);
+  const on = (m: string) => (same(m, plan.seat) ? (atSeat ? 'here' : `on ${m}, where you are,`) : `on ${m}`);
 
   // Who runs what right now: this machine from its session files, the others over ssh.
   const reach = new Map<string, MachineReport | null>();
@@ -1064,9 +1121,18 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
   const elsewhere = [...reach].flatMap(([m, r]) =>
     (r?.sessions ?? []).filter((l) => runsInProject(l, r!.home, plan.projectRoot, deps.home)).map((l) => ({ m, l })),
   );
+  // The project's path on the machine `m`, by its home: the person types it there.
+  const rootOn = (m: string) => {
+    const theirs = [...reach].find(([k]) => same(k, m))?.[1]?.home;
+    const rel = path.relative(deps.home, plan.projectRoot);
+    return theirs && !rel.startsWith('..') && !path.isAbsolute(rel) ? shellQuote(path.join(theirs, rel)) : root;
+  };
+  // `vdx ai` attaches to an agent in tmux; one in a terminal of its own has no command to reach it.
+  const reachAgent = (m: string, l: LiveSession) =>
+    !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(m, l, false)} — there: vdx ai@${m} ${root}`);
+    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);
@@ -1086,7 +1152,7 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
     (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 running = (c: Conversation) => (live.get(c.id) ?? []).map((l) => describeLive(on(l.machine), l.session));
 
   const take = (c: Conversation): ConversationChoice => {
     const m = machine(c);
@@ -1094,7 +1160,7 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
     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` },
+        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)}`],
       };
     }
@@ -1102,7 +1168,7 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
     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' },
+      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)}`],
     };
   };
@@ -1115,7 +1181,7 @@ 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 && 'this machine', !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(', ')}` : ''}`);
     });
@@ -1142,16 +1208,17 @@ 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}`;
       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}`;
+        : `note: ${which} is of an unknown machine (never typed in ${on(host)}) — on its machine: vdx ai@<machine> ${root} --conversation ${c.id}`;
     });
   notes.push(...silent);
   if (firstIdle) {
     const chosen = take(firstIdle);
     return { ...chosen, lines: [...chosen.lines, ...notes] };
   }
-  return fresh(['no idle conversation of this machine — starting a new one', ...notes]);
+  return fresh([`no idle conversation ${atSeat ? 'of this machine' : `on ${host}`} — starting a new one`, ...notes]);
 }
 
 interface Prepared {
@@ -1160,10 +1227,12 @@ interface Prepared {
   profilePath: string | null;
   profileDir: string;
   plan: LaunchPlan;
+  /** The same plan for a focused session or a plain one. */
+  replan: (focused: boolean) => LaunchPlan;
 }
 
 /** 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 {
+function prepare(pathArg: string, deps: AiDeps, focused = false): Prepared | number {
   const { log } = deps;
 
   const projectRoot = resolveProjectRoot(pathArg);
@@ -1201,9 +1270,8 @@ function prepare(pathArg: string, deps: AiDeps): Prepared | number {
     profileDir,
   });
 
-  let plan: LaunchPlan;
-  try {
-    plan = planLaunch({
+  const replan = (asFocused: boolean) =>
+    planLaunch({
       environment,
       profilePath,
       agent,
@@ -1211,12 +1279,38 @@ function prepare(pathArg: string, deps: AiDeps): Prepared | number {
       project: named.name,
       projectSource: named.source,
       host: hostLabel(deps.env),
+      seat: seatLabel(deps.env),
+      focused: asFocused,
     });
+  let plan: LaunchPlan;
+  try {
+    plan = replan(focused);
   } catch (e: any) {
     log(`vdx ai: ${profilePath ?? 'profile'}: ${e?.message ?? e}`);
     return EXIT_USAGE;
   }
-  return { projectRoot, environment, profilePath, profileDir, plan };
+  return { projectRoot, environment, profilePath, profileDir, plan, replan };
+}
+
+/** Was the process started focused — VDX_FOCUSED=1 in its environment (`ps -E` on macOS, /proc on Linux)? */
+export function processFocused(pid: number): boolean {
+  const mark = `${FOCUSED_ENV_VAR}=1`;
+  try {
+    const environ = `/proc/${pid}/environ`;
+    if (fs.existsSync(environ)) return fs.readFileSync(environ, 'utf8').split('\0').includes(mark);
+    const out = execFileSync('ps', ['-E', '-ww', '-o', 'command=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split(/\s+/).includes(mark);
+  } catch {
+    return false;
+  }
+}
+
+/** 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)}`;
 }
 
 /** The nearest ancestor of `pid` that is the agent: the session a hook or a shell tool runs in. */
@@ -1237,9 +1331,12 @@ export function findOwnAgent(procs: ProcInfo[], pid: number, command: string): P
  */
 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);
+  // The hook runs in the agent's environment: a focused session's carries VDX_FOCUSED=1.
+  const focused = deps.env[FOCUSED_ENV_VAR] === '1';
+  const prepared = prepare(pathArg, deps, focused);
   if (typeof prepared === 'number') return prepared;
   const { projectRoot, profilePath, plan } = prepared;
+  const vdxAi = `vdx ai${focused ? ' --focused' : ''}`;
 
   const lines = [
     `${machineLine(plan.host)}; the agent in this project is started with \`vdx ai\`, and its flags come from the profile ` +
@@ -1248,6 +1345,14 @@ export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = proc
       `condition in the profile, not an instruction to type. A project's agent on another machine: ` +
       `\`vdx ai@<machine>\`. More: \`vdx ai --help\`.`,
   ];
+  if (focused) {
+    lines.push(
+      `· this session is focused (\`vdx ai --focused\`): it works on what the user gave it — nothing should wake it, ` +
+        `and it does not read its inbox unless the user asks` +
+        (plan.skipped.length ? `; the profile's ${plan.skipped.join(', ')} is left out` : '') +
+        '.',
+    );
+  }
   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.`);
@@ -1265,10 +1370,10 @@ export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = proc
   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` +
+        ? `\`${vdxAi} --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}\`.`),
+        : `this session runs outside tmux, so vdx cannot restart it: the user exits it and runs \`${vdxAi} ${root}\`.`),
   );
   deps.out(lines.join('\n') + '\n');
   return EXIT_DRIFT;
@@ -1277,10 +1382,18 @@ export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = proc
 export function runAi(opts: AiOptions, deps: AiDeps): number {
   const { log, tmux } = deps;
 
-  const prepared = prepare(opts.path, deps);
+  const prepared = prepare(opts.path, deps, opts.focused === true);
   if (typeof prepared === 'number') return prepared;
   const { projectRoot, environment, profileDir } = prepared;
   let { plan } = prepared;
+  // The agent started here runs on this machine: it does not inherit where the person sat,
+  // and it is focused by this start's flag, not by the shell vdx runs in.
+  delete deps.env[SEAT_ENV_VAR];
+  delete deps.env[FOCUSED_ENV_VAR];
+  // Under `vdx ai@<host>` the person is not here: this machine goes by its name.
+  const atSeat = sameMachine(plan.seat, plan.host);
+  const here = atSeat ? `here, on ${plan.host}` : `on ${plan.host}`;
+  const vdxAiHere = atSeat ? 'vdx ai' : `vdx ai@${plan.host}`;
   if (opts.conversation && !isClaude(plan.command)) {
     log(`vdx ai: --conversation names a Claude Code conversation; the agent here is ${plan.command}`);
     return EXIT_USAGE;
@@ -1299,6 +1412,13 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
       ? findAgentPanes(tmux.panes(), deps.processes(), projectRoot, plan.command)
       : [];
   const current = running[0];
+  // 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 };
+  }
 
   // What a start continues. A restart keeps the conversation the agent is in.
   let choice: ConversationChoice | null = null;
@@ -1317,7 +1437,7 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
 
   const poolDirs = authorPoolDirs(environment, projectRoot, deps.home, profileDir);
   if (opts.dryRun) {
-    deps.out(renderPlan(plan, multiplexer, running));
+    deps.out(renderPlan(plan, multiplexer, running, focusedOf));
     for (const l of choice?.lines ?? []) deps.out(`  conversation: ${l}\n`);
     ensureAuthor(projectRoot, poolDirs, deps, true);
     return EXIT_OK;
@@ -1325,7 +1445,7 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   for (const l of choice?.lines ?? []) log(l);
   if (choice?.abort) return EXIT_LAUNCH_FAILED;
   if (choice?.elsewhere && !current) {
-    const answer = deps.interactive ? deps.ask(`Start a new conversation here, on ${plan.host}, 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;
@@ -1335,17 +1455,17 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   let askHere = choice?.askHere;
   if (choice?.remote) {
     const { host, id, reachable } = choice.remote;
-    if (reachable) return runAiRemote({ ...opts, path: projectRoot, conversation: id }, host, deps);
+    if (reachable) return runAiRemote({ ...opts, path: projectRoot, conversation: id }, host, deps, plan.seat);
     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;
+    const answer = deps.interactive ? deps.ask(`Continue ${id.slice(0, 8)} ${here}? ${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)}`,
+        `nothing started. ${atSeat ? 'Here' : `On ${plan.host}`}: ${vdxAiHere} ${shellQuote(projectRoot)} --conversation ${id}` +
+          ` · a new conversation: ${vdxAiHere} --new ${shellQuote(projectRoot)}`,
       );
       return EXIT_LAUNCH_FAILED;
     }
@@ -1363,16 +1483,17 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
       return EXIT_USAGE;
     }
     for (const c of plan.confirm) log(`note: the agent will ask "${c.screen}" — answer it with ${c.keys.join(' ')}`);
+    const env = plan.focused ? { ...process.env, [FOCUSED_ENV_VAR]: '1' } : undefined;
     const startedAt = Date.now();
-    let res = spawnSync(plan.command, [...plan.args, ...plan.resumeArgs], { cwd: projectRoot, stdio: 'inherit' });
+    let res = spawnSync(plan.command, [...plan.args, ...plan.resumeArgs], { cwd: projectRoot, stdio: 'inherit', env });
     if ((res.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
       log(`vdx ai: \`${plan.command}\` not found on PATH`);
       return 127;
     }
     const failedAtOnce = res.status !== null && res.status !== 0 && Date.now() - startedAt < NOTHING_TO_RESUME_MS;
     if (plan.resumeArgs.length > 0 && failedAtOnce) {
-      log(`↻ nothing to resume — starting without ${plan.resumeArgs.join(' ')}: ${commandLine(plan.command, plan.args)}`);
-      res = spawnSync(plan.command, plan.args, { cwd: projectRoot, stdio: 'inherit' });
+      log(`↻ nothing to resume — starting without ${plan.resumeArgs.join(' ')}: ${agentLine(plan, plan.args)}`);
+      res = spawnSync(plan.command, plan.args, { cwd: projectRoot, stdio: 'inherit', env });
     }
     return res.status ?? 1;
   }
@@ -1395,11 +1516,19 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
         );
       }
     }
+    if (plan.focused && !runningFocused) {
+      log(`✗ ${current.pane.session}: ${plan.command} is running, not focused`);
+      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)'),
+      );
+      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(' ')}`);
       log(
-        `  to apply the profile: vdx ai --restart${opts.fresh ? ' --new' : ''} ${shellQuote(projectRoot)}` +
+        `  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
@@ -1408,19 +1537,19 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
       );
       return EXIT_DRIFT;
     }
-    log(`✓ ${current.pane.session}: already running with the profile — ${current.proc.args}`);
+    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);
   }
 
   if (current) {
-    const line = commandLine(plan.command, [...plan.args, ...plan.resumeArgs]);
+    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);
   }
 
   if (opts.restart) log(`note: no running ${plan.command} in this project — starting one`);
-  const line = commandLine(plan.command, [...plan.args, ...plan.resumeArgs]);
+  const line = agentLine(plan, [...plan.args, ...plan.resumeArgs]);
   const cmd = tmuxShellCommand(line, deps.shell);
   const reuse = tmux.hasSession(plan.sessionName);
   const paneId = reuse

package/src/conversations.ts

@@ -314,10 +314,13 @@ export function parseMachineReport(text: string): MachineReport {
   return { home: text.match(/^home=(.+)$/m)?.[1] ?? null, sessions: parseLiveSessions(text) };
 }
 
-/** "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 {
+/**
+ * "running on m3 now (t23b-program@m3, waiting)" — where a live session is, for
+ * a person choosing; `place` is the machine as they see it: "here", "on m3".
+ */
+export function describeLive(place: string, live: LiveSession): string {
   const where = live.tmux ? live.tmux.replace(/:.*$/, '') : `pid ${live.pid}`;
-  return `running ${here ? 'here' : `on ${machine}`} now (${where}${live.status ? `, ${live.status}` : ''})`;
+  return `running ${place} now (${where}${live.status ? `, ${live.status}` : ''})`;
 }
 
 /** "3 min ago", "yesterday 14:05", "2026-09-30 14:05" — for a person choosing. */

package/src/index.ts

@@ -76,6 +76,11 @@ 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
   --conversation <id>
                 continue this Claude Code conversation
   --restart     restart the running agent in its pane — applies a changed profile
@@ -97,7 +102,8 @@ machine's. A new conversation (--new, or none to continue) while an agent of
 the project runs on another machine starts only after a yes.
 
 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
+3 the running agent lacks profile flags, or is not focused under --focused
+(rerun with --restart); 4 the start
 was not confirmed.
 Profile format: https://github.com/VoDmAl/vdx/blob/main/docs/specs/environment-format.md
 `;
@@ -156,10 +162,10 @@ Exit 2 when something is missing.
     positionals: 1,
   },
   ai: {
-    usage: 'vdx ai[@host] [project_path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]',
+    usage: 'vdx ai[@host] [project_path] [--new | --conversation <id>] [--focused] [--restart] [--detach] [--dry-run]',
     help: AI_HELP,
     // `--resume` asked to continue in 0.12; continuing is the default now.
-    bools: ['new', 'restart', 'resume', 'detach', 'dry-run', 'check'],
+    bools: ['new', 'focused', 'restart', 'resume', 'detach', 'dry-run', 'check'],
     values: ['conversation'],
     positionals: 1,
   },
@@ -500,6 +506,7 @@ function cmdAi(opts: ParsedArgs): void {
     conversation,
     detach: opts.flags.detach === true,
     dryRun: opts.flags['dry-run'] === true,
+    focused: opts.flags.focused === true,
   };
   const deps = { ...defaultDeps(), version: readCliVersion() };
   // `ai@m3`: the same command on another machine. Its own label runs here.

package/src/init.ts

@@ -12,7 +12,7 @@ import {
 export const STANDARD_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
 export type Verb = (typeof STANDARD_VERBS)[number];
 
-export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.0.0';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.2.0';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],