@vodmal/vdx-cli 0.33.0 → 0.35.0

package/README.md

@@ -55,7 +55,7 @@ vdx doctor --fix                    # write the profile's personal hooks (git.ho
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
 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
+vdx ai --check [project-path]   # this session against the profile and the installed Claude Code and plugins — what the plugin's SessionStart hook tells the agent
 
 # What a command does and takes; nothing runs (ai: also where launch flags live)
 vdx <command> --help
@@ -134,7 +134,16 @@ nobody bypasses; a public repo needs no token, a private one takes it from
 its name, or one glab has a token for): nobody may push to the branch directly,
 and a merge request needs a passing pipeline; the token is glab's for that
 host, or `GITLAB_TOKEN` when the host is `GITLAB_HOST` (`gitlab.com` unless
-set) — vdx never sends a token to a host it does not belong to. Not met comes with the reason; another hosting, no network or no token
+set) — vdx never sends a token to a host it does not belong to. Bitbucket
+Server (a host `BITBUCKET_HOST` names, one with `bitbucket` in its name, or one
+git keeps an https login for — and that says it is Bitbucket): a restriction
+lets nothing into the branch but a pull request and exempts nobody, and a pull
+request needs a successful build ("Minimum successful builds"); the login is
+the one git keeps for that host (`git credential fill`, never a prompt — log in
+once with `git ls-remote https://<host>/scm/<project>/<repo>.git`, a personal
+access token as the password), or `BITBUCKET_TOKEN` when the host is
+`BITBUCKET_HOST`. Branch restrictions are visible to a repository admin only.
+Not met comes with the reason; another hosting, no network or no token
 where one is needed leave the axis unknown, with the reason too;
 `VDX_OFFLINE=1` does not ask at all.
 
@@ -177,8 +186,9 @@ npm run typecheck
 ## Not implemented yet
 
 - Above L1 the `ci` axis reads GitHub Actions only; other CI systems answer
-  "unknown". `branch-protection` reads GitHub and GitLab; other hostings
-  (gitolite, Bitbucket) answer "unknown".
+  "unknown". `branch-protection` reads GitHub, GitLab and Bitbucket Server;
+  other hostings (gitolite, Bitbucket Cloud) answer "unknown", and so do
+  Bitbucket restrictions by pattern or branching model.
 - 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.33.0",
+  "version": "0.35.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/src/ai.ts

@@ -29,6 +29,7 @@ import {
   runsInProject,
 } from './conversations.ts';
 import { at, errorMessage, isStringList, str } from './narrow.ts';
+import { type Lag, sessionLag } from './session-versions.ts';
 
 /**
  * `vdx ai` — start the person's agent in a project, with the flags their
@@ -749,6 +750,28 @@ export interface AiDeps {
   ssh?: (args: string[], capture: boolean) => { status: number; stdout: string } | null;
   /** Claude Code processes alive on this machine; read from its session files when not given. */
   liveHere?: () => LiveSession[];
+  /** What the agent process `pid` lags behind; read from Claude Code's files when not given. */
+  lag?: (pid: number, projectRoot: string, command: string) => Lag | null;
+}
+
+function machineLag(deps: AiDeps, pid: number, projectRoot: string, command: string): Lag | null {
+  return sessionLag({
+    env: deps.env,
+    home: deps.home,
+    pid,
+    projectRoot,
+    installedClaude: () => {
+      try {
+        return execFileSync(command, ['--version'], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 5_000,
+        });
+      } catch {
+        return null;
+      }
+    },
+  });
 }
 
 function runSsh(args: string[], capture: boolean): { status: number; stdout: string } | null {
@@ -1534,24 +1557,53 @@ export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = proc
   }
   const missing = missingArgs(own.args, plan.args);
   const why = plan.matched.length ? ` (profile conditions met here: ${plan.matched.join(', ')})` : '';
-  if (missing.length === 0) {
+  // A live session keeps the Claude Code and plugins it started with (vdx-ai, Sidetrack #24).
+  const lag = (deps.lag ?? ((pid, root, command) => machineLag(deps, pid, root, command)))(
+    own.pid,
+    projectRoot,
+    plan.command,
+  );
+  if (missing.length === 0 && !lag) {
     lines.push(`✓ this session carries the profile's flags${why}.`);
     deps.out(lines.join('\n') + '\n');
     return EXIT_OK;
   }
+  const problems: string[] = [];
+  if (missing.length > 0) problems.push(`✗ this session runs without ${missing.join(' ')}${why}.`);
+  else lines.push(`✓ this session carries the profile's flags${why}.`);
+  if (lag) problems.push(`✗ ${describeLag(lag)}.`);
+
   const root = shellQuote(projectRoot);
-  lines.push(
-    `✗ this session runs without ${missing.join(' ')}${why}. Hand the user the fix — ` +
+  const again = [
+    missing.length > 0 ? " with the profile's flags" : '',
+    lag ? `${missing.length > 0 ? ',' : ''} on the installed Claude Code and plugins` : '',
+  ].join('');
+  // Plugins alone: /reload-plugins loads them and the conversation goes on in the same process.
+  const reload =
+    missing.length === 0 && lag && !lag.claude
+      ? '`/reload-plugins`: it loads the installed plugins and keeps the conversation (Claude Code stays as it is); or '
+      : '';
+  problems.push(
+    `Hand the user the fix — ${reload}` +
       (deps.env['TMUX']
-        ? `\`${vdxAi} --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${again}` +
           (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 \`${vdxAi} ${root}\`.`),
   );
+  lines.push(problems.join(' '));
   deps.out(lines.join('\n') + '\n');
   return EXIT_DRIFT;
 }
 
+/** `this session runs Claude Code 2.1.294 — 2.1.304 is installed; plugins updated since it loaded them: vdm 2.54.0`. */
+function describeLag(lag: Lag): string {
+  const names = lag.plugins.map((p) => `${p.name} ${p.version}`).join(', ');
+  if (!lag.claude) return `plugins updated since this session loaded them: ${names} — it still runs the ones it loaded`;
+  const claude = `this session runs Claude Code ${lag.claude.runs} — ${lag.claude.installed} is installed`;
+  return lag.plugins.length > 0 ? `${claude}; plugins updated since it loaded them: ${names}` : claude;
+}
+
 export function runAi(opts: AiOptions, deps: AiDeps): number {
   const { log, tmux } = deps;
 

package/src/hosting.ts

@@ -19,16 +19,26 @@ export interface HostingIo {
   ghToken: () => string | null;
   /** The token `glab` keeps for a GitLab host; null without glab or a login there. */
   glabToken: (host: string) => string | null;
-  /** GET of an api.github.com path, or of a whole https:// URL. Throws when no answer came at all. */
-  get: (apiPath: string, token: string | null) => Answer;
+  /** The login git keeps for https://<host> (`git credential fill`), never by a prompt; null without one. */
+  gitCredential: (host: string) => { username: string; password: string } | null;
+  /**
+   * GET of an api.github.com path, or of a whole https:// URL, with the token as `Bearer`
+   * or `Basic`. Throws when no answer came at all.
+   */
+  get: (apiPath: string, token: string | null, scheme?: 'Bearer' | 'Basic') => Answer;
 }
 
 // A child node runs the request: the audit is synchronous and fetch is not
 // (DL #6 of docs/tasks/hosting-extension). The token travels in its
-// environment, not its arguments — those are visible in ps.
+// environment, not its arguments — those are visible in ps. GitHub's media
+// type only to GitHub: Bitbucket answers it with 406 (DL #17).
 const GET = `
-const headers = { accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'vdx' };
-if (process.env.VDX_HOSTING_TOKEN) headers.authorization = 'Bearer ' + process.env.VDX_HOSTING_TOKEN;
+const headers = new URL(process.argv[1]).host === 'api.github.com'
+  ? { accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'vdx' }
+  : { accept: 'application/json', 'user-agent': 'vdx' };
+if (process.env.VDX_HOSTING_TOKEN) {
+  headers.authorization = (process.env.VDX_HOSTING_SCHEME || 'Bearer') + ' ' + process.env.VDX_HOSTING_TOKEN;
+}
 try {
   const r = await fetch(process.argv[1], { headers, signal: AbortSignal.timeout(15000) });
   process.stdout.write(JSON.stringify({ status: r.status, text: await r.text() }));
@@ -37,10 +47,11 @@ try {
 }
 `;
 
-function get(apiPath: string, token: string | null): Answer {
+function get(apiPath: string, token: string | null, scheme: 'Bearer' | 'Basic' = 'Bearer'): Answer {
   const env = { ...process.env };
   delete env.VDX_HOSTING_TOKEN;
-  if (token) env.VDX_HOSTING_TOKEN = token;
+  delete env.VDX_HOSTING_SCHEME;
+  if (token) Object.assign(env, { VDX_HOSTING_TOKEN: token, VDX_HOSTING_SCHEME: scheme });
   const url = apiPath.startsWith('https://') ? apiPath : `https://api.github.com${apiPath}`;
   const out: unknown = JSON.parse(
     execFileSync(process.execPath, ['--input-type=module', '-e', GET, url], {
@@ -80,6 +91,25 @@ export function machineIo(root: string): HostingIo {
     git: (args) => run('git', ['--no-optional-locks', '-C', root, ...args]),
     ghToken: () => run('gh', ['auth', 'token']),
     glabToken: (host) => run('glab', ['config', 'get', 'token', '--host', host]),
+    gitCredential: (host) => {
+      if (!/^[a-z0-9.-]+$/i.test(host)) return null;
+      try {
+        const out = execFileSync('git', ['--no-optional-locks', '-C', root, 'credential', 'fill'], {
+          encoding: 'utf8',
+          input: `protocol=https\nhost=${host}\n\n`,
+          // Without a login git would ask for one: no terminal, no askpass program, no window.
+          env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '', GCM_INTERACTIVE: 'never' },
+          stdio: ['pipe', 'pipe', 'ignore'],
+          timeout: 5_000,
+        });
+        const field = (key: string) => out.match(new RegExp(`^${key}=(.*)$`, 'm'))?.[1];
+        const username = field('username');
+        const password = field('password');
+        return username && password ? { username, password } : null;
+      } catch {
+        return null;
+      }
+    },
     get,
   };
 }
@@ -164,7 +194,8 @@ function judge(io: HostingIo, repo: string, token: string | null): Verdict {
 
 /**
  * Whether the default branch on the hosting of `origin` takes changes only after a check
- * required of everyone. GitHub and GitLab; what vdx cannot ask is unknown, with the reason.
+ * required of everyone. GitHub, GitLab and Bitbucket Server; what vdx cannot ask is unknown,
+ * with the reason.
  */
 export function branchRequiresChecks(ctx: Ctx, io: HostingIo = machineIo(ctx.projectRoot)): Verdict {
   const key = 'hosting:branch-requires-checks';
@@ -191,10 +222,7 @@ function ask(io: HostingIo): Verdict {
   // or one with gitlab in its name. A token goes only where it belongs: GITLAB_TOKEN to
   // GITLAB_HOST, as glab sends it; glab's to its own host. Any other host is asked without
   // one — an origin is the repository's to name, and may point anywhere.
-  const tokenHost = (io.env.GITLAB_HOST || 'gitlab.com')
-    .replace(/^https?:\/\//, '')
-    .replace(/\/.*$/, '')
-    .toLowerCase();
+  const tokenHost = hostOf(io.env.GITLAB_HOST || 'gitlab.com');
   const glab = io.glabToken(host);
   const token = (host.toLowerCase() === tokenHost ? io.env.GITLAB_TOKEN : undefined) || glab;
   if (host.toLowerCase() === tokenHost || glab || host.includes('gitlab')) {
@@ -204,7 +232,45 @@ function ask(io: HostingIo): Verdict {
       return { unknown: `${host} did not answer: ${errorMessage(e)}` };
     }
   }
-  return { unknown: `origin is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub and GitLab` };
+  // Bitbucket Server: the host BITBUCKET_HOST names, one with bitbucket in its name, or one
+  // git keeps a login for (git.finam.ru, DL #16) — once the host, asked without a login,
+  // says it is Bitbucket. BITBUCKET_TOKEN goes to BITBUCKET_HOST only, git's login to the
+  // host git keeps it for.
+  const bitbucketHost = io.env.BITBUCKET_HOST ? hostOf(io.env.BITBUCKET_HOST) : null;
+  const login = io.gitCredential(host);
+  if (host.toLowerCase() === bitbucketHost || host.toLowerCase().includes('bitbucket') || login) {
+    const auth: BitbucketAuth | null =
+      host.toLowerCase() === bitbucketHost && io.env.BITBUCKET_TOKEN
+        ? { token: io.env.BITBUCKET_TOKEN, scheme: 'Bearer', source: 'BITBUCKET_TOKEN' }
+        : login
+          ? {
+              token: Buffer.from(`${login.username}:${login.password}`).toString('base64'),
+              scheme: 'Basic',
+              source: 'the login git keeps',
+            }
+          : null;
+    try {
+      const about = io.get(`https://${host}/rest/api/1.0/application-properties`, null);
+      if (about.status === 200 && at(about.body, 'displayName') === 'Bitbucket') {
+        return judgeBitbucket(io, host, repo, auth);
+      }
+    } catch (e) {
+      return { unknown: `${host} did not answer: ${errorMessage(e)}` };
+    }
+  }
+  // Not every host is asked whether it is Bitbucket: gitolite has no https, and the audit
+  // would wait out the timeout. The reason says how vdx tells Bitbucket.
+  return {
+    unknown: `origin is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub, GitLab and Bitbucket Server, the last once git keeps a login for it or BITBUCKET_HOST names it`,
+  };
+}
+
+/** The host of a `*_HOST` variable, which may come as a URL. */
+function hostOf(value: string): string {
+  return value
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .toLowerCase();
 }
 
 /** A refusal of a GitLab API as the reason the answer is unknown; null for a 200. */
@@ -262,6 +328,112 @@ function judgeGitlab(io: HostingIo, host: string, repo: string, token: string |
   return { no: why.join('; ') };
 }
 
+/** What vdx asks Bitbucket with, and where it comes from — for the reason when it is refused. */
+interface BitbucketAuth {
+  token: string;
+  scheme: 'Bearer' | 'Basic';
+  source: string;
+}
+
+const MIN_BUILDS = 'com.atlassian.bitbucket.server.bitbucket-build:requiredBuildsMergeCheck';
+
+/** A refusal of Bitbucket as the reason the answer is unknown; null for a 200. */
+function bitbucketRefusal(a: Answer, host: string, repo: string, auth: BitbucketAuth | null): Unknown | null {
+  if (a.status === 200) return null;
+  const message = str(at(list(at(a.body, 'errors'))[0], 'message')) ?? '';
+  if (a.status === 401 && !auth) {
+    return {
+      unknown: `${host} shows ${repo} only after a login — once: git ls-remote https://${host}/scm/${repo}.git, a token as the password; or BITBUCKET_TOKEN with BITBUCKET_HOST`,
+    };
+  }
+  if (a.status === 401) {
+    return { unknown: `${host} refused ${repo} to ${auth?.source} — no access, a changed password, a revoked token?` };
+  }
+  return { unknown: `${host} answered ${a.status} for ${repo}${message ? `: ${message}` : ''}` };
+}
+
+/**
+ * Bitbucket Server: the default branch takes changes only after a build when nothing
+ * reaches it but a pull request — a `pull-request-only` or `read-only` restriction on it
+ * exempts nobody; an exempt user pushes past the build — and a pull request needs a
+ * successful build (the merge check «Minimum successful builds»). Shapes of git.finam.ru,
+ * 5.16.1 (DL #17). The first refusal ends the questions: every login refused brings the
+ * owner's account nearer a CAPTCHA.
+ */
+function judgeBitbucket(io: HostingIo, host: string, path: string, auth: BitbucketAuth | null): Verdict {
+  const [project, slug, ...rest] = path.replace(/^scm\//, '').split('/');
+  if (!project || !slug || rest.length > 0) return { unknown: `${host}: no project and repository in ${path}` };
+  const repo = `${project}/${slug}`;
+  const repoPath = `projects/${encodeURIComponent(project)}/repos/${encodeURIComponent(slug)}`;
+  const api = `https://${host}/rest/api/1.0/${repoPath}`;
+  const ask = (url: string) => (auth ? io.get(url, auth.token, auth.scheme) : io.get(url, null));
+
+  let branch = io.git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])?.replace(/^origin\//, '');
+  if (!branch) {
+    const d = ask(`${api}/branches/default`);
+    const refused = bitbucketRefusal(d, host, repo, auth);
+    if (refused) return refused;
+    branch = str(at(d.body, 'displayId'));
+    if (!branch) return { unknown: `${host} names no default branch for ${repo}` };
+  }
+
+  // Whoever reads the repository sees its merge checks; only an admin sees its restrictions.
+  const hooks = ask(`${api}/settings/hooks?type=PRE_PULL_REQUEST_MERGE&limit=100`);
+  const refusedHooks = bitbucketRefusal(hooks, host, repo, auth);
+  if (refusedHooks) return refusedHooks;
+  const builds = list(at(hooks.body, 'values')).some(
+    (h) => at(h, 'details', 'key') === MIN_BUILDS && at(h, 'enabled') === true,
+  );
+  const noBuilds = `pull requests into ${branch} need no successful build`;
+
+  const r = ask(`https://${host}/rest/branch-permissions/2.0/${repoPath}/restrictions?limit=100`);
+  if (r.status !== 200) {
+    // Without the build check the branch takes unbuilt changes, whoever may push to it.
+    if (!builds) return { no: noBuilds };
+    if (r.status === 401 && auth) {
+      return { unknown: `${host} shows who may change ${branch} of ${repo} only to a repository admin` };
+    }
+    return bitbucketRefusal(r, host, repo, auth) ?? { unknown: `${host} answered ${r.status} for ${repo}` };
+  }
+  if (at(r.body, 'isLastPage') === false) return { unknown: `${repo} has more than 100 branch restrictions` };
+
+  let guarded = false;
+  let byPattern = false;
+  const exempt = new Set<string>();
+  for (const x of list(at(r.body, 'values'))) {
+    if (!['read-only', 'pull-request-only'].includes(str(at(x, 'type')) ?? '')) continue;
+    if (at(x, 'matcher', 'type', 'id') !== 'BRANCH') {
+      byPattern = true;
+      continue;
+    }
+    if (at(x, 'matcher', 'id') !== `refs/heads/${branch}`) continue;
+    const who = [
+      ...list(at(x, 'users')).map((u) => str(at(u, 'name')) ?? 'a user'),
+      ...list(at(x, 'groups')).map((g) => `group ${str(g) ?? '?'}`),
+      ...list(at(x, 'accessKeys')).map((k) => `access key ${str(at(k, 'key', 'label')) ?? '?'}`),
+    ];
+    if (who.length === 0) guarded = true;
+    for (const w of who) exempt.add(w);
+  }
+
+  // A pattern or the branching model may cover the branch: vdx does not read them (DL #17).
+  if (!guarded && byPattern && builds) {
+    return {
+      unknown: `a branch restriction by pattern or branching model on ${repo} may cover ${branch} — vdx reads those that name the branch`,
+    };
+  }
+  const why: string[] = [];
+  if (!guarded && !byPattern) {
+    why.push(
+      exempt.size > 0
+        ? `${branch} takes changes without a pull request from ${[...exempt].join(', ')} — they skip the build`
+        : `${branch} is not restricted — whoever may write pushes to it`,
+    );
+  }
+  if (!builds) why.push(noBuilds);
+  return why.length > 0 ? { no: why.join('; ') } : true;
+}
+
 /** A remote's repository on GitHub and the token to ask with; unknown, with the reason, when vdx cannot ask. */
 export function githubRepo(io: HostingIo, remote: string): { repo: string; token: string | null } | Unknown {
   if (io.env.VDX_OFFLINE) return { unknown: 'VDX_OFFLINE is set — the hosting was not asked' };

package/src/index.ts

@@ -100,8 +100,9 @@ the project's files). Hand a person \`vdx ai\`, not \`<agent> --<flag>\`.
                 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
-                whether this session carries the profile's flags (the vdx plugin's
+  --check       for the agent's own session: how the agent here is launched,
+                whether this session carries the profile's flags, and whether it
+                runs the installed Claude Code and plugins (the vdx plugin's
                 SessionStart hook); prints nothing without a profile; exit 3 on drift
   -h, --help    this help
 
@@ -131,7 +132,9 @@ For branch-protection it asks the hosting of origin whether its default branch
 takes changes only after a check required of everyone: GitHub, with a token from
 $GH_TOKEN, $GITHUB_TOKEN or gh when there is one; GitLab, with glab's token for that host,
 or $GITLAB_TOKEN when the host is $GITLAB_HOST (gitlab.com unless set) — no
-other host gets it. Another hosting is unknown; VDX_OFFLINE=1 does not ask, and the axis says
+other host gets it; Bitbucket Server, with the login git keeps for that host
+(git credential), or $BITBUCKET_TOKEN when the host is $BITBUCKET_HOST.
+Another hosting is unknown; VDX_OFFLINE=1 does not ask, and the axis says
 unknown.
 `,
     bools: ['json'],

package/src/session-versions.ts

@@ -0,0 +1,149 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { claudeConfigDir, projectDirName } from './conversations.ts';
+import { at, dict, list, str } from './narrow.ts';
+
+/**
+ * What a running Claude Code session lags behind: a live session keeps the
+ * Claude Code and the plugins it started with, and takes new ones only when it
+ * starts again or by `/reload-plugins` (docs/tasks/vdx-ai, Sidetrack #24).
+ * Read from Claude Code's own files — its session file, `installed_plugins.json`,
+ * the settings that enable a plugin, the transcript — which are its internals,
+ * not an API.
+ */
+export interface Lag {
+  /** Claude Code: the version the session runs and the one installed now; null when they agree. */
+  claude: { runs: string; installed: string } | null;
+  /** Enabled plugins updated after the session loaded its plugins: their name and the installed version. */
+  plugins: Array<{ name: string; version: string }>;
+}
+
+export interface LagInput {
+  env: NodeJS.ProcessEnv;
+  home: string;
+  /** The session's Claude Code process. */
+  pid: number;
+  projectRoot: string;
+  /** `claude --version` of the Claude Code a new start would run; null when it does not answer. */
+  installedClaude: () => string | null;
+  /** Default `Date.now()`. */
+  now?: number;
+}
+
+/**
+ * How long what a session loaded may stand before newer counts as a lag. On
+ * 2026-10-21 all 14 live sessions on lft were behind, an echelon release minutes
+ * old among them; the harm is a session that runs old code for days (twelve, in
+ * ai-dev-plugins' count). A day lets an update arrive without every session's
+ * next compaction calling for a reload.
+ */
+const LAG_AFTER_MS = 24 * 60 * 60 * 1000;
+
+/** What the session lags behind; null when nothing — or when its session file is not here to say. */
+export function sessionLag(input: LagInput): Lag | null {
+  const now = input.now ?? Date.now();
+  const config = claudeConfigDir(input.env, input.home);
+  const session = readJson(path.join(config, 'sessions', `${input.pid}.json`));
+  const startedAt = at(session, 'startedAt');
+  if (typeof startedAt !== 'number' || now - startedAt < LAG_AFTER_MS) return null;
+
+  const runs = str(at(session, 'version'));
+  const installed = versionOf(input.installedClaude());
+  const claude = runs && installed && newer(installed, runs) ? { runs, installed } : null;
+
+  let plugins = updatedPlugins(config, input.projectRoot).filter((p) => p.at > startedAt);
+  if (plugins.length > 0) {
+    // A /reload-plugins loaded what was installed then: the transcript keeps when (its "Reloaded: …" line).
+    const sessionId = str(at(session, 'sessionId'));
+    const reloaded = sessionId ? lastReload(config, input.projectRoot, sessionId) : null;
+    if (reloaded !== null) plugins = now - reloaded < LAG_AFTER_MS ? [] : plugins.filter((p) => p.at > reloaded);
+  }
+  if (!claude && plugins.length === 0) return null;
+  return { claude, plugins: plugins.map(({ name, version }) => ({ name, version })) };
+}
+
+/** Enabled plugins and when each was last updated (ms) — the user's and this project's. */
+function updatedPlugins(config: string, projectRoot: string): Array<{ name: string; version: string; at: number }> {
+  const records = dict(at(readJson(path.join(config, 'plugins', 'installed_plugins.json')), 'plugins')) ?? {};
+  // The nearest settings that name a plugin decide: the project's local, the project's, the user's.
+  const layers = [
+    path.join(projectRoot, '.claude', 'settings.local.json'),
+    path.join(projectRoot, '.claude', 'settings.json'),
+    path.join(config, 'settings.json'),
+  ].map((f) => dict(at(readJson(f), 'enabledPlugins')) ?? {});
+  const out: Array<{ name: string; version: string; at: number }> = [];
+  for (const [key, entries] of Object.entries(records)) {
+    if (layers.map((l) => l[key]).find((v) => typeof v === 'boolean') !== true) continue;
+    const entry = list(entries).find((e) => at(e, 'scope') === 'user' || at(e, 'projectPath') === projectRoot);
+    const when = Date.parse(str(at(entry, 'lastUpdated')) ?? '');
+    const version = str(at(entry, 'version'));
+    if (Number.isNaN(when) || !version) continue;
+    out.push({ name: key.split('@')[0] ?? key, version, at: when });
+  }
+  return out;
+}
+
+/** When the session last ran /reload-plugins (ms), from its transcript; null — never, or no transcript here. */
+function lastReload(config: string, projectRoot: string, sessionId: string): number | null {
+  const projects = path.join(config, 'projects');
+  let file = path.join(projects, projectDirName(projectRoot), `${sessionId}.jsonl`);
+  if (!fs.existsSync(file)) {
+    // The transcript sits under the directory the session started in, which may be another.
+    const dir = safeReaddir(projects).find((d) => fs.existsSync(path.join(projects, d, `${sessionId}.jsonl`)));
+    if (dir === undefined) return null;
+    file = path.join(projects, dir, `${sessionId}.jsonl`);
+  }
+  let text: string;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let last: number | null = null;
+  for (const line of text.split('\n')) {
+    if (!line.includes('"local_command"') || !line.includes('Reloaded:')) continue;
+    let entry: unknown;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (at(entry, 'type') !== 'system' || at(entry, 'subtype') !== 'local_command') continue;
+    if (!/<local-command-stdout>Reloaded:/.test(str(at(entry, 'content')) ?? '')) continue;
+    const when = Date.parse(str(at(entry, 'timestamp')) ?? '');
+    if (!Number.isNaN(when) && (last === null || when > last)) last = when;
+  }
+  return last;
+}
+
+/** `2.1.304 (Claude Code)` → `2.1.304`. */
+function versionOf(text: string | null): string | null {
+  return text?.match(/\d+\.\d+\.\d+/)?.[0] ?? null;
+}
+
+/** Whether version `a` is newer than `b`, part by part. */
+function newer(a: string, b: string): boolean {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function safeReaddir(dir: string): string[] {
+  try {
+    return fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+}