leerness 1.36.185 → 1.36.186

package/lib/state-git.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { gitSpawn } = require('./git');
+
+class StatePathError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'StatePathError';
+    this.code = code;
+  }
+}
+
+function canonicalDirectory(value) {
+  if (typeof value !== 'string' || !value.trim() || /[\x00-\x1f\x7f]/.test(value)) {
+    throw new StatePathError('path_invalid', 'An existing directory path without control characters is required.');
+  }
+  try {
+    const resolved = fs.realpathSync.native(path.resolve(value));
+    if (!fs.statSync(resolved).isDirectory()) {
+      throw new StatePathError('path_not_directory', 'The inspection target must be a directory.');
+    }
+    return resolved;
+  } catch (error) {
+    if (error instanceof StatePathError) throw error;
+    const missing = error.code === 'ENOENT' || error.code === 'ENOTDIR';
+    throw new StatePathError(missing ? 'path_not_found' : 'path_unreadable',
+      missing ? 'The inspection directory does not exist.' : 'The inspection directory cannot be resolved.');
+  }
+}
+
+function unavailable() {
+  return new StatePathError('git_repository_unavailable',
+    'Git repository discovery failed; no alternate state backend was selected.');
+}
+
+// Distinguish a genuinely non-Git directory from damaged repository metadata.
+// Respect Git's discovery ceilings and filesystem boundary; never inspect above them.
+function hasRepositoryMarker(root, env) {
+  const ceilingValue = Object.keys(env).find(key => key.toUpperCase() === 'GIT_CEILING_DIRECTORIES');
+  const ceilings = new Set(String(env[ceilingValue] || '').split(path.delimiter)
+    .filter(value => value && path.isAbsolute(value)).flatMap(value => {
+      try { return [fs.realpathSync.native(value)]; }
+      catch (error) {
+        // Git ignores nonexistent ceiling entries; they are not project paths.
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return [];
+        throw error;
+      }
+    }));
+  const acrossKey = Object.keys(env).find(key => key.toUpperCase() === 'GIT_DISCOVERY_ACROSS_FILESYSTEM');
+  const across = /^(1|true|yes|on)$/i.test(String(env[acrossKey] || ''));
+  const device = fs.statSync(root).dev;
+  let current = root;
+  for (let depth = 0; depth < 128; depth++) {
+    try { fs.lstatSync(path.join(current, '.git')); return true; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const parent = path.dirname(current);
+    if (parent === current || ceilings.has(parent)) return false;
+    if (!across && fs.statSync(parent).dev !== device) return false;
+    current = parent;
+  }
+  throw unavailable();
+}
+
+function processFailure(result) {
+  // The Windows portable gateway reports missing/unsupported launchers via
+  // its own bounded child exit, not spawnSync.error. Keep the same taxonomy.
+  if (result.status === 127 && /^leerness: command not found on PATH: git\r?\n?$/.test(String(result.stderr || ''))) {
+    throw new StatePathError('git_missing', 'Git is unavailable; install Git before inspecting repository topology.');
+  }
+  if (result.status === 126 && /^leerness: unsupported Windows command shim: /.test(String(result.stderr || ''))) {
+    throw new StatePathError('git_unsupported', 'The configured Git launcher is unsupported.');
+  }
+  if (!result.error) return;
+  const codes = {
+    ENOENT: ['git_missing', 'Git is unavailable; install Git before inspecting repository topology.'],
+    ETIMEDOUT: ['git_timeout', 'Git topology discovery timed out.'],
+    ENOBUFS: ['git_output_limit', 'Git topology output exceeded the inspection limit.'],
+    EACCES: ['git_unreadable', 'Git could not be executed with the current permissions.'],
+    EPERM: ['git_unreadable', 'Git could not be executed with the current permissions.'],
+  };
+  const [code, message] = codes[result.error.code] || ['git_failed', 'Git topology discovery could not run.'];
+  throw new StatePathError(code, message);
+}
+
+function parseTopology(root, result, env) {
+  processFailure(result);
+  const output = String(result.stdout || '').replace(/\r?\n$/, '');
+  const lines = output.split(/\r?\n/);
+  if (lines.includes('--path-format=absolute')) {
+    throw new StatePathError('git_unsupported', 'Git must support rev-parse --path-format=absolute.');
+  }
+  if (lines[0] === 'true') {
+    throw new StatePathError('git_bare_unsupported', 'A bare repository has no worktree-private project runtime.');
+  }
+  if (lines[1] === 'true') {
+    throw new StatePathError('git_metadata_path', 'Inspect a worktree project, not a Git metadata directory.');
+  }
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || '');
+    if (/permission denied|access is denied/i.test(stderr)) {
+      throw new StatePathError('git_unreadable', 'Git could not read repository metadata.');
+    }
+    if (!output && /fatal: not a git repository \(or any (?:of the )?parent (?:directories|up to mount point)/i.test(stderr)
+      && !hasRepositoryMarker(root, env)) return null;
+    throw unavailable();
+  }
+  if (lines.length !== 5 || lines[0] !== 'false' || lines[1] !== 'false'
+    || lines.slice(2).some(value => !path.isAbsolute(value))) {
+    throw new StatePathError('git_output_invalid', 'Git did not return an unambiguous absolute topology.');
+  }
+  const [worktreeRoot, gitDir, gitCommonDir] = lines.slice(2).map(canonicalDirectory);
+  const relative = path.relative(worktreeRoot, root);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw unavailable();
+  return { worktreeRoot, gitDir, gitCommonDir, linkedWorktree: gitDir !== gitCommonDir };
+}
+
+function resolveGitTopology(root, options = {}) {
+  const env = { ...(options.env || process.env), LC_ALL: 'C', LANGUAGE: 'C', GIT_TERMINAL_PROMPT: '0' };
+  const args = ['-C', root, 'rev-parse', '--path-format=absolute', '--is-bare-repository',
+    '--is-inside-git-dir', '--show-toplevel', '--git-dir', '--git-common-dir'];
+  try {
+    const result = gitSpawn(args, { cwd: root, env, encoding: 'utf8', timeout: 5000, maxBuffer: 64 * 1024 });
+    return parseTopology(root, result, env);
+  } catch (error) {
+    if (error instanceof StatePathError && !error.code.startsWith('path_')) throw error;
+    if (['EACCES', 'EPERM', 'path_unreadable'].includes(error.code)) {
+      throw new StatePathError('git_unreadable', 'Git repository directories could not be read.');
+    }
+    if (error.code === 'path_invalid' || error.code === 'path_not_directory') {
+      throw new StatePathError('git_output_invalid', 'Git did not return usable directory paths.');
+    }
+    throw unavailable();
+  }
+}
+
+module.exports = { StatePathError, canonicalDirectory, resolveGitTopology };

package/lib/state-inspect.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const path = require('path');
+const { resolveStatePaths } = require('./state-paths');
+const { inspectLegacyInventory } = require('./state-inventory');
+
+function inspectState(root, options = {}) {
+  const resolved = resolveStatePaths(root, options);
+  // Legacy project memory and canonical runtime/substrate can coexist. Selection
+  // determines the project reader, not whether residual state exists elsewhere.
+  const locations = [...new Set([resolved.workspace.selectedPath, ...resolved.workspace.detectedPaths])];
+  const inventory = locations.flatMap(workspacePath => inspectLegacyInventory(workspacePath).map(row => ({
+    ...row, workspacePath, selectedWorkspace: workspacePath === resolved.workspace.selectedPath,
+  })));
+  return { ...resolved, schema: 'leerness.state-inspection/v1', ok: true,
+    inventory };
+}
+
+function formatStateInspection(report, language = 'en') {
+  const ko = language === 'ko';
+  const lines = [ko ? 'Leerness 상태 범위 진단 (읽기 전용)' : 'Leerness state scopes (read-only)',
+    `${ko ? '프로젝트' : 'Project'}: ${report.projectRoot}`,
+    `${ko ? '현재 저장소' : 'Current workspace'}: ${report.workspace.selectedPath} (${report.workspace.status})`,
+    ko ? '기존 배치 유지 · runtime 활성화 안 됨 · 마이그레이션 미구현'
+      : 'Legacy layout retained; runtime NOT activated; migration NOT implemented.', '',
+    ko ? '제안 경로 (생성/이동하지 않음):' : 'Proposed paths (nothing created or moved):'];
+  for (const value of Object.values(report.scopes)) {
+    const paths = value.proposedPaths || { path: value.proposedPath };
+    for (const [name, target] of Object.entries(paths)) {
+      lines.push(`  ${value.scope}${name === 'path' ? '' : ` / ${name}`}: ${target || (ko ? '사용 불가 (Git 없음)' : 'unavailable (non-Git)')}`);
+    }
+  }
+  lines.push('', ko ? '기존 상태 목록 (내용/하위 폴더는 읽지 않음):' : 'Legacy inventory (no contents or recursive traversal):');
+  for (const row of report.inventory) lines.push(`  ${path.basename(row.workspacePath)}/${row.relativePath}: ${row.metadata.status} -> ${row.proposedScope}`);
+  if (report.warnings.length) lines.push(`\n${ko ? '주의' : 'Warnings'}: ${report.warnings.join(', ')}`);
+  return lines.join('\n');
+}
+
+module.exports = { inspectState, formatStateInspection };

package/lib/state-inventory.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// This is an inventory of known legacy surfaces, NOT a migration manifest.
+// Mixed files contain human intent as well as execution state; preserve both.
+const SURFACES = Object.freeze([
+  ['cache/sessions', 'runtime', 'Worktree'],
+  ['cache/handoffs', 'runtime', 'Worktree'],
+  ['cache/agent-sessions', 'runtime-private-conversation', 'Worktree'],
+  ['cache/agent-runs', 'runtime', 'Worktree'],
+  ['cache/file-leases.json', 'physical-file-coordination', 'Worktree'],
+  ['state.json', 'runtime', 'Worktree'],
+  ['runs', 'mixed-run-evidence', 'Worktree + Immutable-Record'],
+  ['handoff', 'runtime', 'Worktree'],
+  ['execution-ledger.jsonl', 'mixed-run-evidence', 'Worktree + Immutable-Record'],
+  ['decisions.json', 'persistent-memory', 'Immutable-Record'],
+  ['decisions.md', 'mixed-memory-projection', 'Immutable-Record + Generated-View'],
+  ['lessons.json', 'persistent-memory', 'Immutable-Record'],
+  ['lessons.md', 'mixed-memory-projection', 'Immutable-Record + Generated-View'],
+  ['progress-tracker.md', 'mixed-task-authority', 'Project + Generated-View'],
+  ['current-state.md', 'mixed-project-context', 'Project + Generated-View'],
+  ['session-handoff.md', 'mixed-project-context', 'Project + Worktree + Generated-View'],
+  ['active-wakeups.json', 'mixed-intent-runtime', 'Project + Worktree'],
+  ['auto-resume-plan.json', 'mixed-intent-runtime', 'Project + Worktree'],
+  ['next-action-queue.json', 'mixed-intent-runtime', 'Project + Worktree'],
+  ['pre-wake-report.json', 'runtime', 'Worktree'],
+  ['last-handoff.json', 'runtime', 'Worktree'],
+  ['routing-log.json', 'runtime', 'Worktree'],
+]);
+
+function metadata(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    const kind = stat.isSymbolicLink() ? 'link' : stat.isDirectory() ? 'directory'
+      : stat.isFile() ? 'file' : 'special';
+    return { status: kind, sizeBytes: kind === 'file' ? stat.size : null, mtimeMs: stat.mtimeMs };
+  } catch (error) {
+    return { status: error.code === 'ENOENT' ? 'absent' : 'unreadable', errorCode: error.code || 'unknown' };
+  }
+}
+
+function inspectLegacyInventory(workspace) {
+  const cache = new Map();
+  const inspect = file => {
+    if (!cache.has(file)) cache.set(file, metadata(file));
+    return cache.get(file);
+  };
+  return SURFACES.map(([relativePath, classification, proposedScope]) => {
+    const parts = relativePath.split('/');
+    let parent = workspace;
+    let blocked = null;
+    for (const part of parts) {
+      const state = inspect(parent);
+      if (state.status !== 'directory') {
+        blocked = { status: state.status === 'absent' ? 'absent' : 'blocked',
+          parentStatus: state.status, blockedAt: parent };
+        break;
+      }
+      parent = path.join(parent, part);
+    }
+    const currentPath = path.join(workspace, ...parts);
+    return { relativePath, currentPath, classification, proposedScope,
+      migrationAvailable: false, metadata: blocked || inspect(currentPath) };
+  });
+}
+
+module.exports = { inspectLegacyInventory };

package/lib/state-paths.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const path = require('path');
+const crypto = require('crypto');
+const { StatePathError, canonicalDirectory, resolveGitTopology } = require('./state-git');
+const { inspectWorkspace, selectWorkspaceDirName, CANONICAL_WORKSPACE_DIR } = require('./workspace-dir');
+
+function scopeMap(projectPath, currentPath, git, projectKey) {
+  const privatePath = git
+    ? path.join(git.gitDir, 'leerness', 'projects', projectKey, 'runtime')
+    : path.join(projectPath, 'cache', 'state-runtime');
+  const commonPath = git ? path.join(git.gitCommonDir, 'leerness', 'control', 'projects', projectKey) : null;
+  return {
+    project: { scope: 'Project', currentPath, proposedPath: projectPath },
+    worktree: { scope: 'Worktree', proposedPath: privatePath, backend: git ? 'git-private' : 'project-local-fallback' },
+    commonControl: { scope: 'Common-Control', proposedPath: commonPath, available: !!git },
+    immutableRecord: { scope: 'Immutable-Record', proposedPaths: {
+      decisions: path.join(projectPath, 'memory', 'decisions'),
+      lessons: path.join(projectPath, 'memory', 'lessons'),
+      runs: path.join(projectPath, 'records', 'runs'),
+    } },
+    generatedView: { scope: 'Generated-View', proposedPaths: {
+      project: path.join(projectPath, 'generated'), worktree: path.join(privatePath, 'views'),
+    } },
+  };
+}
+
+function resolveStatePaths(root = process.cwd(), options = {}) {
+  const projectRoot = canonicalDirectory(root);
+  const git = resolveGitTopology(projectRoot, options);
+  const snapshot = inspectWorkspace(projectRoot);
+  if (snapshot.legacy.inspectionError || snapshot.canonical.inspectionError) {
+    throw new StatePathError('workspace_unreadable', 'Workspace metadata is unreadable; it was not treated as an empty store.');
+  }
+  const envValue = options.envValue === undefined
+    ? (options.env || process.env).LEERNESS_WORKSPACE_DIR : options.envValue;
+  const selectedName = selectWorkspaceDirName(snapshot, envValue);
+  const selected = selectedName === CANONICAL_WORKSPACE_DIR ? snapshot.canonical : snapshot.legacy;
+  const relative = git ? path.relative(git.worktreeRoot, projectRoot).split(path.sep).join('/') || '.' : '.';
+  const projectKey = `project-${crypto.createHash('sha256').update(relative).digest('hex')}`;
+  const status = !selected.exists ? 'absent' : selected.foreign ? 'foreign'
+    : selected.live ? 'live' : selected.substrateOnly ? 'substrate' : 'unrecognized';
+  const warnings = [];
+  if (!git) warnings.push('non_git_no_common_control');
+  if (status === 'foreign' || status === 'unrecognized') warnings.push('workspace_not_recognized');
+  if (selectedName !== CANONICAL_WORKSPACE_DIR) warnings.push('legacy_workspace_not_migrated');
+  if (snapshot.canonical.foreign && selectedName !== CANONICAL_WORKSPACE_DIR) warnings.push('canonical_workspace_foreign');
+  return {
+    schemaVersion: 1, schema: 'leerness.state-paths/v1',
+    activeLayout: 'legacy', runtimeActivated: false, migrationAvailable: false,
+    projectRoot, projectKey, projectRelativePath: relative, git,
+    workspace: { selectedName, selectedPath: selected.abs, status,
+      canonicalPath: snapshot.canonical.abs, legacyPresent: snapshot.legacy.exists,
+      detectedPaths: [snapshot.canonical, snapshot.legacy].filter(value => value.exists).map(value => value.abs) },
+    scopes: scopeMap(snapshot.canonical.abs, selected.abs, git, projectKey), warnings,
+  };
+}
+
+module.exports = { resolveStatePaths };

package/lib/workspace-dir.js

@@ -68,18 +68,20 @@ function _root(root) {
   return path.resolve(root || process.cwd());
 }
 
-function _entryNames(dir) {
-  try { return fs.readdirSync(dir); } catch { return []; }
-}
-
 function _inspectDir(root, name) {
   const abs = path.join(root, name);
   let stat = null;
-  try { stat = fs.lstatSync(abs); } catch {}
+  let inspectionError = null;
+  try { stat = fs.lstatSync(abs); }
+  catch (error) { if (error.code !== 'ENOENT') inspectionError = error.code || 'unknown'; }
   const exists = !!stat;
   const isSymbolicLink = !!stat && stat.isSymbolicLink();
   const isDirectory = !!stat && stat.isDirectory() && !stat.isSymbolicLink();
-  const entries = isDirectory ? _entryNames(abs) : [];
+  let entries = [];
+  if (isDirectory) {
+    try { entries = fs.readdirSync(abs); }
+    catch (error) { inspectionError = error.code || 'unknown'; }
+  }
   const markers = entries.filter((entry) => STRONG_MARKERS.has(entry));
   const live = markers.length > 0;
   const substrateEntries = name === CANONICAL_WORKSPACE_DIR
@@ -105,6 +107,9 @@ function _inspectDir(root, name) {
     substrateEntries,
     nonSubstrateEntries,
     foreign,
+    // Existing selection semantics are unchanged. Strict diagnostic consumers
+    // can distinguish unreadable metadata from an actually absent/empty store.
+    ...(inspectionError ? { inspectionError } : {}),
   };
 }
 
@@ -132,9 +137,10 @@ function validateWorkspaceDirName(value) {
   return v;
 }
 
-function resolveWorkspaceDirName(root, opts = {}) {
-  const state = inspectWorkspace(root);
-  const envValue = opts.envValue === undefined ? process.env.LEERNESS_WORKSPACE_DIR : opts.envValue;
+// Selection is pure so one read-only operation can reuse its inspection
+// snapshot without repeating directory reads. Callers that need a fresh
+// filesystem view should keep using resolveWorkspaceDirName below.
+function selectWorkspaceDirName(state, envValue) {
   const forced = validateWorkspaceDirName(envValue);
   for (const candidate of [state.legacy, state.canonical]) {
     if (candidate.isSymbolicLink) {
@@ -175,6 +181,12 @@ function resolveWorkspaceDirName(root, opts = {}) {
   return CANONICAL_WORKSPACE_DIR;
 }
 
+function resolveWorkspaceDirName(root, opts = {}) {
+  const state = inspectWorkspace(root);
+  const envValue = opts.envValue === undefined ? process.env.LEERNESS_WORKSPACE_DIR : opts.envValue;
+  return selectWorkspaceDirName(state, envValue);
+}
+
 function workspacePath(root, ...parts) {
   const resolvedRoot = _root(root);
   return path.join(resolvedRoot, resolveWorkspaceDirName(resolvedRoot), ...parts);
@@ -832,6 +844,7 @@ module.exports = {
   PROTECTED_GITIGNORE_LINES,
   WorkspaceDirectoryError,
   inspectWorkspace,
+  selectWorkspaceDirName,
   validateWorkspaceDirName,
   resolveWorkspaceDirName,
   workspacePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.36.185",
+  "version": "1.36.186",
   "description": "The AI-coding operations layer that makes \"done\" require evidence — persistent memory, evidence-gated completion checks, and clean handoffs for any AI agent (Claude Code, Codex, Cursor). State lives as plain files in your repo. CLI + MCP, 0 runtime dependencies.",
   "keywords": [
     "leerness",
@@ -48,13 +48,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/parent-detect-selftest-probe.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/i18n-priority-surface-probe.js && node ./scripts/i18n-next-cluster-probe.js && node ./scripts/provider-capacity-probe.js && node ./scripts/file-lease-probe.js && node ./scripts/role-agent-schema-probe.js && node ./scripts/role-store-loader-probe.js && node ./scripts/role-fallback-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js && npm run test:commands && npm run test:installed && node ./scripts/e2e.js",
-    "test:core": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/parent-detect-selftest-probe.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/i18n-priority-surface-probe.js && node ./scripts/i18n-next-cluster-probe.js && node ./scripts/provider-capacity-probe.js && node ./scripts/file-lease-probe.js && node ./scripts/role-agent-schema-probe.js && node ./scripts/role-store-loader-probe.js && node ./scripts/role-fallback-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js",
+    "test": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && npm run test:state-scopes && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/parent-detect-selftest-probe.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/i18n-priority-surface-probe.js && node ./scripts/i18n-next-cluster-probe.js && node ./scripts/provider-capacity-probe.js && node ./scripts/file-lease-probe.js && node ./scripts/role-agent-schema-probe.js && node ./scripts/role-store-loader-probe.js && node ./scripts/role-fallback-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js && npm run test:commands && npm run test:installed && node ./scripts/e2e.js",
+    "test:core": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && npm run test:state-scopes && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/parent-detect-selftest-probe.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/i18n-priority-surface-probe.js && node ./scripts/i18n-next-cluster-probe.js && node ./scripts/provider-capacity-probe.js && node ./scripts/file-lease-probe.js && node ./scripts/role-agent-schema-probe.js && node ./scripts/role-store-loader-probe.js && node ./scripts/role-fallback-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js",
     "test:commands": "node ./scripts/command-flags-probe.js && node ./scripts/dead-flags-probe.js && node ./scripts/false-claim-probe.js && node ./scripts/next-action-suggestion-probe.js && node ./scripts/claims-baseline-probe.js && node ./scripts/claims-baseline-concurrency-probe.js && node ./scripts/e2e-command-surface.js",
     "test:next-actions": "node ./scripts/next-action-suggestion-probe.js",
     "test:installed": "node ./scripts/installed-cleanroom-probe.js",
     "test:handoff": "node ./scripts/handoff-readonly-probe.js",
-    "test:fast": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/parent-detect-selftest-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/i18n-priority-surface-probe.js && node ./scripts/i18n-next-cluster-probe.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/mcp-presence-probe.js && node ./scripts/provider-capacity-probe.js && node ./scripts/file-lease-probe.js && node ./scripts/role-agent-schema-probe.js && node ./scripts/role-store-loader-probe.js && node ./scripts/role-fallback-probe.js && node ./scripts/false-claim-probe.js && node ./scripts/smoke.js",
+    "test:fast": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && npm run test:state-scopes && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/parent-detect-selftest-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/i18n-priority-surface-probe.js && node ./scripts/i18n-next-cluster-probe.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/mcp-presence-probe.js && node ./scripts/provider-capacity-probe.js && node ./scripts/file-lease-probe.js && node ./scripts/role-agent-schema-probe.js && node ./scripts/role-store-loader-probe.js && node ./scripts/role-fallback-probe.js && node ./scripts/false-claim-probe.js && node ./scripts/smoke.js",
     "test:false-claims": "node ./scripts/false-claim-probe.js",
     "test:workspace-lock-order": "node ./scripts/workspace-dir-lock-order-probe.js",
     "test:mcp-presence": "node ./scripts/mcp-presence-probe.js",
@@ -67,7 +67,8 @@
     "test:file-lease": "node ./scripts/file-lease-probe.js",
     "test:role-agent-schema": "node ./scripts/role-agent-schema-probe.js",
     "test:role-store-loader": "node ./scripts/role-store-loader-probe.js",
-    "test:role-fallback": "node ./scripts/role-fallback-probe.js"
+    "test:role-fallback": "node ./scripts/role-fallback-probe.js",
+    "test:state-scopes": "node ./scripts/workspace-selection-probe.js && node ./scripts/state-scopes-probe.js && node ./scripts/state-inspect-cli-probe.js"
   },
   "publishConfig": {
     "access": "public"

package/scripts/command-flags-probe.js

@@ -72,7 +72,7 @@ const catalog = run(['commands', '--json']);
 const catalogJson = json(catalog);
 const catalogRows = catalogJson?.categories ? Object.values(catalogJson.categories).flat() : [];
 check('commands --json returns the machine-readable catalog',
-  catalog.status === 0 && catalogJson?.totalCommands === 100 && catalogJson?.categories && !catalog.stderr,
+  catalog.status === 0 && catalogJson?.totalCommands === 101 && catalogJson?.categories && !catalog.stderr,
   catalog);
 check('commands totalCommands equals the category sum',
   catalogJson?.totalCommands === catalogRows.length,

package/scripts/false-claim-probe.js

@@ -403,6 +403,7 @@ try {
     ['preview', ['preview']],
     ['preview', ['preview', 'list']],
     ['preview', ['preview', 'show', 'P-0001']],
+    ['state', ['state', 'inspect']],
   ].every(([cmd, argv]) => _cliMutationClass(argv, cmd) === 'observation-only'));
   let readOnlyStatusesOk = true;
   for (const args of [
@@ -421,6 +422,7 @@ try {
     ['security-surface', '--json'],
     ['preview', '--json'],
     ['preview', 'list', '--json'],
+    ['state', 'inspect', '--json'],
   ]) {
     const readOnlyResult = run(root, args);
     if (readOnlyResult.status !== 0) readOnlyStatusesOk = false;
@@ -441,6 +443,7 @@ try {
       { args: ['identity', '--json'], status: 0 },
       { args: ['status', '--json'], status: 0 },
       { args: ['auto-update', 'status', '--json'], status: 0 },
+      { args: ['state', 'inspect', '--json'], status: 0 },
       // These surfaces currently require the canonical workspace to render;
       // on legacy input they may fail read-only, but must never migrate it.
       { args: ['dashboard', '--json'], status: 1 },

package/scripts/file-lease-probe.js

@@ -1054,7 +1054,7 @@ async function main() {
       && PU._requiredTier('npx --yes leerness lease acquire reports/release publish/status.js') === 'safe-write');
 
   check('command catalog and both help locales advertise exact-file lease',
-    catalog.status === 0 && catalogJson?.totalCommands === 100
+    catalog.status === 0 && catalogJson?.totalCommands === rows.length
       && rows.some(row => /^lease acquire\|release\|list\|check\b/.test(row.cmd))
       && /lease acquire\|release\|list\|check/.test(helpEn.stdout)
       && /leerness lease acquire\|release\|list\|check/.test(helpKo.stdout),