@agilno-tech/rivet 0.1.0-alpha.0

package/src/commands/verify.js

@@ -0,0 +1,171 @@
+import { CliError, EXIT_CODES } from '../cli/output.js';
+import { runQualityGates } from '../quality/runner.js';
+import { validateTraceability } from '../quality/traceability.js';
+
+function immutable(value) {
+  if (Array.isArray(value)) return Object.freeze(value.map(immutable));
+  if (value && typeof value === 'object') {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, immutable(child)])));
+  }
+  return value;
+}
+
+function snapshot(value, allowed, required) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Verification input is invalid.');
+  let keys;
+  try { keys = Reflect.ownKeys(value); } catch { throw new TypeError('Verification input is invalid.'); }
+  if (keys.some(key => typeof key !== 'string' || !allowed.includes(key))) throw new TypeError('Verification input is invalid.');
+  const result = Object.create(null);
+  for (const key of keys) {
+    let descriptor;
+    try { descriptor = Object.getOwnPropertyDescriptor(value, key); } catch { throw new TypeError('Verification input is invalid.'); }
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) throw new TypeError('Verification input is invalid.');
+    result[key] = descriptor.value;
+  }
+  if (required.some(key => !Object.hasOwn(result, key))) throw new TypeError('Verification input is invalid.');
+  return result;
+}
+
+function boundedArray(value, maximum, convert) {
+  try {
+    if (!Array.isArray(value)) throw new TypeError('Verification input is invalid.');
+    const length = Object.getOwnPropertyDescriptor(value, 'length')?.value;
+    if (!Number.isSafeInteger(length) || length < 0 || length > maximum
+      || Reflect.ownKeys(value).length !== length + 1) throw new TypeError('Verification input is invalid.');
+    const result = [];
+    for (let index = 0; index < length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) {
+        throw new TypeError('Verification input is invalid.');
+      }
+      result.push(convert(descriptor.value));
+    }
+    return Object.freeze(result);
+  } catch {
+    throw new TypeError('Verification input is invalid.');
+  }
+}
+
+function boundedString(value, maximum) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > maximum || value.includes('\0')) {
+    throw new TypeError('Verification input is invalid.');
+  }
+  return value;
+}
+
+function acceptanceCriterion(value) {
+  const criterion = snapshot(value, ['id', 'inScope'], ['id', 'inScope']);
+  if (typeof criterion.inScope !== 'boolean') throw new TypeError('Verification input is invalid.');
+  return Object.freeze({ id: boundedString(criterion.id, 100), inScope: criterion.inScope });
+}
+
+const APPROVAL_FIELDS = [
+  'id', 'approverId', 'approverPrincipal', 'subjectId', 'action', 'resource', 'policyId',
+  'decision', 'expiresAt', 'singleUse',
+];
+
+function immutableApproval(value) {
+  const approval = snapshot(value, APPROVAL_FIELDS, APPROVAL_FIELDS);
+  try {
+    if (!Object.isFrozen(value)) throw new TypeError('Verification input is invalid.');
+  } catch {
+    throw new TypeError('Verification input is invalid.');
+  }
+  for (const key of APPROVAL_FIELDS) {
+    if (key === 'singleUse') {
+      if (typeof approval[key] !== 'boolean') throw new TypeError('Verification input is invalid.');
+    } else {
+      boundedString(approval[key], key === 'resource' ? 1_024 : 100);
+    }
+  }
+  return value;
+}
+
+function manualReview(value) {
+  const review = snapshot(value, [
+    'id', 'acceptanceCriterion', 'expectedApproverId', 'approval',
+  ], ['id', 'acceptanceCriterion', 'expectedApproverId', 'approval']);
+  return Object.freeze({
+    id: boundedString(review.id, 64),
+    acceptanceCriterion: boundedString(review.acceptanceCriterion, 100),
+    expectedApproverId: boundedString(review.expectedApproverId, 64),
+    approval: immutableApproval(review.approval),
+  });
+}
+
+function callerTest(value) {
+  const test = snapshot(value, [
+    'id', 'status', 'acceptanceCriteria', 'gateId', 'resultPath', 'resultSha256',
+  ], ['id', 'status', 'acceptanceCriteria', 'gateId']);
+  const result = {
+    id: boundedString(test.id, 64),
+    status: boundedString(test.status, 32),
+    acceptanceCriteria: boundedArray(test.acceptanceCriteria, 128, criterion => boundedString(criterion, 100)),
+    gateId: boundedString(test.gateId, 64),
+  };
+  if (test.resultPath !== undefined) result.resultPath = boundedString(test.resultPath, 500);
+  if (test.resultSha256 !== undefined) result.resultSha256 = boundedString(test.resultSha256, 64);
+  return Object.freeze(result);
+}
+
+function traceabilityRequest(value) {
+  const request = snapshot(value, [
+    'subjectId', 'acceptanceCriteria', 'manualReviews', 'tests',
+  ], ['subjectId', 'acceptanceCriteria', 'manualReviews']);
+  return Object.freeze({
+    subjectId: boundedString(request.subjectId, 64),
+    acceptanceCriteria: boundedArray(request.acceptanceCriteria, 2_000, acceptanceCriterion),
+    manualReviews: boundedArray(request.manualReviews, 2_000, manualReview),
+    tests: request.tests === undefined
+      ? Object.freeze([])
+      : boundedArray(request.tests, 2_000, callerTest),
+  });
+}
+
+export async function verifyProject(input, options = {}) {
+  const request = snapshot(input, ['quality', 'traceability'], ['quality', 'traceability']);
+  const configured = snapshot(options, ['now', 'approvalRegistry', 'nowMs', 'gitClient'], ['gitClient']);
+  const traceRequest = traceabilityRequest(request.traceability);
+  const quality = await runQualityGates(request.quality, {
+    gitClient: configured.gitClient,
+    ...(configured.now === undefined ? {} : { now: configured.now }),
+  });
+  const traceability = validateTraceability({
+    subjectId: traceRequest.subjectId,
+    qualityRun: quality,
+    acceptanceCriteria: traceRequest.acceptanceCriteria,
+    manualReviews: traceRequest.manualReviews,
+  }, {
+    approvalRegistry: configured.approvalRegistry,
+    nowMs: configured.nowMs,
+  });
+  const gateBindingsValid = true;
+  const ok = quality.status === 'pass' && traceability.valid;
+  return immutable({
+    ok,
+    status: ok ? 'pass' : 'fail',
+    commitSha: quality.commitSha,
+    quality,
+    traceability,
+    gateBindingsValid,
+  });
+}
+
+export async function verifyCommand(parsed, dependencies = {}) {
+  if (!parsed || parsed.command !== 'verify' || parsed.subcommand !== null
+    || !Array.isArray(parsed.operands) || parsed.operands.length !== 0
+    || !parsed.flags || Reflect.ownKeys(parsed.flags).some(key => key !== 'json')) {
+    throw new CliError('Verify command options are invalid.', 'INVALID_INPUT');
+  }
+  const context = dependencies.quality;
+  if (!context || typeof context.requestFor !== 'function') {
+    throw new CliError('Quality verification is not configured.', 'MISSING_CONFIGURATION');
+  }
+  const request = await context.requestFor(Object.freeze({ command: 'verify' }));
+  const result = await verifyProject(request, context);
+  const exitCode = result.ok ? EXIT_CODES.SUCCESS : EXIT_CODES.FAILED_GATE;
+  if (parsed.flags.json) dependencies.output.json({ ok: result.ok, command: 'verify', result }, result.ok ? 'stdout' : 'stderr');
+  else if (result.ok) dependencies.output.log('Verification: pass.');
+  else dependencies.output.error('Verification: fail.');
+  return exitCode;
+}

package/src/commands/work.js

@@ -0,0 +1,220 @@
+import { parseAcceptanceCriteriaText } from '../work-request/contract.js';
+import * as filesystem from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { TextDecoder } from 'node:util';
+
+import { immutableJson } from '../clients/contract.js';
+import { CliError, EXIT_CODES } from '../cli/output.js';
+
+const RUN_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const MAX_DECOMPOSITION_BYTES = 128 * 1024;
+const MAX_INLINE_JSON_BYTES = 64 * 1024;
+const SUBCOMMANDS = new Set(['propose', 'prepare', 'next', 'status', 'submit', 'verify', 'recover']);
+
+function fail(message, code = 'INVALID_INPUT') { throw new CliError(message, code); }
+
+function supplementalCriteria(value) {
+  try { return parseAcceptanceCriteriaText(value); }
+  catch { fail('Acceptance criteria must be nonempty bounded text, one criterion per line, without duplicates, control characters or credentials.'); }
+}
+
+function absolute(value, label) {
+  if (typeof value !== 'string' || value.length < 2 || value.length > 4096 || !isAbsolute(value)
+    || resolve(value) !== value || /[\u0000\r\n]/.test(value)) fail(`${label} is invalid.`);
+  return value;
+}
+
+function runId(value) {
+  if (typeof value !== 'string' || value.length > 64 || !RUN_ID.test(value)) fail('Work run ID is invalid.');
+  return value;
+}
+
+function version(value, label) {
+  if (typeof value !== 'string' || !/^[1-9][0-9]*$/.test(value)) fail(`${label} is invalid.`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) fail(`${label} is invalid.`);
+  return parsed;
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.nlink === right.nlink;
+}
+
+function readJson(project, path, fs, label) {
+  const target = absolute(path, `${label} path`);
+  const contained = relative(project, target);
+  if (!contained || contained === '..' || contained.startsWith(`..${sep}`) || isAbsolute(contained)) {
+    fail(`${label} must stay within the project.`);
+  }
+  let ancestor = project;
+  for (const part of contained.split(sep).slice(0, -1)) {
+    ancestor = join(ancestor, part);
+    let status;
+    try { status = fs.lstatSync(ancestor); } catch { fail(`${label} has an unsafe ancestor.`, 'REPOSITORY_CONFLICT'); }
+    if (status.isSymbolicLink() || !status.isDirectory()) fail(`${label} has an unsafe ancestor.`, 'REPOSITORY_CONFLICT');
+  }
+  let descriptor;
+  try {
+    const before = fs.lstatSync(target);
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1
+      || before.size < 1 || before.size > MAX_DECOMPOSITION_BYTES) fail(`${label} must be a bounded regular file.`);
+    descriptor = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const opened = fs.fstatSync(descriptor);
+    if (!sameFile(before, opened)) fail(`${label} changed during validation.`, 'REPOSITORY_CONFLICT');
+    const bytes = fs.readFileSync(descriptor);
+    const after = fs.fstatSync(descriptor);
+    if (!sameFile(opened, after) || bytes.byteLength !== after.size) fail(`${label} changed during validation.`, 'REPOSITORY_CONFLICT');
+    let source;
+    try { source = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail(`${label} is not valid UTF-8.`); }
+    try { return JSON.parse(source); } catch { fail(`${label} is not valid JSON.`); }
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    fail(`${label} could not be read.`, 'REPOSITORY_CONFLICT');
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+function inputJson(project, flags, name, fs, label) {
+  const inlineName = `${name}-json`;
+  const selected = [name, inlineName].filter(key => flags[key] !== undefined);
+  if (selected.length !== 1) fail(`${label} requires exactly one of --${name} or --${inlineName}.`);
+  if (selected[0] === name) return readJson(project, flags[name], fs, label);
+  const source = flags[inlineName];
+  if (typeof source !== 'string' || !source.length || Buffer.byteLength(source, 'utf8') > MAX_INLINE_JSON_BYTES) {
+    fail(`${label} inline JSON must be between 1 and ${MAX_INLINE_JSON_BYTES} UTF-8 bytes. Use --${name} for larger input.`);
+  }
+  try { return JSON.parse(source); } catch { fail(`${label} is not valid JSON.`); }
+}
+
+function service(dependencies, name, method) {
+  const value = dependencies?.[name];
+  if (!value || typeof value !== 'object' || typeof value[method] !== 'function') {
+    fail('Host work execution is not configured.', 'MISSING_CONFIGURATION');
+  }
+  return value;
+}
+
+async function invoke(target, method, input) {
+  try { return await target[method](input); }
+  catch (error) {
+    if (error instanceof CliError) throw error;
+    const code = String(error?.code ?? '');
+    if (code === 'EPERM' || code === 'EACCES') {
+      throw new CliError('Rivet lacks filesystem permission for this host operation. Request approval for this exact command through your harness, including private Git state and isolated worktree access. If approval is unavailable, use an approved interactive session or the terminal workflow.', 'REPOSITORY_CONFLICT', { cause: error });
+    }
+    const publicCode = code === 'ERR_INTEGRATION_INPUT' ? 'INVALID_INPUT'
+      : code.startsWith('ERR_INTEGRATION_') ? 'PROVIDER_UNAVAILABLE'
+      : code === 'ERR_HOST_EXECUTION_VERIFICATION_FAILED' ? 'FAILED_GATE'
+      : code === 'ERR_HOST_EXECUTION_REPOSITORY' || code.startsWith('ERR_HOST_RUN_') || code.includes('STATE_CONFLICT') || code.includes('VERSION') || code.startsWith('ERR_GIT_')
+      ? 'REPOSITORY_CONFLICT'
+      : code.includes('INVALID') ? 'INVALID_INPUT'
+        : code.includes('MISSING') || code.includes('CONFIGURATION') ? 'MISSING_CONFIGURATION' : 'INTERNAL_ERROR';
+    throw new CliError(error?.safeMessage ?? 'Host work execution failed.', publicCode, { cause: error });
+  }
+}
+
+function emit(parsed, dependencies, result) {
+  const safe = immutableJson(result);
+  if (parsed.flags.json) dependencies.output.json({ ok: true, command: 'work', subcommand: parsed.subcommand, result: safe });
+  else dependencies.output.log(JSON.stringify(safe, null, 2));
+  return EXIT_CODES.SUCCESS;
+}
+
+function proposalInput(parsed, dependencies) {
+  if (parsed.operands.length !== 0) fail('Work propose does not accept a run ID.');
+  const project = absolute(parsed.flags.project, 'Work project');
+  const selectors = ['request', 'request-text', 'ticket', 'host-context-json'].filter(key => parsed.flags[key] !== undefined);
+  if (selectors.length !== 1) {
+    fail('Work propose requires one request source.');
+  }
+  const selected = selectors[0];
+  let source;
+  if (selected === 'request') source = { kind: 'file', value: absolute(parsed.flags.request, 'Work request path') };
+  else if (selected === 'request-text') source = { kind: 'inline', value: parsed.flags['request-text'] };
+  else if (selected === 'host-context-json') {
+    source = { kind: 'host-observation', value: inputJson(project, parsed.flags, 'host-context', dependencies.fs ?? filesystem, 'Host context') };
+  } else source = { kind: 'ticket', value: parsed.flags.ticket };
+  if (selected !== 'ticket' && parsed.flags['acceptance-criteria'] !== undefined) fail('--acceptance-criteria requires --ticket.');
+  if (selected !== 'ticket' && parsed.flags.tracker !== undefined) fail('--tracker is only valid with --ticket.');
+  return Object.freeze({
+    project,
+    source: Object.freeze(source),
+    client: 'host',
+    ...(parsed.flags['acceptance-criteria'] === undefined ? {} : { userAcceptanceCriteria: supplementalCriteria(parsed.flags['acceptance-criteria']) }),
+    decomposition: inputJson(project, parsed.flags, 'decomposition', dependencies.fs ?? filesystem, 'Work decomposition'),
+    ...(parsed.flags.tracker === undefined ? {} : { tracker: parsed.flags.tracker }),
+  });
+}
+
+function lifecycleInput(parsed, versionFlag = null) {
+  const hasRunFlag = parsed.flags.run !== undefined;
+  if (parsed.operands.length !== (hasRunFlag ? 0 : 1)) fail('Use one run selector: --run or a positional run ID.');
+  const input = { project: absolute(parsed.flags.project, 'Work project'), runId: runId(hasRunFlag ? parsed.flags.run : parsed.operands[0]) };
+  if (versionFlag) input[versionFlag.output] = version(parsed.flags[versionFlag.flag], `--${versionFlag.flag}`);
+  return Object.freeze(input);
+}
+
+export async function workCommand(parsed, dependencies) {
+  if (!parsed || parsed.command !== 'work' || !SUBCOMMANDS.has(parsed.subcommand)
+    || !Array.isArray(parsed.operands) || !parsed.flags || typeof parsed.flags !== 'object') fail('Work command is invalid.');
+  const allowedFlags = {
+    propose: ['project', 'request', 'request-text', 'host-context-json', 'ticket', 'tracker', 'acceptance-criteria', 'decomposition', 'decomposition-json', 'json'],
+    prepare: ['project', 'expected-version', 'json'],
+    next: ['project', 'expected-runtime-version', 'json'],
+    status: ['project', 'json'],
+    recover: ['project', 'json'],
+    submit: ['project', 'expected-runtime-version', 'action', 'action-json', 'result', 'result-json', 'json'],
+    verify: ['project', 'expected-version', 'expected-runtime-version', 'json'],
+  };
+  if (parsed.subcommand !== 'propose') allowedFlags[parsed.subcommand].push('run');
+  if (Object.keys(parsed.flags).some(key => !allowedFlags[parsed.subcommand].includes(key))) {
+    fail(`Work ${parsed.subcommand} options are invalid.`);
+  }
+  if (parsed.subcommand === 'recover') {
+    const result = immutableJson(await invoke(service(dependencies, 'work', 'recover'), 'recover', lifecycleInput(parsed)));
+    const ok = result.status === 'recovered';
+    if (parsed.flags.json) dependencies.output.json({ ok, command: 'work', subcommand: 'recover', result }, ok ? 'stdout' : 'stderr');
+    else (ok ? dependencies.output.log : dependencies.output.error)(JSON.stringify(result, null, 2));
+    return ok ? EXIT_CODES.SUCCESS : EXIT_CODES.REPOSITORY_CONFLICT;
+  }
+  if (parsed.subcommand === 'propose') {
+    return emit(parsed, dependencies, await invoke(
+      service(dependencies, 'feature', 'propose'), 'propose', proposalInput(parsed, dependencies),
+    ));
+  }
+  if (parsed.subcommand === 'prepare') {
+    return emit(parsed, dependencies, await invoke(service(dependencies, 'work', 'prepare'), 'prepare', lifecycleInput(
+      parsed, { flag: 'expected-version', output: 'expectedRunVersion' },
+    )));
+  }
+  if (parsed.subcommand === 'next') {
+    return emit(parsed, dependencies, await invoke(service(dependencies, 'work', 'nextAction'), 'nextAction', lifecycleInput(
+      parsed, { flag: 'expected-runtime-version', output: 'expectedRuntimeVersion' },
+    )));
+  }
+  if (parsed.subcommand === 'status') {
+    return emit(parsed, dependencies, await invoke(
+      service(dependencies, 'work', 'status'), 'status', lifecycleInput(parsed),
+    ));
+  }
+  if (parsed.subcommand === 'submit') {
+    const input = lifecycleInput(parsed, { flag: 'expected-runtime-version', output: 'expectedRuntimeVersion' });
+    const fs = dependencies.fs ?? filesystem;
+    return emit(parsed, dependencies, await invoke(service(dependencies, 'work', 'submitResult'), 'submitResult', Object.freeze({
+      ...input,
+      action: inputJson(input.project, parsed.flags, 'action', fs, 'Work action'),
+      result: inputJson(input.project, parsed.flags, 'result', fs, 'Work result'),
+    })));
+  }
+  if (parsed.subcommand === 'verify') {
+    const input = lifecycleInput(parsed, { flag: 'expected-version', output: 'expectedRunVersion' });
+    return emit(parsed, dependencies, await invoke(service(dependencies, 'work', 'verify'), 'verify', Object.freeze({
+      ...input,
+      expectedRuntimeVersion: version(parsed.flags['expected-runtime-version'], '--expected-runtime-version'),
+    })));
+  }
+  fail(`Work ${parsed.subcommand} is invalid.`);
+}
+
+export { MAX_DECOMPOSITION_BYTES };

package/src/commands/worktrees.js

@@ -0,0 +1,52 @@
+import { createReservedWorktree, recoverStaleWorktree, verifyReservedWorktree } from '../git/worktrees.js';
+import { reconcileWorktree } from '../git/reconcile.js';
+
+function captureRequest(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('Invalid worktree command request');
+  const keys = Reflect.ownKeys(input);
+  if (keys.some(key => typeof key !== 'string')) throw new TypeError('Invalid worktree command request');
+  const result = Object.create(null);
+  try {
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable) throw new TypeError('Invalid worktree command request');
+      result[key] = input[key];
+    }
+  } catch {
+    throw new TypeError('Invalid worktree command request');
+  }
+  if (typeof result.action !== 'string') throw new TypeError('Invalid worktree command request');
+  return Object.freeze(result);
+}
+
+export async function runWorktreeCommand(input, dependencies = {}) {
+  const request = captureRequest(input);
+  const options = Object.freeze({
+    gitClient: dependencies.gitClient,
+    nowMs: dependencies.nowMs,
+  });
+  if (request.action === 'create') {
+    const { action: _action, ...payload } = request;
+    return createReservedWorktree(payload, options);
+  }
+  if (request.action === 'inspect') {
+    const { action: _action, ...payload } = request;
+    return verifyReservedWorktree(payload, options);
+  }
+  if (request.action === 'reconcile') {
+    const { action: _action, ...payload } = request;
+    return reconcileWorktree(payload, options);
+  }
+  if (request.action === 'recover') {
+    const { action: _action, ...payload } = request;
+    return recoverStaleWorktree(payload, dependencies);
+  }
+  throw new TypeError('Invalid worktree command action');
+}
+
+export function formatWorktreeResult(result, options = {}) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) throw new TypeError('Invalid worktree command result');
+  if (options.json === true) return JSON.stringify(result);
+  const status = typeof result.status === 'string' ? result.status : result.reservation?.status;
+  return `Worktree: ${status ?? 'unknown'}.`;
+}

package/src/config/command-readiness.js

@@ -0,0 +1,218 @@
+import * as filesystem from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { commandToolKey, compileProjectDependencies, compileQualitySteps } from './commands.js';
+
+const MAX_MANIFEST_BYTES = 256 * 1024;
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function within(root, candidate) {
+  const path = relative(root, candidate);
+  return path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`));
+}
+
+function runnerManager(runner) {
+  return runner.toLowerCase().replace(/\.(?:cmd|exe)$/, '');
+}
+
+function directoryFor(root, cwd, fs) {
+  let current = root;
+  for (const component of cwd === '.' ? [] : cwd.split('/')) {
+    current = join(current, component);
+    const before = fs.lstatSync(current, { throwIfNoEntry: false });
+    if (!before?.isDirectory() || before.isSymbolicLink()) return { status: 'unsafe-directory' };
+    const canonical = fs.realpathSync(current);
+    const after = fs.statSync(canonical);
+    if (!within(root, canonical)) return { status: 'unsafe-directory' };
+    if (!sameIdentity(before, after)) return { status: 'directory-identity-changed' };
+  }
+  const metadata = fs.lstatSync(current, { throwIfNoEntry: false });
+  if (!metadata?.isDirectory() || metadata.isSymbolicLink()) return { status: 'unsafe-directory' };
+  const canonical = fs.realpathSync(current);
+  const canonicalMetadata = fs.statSync(canonical);
+  if (!within(root, canonical)) return { status: 'unsafe-directory' };
+  if (!sameIdentity(metadata, canonicalMetadata)) return { status: 'directory-identity-changed' };
+  return { status: 'ready', path: canonical, identity: metadata };
+}
+
+function directoryIdentityStatus(directory, fs) {
+  try {
+    const current = fs.lstatSync(directory.path, { throwIfNoEntry: false });
+    if (!current?.isDirectory() || current.isSymbolicLink()
+      || !sameIdentity(directory.identity, current)) return 'directory-identity-changed';
+    const canonical = fs.realpathSync(directory.path);
+    const canonicalMetadata = fs.statSync(canonical);
+    return canonical === directory.path && sameIdentity(directory.identity, canonicalMetadata)
+      ? 'ready' : 'directory-identity-changed';
+  } catch {
+    return 'directory-identity-changed';
+  }
+}
+
+function readManifest(directory, fs) {
+  const path = join(directory.path, 'package.json');
+  const before = fs.lstatSync(path, { throwIfNoEntry: false });
+  if (!before) return { status: 'missing-manifest' };
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_MANIFEST_BYTES) {
+    return { status: 'unsafe-manifest' };
+  }
+  let descriptor;
+  try {
+    descriptor = fs.openSync(path, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const opened = fs.fstatSync(descriptor);
+    if (!opened.isFile() || !sameIdentity(before, opened) || opened.size > MAX_MANIFEST_BYTES) {
+      return { status: 'manifest-identity-changed' };
+    }
+    const bytes = Buffer.alloc(MAX_MANIFEST_BYTES + 1);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const count = fs.readSync(descriptor, bytes, offset, bytes.length - offset, null);
+      if (!Number.isSafeInteger(count) || count < 0 || count > bytes.length - offset) return { status: 'unsafe-manifest' };
+      if (count === 0) break;
+      offset += count;
+    }
+    if (offset > MAX_MANIFEST_BYTES) return { status: 'unsafe-manifest' };
+    const after = fs.fstatSync(descriptor);
+    const current = fs.lstatSync(path, { throwIfNoEntry: false });
+    if (!current?.isFile() || current.isSymbolicLink() || !sameIdentity(opened, after)
+      || !sameIdentity(after, current) || after.size !== current.size) return { status: 'manifest-identity-changed' };
+    let parsed;
+    try {
+      parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, offset)));
+    } catch { return { status: 'invalid-manifest' }; }
+    return { status: 'ready', manifest: parsed };
+  } catch {
+    return { status: 'unsafe-manifest' };
+  } finally {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch {}
+    }
+  }
+}
+
+function frozen(value) {
+  if (Array.isArray(value)) return Object.freeze(value.map(frozen));
+  if (value && typeof value === 'object') {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, frozen(child)])));
+  }
+  return value;
+}
+
+function localExecutableStatus(root, cwd, runner, fs) {
+  if (!runner.startsWith('./')) return 'external';
+  let current = root;
+  const parts = [...(cwd === '.' ? [] : cwd.split('/')), ...runner.slice(2).split('/')];
+  try {
+    for (const part of parts.slice(0, -1)) {
+      current = join(current, part);
+      const metadata = fs.lstatSync(current, { throwIfNoEntry: false });
+      if (!metadata) return 'missing';
+      if (!metadata.isDirectory() || metadata.isSymbolicLink() || fs.realpathSync(current) !== current) return 'unsafe';
+    }
+    return fs.lstatSync(join(current, parts.at(-1)), { throwIfNoEntry: false }) ? 'exists' : 'missing';
+  } catch { return 'unsafe'; }
+}
+
+function providedExecutable(dependencies, cwd, runner) {
+  return runner.startsWith('./') && dependencies?.provides.includes(`./${cwd === '.' ? '' : `${cwd}/`}${runner.slice(2)}`);
+}
+
+function dependencyReadiness(root, rootSafe, dependencies, tools, fs) {
+  if (!dependencies) return undefined;
+  const inputs = dependencies.inputs.map(path => {
+    let status = 'unsafe-input';
+    try {
+      const directory = directoryFor(root, dirname(path), fs);
+      const file = join(root, path);
+      const metadata = fs.lstatSync(file, { throwIfNoEntry: false });
+      if (!metadata) status = 'missing-input';
+      else if (rootSafe && directory.status === 'ready' && metadata.isFile() && !metadata.isSymbolicLink()
+        && metadata.nlink === 1 && metadata.size <= 4 * 1024 * 1024 && fs.realpathSync(file) === file
+        && sameIdentity(metadata, fs.statSync(file)) && directoryIdentityStatus(directory, fs) === 'ready') status = 'ready';
+    } catch {}
+    return { path, status };
+  });
+  let precedingStep = false;
+  const steps = dependencies.steps.map(step => {
+    let status = rootSafe ? directoryFor(root, step.cwd, fs).status : 'unsafe-directory';
+    if (status === 'ready') {
+      if (tools[commandToolKey(step.argv[0], step.cwd)]?.runtimeResolved === true) status = 'ready';
+      else if (precedingStep && providedExecutable(dependencies, step.cwd, step.argv[0])
+        && localExecutableStatus(root, step.cwd, step.argv[0], fs) === 'missing') status = 'preparation-required';
+      else status = 'tool-unavailable';
+    }
+    if (status === 'ready') precedingStep = true;
+    return { ...step, status, available: status === 'ready' };
+  });
+  const preparationReady = rootSafe && inputs.every(input => input.status === 'ready')
+    && steps.every(step => ['ready', 'preparation-required'].includes(step.status));
+  return { preparationReady, inputs, steps };
+}
+
+export function inspectCommandReadiness(projectRoot, config, options = {}) {
+  const fs = options.fs ?? filesystem;
+  const tools = options.tools ?? {};
+  const lexicalRoot = resolve(projectRoot);
+  const rootMetadata = fs.lstatSync(lexicalRoot, { throwIfNoEntry: false });
+  const root = rootMetadata?.isDirectory() && !rootMetadata.isSymbolicLink()
+    ? fs.realpathSync(lexicalRoot) : lexicalRoot;
+  const rootSafe = rootMetadata?.isDirectory() && !rootMetadata.isSymbolicLink()
+    && sameIdentity(rootMetadata, fs.statSync(root));
+  const expectedManager = config.project.stack.packageManager;
+  const dependencies = compileProjectDependencies(config.project);
+  const dependencyStatus = dependencyReadiness(root, rootSafe, dependencies, tools, fs);
+  const steps = compileQualitySteps(config).map(step => {
+    const direct = step.execution === 'argv';
+    const manager = direct ? step.argv[0] : runnerManager(step.argv[0]);
+    let status = 'ready';
+    if (!rootSafe) status = 'unsafe-directory';
+    else if (config.project.schemaVersion === 2 && manager !== expectedManager) status = 'manager-mismatch';
+    else if (direct ? tools[commandToolKey(manager, step.cwd)]?.runtimeResolved !== true
+      : tools[manager]?.present !== true || tools[manager]?.supported !== true
+      || tools[manager]?.runtimeResolved === false) status = 'tool-unavailable';
+    else {
+      const directory = directoryFor(root, step.cwd, fs);
+      status = directory.status;
+      if (status === 'ready') {
+        status = directoryIdentityStatus(directory, fs);
+        const manifest = status === 'ready' && !direct ? readManifest(directory, fs) : null;
+        if (manifest) status = manifest.status;
+        const finalDirectoryStatus = directoryIdentityStatus(directory, fs);
+        if (finalDirectoryStatus !== 'ready') status = finalDirectoryStatus;
+        if (status === 'ready' && manifest) {
+          const scripts = manifest.manifest?.scripts;
+          status = scripts && typeof scripts === 'object' && !Array.isArray(scripts)
+            && typeof scripts[step.argv[2]] === 'string' ? 'ready' : 'missing-script';
+        }
+      }
+    }
+    if (direct && status === 'tool-unavailable' && dependencyStatus?.preparationReady
+      && directoryFor(root, step.cwd, fs).status === 'ready'
+      && providedExecutable(dependencies, step.cwd, manager)
+      && localExecutableStatus(root, step.cwd, manager, fs) === 'missing') status = 'preparation-required';
+    return {
+      id: step.id,
+      logicalId: step.logicalId,
+      cwd: step.cwd,
+      argv: step.argv,
+      script: direct ? null : step.argv[2],
+      manager,
+      required: step.required,
+      status,
+      available: status === 'ready',
+    };
+  });
+  return frozen({
+    ready: steps.filter(step => step.required).every(step => step.status === 'ready'),
+    allReady: steps.every(step => step.status === 'ready'),
+    preparationReady: steps.filter(step => step.required).every(step => ['ready', 'preparation-required'].includes(step.status))
+      && (!dependencyStatus || dependencyStatus.preparationReady),
+    ...(dependencyStatus ? { dependencies: dependencyStatus } : {}),
+    steps,
+  });
+}
+
+export { MAX_MANIFEST_BYTES as MAX_COMMAND_MANIFEST_BYTES };