@vodmal/vdx-cli 0.21.1 → 0.22.1

package/README.md

@@ -26,8 +26,9 @@ ephemeral environment.
 
 **First command after install: `vdx doctor`** — it inspects your environment
 (Node version, `vdx` on PATH, git, mise, npm auth, container runtime, Claude
-Code plugin; in a project — git hooks and the commit author) and points to remedies for everything that's missing or
-sub-optimal.
+Code plugin; in a project — whether its git hooks are on in this clone, and the
+commit author; with a profile — whether your personal hooks run on this machine)
+and points to remedies for everything that's missing or sub-optimal.
 
 ## Use
 
@@ -44,8 +45,10 @@ vdx init  [project-path] [--baseline github.com/org/repo@vX.Y] [--stack <id>] [-
 # Publish a library (Node MVP; PHP/Python coming in Y.3)
 vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
 
-# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin)
-vdx doctor [--format=ansi|markdown|json]
+# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project)
+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
 
 # 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
@@ -123,9 +126,14 @@ npm run typecheck
 - `src/rubric.ts`     — types + YAML loader
 - `src/manifest.ts`   — parser for `[vdx]` block in `mise.toml` + `.vdx-overrides.yml`
 - `src/facts.ts`      — fact source loaders (tasks, packages, configs, sub-package detection)
-- `src/predicates.ts` — predicate registry (11 functions)
+- `src/predicates.ts` — predicate registry; true / false / unknown with a reason (schema 0.3)
 - `src/evaluator.ts`  — recursive evaluator + sugar notation
-- `src/scoring.ts`    — delta-style levels, flags for orthogonal axes
+- `src/scoring.ts`    — delta-style levels, `not_required` levels, flags for orthogonal axes
+- `src/gha.ts`        — GitHub Actions workflows as the `ci` axis reads them
+- `src/vocabulary.ts` — which project tasks a command calls through the project's runner
+- `src/hooks.ts`      — one recognizer of hook frameworks for audit and doctor
+- `src/clone-checks.ts` — clone checks printed by doctor and next to an axis in audit
+- `src/personal-hooks.ts` — the profile's personal hooks in ~/.gitconfig: check and `--fix`
 - `src/audit.ts`      — orchestrator: overrides + applies_to filter + subpackage-ctx
 - `src/init.ts`       — `vdx init` planner (`selectVerbTask` + mise.toml renderer)
 - `src/run.ts`        — `resolveLifecycleVerb` + error renderer (pure logic for `vdx <verb>`)
@@ -139,7 +147,9 @@ npm run typecheck
 
 ## Not implemented yet
 
-- `command_succeeds` predicate is a stub (warning at evaluation).
+- Above L1 the `ci` axis reads GitHub Actions only; other CI systems answer
+  "unknown". `branch-protection` is "unknown" everywhere until a hosting
+  extension exists.
 - Baseline loading from a git ref is documented but evaluator still reads file
   paths only — `baseline:` in `mise.toml` is recorded but does not auto-fetch.
 - Watermark drift (phase 2 of `drift-algorithm.md`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.21.1",
+  "version": "0.22.1",
   "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

@@ -7,11 +7,11 @@
 # дельту относительно L(N-1). Уровень оси = max L, для которого истинны
 # requires(L1), ..., requires(L) подряд (без разрывов).
 
-schema_version: "0.2"
+schema_version: "0.3"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "0.7.0"
+  version: "1.0.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"
@@ -24,8 +24,8 @@ levels:
   L0: { name: chaos,        description: "Не поднимается, знание в голове" }
   L1: { name: reproducible, description: "Поднимается одной задокументированной командой" }
   L2: { name: testable,     description: "Тесты есть; единый словарь up/test/build" }
-  L3: { name: gated,        description: "Статанализ + стиль + CI-гейты на PR (реальные!)" }
-  L4: { name: exemplar,     description: "Полная глубина: хуки, mock-инфра, observability, версионированная общая инфра" }
+  L3: { name: gated,        description: "Статанализ + стиль; CI зовёт словарь проекта; main на хостинге принимает только проверенное" }
+  L4: { name: exemplar,     description: "Полная глубина: хуки повторяют CI, mock-инфра, observability, версионированная общая инфра" }
 
 axes:
 
@@ -183,13 +183,15 @@ axes:
 
   - id: ci
     class: critical
-    description: "Реальное гейтование PR (no `|| true`!)"
+    description: "Сигнал: тесты на каждый push в основную ветку, падение не замаскировано. Гейт до слияния — ось branch-protection"
     storage: level
     default_target: L4
     fact_sources:
       - .github/workflows/
       - .gitlab-ci.yml
       - .circleci/config.yml
+    # Выше L1 vdx читает только GitHub Actions; у прочих CI-систем L2+ —
+    # «неизвестно», в общем уровне это «не выполнено».
     levels:
       L1:
         requires:
@@ -197,28 +199,45 @@ axes:
             - has_file: .github/workflows
             - has_file: .gitlab-ci.yml
             - has_file: .circleci/config.yml
+      # Тесты на push в main/master (фильтр веток или без него). Шаг с `|| true`
+      # или continue-on-error не засчитывается. Только PR-триггер — тоже: в репо
+      # с пушами в main такой CI не запускается никогда.
       L2:
         requires:
-          any_of:
-            - file_contains:
-                paths: [.github/workflows/*.yml, .gitlab-ci.yml]
-                pattern: "(phpstan|phpunit|composer test|npm test|jest|pytest)"
+          gha_tests_on_push:
+            pattern: "\\b(phpunit|pest|composer test|npm test|npm run test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|mix test|rspec|vdx test|mise run test)\\b"
+      # Паритет: CI вызывает задачи проекта check и test (или check:* / test:*)
+      # через его раннер — то же, что человек и агент запускают локально.
       L3:
         requires:
-          all_of:
-            - any_of:
-                - gh_workflow_blocks_pr: {}
-                - file_contains: { path: .gitlab-ci.yml, pattern: "rules:.+merge_request" }
-            - not:
-                file_contains:
-                  paths: [.github/workflows/*.yml, .gitlab-ci.yml]
-                  pattern: "\\|\\| true"
+          gha_runs_tasks: { tasks: [check, test] }
+      # Ширина или конвейер: проверяющая задача идёт по matrix, либо всё, что CI
+      # выкладывает или выпускает (deploy/release/publish), ждёт её через needs:.
       L4:
         requires:
           any_of:
-            - file_contains: { path: .github/workflows/*.yml, pattern: "matrix:" }
-            - file_contains: { path: .github/workflows/*.yml, pattern: "sentry-release|action-release" }
-            - gh_workflow_blocks_pr: { check_name: "deploy" }
+            - gha_test_matrix:
+                pattern: "\\b(phpunit|pest|composer test|npm test|npm run test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|mix test|rspec|vdx test|mise run test)\\b"
+            - gha_ship_needs_checks:
+                pattern: "\\b(phpunit|pest|composer test|npm test|npm run test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|mix test|rspec|vdx test|mise run test)\\b"
+
+  - id: branch-protection
+    class: critical
+    description: "Основная ветка на хостинге принимает изменения только после обязательной проверки"
+    storage: level
+    default_target: L4
+    fact_sources: [hosting API]
+    # Гейт — свойство L3 общей лестницы; ниже ось ничего не требует и уровень
+    # не ограничивает. Знает о защите только хостинг: пока расширения для него
+    # нет, L3 — «неизвестно» у всех. L4 — позже: force-push, удаление ветки,
+    # ревью (как Branch-Protection у Scorecard).
+    levels:
+      L1: { not_required: true }
+      L2: { not_required: true }
+      L3:
+        requires:
+          branch_requires_checks: {}
+      L4: { not_required: true }
 
   # =========================================================================
   # SUPPORTING
@@ -364,32 +383,36 @@ axes:
 
   - id: git-hygiene
     class: supporting
+    description: "Хуки репозитория: ставятся сами, зовут словарь проекта, повторяют проверки CI"
     storage: level
     default_target: L4
-    fact_sources: [.husky/, .lefthook.yml, lefthook.yml, composer.json, package.json]
+    fact_sources: [.gitignore, .husky/, lefthook.yml, .lefthook.yml, .githooks/, package.json, composer.json, mise.toml]
+    # Включены ли хуки в этом клоне — пометка рядом с осью в `vdx audit` и строка
+    # `vdx doctor`; уровень не меняет: тот же репо и тот же тег дают тот же отчёт
+    # в любом клоне.
+    clone_check: git-hooks
     levels:
       L1:
         requires:
           has_file: .gitignore
+      # Репо ставит свои хуки сам на обычной установке: husky в prepare/postinstall
+      # (под Yarn 2+ — только postinstall), пакеты lefthook / simple-git-hooks,
+      # `cghooks add` в post-install-cmd, `git config core.hooksPath` в шаге
+      # установки или в задаче up. Объявленный, но не ставящийся сам — не L2.
       L2:
         requires:
-          any_of:
-            - has_file: .husky
-            - has_file: .lefthook.yml
-            - has_file: lefthook.yml
-            - package_present: { name: brainmaestro/composer-git-hooks, ecosystem: composer }
-            - package_present: { name: husky, ecosystem: npm }
+          git_hooks_arranged: {}
+      # pre-commit или pre-push зовёт задачу словаря (test, check, check:*, test:*)
+      # через раннер проекта.
       L3:
         requires:
-          any_of:
-            - file_contains: { path: composer.json, pattern: "\"pre-push\"" }
-            - file_contains: { paths: [.lefthook.yml, lefthook.yml], pattern: "pre-push:" }
-            - has_file: .husky/pre-push
+          git_hook_runs_task: { tasks: [test, check] }
+      # pre-push вызывает все задачи словаря, которые вызывает CI на push в main
+      # (@-ссылки composer и npm run раскрываются): пуш, прошедший хук, не падает
+      # в CI на проверках.
       L4:
         requires:
-          any_of:
-            - file_contains: { path: composer.json, pattern: "\"(post-commit|commit-msg|post-merge)\"" }
-            - file_contains: { paths: [.lefthook.yml, lefthook.yml], pattern: "(post-commit|commit-msg|post-merge):" }
+          git_hook_covers_ci: { tasks: [test, check] }
 
   - id: observability
     class: supporting

package/src/ai.ts

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import YAML from 'js-yaml';
 import { evalPredicate } from './evaluator.ts';
+import { GIT_HOOK_EVENTS } from './hooks.ts';
 import { autoDetectStack, readStructured, resolveConfigPath, type Ctx } from './facts.ts';
 import { loadManifest } from './manifest.ts';
 import { type Author, effectiveAuthor, isGitRepo, rankAuthors, scanPool, writeAuthor } from './author.ts';
@@ -83,9 +84,26 @@ export interface SessionProfile {
   machines?: string[];
 }
 
+/**
+ * A personal hook: the owner's own gate, kept in git's user config
+ * (`hook.<name>.event` / `.command`, Git 2.54) instead of in every repository.
+ * `vdx doctor` checks it is there, `vdx doctor --fix` writes it.
+ */
+export interface PersonalHook {
+  name: string;
+  /** Git hook event(s): `pre-commit`, … */
+  event: string | string[];
+  /** Run by git through the shell; `$HOME` and quotes work as in a hook script. */
+  command: string;
+  /** The hook applies on a machine where this path exists (the tool is installed); `~` is home. */
+  when_exists?: string;
+  description?: string;
+}
+
 export interface GitProfile {
   /** Directories whose repos are the neighbours an author is proposed from; default — the project's parent. */
   author_pool?: string[];
+  hooks?: PersonalHook[];
 }
 
 export interface Environment {
@@ -98,6 +116,8 @@ 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';
 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;
@@ -202,6 +222,27 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (gitDoc.author_pool !== undefined && !isStringList(gitDoc.author_pool)) {
       fail('git.author_pool', 'must be a list of directories');
     }
+    if (gitDoc.hooks !== undefined) {
+      if (!Array.isArray(gitDoc.hooks)) fail('git.hooks', 'must be a list');
+      const names = new Set<string>();
+      gitDoc.hooks.forEach((h, i) => {
+        const at = `git.hooks[${i}]`;
+        if (typeof h !== 'object' || h === null) fail(at, 'must be a mapping');
+        if (typeof h.name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(h.name)) {
+          fail(`${at}.name`, 'must be a name of letters, digits, . _ - (the git config subsection)');
+        }
+        if (names.has(h.name)) fail(`${at}.name`, `"${h.name}" is declared twice`);
+        names.add(h.name);
+        const events = Array.isArray(h.event) ? h.event : [h.event];
+        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 (h.when_exists !== undefined && (typeof h.when_exists !== 'string' || h.when_exists === '')) {
+          fail(`${at}.when_exists`, 'must be a path');
+        }
+      });
+    }
   }
   return envDoc;
 }
@@ -240,6 +281,8 @@ 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. */
@@ -261,6 +304,7 @@ export function planLaunch(input: {
   project: string;
   projectSource?: string;
   host: string;
+  seat?: string;
 }): LaunchPlan {
   const { environment, agent, projectRoot } = input;
   const ctx: Ctx = { projectRoot, stack: autoDetectStack(projectRoot), cache: new Map() };
@@ -278,6 +322,7 @@ 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,
@@ -496,6 +541,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;
@@ -856,9 +911,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;
@@ -877,6 +935,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];
 }
@@ -936,10 +995,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) {
@@ -1012,9 +1072,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>();
@@ -1025,9 +1088,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);
@@ -1047,7 +1119,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);
@@ -1055,7 +1127,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)}`],
       };
     }
@@ -1063,7 +1135,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)}`],
     };
   };
@@ -1076,7 +1148,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(', ')}` : ''}`);
     });
@@ -1103,16 +1175,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 {
@@ -1172,6 +1245,7 @@ function prepare(pathArg: string, deps: AiDeps): Prepared | number {
       project: named.name,
       projectSource: named.source,
       host: hostLabel(deps.env),
+      seat: seatLabel(deps.env),
     });
   } catch (e: any) {
     log(`vdx ai: ${profilePath ?? 'profile'}: ${e?.message ?? e}`);
@@ -1242,6 +1316,12 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
   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.
+  delete deps.env[SEAT_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;
@@ -1286,7 +1366,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;
@@ -1296,17 +1376,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;
     }

package/src/audit.ts

@@ -4,7 +4,8 @@ import type { Rubric, LevelName } from './rubric.ts';
 import { findSubPackages, stackForDir, type Ctx } from './facts.ts';
 import { evalPredicate } from './evaluator.ts';
 import type { Override, VdxManifest } from './manifest.ts';
-import { evalAxis, projectLevel, type AxisResult } from './scoring.ts';
+import { evalAxisDetailed, projectLevel, type AxisResult } from './scoring.ts';
+import { cloneCheck } from './clone-checks.ts';
 
 function levelToInt(L: LevelName): number {
   return parseInt(L.slice(1), 10);
@@ -126,7 +127,7 @@ export function audit(
       });
       continue;
     }
-    const achieved = evalAxis(axis, evalCtx);
+    const { achieved, not_required, unknown } = evalAxisDetailed(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;
     const drift: 'aligned' | 'gap' | 'over' =
@@ -143,6 +144,12 @@ export function audit(
       drift_kind: drift,
     };
     if (ov?.target) entry.override_target = ov.target as LevelName;
+    if (not_required) entry.not_required = not_required;
+    if (unknown) entry.unknown = unknown;
+    if (axis.clone_check) {
+      const c = cloneCheck(axis.clone_check, ctx.projectRoot);
+      if (c && c.status !== 'ok') entry.note = c.remedy ? `${c.message} → ${c.remedy}` : c.message;
+    }
     perAxis.push(entry);
   }