@vodmal/vdx-cli 0.22.1 → 0.24.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)
@@ -75,11 +75,12 @@ vdx init --stack node
 vdx test            # → mise run test (which calls `vitest run` or whatever was detected)
 
 # 3. Ship a new minor release of a Node lib
-vdx publish minor   # npm login if expired → bump package.json + lock → npm publish (OTP) → commit + tag → push → wait for the registry
+vdx publish minor   # npm login if expired → bump package.json + lock → npm publish (OTP or browser) → commit + tag → push → wait for the registry
 
 # 4. Start the agent here, continuing its last conversation (--new: a new one;
 #    another machine's conversation is continued on that machine);
-#    re-run to attach, --restart to apply a changed profile
+#    re-run to attach; an agent without the profile's flags is a question:
+#    Enter attaches as is, r restarts it; --restart applies a changed profile
 vdx ai
 
 # 5. The same on another machine (an ssh host with vdx), attaching from here

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.22.1",
+  "version": "0.24.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.3.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 {
@@ -82,6 +84,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;
 }
 
 /**
@@ -118,6 +122,11 @@ 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;
@@ -170,6 +179,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) => {
@@ -214,6 +224,9 @@ export function parseEnvironment(text: string, source: string): Environment {
         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;
@@ -289,6 +302,10 @@ export interface LaunchPlan {
   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;
@@ -305,14 +322,21 @@ export function planLaunch(input: {
   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 ?? []));
@@ -328,6 +352,8 @@ export function planLaunch(input: {
     args,
     resumeArgs: [...(agent.resume_args ?? [])],
     matched,
+    focused,
+    skipped,
     confirm,
     multiplexer: environment.session?.multiplexer ?? 'none',
     sessionName: renderSessionName(environment.session?.name ?? DEFAULT_SESSION_NAME, {
@@ -670,6 +696,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 {
@@ -683,6 +711,10 @@ 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;
+  /** 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. */
@@ -758,15 +790,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'
@@ -777,10 +815,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' : ''}`,
       );
     }
   }
@@ -880,7 +919,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';
@@ -926,6 +965,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',
@@ -1194,10 +1234,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);
@@ -1235,9 +1277,8 @@ function prepare(pathArg: string, deps: AiDeps): Prepared | number {
     profileDir,
   });
 
-  let plan: LaunchPlan;
-  try {
-    plan = planLaunch({
+  const replan = (asFocused: boolean) =>
+    planLaunch({
       environment,
       profilePath,
       agent,
@@ -1246,12 +1287,77 @@ function prepare(pathArg: string, deps: AiDeps): Prepared | number {
       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;
+  }
+}
+
+/** 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));
+  // `ls`, not `[ -d ]`: a denied folder still passes -d.
+  const script = dirs.map((d) => `{ [ ! -d ${shellQuote(d)} ] || ls ${shellQuote(d)} >/dev/null 2>&1 || echo ${shellQuote(d)}; }`).join('; ');
+  const out = tmux?.tryRun(['run-shell', script]);
+  if (out !== undefined && out !== null) return out.split('\n').filter(Boolean);
+  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)}`;
 }
 
 /** The nearest ancestor of `pid` that is the agent: the session a hook or a shell tool runs in. */
@@ -1272,9 +1378,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 ` +
@@ -1283,6 +1392,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.`);
@@ -1300,10 +1417,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;
@@ -1312,12 +1429,14 @@ 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.
+  // 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}`;
@@ -1340,6 +1459,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;
@@ -1357,13 +1483,18 @@ 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));
+    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;
@@ -1404,16 +1535,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;
   }
@@ -1436,32 +1568,50 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
         );
       }
     }
-    const missing = missingArgs(current.proc.args, plan.args);
-    if (missing.length > 0) {
-      log(`✗ ${current.pane.session}: ${plan.command} is running without ${missing.join(' ')}`);
-      log(
-        `  to apply the profile: vdx ai --restart${opts.fresh ? ' --new' : ''} ${shellQuote(projectRoot)}` +
-          (plan.resumeArgs.length
-            ? ` (stops the running agent, then resumes 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)'),
-      );
+    const unfocused = plan.focused && !runningFocused;
+    const missing = unfocused ? [] : missingArgs(current.proc.args, plan.args);
+    if (!unfocused && missing.length === 0) {
+      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);
+    }
+    // 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)}`;
+    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(`⚠ ${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;
     }
-    log(`✓ ${current.pane.session}: already running with the profile — ${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/index.ts

@@ -76,9 +76,17 @@ 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
+  --restart     restart the running agent in its pane — applies a changed profile.
+                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
   --detach      start without attaching; print the command that attaches
   --dry-run     print the plan and the project's running agents; start nothing
   --check       for the agent's own session: how the agent here is launched, and
@@ -97,7 +105,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,
+and was left as is — no terminal, or q (rerun with --restart); 4 the start
 was not confirmed.
 Profile format: https://github.com/VoDmAl/vdx/blob/main/docs/specs/environment-format.md
 `;
@@ -128,7 +137,8 @@ mise.toml is overwritten only with --force.
   pre-flight checks — at a terminal an expired npm login is renewed (\`npm login\`)
   and the checks run again;
   the version bump in package.json and package-lock.json;
-  npm publish (npm asks for an OTP);
+  npm publish (npm asks for an OTP or a confirmation in the browser; Ctrl-C
+  there puts the version back);
   git commit and tag, then \`git push --follow-tags\` to the branch's upstream;
   a wait until the registry shows the new version (up to 3 min).
 --dry-run runs the pre-flight and prints the plan; --force goes on past a failed
@@ -156,10 +166,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 +510,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.3.0';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],

package/src/publish.ts

@@ -481,7 +481,7 @@ export function waitForRegistry(name: string, version: string, deps: PublishDeps
  *      or there is none. The pre-flight refused a branch behind its upstream.
  *   5. Wait until the registry shows the version.
  *
- * On npm publish failure → restore the original files.
+ * On npm publish failure or interruption (Ctrl-C at its prompt) → restore the original files.
  * Git failures after a successful npm publish leave the user in a
  * partially-released state; they fix it manually (commit/tag/push what's
  * needed) — we don't try to unpublish.
@@ -511,14 +511,22 @@ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPub
     `✓ bumped ${bumped.map((f) => path.relative(plan.projectRoot, f)).join(' and ')}: ${plan.currentVersion} → ${plan.newVersion}`,
   );
 
-  // 2. npm publish (interactive — OTP prompt may appear)
-  deps.log('→ running `npm publish` (OTP prompt may appear)...');
+  // 2. npm publish (interactive — npm asks for an OTP or a confirmation in the browser).
+  // Ctrl-C at that prompt reaches npm and vdx alike: vdx holds out while npm runs, so the
+  // interrupted npm comes back as an error and the bump is put back — not left for the next run.
+  deps.log('→ running `npm publish` (npm may ask for an OTP or a confirmation in the browser)...');
+  const holdOut = () => {};
+  const signals: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  for (const s of signals) process.on(s, holdOut);
   try {
     deps.run('npm', ['publish'], path.dirname(plan.packageJsonPath));
   } catch (e: any) {
     for (const [file, text] of originals) fs.writeFileSync(file, text, 'utf8');
-    deps.log(`✗ npm publish failed (exit ${e?.status ?? '?'}); reverted ${bumped.map((f) => path.basename(f)).join(' and ')}`);
-    throw new Error('npm publish failed');
+    const what = e?.signal ? `interrupted (${e.signal})` : `failed (exit ${e?.status ?? '?'})`;
+    deps.log(`✗ npm publish ${what}; reverted ${bumped.map((f) => path.basename(f)).join(' and ')}`);
+    throw new Error(`npm publish ${e?.signal ? 'interrupted' : 'failed'}`);
+  } finally {
+    for (const s of signals) process.off(s, holdOut);
   }
   deps.log(`✓ published ${plan.packageName}@${plan.newVersion}`);