@renzrollon/interlock 1.1.1 → 1.2.0

package/lib/doctor.mjs

@@ -39,13 +39,46 @@
 // report that checked the developer's checkout of Interlock while the run used
 // the installed one.
 //
+// ROOT vs STATE HOME. A third place, and the same mistake one level down. From
+// a linked worktree the run's append-only corpora go to the main checkout
+// (`lib/state-home.mjs`), so the doctor resolves that home once and probes
+// each state directory under the home it is actually written to — a read-only
+// main checkout is found from the worktree session, not on wave three.
+//
 // Exposed to skills and to `/interlock:ship` as `interlock doctor [--json]`.
 
 import { execFileSync } from 'node:child_process'
-import { accessSync, constants, existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { homedir, platform } from 'node:os'
+import {
+  accessSync,
+  constants,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from 'node:fs'
+import { cpus, homedir, platform } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import {
+  AGENT_TEAMS_ENV,
+  SUBAGENT_MODEL_DEFAULT_ONLY_MIN_VERSION,
+  SUBAGENT_MODEL_ENV,
+  SUBAGENT_MODEL_FORCE_ENV,
+  SUBAGENT_MODEL_FORCE_MIN_VERSION,
+  MODS_MIN_HOST_VERSION,
+  compareVersions,
+  WORKFLOW_MAX_CONCURRENT_ENV,
+  WORKFLOW_MAX_CONCURRENT_RANGE,
+  claudeCommandArgv,
+  observeClaudeEnv,
+  parseClaudeVersion,
+  readModelRouting
+} from './host/claude-env.mjs'
+import { RUNTIME } from './limits.mjs'
+import { STATE_HOME_ENV, resolveStateHome } from './state-home.mjs'
 
 /** The installed copy of the plugin — the one whose workflow and agents run. */
 export const PLUGIN_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
@@ -101,16 +134,45 @@ export const PROMPT_CACHE_MIN_HOST_VERSION = '2.1.242'
  * `wave-state` call whose trajectory append fails now exits 1 rather than
  * warning on stderr. `.claude/ship/spill` is fatal for a different reason —
  * `verify spill` has no fallback, and a verify agent that cannot spill an
- * oversized suite log has no legal way to report it. The other two are
- * explicitly never-fatal in their own modules ("losing a corpus line must never
- * fail the run that made it"; metrics "report their own failure and never touch
- * the exit code"), so an unwritable one is a warning here too.
+ * oversized suite log has no legal way to report it. The rest are explicitly
+ * never-fatal in their own modules ("losing a corpus line must never fail the
+ * run that made it"; metrics "report their own failure and never touch the exit
+ * code"), so an unwritable one is a warning here too.
+ *
+ * Each entry also names its `home`, because from a linked worktree the two are
+ * different directories (design D15). `state`: the append-only corpora a report
+ * reads across every run the project has had — the trajectory, the outcome
+ * corpus, the metrics, the resume cards, the interrupted-run notes — which go to
+ * the state home so they outlive a worktree that is deleted when its session is
+ * archived. `root`: per-run working state, which stays with the run — the spill,
+ * whose locators are root-relative and which `verify spill` writes under the
+ * root, and the agent-usage sidecar the SubagentStop recorder keys by run.
+ * Probing a directory under the wrong home tests a directory nothing writes to,
+ * and misses the one the run will fail on.
  */
 export const STATE_DIRS = Object.freeze([
-  { path: join('.claude', 'ship', 'runs'), fatal: true, why: 'run trajectory; a failed append exits 1' },
-  { path: join('.claude', 'ship', 'spill'), fatal: true, why: 'spilled suite output; no fallback path' },
-  { path: join('.claude', 'learning'), fatal: false, why: 'outcome corpus; never fatal at runtime' },
-  { path: join('.claude', 'metrics'), fatal: false, why: 'review metrics; never fatal at runtime' }
+  { path: join('.claude', 'ship', 'runs'), home: 'state', fatal: true, why: 'run trajectory; a failed append exits 1' },
+  { path: join('.claude', 'ship', 'spill'), home: 'root', fatal: true, why: 'spilled suite output; no fallback path' },
+  { path: join('.claude', 'learning'), home: 'state', fatal: false, why: 'outcome corpus; never fatal at runtime' },
+  { path: join('.claude', 'metrics'), home: 'state', fatal: false, why: 'review metrics; never fatal at runtime' },
+  {
+    path: join('.claude', 'handoff'),
+    home: 'state',
+    fatal: false,
+    why: 'resume cards; outcome-class, a failed write is reported and never fails the run'
+  },
+  {
+    path: join('.claude', 'ship', 'interrupted'),
+    home: 'state',
+    fatal: false,
+    why: 'interrupted-run notes; outcome-class, a failed write is a stderr line from the SessionEnd hook'
+  },
+  {
+    path: join('.claude', 'ship', 'agent-usage'),
+    home: 'root',
+    fatal: false,
+    why: 'per-agent usage sidecar; outcome-class, a failed write is a stderr line from the SubagentStop recorder'
+  }
 ])
 
 /**
@@ -127,12 +189,12 @@ export const REQUIRED_COMMANDS = Object.freeze([
   {
     tokens: ['test'],
     open: true,
-    why: 'the environment probe checks for the graph and the test profile (workflows/ship.js)'
+    why: 'the bootstrap skill checks for openspec/config.yaml (skills/bootstrap)'
   },
   {
     tokens: ['printenv'],
     open: true,
-    why: 'the environment probe reads CLAUDE_CODE_SUBAGENT_MODEL and the Bedrock variables'
+    why: 'the environment probe reads CLAUDE_CODE_EFFORT_LEVEL'
   },
   { tokens: ['mkdir'], open: true, why: 'the environment probe creates .claude/ship/' }
 ])
@@ -561,8 +623,15 @@ function checkGit(root, env, probe) {
   return check('git', 'ok', `${version || 'git'} in a work tree`, { evidence: [`git → ${bin}`] })
 }
 
-function checkTestProfile(root) {
-  const path = join(root, TEST_PROFILE_PATH)
+function checkTestProfile(root, home = root) {
+  // Root first, then the state home: the same read-through `run start` performs
+  // (ship/state-home), so a linked worktree with no profile of its own is not
+  // failed for a profile its run will read from the main checkout.
+  const atRoot = join(root, TEST_PROFILE_PATH)
+  const atHome = join(home, TEST_PROFILE_PATH)
+  const readThrough = !existsSync(atRoot) && resolve(home) !== resolve(root) && existsSync(atHome)
+  const path = readThrough ? atHome : atRoot
+  const via = readThrough ? ` (read through from the state home: ${atHome})` : ''
   if (!existsSync(path)) {
     return check('test-profile', 'fail', `${TEST_PROFILE_PATH} is missing, so verification has no command to run and continuity refuses to start`, {
       fix: 'Run /interlock:fix-tests once to discover and persist the project test setup.'
@@ -581,7 +650,7 @@ function checkTestProfile(root) {
       fix: 'Add a "unit": { "command": "..." } section, or re-run /interlock:fix-tests.'
     })
   }
-  return check('test-profile', 'ok', `unit suite: ${command}`, {
+  return check('test-profile', 'ok', `unit suite: ${command}${via}`, {
     evidence: [parsed.value.e2e ? 'e2e configured' : 'no e2e configured'],
     profile: parsed.value
   })
@@ -597,19 +666,33 @@ function checkTestProfile(root) {
  * again. A directory that does not exist yet is judged by the writability of
  * its nearest existing ancestor, because that is what `mkdirSync(recursive)`
  * will need — nothing is created here.
+ *
+ * Each directory is probed under the home it is written to (`STATE_DIRS[].home`):
+ * `state` under the resolved state home, `root` under the working root. The
+ * evidence names every absolute path probed, so a reader of a worktree
+ * session's report can see that the trajectory was tested in the main checkout.
+ *
+ * @param {string} root      the working root
+ * @param {string} [stateHome] the resolved state home; the root when absent
  */
-function checkStateDirs(root) {
+export function checkStateDirs(root, stateHome = root) {
+  // Real paths on both sides, as the resolver compares them: macOS keeps `/tmp`
+  // behind a symlink, and one directory under two spellings is still one.
+  const workingRoot = realOrSelf(resolve(root))
+  const home = typeof stateHome === 'string' && stateHome ? realOrSelf(resolve(stateHome)) : workingRoot
   const blocked = []
   const evidence = []
   for (const dir of STATE_DIRS) {
-    const abs = join(root, dir.path)
+    const base = dir.home === 'state' ? home : workingRoot
+    const where = dir.home === 'state' ? 'state home' : 'working root'
+    const abs = join(base, dir.path)
     let reason = null
     if (existsSync(abs)) {
       const probe = join(abs, `.interlock-doctor-${process.pid}.tmp`)
       try {
         writeFileSync(probe, '')
         rmSync(probe, { force: true })
-        evidence.push(`${dir.path}: writable`)
+        evidence.push(`${abs}: writable (${where})`)
       } catch (err) {
         reason = messageOf(err)
       }
@@ -618,35 +701,127 @@ function checkStateDirs(root) {
       while (ancestor && !existsSync(ancestor) && ancestor !== dirname(ancestor)) ancestor = dirname(ancestor)
       try {
         accessSync(ancestor, constants.W_OK)
-        evidence.push(`${dir.path}: absent, creatable under ${ancestor}`)
+        evidence.push(`${abs}: absent, creatable under ${ancestor} (${where})`)
       } catch (err) {
         reason = `cannot be created under ${ancestor}: ${messageOf(err)}`
       }
     }
-    if (reason) blocked.push({ ...dir, reason })
+    if (reason) blocked.push({ ...dir, abs, base, reason })
   }
 
   if (!blocked.length) {
     return check('state-dirs', 'ok', 'every run-state directory is writable or creatable', { evidence })
   }
 
-  const lines = blocked.map(b => `${b.path}: ${b.reason} — ${b.why}`)
+  const lines = blocked.map(b => `${b.abs}: ${b.reason} — ${b.why}`)
+  // Name the directory to repair. From a worktree session the one that blocks
+  // may be the main checkout's, which is not the `.claude/` the reader is in.
+  const bases = [...new Set(blocked.map(b => b.base))]
+  const target = bases.map(b => join(b, '.claude')).join(' and ')
+  const elsewhere =
+    home !== workingRoot && blocked.some(b => b.home === 'state')
+    ? ` — ${join(home, '.claude')} is the state home this root's corpora are written to; pin another with --state-home or ${STATE_HOME_ENV}`
+    : ''
   const fatal = blocked.filter(b => b.fatal)
   if (!fatal.length) {
-    // Bookkeeping only. The modules behind these two say so themselves, and a
+    // Bookkeeping only. The modules behind these say so themselves, and a
     // preflight that failed the run over a lost metrics line would be applying
     // a rule the runtime does not.
     return check('state-dirs', 'warn', `${blocked.length} bookkeeping director${blocked.length === 1 ? 'y is' : 'ies are'} not writable; the run continues without them`, {
       evidence: lines,
-      fix: 'Make .claude/ writable to keep the outcome corpus and review metrics.'
+      fix: `Make ${target} writable to keep the outcome corpus and review metrics${elsewhere}.`
     })
   }
   return check('state-dirs', 'fail', `${fatal.length} run-state director${fatal.length === 1 ? 'y is' : 'ies are'} not writable, and losing ${fatal.length === 1 ? 'it' : 'them'} ends the run`, {
     evidence: lines,
-    fix: 'Make .claude/ writable, or run from a checkout that is not read-only. A failed trajectory append exits 1 mid-run.'
+    fix: `Make ${target} writable, or run from a checkout that is not read-only${elsewhere}. A failed trajectory append exits 1 mid-run.`
   })
 }
 
+/**
+ * Advice, never a gate: where this root's corpora go, and what the root is.
+ *
+ * `checkNotify`'s posture — `ok` or `skip`, NEVER `fail`, its own try/catch,
+ * outside `diagnose`'s `run()`. The writability of the home is `state-dirs`'
+ * question and that row can fail; this one only says which home was resolved,
+ * so a worktree session's reader learns before a run that its trajectory, its
+ * outcome line and its resume card land in the main checkout. A fallback is
+ * `skip` with the resolver's reason, in the same words the run banners, because
+ * a fallback is exactly today's behaviour — a degradation to speak, not a block.
+ *
+ * @param {string} root the working root
+ * @param {{home: string, surface: string, reason: string|null, resolvedFrom: string}} resolved
+ *   what `resolveStateHome` returned for it
+ */
+export function checkStateHome(root, resolved) {
+  try {
+    const home = resolved && typeof resolved.home === 'string' && resolved.home ? resolved.home : null
+    if (!home) {
+      return check(
+        'state-home',
+        'skip',
+        'STATE HOME UNRESOLVED: the resolver returned no home; corpora of this run go to the working root'
+      )
+    }
+    const surface = typeof resolved.surface === 'string' && resolved.surface ? resolved.surface : 'unknown'
+    const from = typeof resolved.resolvedFrom === 'string' ? resolved.resolvedFrom : null
+    const reason = typeof resolved.reason === 'string' && resolved.reason ? resolved.reason : null
+    const workingRoot = realOrSelf(resolve(root))
+    const evidence = [
+      `working root: ${workingRoot}`,
+      `state home: ${home}`,
+      `surface: ${surface}`,
+      `resolved from: ${from || 'unknown'}`
+    ]
+    const corpora = `corpora of this run go to ${home}; the test profile and graph are read from there when this root has none`
+
+    if (from === 'fallback') {
+      return check(
+        'state-home',
+        'skip',
+        `STATE HOME UNRESOLVED: ${reason || 'the resolver gave no reason'}; corpora of this run go to the working root ${home}`,
+        { evidence }
+      )
+    }
+    if (from === 'explicit') {
+      const parts = [`state home ${home}, set explicitly (--state-home or ${STATE_HOME_ENV}); surface ${surface}`]
+      if (reason) parts.push(`the surface could not be read: ${reason}`)
+      if (realOrSelf(home) !== workingRoot) parts.push(corpora)
+      return check('state-home', 'ok', parts.join('; '), { evidence })
+    }
+    if (surface === 'linked-worktree') {
+      return check('state-home', 'ok', `state home ${home}, surface linked-worktree; ${corpora}`, { evidence })
+    }
+    if (surface === 'main') {
+      return check('state-home', 'ok', `state home is the root itself, ${home}, surface main`, { evidence })
+    }
+    if (surface === 'lane-worktree') {
+      return check(
+        'state-home',
+        'ok',
+        `state home is the root itself, ${home}, surface lane-worktree: an Interlock lane worktree keeps its own state`,
+        { evidence }
+      )
+    }
+    return check('state-home', 'skip', `the state home ${home} was resolved with an unrecognised surface "${surface}"`, {
+      evidence
+    })
+  } catch (err) {
+    // Fail-open, and never `fail`: a resolution this row cannot read is a
+    // reason to withhold the advice, not a reason to block a run.
+    return check('state-home', 'skip', `the state-home check could not run: ${messageOf(err)}`)
+  }
+}
+
+/** A path made real when it can be, left as given when it cannot. Never throws. */
+function realOrSelf(path) {
+  try {
+    return realpathSync(path)
+  } catch {
+    return path
+  }
+}
+
 /**
  * The allowlist preflight. A required command with no covering rule is a `fail`,
  * not a warning: an approval prompt in the middle of a zero-touch run is not a
@@ -770,6 +945,227 @@ function checkNotify(env) {
   }
 }
 
+/**
+ * Advice, never a gate: what the Claude Code environment does to a run's model
+ * routing, read the way `interlock run start --host workflow` reads it.
+ *
+ * `checkNotify`'s posture: `ok` only when none of the four variables is set AND
+ * the host version was read — an unread version is not a clean reading, because
+ * what the plain subagent-model variable means depends on it — otherwise `skip`,
+ * and never `fail`. The variables are the operator's environment; a preflight
+ * that failed on them would fail every session that set one on purpose.
+ *
+ * The values printed are model slugs and small integers. Bedrock is named by
+ * variable and never by value, under the same presence-only rule as the
+ * credential rows: this report is written to disk and pasted into issues.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @param {{version: string|null, cpuCount: number|null}} host
+ */
+function checkClaudeEnv(env, { version, cpuCount }) {
+  try {
+    const o = observeClaudeEnv(env, { version, cpuCount })
+    const routing = readModelRouting(o)
+    const shown = (name, value) => `${name}=${value === null ? 'unset' : value}`
+    const four = [
+      shown(SUBAGENT_MODEL_ENV, o.subagentModel),
+      shown(SUBAGENT_MODEL_FORCE_ENV, o.subagentModelForce),
+      shown(WORKFLOW_MAX_CONCURRENT_ENV, o.maxConcurrent ? o.maxConcurrent.raw : null),
+      shown(AGENT_TEAMS_ENV, o.agentTeams)
+    ]
+    const anySet = [o.subagentModel, o.subagentModelForce, o.maxConcurrent, o.agentTeams].some(v => v !== null)
+
+    const detail = [`Claude Code ${o.version || 'unknown (the version probe did not answer)'}`, ...four]
+    if (o.subagentModel !== null) {
+      detail.push(
+        routing.plainDefaultOnly
+          ? `${SUBAGENT_MODEL_ENV} sets only the default subagent model on this host (>= ${SUBAGENT_MODEL_DEFAULT_ONLY_MIN_VERSION}); a model a spawn names takes precedence`
+          : routing.forceEffective
+            ? `${SUBAGENT_MODEL_ENV} names the model FORCE applies`
+            : `${SUBAGENT_MODEL_ENV} replaces every agent's model on ` +
+              (routing.versionKnown
+                ? `this host (below ${SUBAGENT_MODEL_DEFAULT_ONLY_MIN_VERSION})`
+                : 'a host whose version is unknown, the conservative reading') +
+              ', so the plan\'s per-tier assignment is not in effect'
+      )
+    }
+    if (o.subagentModelForce !== null) {
+      detail.push(
+        routing.forceInert
+          ? `${SUBAGENT_MODEL_FORCE_ENV} has no effect on this host (below ${SUBAGENT_MODEL_FORCE_MIN_VERSION})`
+          : o.subagentModelForceEnabled
+            ? `${SUBAGENT_MODEL_FORCE_ENV} forces one model: every agent runs on one model`
+            : `${SUBAGENT_MODEL_FORCE_ENV} is set to an off value`
+      )
+    }
+    if (o.maxConcurrent && !o.maxConcurrent.valid) {
+      const { min, max } = WORKFLOW_MAX_CONCURRENT_RANGE
+      detail.push(`${WORKFLOW_MAX_CONCURRENT_ENV} is not an integer from ${min} to ${max}, so a run reads it as unset`)
+    }
+    if (o.agentTeams !== null) detail.push(`${AGENT_TEAMS_ENV} does not affect Workflow agents`)
+    detail.push(
+      o.bedrock.length
+        ? `Bedrock: ${o.bedrock.join(', ')} set, so control-plane pings inherit the session model`
+        : 'Bedrock: not set'
+    )
+    detail.push(
+      `${o.cpuCount === null ? 'CPU count unknown' : `${o.cpuCount} CPUs`} beside the vendor default of ` +
+        `${RUNTIME.maxConcurrentAgents} concurrent agents, which the runtime may reduce on a small machine`
+    )
+
+    return check('claude-env', !anySet && o.version !== null ? 'ok' : 'skip', detail.join('; '))
+  } catch (err) {
+    // Fail-open, and never `fail`: an unreadable environment is a reason to
+    // withhold the advice, not a reason to block a run.
+    return check('claude-env', 'skip', `the claude-env check could not run: ${messageOf(err)}`)
+  }
+}
+
+/**
+ * Whether the host can load the plugin's hooks module (the ship meter), as
+ * advice: `ok` at or above the mods floor, `skip` below it or with the version
+ * unknown, never `fail`. It reads the version the `claude-env` row already
+ * probed, so the preflight spawns nothing new. The binary it names is the one
+ * on PATH (or `INTERLOCK_CLAUDE_COMMAND`); a Desktop session's engine is not
+ * that binary, which is why the module logs the engine it actually loaded in.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @param {string|null} version
+ */
+export function checkMods(env, version) {
+  try {
+    const bin = claudeCommandArgv(env)[0]
+    const desktop = 'a Desktop session\'s engine may differ from this binary; the meter logs the engine it loaded in at session start'
+    const unchanged = 'a host that cannot load mods runs exactly today\'s run and prints every banner at close'
+    if (version === null || version === undefined) {
+      return check('mods', 'skip', `${bin}: version unknown (the version probe did not answer); mods need ${MODS_MIN_HOST_VERSION}+; ${unchanged}; ${desktop}`)
+    }
+    if (compareVersions(version, MODS_MIN_HOST_VERSION) >= 0) {
+      return check('mods', 'ok', `${bin} ${version} loads the hooks module (mods ${MODS_MIN_HOST_VERSION}+): /interlock-meter draws a ship run live; ${desktop}`)
+    }
+    return check(
+      'mods',
+      'skip',
+      `${bin} ${version} is below the mods floor ${MODS_MIN_HOST_VERSION}: the meter draws nothing here; ${unchanged}; ${desktop}`
+    )
+  } catch (err) {
+    return check('mods', 'skip', `the mods check could not run: ${messageOf(err)}`)
+  }
+}
+
+/** The installed Claude CLI's version through the doctor's probe, or null. Never throws. */
+function claudeVersionOf(env, probe) {
+  try {
+    const [bin, ...fixedArgs] = claudeCommandArgv(env)
+    return parseClaudeVersion(probe(bin, [...fixedArgs, '--version']))
+  } catch {
+    return null
+  }
+}
+
+/** This machine's CPU count, or null. Never throws. */
+function cpuCountOf() {
+  try {
+    const n = cpus().length
+    return Number.isInteger(n) && n > 0 ? n : null
+  } catch {
+    return null
+  }
+}
+
+/** The credential a bare print-mode run reads from the environment, by name. */
+const BARE_KEY_ENV = 'ANTHROPIC_API_KEY'
+/** The settings key a bare print-mode run can take a credential from instead. */
+const BARE_HELPER_KEY = 'apiKeyHelper'
+/** What `--bare` sets, and what a session already in simple mode carries. */
+const CLAUDE_SIMPLE_ENV = 'CLAUDE_CODE_SIMPLE'
+
+/**
+ * The vendor's bare-mode facts this row repeats. A host claim this module
+ * cannot verify, so it is stated as what the documentation says, not as a
+ * measurement of the session.
+ */
+const BARE_MODE_FACT =
+  'the headless docs recommend --bare and say it will become the default for -p; under it OAuth and the keychain ' +
+  'are never read, so --host claude lanes need a key or a helper, and a plugin loads only through --plugin-dir'
+
+/**
+ * Advice, never a gate: would a bare print-mode run have a credential?
+ *
+ * `checkNotify`'s posture — `ok` or `skip`, NEVER `fail`, its own try/catch,
+ * outside `diagnose`'s `run()`. A session that authenticates with OAuth runs
+ * every lane today; the row exists because the vendor intends `--bare` to
+ * become the print-mode default, and under it that same session's `--host
+ * claude` lanes would start with nothing to authenticate with. A preflight that
+ * failed on a default that has not changed yet would block working runs.
+ *
+ * Read by NAME and never by value: `ANTHROPIC_API_KEY` is reported as set or
+ * not, and an `apiKeyHelper` by the settings scope that configures it, never by
+ * the command it runs. This report is written to disk and pasted into issues.
+ *
+ * A settings file that is absent, unreadable or not JSON is skipped here and
+ * not reported — `checkPermissions` owns that finding, and an unparseable file
+ * is not evidence that a helper is unset.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @param {{root?: string, home?: string, sources?: Array<{scope: string, path: string}>}} [opts]
+ */
+export function checkClaudeBare(env, { root = '.', home, sources } = {}) {
+  try {
+    const key = isSet(env, BARE_KEY_ENV)
+    const simple = isSet(env, CLAUDE_SIMPLE_ENV)
+    const helperScopes = []
+    const evidence = []
+    for (const source of sources || settingsSources(resolve(root), home)) {
+      if (!source || typeof source.path !== 'string' || !existsSync(source.path)) continue
+      const parsed = readJson(source.path)
+      if (!parsed.value || typeof parsed.value !== 'object') continue
+      const helper = parsed.value[BARE_HELPER_KEY]
+      if (typeof helper === 'string' && helper.trim()) {
+        helperScopes.push(source.scope)
+        evidence.push(`${BARE_HELPER_KEY}: ${source.scope} (${source.path})`)
+      }
+    }
+
+    const helpers = helperScopes.length
+      ? `${BARE_HELPER_KEY} is configured in ${helperScopes.join(', ')} settings`
+      : null
+    const detail = []
+    if (key && helpers) {
+      detail.push(`${BARE_KEY_ENV} is set and ${helpers}, so a bare print-mode run has a credential`)
+    } else if (key) {
+      detail.push(`${BARE_KEY_ENV} is set, so a bare print-mode run has a credential`)
+    } else if (helpers) {
+      detail.push(
+        `${helpers}, so a bare print-mode run has a credential`,
+        `\`claude --help\` words bare-mode auth as an ${BARE_HELPER_KEY} "via --settings", so a helper configured only in a settings file may need passing with --settings`
+      )
+    } else {
+      detail.push(
+        `neither ${BARE_KEY_ENV} nor an ${BARE_HELPER_KEY} is configured, so a bare print-mode run would have no credential — set ${BARE_KEY_ENV} or configure ${BARE_HELPER_KEY}`
+      )
+    }
+    detail.push(
+      simple
+        ? `${CLAUDE_SIMPLE_ENV} is set (the simple mode --bare turns on)`
+        : `${CLAUDE_SIMPLE_ENV} is not set`,
+      BARE_MODE_FACT
+    )
+
+    const ok = key || Boolean(helpers)
+    return check('claude-bare', ok ? 'ok' : 'skip', detail.join('; '), {
+      evidence,
+      fix: ok
+        ? undefined
+        : `Set ${BARE_KEY_ENV}, or configure "${BARE_HELPER_KEY}" in a settings file (passed with --settings under --bare), before --host claude lanes run bare. Nothing changes for a run today.`
+    })
+  } catch (err) {
+    // Fail-open, and never `fail`: an unreadable environment or settings tree
+    // is a reason to withhold the advice, not a reason to block a run.
+    return check('claude-bare', 'skip', `the claude-bare check could not run: ${messageOf(err)}`)
+  }
+}
+
 /**
  * Advice, never a gate, and never a measurement.
  *
@@ -1074,9 +1470,12 @@ export function evalPrerequisiteChecks(pluginRoot, env = process.env) {
  * @param {object} [opts.env]               environment PATH is read from
  * @param {string} [opts.home]              home directory user settings are read from
  * @param {string} [opts.nodeVersion]       overrides process.version, for tests
- * @param {(bin: string) => string|null} [opts.probeVersion]  version probe; injected in tests
+ * @param {(bin: string, args?: string[]) => string|null} [opts.probeVersion]  version probe; injected in tests
+ * @param {number} [opts.cpuCount]          overrides the machine's CPU count, for tests
  * @param {Array<{scope:string,path:string}>} [opts.settingsSources]  overrides the merge list
- * @returns {object} report
+ * @param {string} [opts.stateHome]         an explicit state home (`--state-home`); when absent,
+ *                                          `INTERLOCK_STATE_HOME` in `opts.env` and then git decide
+ * @returns {object} report, carrying `stateHome` (absolute) and `surface`
  */
 export function diagnose(root = '.', opts = {}) {
   const projectRoot = resolve(root)
@@ -1084,6 +1483,11 @@ export function diagnose(root = '.', opts = {}) {
   const env = opts.env || process.env
   const probe = typeof opts.probeVersion === 'function' ? opts.probeVersion : probeVersion
 
+  // Resolved ONCE, here, and handed to every row that needs it — and to the
+  // SessionStart preflight through the report, so it reads interrupted-run
+  // notes from this home without resolving a second time.
+  const resolved = resolveHomeFor(projectRoot, opts.stateHome, env)
+
   const run = (id, fn) => {
     try {
       return fn()
@@ -1101,7 +1505,7 @@ export function diagnose(root = '.', opts = {}) {
   checks.push(run('openspec', () => checkOpenSpec(projectRoot, env, probe)))
   checks.push(run('git', () => checkGit(projectRoot, env, probe)))
 
-  const profileCheck = run('test-profile', () => checkTestProfile(projectRoot))
+  const profileCheck = run('test-profile', () => checkTestProfile(projectRoot, resolved.home || projectRoot))
   const profile = profileCheck.profile
   delete profileCheck.profile
   checks.push(profileCheck)
@@ -1115,7 +1519,10 @@ export function diagnose(root = '.', opts = {}) {
       checkPermissions(projectRoot, required, { home: opts.home, sources: opts.settingsSources })
     )
   )
-  checks.push(run('state-dirs', () => checkStateDirs(projectRoot)))
+  // Not behind `run()`: which home was resolved is advice and may never be a
+  // `fail`; whether that home is writable is `state-dirs`' question, which can.
+  checks.push(checkStateHome(projectRoot, resolved))
+  checks.push(run('state-dirs', () => checkStateDirs(projectRoot, resolved.home)))
 
   // Not behind `run()`: that wrapper's thrown-probe verdict is `fail`, and
   // this row may never carry one — push is optional, so `checkNotify` owns
@@ -1128,6 +1535,24 @@ export function diagnose(root = '.', opts = {}) {
   // try/catch. See `checkPromptCache`.
   checks.push(checkPromptCache(projectRoot, { home: opts.home, sources: opts.settingsSources, env }))
 
+  // And again: the Claude Code environment a run's routing reads is the
+  // operator's, so this row is advice. One `claude --version` spawn, bounded by
+  // the probe's own timeout. See `checkClaudeEnv`.
+  const claudeVersion = claudeVersionOf(env, probe)
+  checks.push(
+    checkClaudeEnv(env, {
+      version: claudeVersion,
+      cpuCount: Number.isInteger(opts.cpuCount) ? opts.cpuCount : cpuCountOf()
+    })
+  )
+  // The same reading, no second spawn: whether the ship meter can draw here.
+  // Advice, `ok`/`skip`, its own try/catch. See `checkMods`.
+  checks.push(checkMods(env, claudeVersion))
+
+  // And again: whether a bare print-mode run would have a credential is advice
+  // about the operator's environment and settings. See `checkClaudeBare`.
+  checks.push(checkClaudeBare(env, { root: projectRoot, home: opts.home, sources: opts.settingsSources }))
+
   // Not behind `run()`: that wrapper's thrown-probe verdict is `fail`, and
   // these rows may never carry one. See `evalPrerequisiteChecks`.
   checks.push(...evalPrerequisiteChecks(pluginRoot, env))
@@ -1138,6 +1563,8 @@ export function diagnose(root = '.', opts = {}) {
   return {
     ok: counts.fail === 0,
     root: projectRoot,
+    stateHome: resolved.home,
+    surface: resolved.surface,
     pluginRoot,
     counts,
     checks,
@@ -1147,6 +1574,30 @@ export function diagnose(root = '.', opts = {}) {
   }
 }
 
+/**
+ * The state home for `root`, never throwing. `resolveStateHome` already holds
+ * that contract; the guard is here because a doctor that crashed resolving
+ * where to look would produce no report at all, and the fallback carries its
+ * reason so the `state-home` row can speak it.
+ */
+function resolveHomeFor(root, explicit, env) {
+  try {
+    const resolved = resolveStateHome(root, {
+      explicit: typeof explicit === 'string' && explicit.trim() ? explicit : undefined,
+      env
+    })
+    if (resolved && typeof resolved.home === 'string' && resolved.home) return resolved
+    return { home: root, surface: 'unknown', reason: 'the state home resolver returned no home', resolvedFrom: 'fallback' }
+  } catch (err) {
+    return {
+      home: root,
+      surface: 'unknown',
+      reason: `the state home could not be resolved: ${messageOf(err)}`,
+      resolvedFrom: 'fallback'
+    }
+  }
+}
+
 /** Human-readable preflight, in the shape `interlock ready` already prints. */
 export function formatDoctor(report) {
   const lines = []
@@ -1158,6 +1609,15 @@ export function formatDoctor(report) {
         (report.counts.warn ? `, ${report.counts.warn} warning(s)` : '')
   )
   lines.push(`  root: ${report.root}`)
+  // Under `root:` only when the two differ, so a main checkout's report reads as
+  // it always did and a worktree session's names where its corpora go.
+  if (
+    typeof report.stateHome === 'string' &&
+    report.stateHome &&
+    realOrSelf(report.stateHome) !== realOrSelf(report.root)
+  ) {
+    lines.push(`  state home: ${report.stateHome}`)
+  }
   if (report.pluginRoot !== report.root) lines.push(`  plugin: ${report.pluginRoot}`)
   for (const c of report.checks) {
     lines.push(`  [${STATUS_MARK[c.status] || c.status}] ${c.id}: ${c.detail}`)