@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/service-manager.mjs

@@ -6,13 +6,14 @@
  * spawns whatever is available and returns a result per service.
  */
 import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { findAvailablePort } from './host-capabilities.mjs';
+import { findAvailablePort, detectActiveSessions } from './host-capabilities.mjs';
 import { wrapWithOpRun } from './providers/op-run.mjs';
 import { getUserEnvPath, loadConstructEnv, parseEnvFile, writeEnvValues } from './env-config.mjs';
 import { runPressureRelease } from './runtime-pressure.mjs';
@@ -22,6 +23,7 @@ import { readHeartbeat } from './daemons/contract.mjs';
 import { heartbeatPath } from './oracle/index.mjs';
 import { stateDir } from './config/xdg.mjs';
 import { doctorRoot } from './config/xdg.mjs';
+import { resolveStateDir } from './state-root.mjs';
 
 const INSTALL_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -163,13 +165,19 @@ async function isCopilotBridgeRunning(port) {
   return probeRuntimePort(port);
 }
 
-// Opt-in 1Password resolution (ADR-0049 Design A): each long-lived service launches
-// under `op run --env-file -- <cmd>` so op:// references resolve once at this stable
-// parent and every child inherits resolved provider keys. wrapWithOpRun returns the
-// command unchanged when CONSTRUCT_OP_ENV_FILE is unset, the file is missing, or `op`
-// is absent, so the un-opted path is byte-for-byte the prior behavior. The env that
-// carries CONSTRUCT_OP_ENV_FILE is options.env when a site sets one (doctor, oracle)
-// and process.env otherwise (cm, opencode, copilot bridge).
+// Opt-in 1Password resolution (ADR-0049 Design A): under `construct dev` the process
+// re-execs once under a single `op run --env-file` (maybeReExecUnderOpRun), so op://
+// references resolve one time at that stable parent and every daemon here inherits the
+// resolved keys through liveEnv — the CONSTRUCT_OP_RUN_ACTIVE sentinel then makes
+// wrapWithOpRun a no-op so no daemon nests a second op run. wrapWithOpRun stays the
+// fallback for daemons started outside that parent (an opencode/copilot-bridge restart
+// from a hook), wrapping them individually. It returns the command unchanged when
+// CONSTRUCT_OP_ENV_FILE is unset, the file is missing, `op` is absent, or the sentinel
+// is set, so the un-opted path is byte-for-byte the prior behavior. doctor, oracle, and
+// cm consume no provider API keys (construct-0wmj) and are spawned unwrapped; every
+// service is still spawned with the merged liveEnv, so config.env-only vars (including
+// CONSTRUCT_OP_ENV_FILE and an OP_SERVICE_ACCOUNT_TOKEN) reach the child rather than
+// only the wrapped op-run subset.
 
 function wrapServiceSpawn(command, args, homeDir, options = {}) {
   const env = options.env || process.env;
@@ -225,9 +233,9 @@ export function startDoctor({ rootDir, homeDir = os.homedir() } = {}) {
   if (existing) return { started: false, reused: true, pid: existing.pid };
   const indexPath = path.join(INSTALL_ROOT, 'lib', 'doctor', 'index.mjs');
   if (!fs.existsSync(indexPath)) return { started: false, reason: 'missing-binary' };
+  // doctor consumes no provider API keys (construct-0wmj) — no op-run wrap needed.
   const doctorEnv = { ...process.env };
-  const launch = wrapServiceSpawn('node', [indexPath], homeDir, { env: doctorEnv });
-  const { logPath } = spawnDetached(launch.command, launch.args, homeDir, 'doctor.log', { cwd: rootDir, env: doctorEnv });
+  const { logPath } = spawnDetached('node', [indexPath], homeDir, 'doctor.log', { cwd: rootDir, env: doctorEnv });
   return { started: true, logPath };
 }
 
@@ -244,8 +252,8 @@ export function startOracle({ rootDir, homeDir = os.homedir(), projectDir = root
     CONSTRUCT_ORACLE_ROOT: rootDir,
     CONSTRUCT_ORACLE_PROJECT: projectDir,
   };
-  const launch = wrapServiceSpawn('node', [entry], homeDir, { env: oracleEnv });
-  const { logPath } = spawnDetached(launch.command, launch.args, homeDir, 'oracle-daemon.log', {
+  // oracle consumes no provider API keys (construct-0wmj) — no op-run wrap needed.
+  const { logPath } = spawnDetached('node', [entry], homeDir, 'oracle-daemon.log', {
     cwd: projectDir,
     env: oracleEnv,
   });
@@ -338,6 +346,17 @@ export async function startServices({
   const operatorKeepAlive = resolveOllamaKeepAlive(liveEnv);
   if (operatorKeepAlive) liveEnv.OLLAMA_KEEP_ALIVE = operatorKeepAlive;
 
+  // The Copilot bridge fronts the user's Copilot entitlement over loopback HTTP, so it
+  // requires a bearer token. Generate a stable token once, persist it to the 0600
+  // config.env, and set it on liveEnv before OpenCode (the only caller) spawns so both
+  // the bridge and OpenCode inherit it; writeOpenCodeConfig wires it as an {env:} auth
+  // header. Reusing the persisted value keeps a restarted bridge and OpenCode in sync.
+  if (wants('copilot-bridge') && support.gh && detectActiveSessions().includes('github-copilot') && !liveEnv.CONSTRUCT_COPILOT_BRIDGE_TOKEN) {
+    const copilotBridgeToken = randomBytes(24).toString('hex');
+    liveEnv.CONSTRUCT_COPILOT_BRIDGE_TOKEN = copilotBridgeToken;
+    writeEnvValues(envPath, { CONSTRUCT_COPILOT_BRIDGE_TOKEN: copilotBridgeToken });
+  }
+
   const pressureReport = runPressureReleaseFn({ env: { ...liveEnv, HOME: homeDir } });
   if (pressureReport?.killed?.length) {
     results.push({
@@ -354,14 +373,14 @@ export async function startServices({
     if (traceBackend === 'local') {
       results.push({
         name: 'Telemetry',
-        url: path.join(rootDir, '.cx', 'traces'),
+        url: resolveStateDir(rootDir, 'traces', { ensureDir: false }),
         status: 'configured',
         note: 'local JSONL traces; remote export not configured',
       });
     } else if (traceBackend === 'none') {
       results.push({
         name: 'Telemetry',
-        url: path.join(rootDir, '.cx', 'traces'),
+        url: resolveStateDir(rootDir, 'traces', { ensureDir: false }),
         status: 'configured',
         note: 'remote export disabled; local JSONL traces preserved',
       });
@@ -390,12 +409,12 @@ export async function startServices({
     if (await memoryProbeFn(ports.memory)) {
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'reused' });
     } else {
-      const cm = wrapServiceSpawn('cm', ['serve', '--port', String(ports.memory)], homeDir, { env: liveEnv });
-      const cmSpawn = spawnDetachedFn(cm.command, cm.args, homeDir, 'cm.log');
+      // cm consumes no provider API keys (construct-0wmj) — no op-run wrap needed.
+      const cmSpawn = spawnDetachedFn('cm', ['serve', '--port', String(ports.memory)], homeDir, 'cm.log', { env: liveEnv });
       try {
         if (cmSpawn?.child?.pid) {
           writeJson(portOwnershipPath(ports.memory, homeDir), {
-            pid: cmSpawn.child.pid, command: `${cm.command} ${cm.args.join(' ')}`,
+            pid: cmSpawn.child.pid, command: `cm serve --port ${ports.memory}`,
             cwd: process.cwd(), marker: 'construct', constructManaged: true,
             startedAt: new Date().toISOString(),
           });
@@ -413,7 +432,7 @@ export async function startServices({
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'reused' });
     } else {
       const opencode = wrapServiceSpawn('opencode', ['serve', '--port', String(ports.bridge)], homeDir, { env: liveEnv });
-      const ocSpawn = spawnDetachedFn(opencode.command, opencode.args, homeDir, 'opencode.log');
+      const ocSpawn = spawnDetachedFn(opencode.command, opencode.args, homeDir, 'opencode.log', { env: liveEnv });
       try {
         if (ocSpawn?.child?.pid) {
           writeJson(portOwnershipPath(ports.bridge, homeDir), {
@@ -438,7 +457,7 @@ export async function startServices({
         const proxyPath = path.join(INSTALL_ROOT, 'lib', 'bridges', 'copilot-proxy.mjs');
         if (fs.existsSync(proxyPath)) {
           const copilot = wrapServiceSpawn('node', [proxyPath, '--port', String(ports.copilotBridge)], homeDir, { env: liveEnv });
-          const copilotSpawn = spawnDetachedFn(copilot.command, copilot.args, homeDir, 'copilot-bridge.log');
+          const copilotSpawn = spawnDetachedFn(copilot.command, copilot.args, homeDir, 'copilot-bridge.log', { env: liveEnv });
           try {
             if (copilotSpawn?.child?.pid) {
               writeJson(portOwnershipPath(ports.copilotBridge, homeDir), {

package/lib/setup.mjs

@@ -2,10 +2,14 @@
 /**
  * lib/setup.mjs — Machine-scoped first-run setup wizard for Construct.
  *
- * Installs cm/cass, configures managed defaults, pre-warms the embedding model,
- * wires MCP integrations, and writes the XDG user config (~/.config/construct/config.env).
- * Invoked by `construct install` and by lib/install/first-invocation.mjs
- * when a TTY user is missing resources.
+ * Installs cm/cass, configures managed defaults, wires MCP integrations, and
+ * writes the XDG user config (~/.config/construct/config.env). Invoked by
+ * `construct install` and by lib/install/first-invocation.mjs when a TTY
+ * user is missing resources.
+ *
+ * The embedding model and LanceDB vector store provision lazily by default
+ * (construct-rf26.17) — pass --with-embeddings to warm both up during
+ * install instead of at first semantic-search use, mirroring --with-docling.
  *
  * Project-scoped scaffolding (`.cx/`, AGENTS.md, plan.md, adapters) lives
  * in lib/init-unified.mjs — invoked by `construct init`. These two flows
@@ -35,6 +39,7 @@ import { getEmbeddingModelInfo, warmupEmbeddingModel } from './storage/embedding
 import { buildPressureGuardValues, installPressureGuardLaunchAgent, loadPressureGuardLaunchAgent } from './runtime-pressure.mjs';
 import { consentToInstall } from './setup-prompts.mjs';
 import { cleanupLegacyGlobalConstruct } from './install/legacy-global-cleanup.mjs';
+import { isMainModule } from './roots.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
@@ -59,6 +64,9 @@ Flags:
   --with-docling    eagerly provision the docling document-extraction venv now
                       (heavy, ~10 min via uv; otherwise provisioned lazily on
                       first document ingest)
+  --with-embeddings warm the embedding model + LanceDB vector store dir now
+                      (loads from local cache only, offline-safe; otherwise
+                      both provision lazily on first semantic-search use)
   --cleanup-legacy-global
                     remove legacy user-global Construct adapters/MCP/history
                       before setup; does not uninstall a global construct CLI
@@ -330,7 +338,7 @@ function runLegacyGlobalCleanup({ homeDir, dryRun }) {
 // network call, or service registration that the real run would perform — and
 // returns before touching disk so the preview is provably side-effect-free.
 
-function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupLegacyGlobal }) {
+function printInstallPlan({ scope, homeDir, withDocling, withEmbeddings, noLaunchAgent, cleanupLegacyGlobal }) {
   console.log('Construct install — dry-run (no changes written)');
   console.log('────────────────────────────────────────────────');
   console.log(`Scope: ${scope}`);
@@ -350,11 +358,11 @@ function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupL
   console.log(`  · ${getCanonicalOpenCodeConfigPath(homeDir)} (OpenCode config)`);
   console.log(`  · ${path.join(configDir(homeDir), 'lib')} → ${path.join(ROOT_DIR, 'lib')} (hook lib symlink)`);
   console.log(`  · ${path.join(stateDir(homeDir), 'workspace')} (workspace docs scaffold)`);
-  console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
+  if (withEmbeddings) console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
   console.log('\nWould check / install runtime tooling:');
   console.log('  · cm (memory CLI) and cass (session search) when available on PATH');
-  console.log('\nWould reach the network / external services:');
-  console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
+  if (withEmbeddings || withDocling) console.log('\nWould reach the network / external services:');
+  if (withEmbeddings) console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
   if (withDocling) console.log('  · docling Python venv provisioning via uv (~10 min)');
   console.log('  · construct sync --quiet, construct sync --global, construct doctor');
   if (process.platform === 'darwin' && !noLaunchAgent) {
@@ -375,9 +383,10 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     return;
   }
 
-  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--cleanup-legacy-global', '--help', '-h']);
+  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--with-embeddings', '--cleanup-legacy-global', '--help', '-h']);
   const dryRun = argSet.has('--dry-run');
   const withDocling = argSet.has('--with-docling');
+  const withEmbeddings = argSet.has('--with-embeddings');
   const unknownFlags = args.filter((a) => {
     if (!a.startsWith('-')) return false;
     if (a.startsWith('--scope=') || a === '--scope') return false;
@@ -402,7 +411,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
       printProjectScopeGuidance();
       return;
     }
-    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent'), cleanupLegacyGlobal });
+    printInstallPlan({ scope, homeDir, withDocling, withEmbeddings, noLaunchAgent: argSet.has('--no-launch-agent'), cleanupLegacyGlobal });
     return;
   }
 
@@ -470,20 +479,29 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
 
   const telemetryResult = process.env.CONSTRUCT_TELEMETRY_URL
     ? { status: 'configured', note: `remote export configured (${process.env.CONSTRUCT_TELEMETRY_URL})` }
-    : { status: 'local', note: 'local JSONL traces in .cx/traces; remote export optional' };
+    : { status: 'local', note: 'local JSONL traces in the machine-scoped state root; remote export optional' };
   console.log(`Telemetry: ${telemetryResult.note}`);
 
-  fs.mkdirSync(path.dirname(defaultVectorIndexPath(homeDir)), { recursive: true });
-
-  try {
-    const warm = await warmupEmbeddingModel({ env: process.env });
-    if (warm.degraded) {
-      console.log(`Embeddings: degraded fallback (${warm.fallbackReason || 'model unavailable'}) — semantic search will use the hashing backend`);
-    } else {
-      console.log(`Embeddings: ${warm.model} ready (${warm.dimensions}d, warmed in ${warm.durationMs}ms)`);
+  // The embedding model and LanceDB vector store dir are provisioned lazily
+  // by default (construct-rf26.17): a project that never runs semantic
+  // search never pays for the ONNX model cache or an index directory. Both
+  // provision on first real use (`construct ingest`, first observation
+  // store/search) exactly like docling below. --with-embeddings opts into
+  // warming both up now instead of at first query.
+  if (withEmbeddings) {
+    fs.mkdirSync(path.dirname(defaultVectorIndexPath(homeDir)), { recursive: true });
+    try {
+      const warm = await warmupEmbeddingModel({ env: process.env });
+      if (warm.degraded) {
+        console.log(`Embeddings: degraded fallback (${warm.fallbackReason || 'model unavailable'}) — semantic search will use the hashing backend`);
+      } else {
+        console.log(`Embeddings: ${warm.model} ready (${warm.dimensions}d, warmed in ${warm.durationMs}ms)`);
+      }
+    } catch (err) {
+      console.log(`Embeddings: warmup skipped (${err?.message || 'unknown error'}) — model will load on first use`);
     }
-  } catch (err) {
-    console.log(`Embeddings: warmup skipped (${err?.message || 'unknown error'}) — model will load on first use`);
+  } else {
+    console.log('Embeddings: will provision on first semantic-search use (pass --with-embeddings to warm up now)');
   }
 
   // Docling (document/PDF extraction) provisions a pinned Python venv via uv,
@@ -592,7 +610,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   console.log('Setup complete.');
 
   console.log('\nLocal services:');
-  console.log('  Traces:      local JSONL (.cx/traces)');
+  console.log('  Traces:      local JSONL (machine-scoped state root)');
   console.log(`  Vector:      LanceDB (embedded)`);
   console.log(`    ${managedValues.CONSTRUCT_LANCEDB_PATH}`);
   console.log(`  Credentials are saved to ${getUserEnvPath(homeDir)} for later reference.`);
@@ -623,6 +641,6 @@ export function ensureWorkspace(homeDir = HOME) {
   return wsPath;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   runSetup({ args: process.argv.slice(2) });
 }

package/lib/skills-apply.mjs

@@ -87,8 +87,10 @@ export function writeConstructManifest(cwd, profile, classification) {
  * that records the recommended per-project scoping for Claude Code.
  *
  * Why a sidecar and not `settings.json`? Claude Code today only reads
- * `permissions`, `hooks`, and `mcpServers` from settings.json. A
- * `disabledPlugins` key would be ignored silently. Writing a sidecar is
+ * `permissions`, `hooks`, and policy keys (`allowedMcpServers`,
+ * `deniedMcpServers`, etc.) from settings.json — MCP server definitions
+ * live in `~/.claude.json` or `.mcp.json` instead (construct-ranh). A
+ * `disabledPlugins` key would be ignored silently either way. Writing a sidecar is
  * honest — it documents the recommendation without pretending the harness
  * enforces it. The construct-mcp session-start path can read this sidecar
  * and inject a "skills out of scope for this project" note.

package/lib/specialists/postconditions.mjs

@@ -18,7 +18,7 @@
  *   - cx-reviewer       prevents silent rubber-stamp reviews
  *   - cx-security       prevents post-hoc threat models
  *   - cx-debugger       prevents symptom-only fixes
- *   - cx-docs-keeper    prevents stale-doc PRs
+ *   - cx-operations     prevents stale-doc PRs (docs-keeper folded in, construct-rf26.11)
  *   - cx-designer       prevents post-hoc accessibility
  */
 
@@ -75,7 +75,7 @@ export const POSTCONDITIONS = {
       reason: `rootCauseConfirmedVia must be one of: ${[...ROOT_CAUSE_SOURCES].join(', ')}.`,
     },
   ],
-  'cx-docs-keeper': [
+  'cx-operations': [
     {
       id: 'docs-keeper.cross-doc-coherence-check-ran',
       description: 'Docs-keeper must run the cross-doc coherence check and attach a named diff.',

package/lib/state-root.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/state-root.mjs — machine-scoped state roots for heavy runtime state (ADR-0066).
+ *
+ * Two distinct scopes live under `constructDir()` (`~/.construct/` or
+ * `$CX_TOOLKIT_DIR`), and this module is the only place either is resolved:
+ *
+ *   - Per-project state (`resolveStateRoot`/`resolveStateDir`/`resolveStatePath`):
+ *     `~/.construct/projects/<key>/` — traces, observations, the vector index,
+ *     task graphs. Keyed by `deriveProjectKey`, a derivation stable across
+ *     clones of the same git remote so two checkouts of one repository share
+ *     accumulated state. A project with no remote (a fresh local-only repo)
+ *     falls back to a hash of its resolved absolute path.
+ *
+ *   - Machine-shared state (`resolveSharedRuntimeDir`): `~/.construct/runtime/`
+ *     — not keyed per project at all. Reserved for state whose cost scales with
+ *     the binary itself, not with any one project (the docling venv,
+ *     construct-rf26.16): provisioning it per-project multiplies a genuinely
+ *     large cost for content that isn't project-specific.
+ *
+ * `.beads/` is a deliberate exception (ADR-0026): issue history travels with
+ * the repository and is never resolved through this module.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+import { constructDir } from './paths.mjs';
+
+function normalizeRemote(url) {
+  let s = url.trim();
+
+  // `git@host:owner/repo.git` (scp-like shorthand) has no `scheme://` prefix,
+  // so it needs its own split before the generic scheme/credential strip.
+  const scp = s.match(/^[^@/]+@([^:]+):(.+)$/);
+  if (scp && !/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(s)) {
+    s = `${scp[1]}/${scp[2]}`;
+  } else {
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, '');
+    s = s.replace(/^[^@/]+@/, '');
+  }
+
+  return s.replace(/\.git$/, '').replace(/\/+$/, '').toLowerCase();
+}
+
+function readOriginRemote(projectRoot) {
+  try {
+    const out = execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: projectRoot,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).toString().trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+// The path-hash fallback (no remote) must be symlink-invariant: a caller that
+// reaches the same directory through a symlinked path (e.g. macOS's /var/folders
+// tmp symlink, or a home-directory alias) must still resolve to the same key.
+// realpath is best-effort — a not-yet-created path falls back to path.resolve.
+
+function canonicalPath(projectRoot) {
+  const resolved = path.resolve(projectRoot);
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+/**
+ * Derive a stable key for a project: the normalized git origin remote when
+ * one exists (so every clone of the same repository resolves to the same
+ * key), otherwise a hash of the canonical (symlink-resolved) absolute project
+ * path.
+ */
+export function deriveProjectKey(projectRoot) {
+  const resolved = path.resolve(projectRoot);
+  const remote = readOriginRemote(resolved);
+  const material = remote ? `remote:${normalizeRemote(remote)}` : `path:${canonicalPath(projectRoot)}`;
+  return createHash('sha256').update(material).digest('hex').slice(0, 24);
+}
+
+// A trailing plain-object argument is an options bag ({ ensureDir }), never a
+// path segment — path segments are always strings.
+
+function popOptions(segments) {
+  const last = segments[segments.length - 1];
+  if (last !== null && typeof last === 'object' && !Array.isArray(last)) {
+    return [segments.slice(0, -1), last];
+  }
+  return [segments, {}];
+}
+
+/**
+ * Resolve the machine-scoped state root for a project. Creates the directory
+ * (mkdir -p) on this access by default rather than up front — pass
+ * `{ ensureDir: false }` for a caller that only wants the path (e.g. a probe
+ * that may never actually write). Built on constructDir() so the existing
+ * CX_TOOLKIT_DIR override relocates per-project state along with the rest of
+ * `~/.construct/`.
+ */
+export function resolveStateRoot(projectRoot, { ensureDir = true } = {}) {
+  const dir = path.join(constructDir(), 'projects', deriveProjectKey(projectRoot));
+  if (ensureDir) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Resolve a subdirectory under a project's state root, creating it by
+ * default. Pass a trailing `{ ensureDir: false }` to skip creation.
+ */
+export function resolveStateDir(projectRoot, ...segments) {
+  const [parts, { ensureDir = true }] = popOptions(segments);
+  const dir = path.join(resolveStateRoot(projectRoot, { ensureDir: false }), ...parts);
+  if (ensureDir) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Resolve a file path under a project's state root, creating the parent
+ * directory (not the file itself) by default. Pass a trailing
+ * `{ ensureDir: false }` to skip creation.
+ */
+export function resolveStatePath(projectRoot, ...segments) {
+  const [parts, { ensureDir = true }] = popOptions(segments);
+  const filePath = path.join(resolveStateRoot(projectRoot, { ensureDir: false }), ...parts);
+  if (ensureDir) fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  return filePath;
+}
+
+/**
+ * Resolve a machine-shared runtime directory: not project-keyed, unlike
+ * resolveStateRoot/resolveStateDir. Every project on this machine — and every
+ * clone or worktree of every project — resolves the same segments to the
+ * identical directory. Use for state whose provisioning cost is per-machine,
+ * per-binary (a shared uv venv), never per-project.
+ */
+export function resolveSharedRuntimeDir(...segments) {
+  const [parts, { ensureDir = true }] = popOptions(segments);
+  const dir = path.join(constructDir(), 'runtime', ...parts);
+  if (ensureDir) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}