@vodmal/vdx-cli 0.31.1 → 0.31.3

package/README.md

@@ -48,7 +48,7 @@ vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
 # Push the branch; one that requires checks on GitHub takes the commit once they pass
 vdx push [project-path] [--dry-run]   # default: cwd
 
-# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project)
+# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project; the GitHub token vdx asks with)
 vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
 vdx doctor --check [project-path]   # one line per hook declared but not running here — the plugin's SessionStart hook tells the agent
 vdx doctor --fix                    # write the profile's personal hooks (git.hooks) into ~/.gitconfig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.31.1",
+  "version": "0.31.3",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/src/ai.ts

@@ -292,6 +292,20 @@ export function renderSessionName(template: string, vars: Record<string, string>
   return name.replace(/[.:]/g, '_');
 }
 
+/**
+ * The session for an agent started next to running ones: `name`, `name-2`, `name-3`… — the
+ * first no agent of the project runs in (absent, or a shell left behind). Each agent has a
+ * session of its own: tmux keeps one current window per session, and an agent started as a
+ * window next to another moved every terminal on the session to it (vdx-ai DL #36).
+ */
+export function freeSessionName(name: string, running: { pane: { session: string } }[]): string {
+  const busy = new Set(running.map((a) => a.pane.session));
+  for (let n = 1; ; n++) {
+    const candidate = n === 1 ? name : `${name}-${n}`;
+    if (!busy.has(candidate)) return candidate;
+  }
+}
+
 export interface LaunchPlan {
   projectRoot: string;
   project: string;
@@ -748,7 +762,7 @@ export function sleepSync(ms: number): void {
 }
 
 /** Read one line from the terminal, synchronously: the prompt runs before tmux takes it. */
-function askLine(prompt: string): string | null {
+export function askLine(prompt: string): string | null {
   process.stderr.write(prompt);
   const buf = Buffer.alloc(256);
   let text = '';
@@ -804,7 +818,9 @@ function renderPlan(
   plan: LaunchPlan,
   multiplexer: Multiplexer,
   running: AgentPane[],
-  focusedOf: (pid: number) => boolean = () => false,
+  focusedOf: (pid: number) => boolean,
+  /** The session a start would make: next to running agents, one of its own. */
+  session: string,
 ): string {
   const lines = [
     `vdx ai — ${plan.projectRoot}`,
@@ -819,7 +835,7 @@ function renderPlan(
   for (const c of plan.confirm) lines.push(`  confirm:  "${c.screen}" → ${c.keys.join(' ')}`);
   lines.push(
     multiplexer === 'tmux'
-      ? `  session:  tmux; a new session is named "${plan.sessionName}"`
+      ? `  session:  tmux; a new session is named "${session}"`
       : '  session:  this terminal (no tmux)',
   );
   if (multiplexer === 'tmux') {
@@ -1618,7 +1634,9 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     ? foldersWarning(denied, multiplexer === 'tmux', environment.session?.folders_fix, deps.home)
     : [];
   if (opts.dryRun) {
-    deps.out(renderPlan(plan, multiplexer, running, focusedOf));
+    deps.out(
+      renderPlan(plan, multiplexer, running, focusedOf, freeSessionName(plan.sessionName, alongside ? running : [])),
+    );
     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);
@@ -1758,10 +1776,9 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   if (opts.restart) log(`note: no running ${plan.command} in this project — starting one`);
   const line = agentLine(plan, [...plan.args, ...plan.resumeArgs]);
   const cmd = tmuxShellCommand(line, deps.shell);
-  const reuse = tmux.hasSession(plan.sessionName);
-  const paneId = reuse
-    ? tmux.newWindow(plan.sessionName, projectRoot, cmd)
-    : tmux.newSession(plan.sessionName, projectRoot, cmd);
-  log(`▶ ${plan.sessionName}${reuse ? ' (new window)' : ''}: ${line}`);
-  return finish(settleResumed(plan, paneId, deps), plan.sessionName, paneId, opts, deps);
+  const session = freeSessionName(plan.sessionName, running);
+  const reuse = tmux.hasSession(session);
+  const paneId = reuse ? tmux.newWindow(session, projectRoot, cmd) : tmux.newSession(session, projectRoot, cmd);
+  log(`▶ ${session}${reuse ? ' (new window)' : ''}: ${line}`);
+  return finish(settleResumed(plan, paneId, deps), session, paneId, opts, deps);
 }

package/src/doctor.ts

@@ -3,10 +3,11 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
-import { effectiveAuthor, isGitRepo, rankAuthors, scanPool } from './author.ts';
+import { effectiveAuthor, isGitRepo, rankAuthors, remoteParts, scanPool } from './author.ts';
 import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
 import { checkRepoHooks } from './clone-checks.ts';
-import { at, dict } from './narrow.ts';
+import { githubToken, machineIo, type HostingIo } from './hosting.ts';
+import { at, dict, errorMessage, str } from './narrow.ts';
 import {
   checkPersonalHooks,
   defaultPersonalHookDeps,
@@ -417,6 +418,61 @@ export function checkGitAuthor(ctx: DoctorCtx): CheckResult | null {
   };
 }
 
+/**
+ * The token vdx asks GitHub with, for a repository whose origin is there — the audit
+ * (`branch-protection`) and `vdx push` ask. Without one GitHub answers 60 requests an
+ * hour; a token that no longer works is worse than none: every answer is a 401.
+ * `/rate_limit` tells both apart and costs nothing of the limit.
+ */
+export function checkGithubToken(
+  ctx: DoctorCtx,
+  io: HostingIo | null = ctx.projectRoot ? machineIo(ctx.projectRoot) : null,
+  ghOnPath: boolean = findOnPath('gh') !== null,
+  platform: NodeJS.Platform = process.platform,
+): CheckResult | null {
+  if (ctx.projectRoot === null || io === null) return null;
+  const url = io.git(['remote', 'get-url', 'origin']);
+  if (!url || remoteParts(url).host !== 'github.com') return null;
+  const id = 'github-token';
+  const label = 'GitHub token';
+  if (io.env.VDX_OFFLINE) return { id, label, status: 'ok', message: 'VDX_OFFLINE is set — vdx does not ask GitHub' };
+  const t = githubToken(io);
+  let status: number;
+  let body: unknown;
+  try {
+    ({ status, body } = io.get('/rate_limit', t?.token ?? null));
+  } catch (e) {
+    return { id, label, status: 'warning', message: `GitHub did not answer: ${errorMessage(e)}` };
+  }
+  if (status === 401 && t) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: `the token from ${t.source} does not work (GitHub: ${str(at(body, 'message')) ?? '401'}) — every answer is a 401`,
+      remedy: t.source === 'gh' ? 'gh auth login -h github.com' : `a working ${t.source}, or unset it`,
+    };
+  }
+  if (status !== 200) return { id, label, status: 'warning', message: `GitHub answered ${status} for /rate_limit` };
+  const limit = at(body, 'resources', 'core', 'limit');
+  const left = at(body, 'resources', 'core', 'remaining');
+  const hour = typeof limit === 'number' ? `${limit} requests an hour` : 'its limit';
+  const remaining = typeof left === 'number' ? `, ${left} left` : '';
+  if (t) return { id, label, status: 'ok', message: `from ${t.source}: ${hour}${remaining}` };
+  return {
+    id,
+    label,
+    status: 'warning',
+    message: `none — GitHub answers ${hour} without one${remaining}; an audit takes about 3, vdx push about 10`,
+    remedy: !ghOnPath
+      ? 'install gh (https://cli.github.com) and gh auth login, or set GH_TOKEN'
+      : io.env.SSH_CONNECTION && platform === 'darwin'
+        ? // m3, 2026-10-19: logged in, and `ssh m3 gh` saw no token, while tmux there did.
+          'over ssh gh cannot read the macOS keychain where it keeps the token — in a local terminal or tmux it can; else gh auth login -h github.com'
+        : 'gh auth login -h github.com',
+  };
+}
+
 const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkVdxVersion,
   checkVdx,
@@ -430,6 +486,7 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   (ctx) => checkRepoHooks(ctx.projectRoot),
   (ctx) => checkPersonalHooks(ctx.projectRoot),
   checkGitAuthor,
+  (ctx) => checkGithubToken(ctx),
 ];
 
 export function resolveDoctorCtx(cwd: string = process.cwd()): DoctorCtx {

package/src/hosting.ts

@@ -170,7 +170,15 @@ export function githubRepo(io: HostingIo, remote: string): { repo: string; token
   // The host only: a URL can carry a token.
   if (host !== 'github.com')
     return { unknown: `${remote} is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub only` };
-  return { repo, token: io.env.GH_TOKEN || io.env.GITHUB_TOKEN || io.ghToken() };
+  return { repo, token: githubToken(io)?.token ?? null };
+}
+
+/** The token vdx asks GitHub with and where it comes from — `GH_TOKEN`, `GITHUB_TOKEN`, then gh, as gh itself picks. */
+export function githubToken(io: HostingIo): { token: string; source: 'GH_TOKEN' | 'GITHUB_TOKEN' | 'gh' } | null {
+  if (io.env.GH_TOKEN) return { token: io.env.GH_TOKEN, source: 'GH_TOKEN' };
+  if (io.env.GITHUB_TOKEN) return { token: io.env.GITHUB_TOKEN, source: 'GITHUB_TOKEN' };
+  const gh = io.ghToken();
+  return gh ? { token: gh, source: 'gh' } : null;
 }
 
 function isUnknownRepo(v: { repo: string } | Unknown): v is Unknown {

package/src/index.ts

@@ -35,7 +35,7 @@ import {
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
 import { defaultGateDeps, GATE_PREFIX, planGate, pushThroughGate } from './gate.ts';
-import { runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
+import { askLine, runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
 import { isConversationId } from './conversations.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
@@ -83,7 +83,7 @@ the project's files). Hand a person \`vdx ai\`, not \`<agent> --<flag>\`.
   @host         the same command on <host> over ssh: its vdx, profile and tmux
   --new         a new conversation instead of continuing the last one; an agent
                 already running here keeps running, the new one starts next to
-                it (a new tmux window)
+                it, in a tmux session of its own (<name>-2, -3, …)
   --focused     a new conversation, as --new, in a session nothing wakes: the
                 agent, its hooks and MCP servers get VDX_FOCUSED=1 — for the
                 plugins that wake sessions to leave it alone — and the profile's
@@ -156,7 +156,10 @@ mise.toml is overwritten only with --force.
   git commit and tag, then \`git push --follow-tags\` to the branch's upstream —
   through its checks when it requires some, as \`vdx push\` does: the pre-flight
   then refuses local commits not pushed yet, npm would get them before CI;
-  a wait until the registry shows the new version (up to 3 min).
+  a wait until the registry shows the new version (up to 10 min from npm publish;
+  Ctrl-C there stops only the wait).
+Nothing in the package's directory changed since the tag of its version: the
+same package under a new number — at a terminal a question, Enter releases nothing.
 --dry-run runs the pre-flight and prints the plan; --force goes on past a failed
 pre-flight; --no-push leaves the commit and the tag local.
 `,
@@ -193,7 +196,9 @@ or GitHub stopped answering; a plain git push exits with git's own code.
     help: `Checks this machine for what vdx needs (Node, git, mise, npm auth, docker, the
 Claude Code plugin) and, inside a project (default: cwd), its commit author and
 its git hooks: are the hooks the repository declares on in this clone, and do
-the personal hooks of your profile (git.hooks) run on this machine. Reads only.
+the personal hooks of your profile (git.hooks) run on this machine; with origin on
+GitHub, the token vdx asks GitHub with ($GH_TOKEN, $GITHUB_TOKEN or gh) and
+whether it works — without one GitHub answers 60 requests an hour. Reads only.
 Exit 2 when something is missing.
 
   --check  for the agent's own session (the vdx plugin's SessionStart hook): one
@@ -438,7 +443,8 @@ function cmdPublish(opts: ParsedArgs): void {
   const deps = defaultPublishDeps();
   const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
   if (!plan.preflightPassed && !planOpts.force && interactive && preflightFixable(plan)) {
-    for (const c of plan.preflight.filter((c) => !c.ok && c.fix)) {
+    const fixes = plan.preflight.filter((c) => !c.ok && c.fix);
+    for (const c of fixes) {
       process.stderr.write(`\n→ ${c.name}: ${c.fix!.cmd} ${c.fix!.args.join(' ')}\n`);
       try {
         deps.run(c.fix!.cmd, c.fix!.args, projectRoot);
@@ -447,11 +453,27 @@ function cmdPublish(opts: ParsedArgs): void {
         process.exit(2);
       }
     }
-    plan = replan();
-    process.stdout.write('\n' + renderPublishPlan(plan));
+    if (fixes.length > 0) {
+      plan = replan();
+      process.stdout.write('\n' + renderPublishPlan(plan));
+    }
+  }
+
+  // A failure the person may waive (nothing changed since the release): a question, Enter no.
+  let waived = false;
+  const left = plan.preflight.filter((c) => !c.ok);
+  if (!planOpts.force && interactive && left.length > 0 && left.every((c) => c.waive)) {
+    for (const c of left) {
+      process.stderr.write(`\n${c.name}: ${c.message}\n`);
+      if (!/^y(es)?$/i.test(askLine(c.waive!) ?? '')) {
+        process.stderr.write('nothing released\n');
+        process.exit(2);
+      }
+    }
+    waived = true;
   }
 
-  if (!plan.preflightPassed && !planOpts.force) {
+  if (!plan.preflightPassed && !planOpts.force && !waived) {
     process.stderr.write('\nerror: pre-flight failed (use --force to bypass)\n');
     process.exit(2);
   }

package/src/publish.ts

@@ -24,6 +24,8 @@ export interface PreflightCheck {
   message: string;
   /** A failed check a command at the terminal can fix — `npm login` for an expired session. */
   fix?: { cmd: string; args: string[] };
+  /** A failed check the person at the terminal may waive: the question, Enter answering no. */
+  waive?: string;
 }
 
 /** Where the release goes after the tag. */
@@ -311,6 +313,9 @@ export function planPublish(
   });
 
   preflight.push(checkNpmAuth(publishRegistry(pkg, npm), npm));
+  preflight.push(
+    checkChangesSinceRelease(opts.projectRoot, path.dirname(pkgJsonPath), currentVersion, newVersion, git),
+  );
 
   let published: string | null = null;
   let registryError: string | null = null;
@@ -397,10 +402,50 @@ export function planPublish(
   };
 }
 
-/** Every failed check has a command that fixes it — run at a terminal, then plan again. */
+/**
+ * Anything to release? 0.30.0 went out on 2026-10-18 with nothing since v0.29.0 but
+ * its release commit (hosting-extension Sidetrack #6). Nothing in the package's
+ * directory since the tag of the current version — the same package under a new
+ * number; a terminal asks, Enter answering no.
+ */
+export function checkChangesSinceRelease(
+  projectRoot: string,
+  packageDir: string,
+  current: string,
+  next: string,
+  git: GitRunner,
+): PreflightCheck {
+  const name = 'changes-since-release';
+  const tag = `v${current}`;
+  try {
+    git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], projectRoot);
+  } catch {
+    return { name, ok: true, message: `OK (no tag ${tag} to compare with)` };
+  }
+  const where = path.relative(projectRoot, packageDir) || '.';
+  const shown = where === '.' ? `${path.basename(packageDir)}/` : `${where}/`;
+  let count: number;
+  try {
+    count = parseInt(git(['rev-list', '--count', `${tag}..HEAD`, '--', where], projectRoot).trim(), 10) || 0;
+  } catch {
+    return { name, ok: true, message: `OK (git could not compare with ${tag})` };
+  }
+  if (count > 0) return { name, ok: true, message: `OK (${count} commit(s) in ${shown} since ${tag})` };
+  return {
+    name,
+    ok: false,
+    message: `nothing in ${shown} has changed since ${tag}: ${next} would be the package ${current} is`,
+    waive: `Release ${next} anyway, the same package under a new number? [y/N] `,
+  };
+}
+
+/**
+ * Every failed check is resolved at a terminal: a command that fixes it (run, then
+ * plan again) or a question the person may answer yes to.
+ */
 export function preflightFixable(plan: PublishPlan): boolean {
   const failed = plan.preflight.filter((c) => !c.ok);
-  return failed.length > 0 && failed.every((c) => c.fix);
+  return failed.length > 0 && failed.every((c) => c.fix || c.waive);
 }
 
 /** Runs a command on this terminal (stdio inherited); throws on a non-zero exit. */
@@ -431,7 +476,7 @@ export function defaultPublishDeps(): PublishDeps {
     npm: runNpm,
     log: (line) => process.stderr.write(line + '\n'),
     sleep: sleepSync,
-    registryWaitMs: 180_000,
+    registryWaitMs: 10 * 60_000,
     progress: process.stderr.isTTY ? (text) => process.stderr.write(`\r${text}\x1b[K`) : undefined,
     gatePush: (target, projectRoot) => pushThroughGate(target, defaultGateDeps(projectRoot)),
   };
@@ -447,19 +492,22 @@ export function bumpLockText(text: string, version: string): string {
 }
 
 /**
- * npm answers `202 Accepted` and the version shows up a minute or two later;
- * until then `npm view` and `npx` still see the previous one. Waiting here
- * turns "is it out?" into an answer. A version that does not show up in time
- * is not a failure: npm took it.
+ * npm answers `202 Accepted` and the version shows up minutes later — 0.30.0
+ * about 6 min after publish, 0.31.2 past 5 (hosting-extension Sidetrack #9); until
+ * then `npm view` and `npx` still see the previous one. Waiting here turns "is it
+ * out?" into an answer. The time counts from `npm publish` (`since`): the push
+ * through CI before the wait is part of it. A version that does not show up in
+ * time is not a failure: npm took it.
  */
-export function waitForRegistry(name: string, version: string, deps: PublishDeps): boolean {
-  const started = Date.now();
+export function waitForRegistry(name: string, version: string, deps: PublishDeps, since = Date.now()): boolean {
+  const started = since;
   const deadline = started + deps.registryWaitMs;
   const limit = Math.round(deps.registryWaitMs / 1000);
   const seconds = () => Math.round((Date.now() - started) / 1000);
   deps.log(
     `→ waiting for the registry to show ${name}@${version} — npm has taken it; ` +
-      `the registry usually shows it within ~2 min (giving it ${limit} s)`,
+      `the registry has taken up to 6 min to show a version (giving it ${limit} s from publish; ` +
+      `Ctrl-C stops only this wait)`,
   );
   const shown = () => {
     try {
@@ -556,6 +604,7 @@ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPub
   } finally {
     for (const s of signals) process.off(s, holdOut);
   }
+  const publishedAt = Date.now();
   deps.log(`✓ published ${plan.packageName}@${plan.newVersion}`);
 
   // 3. git add + commit + tag (at project root)
@@ -597,7 +646,7 @@ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPub
   }
 
   // 5. registry
-  waitForRegistry(plan.packageName, plan.newVersion, deps);
+  waitForRegistry(plan.packageName, plan.newVersion, deps, publishedAt);
 }
 
 export function renderPublishPlan(plan: PublishPlan): string {
@@ -643,7 +692,10 @@ export function renderPublishPlan(plan: PublishPlan): string {
       const fixes = plan.preflight
         .filter((c) => !c.ok && c.fix)
         .map((c) => `\`${c.fix!.cmd} ${c.fix!.args.join(' ')}\``);
-      lines.push(`0. ${fixes.join(', ')} — at a terminal, then the pre-flight again`);
+      if (fixes.length > 0) lines.push(`0. ${fixes.join(', ')} — at a terminal, then the pre-flight again`);
+      for (const c of plan.preflight.filter((c) => !c.ok && c.waive)) {
+        lines.push(`0. At a terminal: ${c.waive!.trim()} — Enter releases nothing`);
+      }
     }
     lines.push(`1. Set \`version\` in ${files} → \`${plan.newVersion}\``);
     lines.push(`2. \`npm publish\` (cwd = directory containing package.json)`);
@@ -658,7 +710,7 @@ export function renderPublishPlan(plan: PublishPlan): string {
             ? `5. \`git push --follow-tags\` → ${push.upstream}${push.ahead ? ` (with ${push.ahead} local commit(s) not pushed yet)` : ''}`
             : '5. Not pushed: the branch has no upstream',
     );
-    lines.push(`6. Wait until the registry shows ${plan.newVersion} (up to 3 min)`);
+    lines.push(`6. Wait until the registry shows ${plan.newVersion} (up to 10 min from publish)`);
   } else {
     lines.push('> Pre-flight failed. Use `--force` to bypass at your own risk.');
   }