@thebackstoryis/engineering-with-ai 0.2.9

package/src/runtime/policy-workspace.mjs

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { loadProjectConfig } from '../project.mjs';
+import { readPolicyBaselineStatus } from '../organisation-policies.mjs';
+import {
+  confirmPolicyFacts, evaluatePolicyDesign, readPolicyEvaluationStatus,
+  recordPolicyException, recordPolicyReview,
+} from '../policy-design-gates.mjs';
+import { POLICY_DESIGN_AUTHORITY_NOTICE } from '../policy-gate-integration.mjs';
+import { listRuntimeIntents, readRuntimeIntent } from './intents.mjs';
+import { selectPolicyPersonas } from './persona-engagement.mjs';
+import { publishLifecycleEventSafely } from './lifecycle-hooks.mjs';
+
+const actions = Object.freeze({
+  facts: { event: 'ewai.policy.facts.confirmed', allowed: ['intentReference', 'expectedRevision', 'expectedProposalDigest', 'confirmed', 'authority', 'confirmedBy', 'decisions'] },
+  evaluation: { event: 'ewai.policy.evaluation.recorded', allowed: ['intentReference', 'expectedIntentRevision', 'expectedPolicyDigest', 'expectedFactsDigest'] },
+  review: { event: 'ewai.policy.review.recorded', allowed: ['intentReference', 'evaluationDigest', 'ruleId', 'authority', 'reviewedBy', 'reviewerRole', 'decision', 'rationale', 'evidence', 'controls'] },
+  exception: { event: 'ewai.policy.exception.recorded', allowed: ['intentReference', 'evaluationDigest', 'ruleId', 'authority', 'approvedBy', 'owner', 'reviewerRole', 'scope', 'rationale', 'compensatingControls', 'evidence', 'expiresAt'] },
+});
+
+export { POLICY_DESIGN_AUTHORITY_NOTICE };
+
+function exact(input, allowed, label) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error(`${label} must be an object`);
+  const unsupported = Object.keys(input).filter((key) => !allowed.includes(key));
+  if (unsupported.length) throw new Error(`${label} contains unsupported field(s): ${unsupported.join(', ')}`);
+  return input;
+}
+
+function safeReference(value) {
+  const text = String(value ?? '').trim();
+  const segments = text.split(/[\\/]+/);
+  return isAbsolute(text) || text.includes('/private/') || text.includes('\\') || segments.includes('..')
+    ? '[redacted-local-reference]'
+    : text.slice(0, 500);
+}
+
+function safeFacts(record) {
+  if (!record) return null;
+  return {
+    revision: record.revision, intent: record.intent, policyDigest: record.policyDigest,
+    proposalDigest: record.proposalDigest, factsDigest: record.factsDigest,
+    facts: (record.facts ?? []).map((fact) => ({
+      id: fact.id, dimension: fact.dimension, values: fact.values, rationale: fact.rationale,
+      provenance: { ...fact.provenance, reference: safeReference(fact.provenance?.reference), ...(fact.provenance?.persona ? { persona: fact.provenance.persona } : {}) },
+    })),
+    confirmation: record.confirmation,
+    authority: record.authority,
+  };
+}
+
+function factsRecord(projectRoot, reference) {
+  const { paths } = loadProjectConfig(projectRoot);
+  const path = resolve(paths.specsRoot, '3.Evidence/policy/facts', `${reference}.json`);
+  if (!existsSync(path)) return null;
+  try { return safeFacts(JSON.parse(readFileSync(path, 'utf8'))); } catch { return null; }
+}
+
+function evaluationRecord(projectRoot, reference, expectedDigest) {
+  if (!expectedDigest) return null;
+  const { paths } = loadProjectConfig(projectRoot);
+  const path = resolve(paths.specsRoot, '3.Evidence/policy/evaluations', `${reference}.json`);
+  if (!existsSync(path)) return null;
+  try {
+    const record = JSON.parse(readFileSync(path, 'utf8'));
+    return record.schema === 'ewai.policy-design-evaluation/v1' && record.evaluationDigest === expectedDigest
+      ? record
+      : null;
+  } catch { return null; }
+}
+
+function authority() {
+  return { advisory: true, designTimeOnly: true, productionEnforcement: false, productionCodeExecution: false, buildApproved: false, manualQaApproved: false, complianceCertified: false, releaseApproved: false, residualRiskAccepted: false };
+}
+
+function chosenIntent(projectRoot, reference = '') {
+  if (reference) return readRuntimeIntent(projectRoot, reference);
+  return listRuntimeIntents(projectRoot)[0] ?? null;
+}
+
+export function readPolicyWorkspace(projectRoot, options = {}) {
+  if (!['business', 'technical'].includes(options.mode ?? 'business')) throw new Error('Policy workspace mode must be business or technical');
+  const intent = chosenIntent(projectRoot, String(options.intentReference ?? ''));
+  const baseline = readPolicyBaselineStatus(projectRoot);
+  const reference = intent?.id ?? '';
+  const policyStatus = reference && baseline.status !== 'not-configured'
+    ? readPolicyEvaluationStatus(projectRoot, reference, options)
+    : { schema: 'ewai.policy-evaluation-status/v1', status: baseline.status, blocking: false, controls: [] };
+  const evaluation = reference ? evaluationRecord(projectRoot, reference, policyStatus.evaluationDigest) : null;
+  const policy = {
+    ...policyStatus,
+    matchedRules: evaluation?.matchedRules ?? [],
+    requiredReviews: evaluation?.requiredReviews ?? [],
+    unmatchedPolicies: evaluation?.unmatchedPolicies ?? [],
+  };
+  const facts = reference ? factsRecord(projectRoot, reference) : null;
+  const dimensions = [...new Set((facts?.facts ?? []).map(({ dimension }) => dimension))];
+  const engagement = selectPolicyPersonas({ stage: options.stage ?? 'facts', dimensions, context: { intent: reference, status: policy.status } }, options.personas ?? []);
+  const activePersonas = engagement.activePersonas.map(({ id, name, tier, category, description, matchedSignals, engagementReason }) => ({ id, name, tier, category, description, matchedSignals, engagementReason, advisory: true }));
+  const status = policy.status ?? baseline.status;
+  const blocking = baseline.status === 'not-configured' ? false : policy.blocking !== false;
+  const shared = { intentReference: reference, status, blocking };
+  return {
+    schema: 'ewai.policy-workspace/v1', ...shared,
+    baseline: { status: baseline.status, enabled: baseline.enabled, blocking: baseline.blocking, effectiveDigest: baseline.effectiveDigest ?? null, policyCount: baseline.policyCount ?? 0, ruleCount: baseline.ruleCount ?? 0, approvedBy: baseline.approvedBy ?? null, approvedAt: baseline.approvedAt ?? null },
+    facts, policy, activePersonas, personaAvailability: { baseline: engagement.baseline, premium: engagement.premium },
+    views: {
+      business: { ...shared, outcome: status, nextActions: blocking ? ['Resolve the current policy evidence and named decisions.'] : [], controls: (policy.controls ?? []).map(({ ruleId, id, title, description }) => ({ ruleId, id, title, description })) },
+      technical: { ...shared, policyDigest: policy.policyDigest ?? baseline.effectiveDigest ?? null, factsDigest: policy.factsDigest ?? null, evaluationDigest: policy.evaluationDigest ?? null, matchedRules: policy.matchedRules ?? [], controls: policy.controls ?? [] },
+    },
+    notices: [POLICY_DESIGN_AUTHORITY_NOTICE], authority: authority(),
+  };
+}
+
+export function policyLifecycleEvent(projectRoot, kind, record, options = {}) {
+  const definition = actions[kind];
+  if (!definition) throw new Error(`Unsupported policy lifecycle event: ${kind}`);
+  if (!record || typeof record !== 'object') throw new Error('Policy lifecycle event requires a persisted policy record');
+  const reference = record.intentReference ?? record.intent?.reference;
+  const revision = record.evaluationDigest ?? record.factsDigest ?? record.decisionDigest;
+  if (!reference || !revision) throw new Error('Policy lifecycle event requires a persisted record identity');
+  const status = readPolicyEvaluationStatus(projectRoot, reference);
+  const persisted = kind === 'facts'
+    ? factsRecord(projectRoot, reference)?.factsDigest === record.factsDigest
+    : kind === 'evaluation'
+      ? status.evaluationDigest === record.evaluationDigest
+      : kind === 'review'
+        ? status.reviews?.some(({ decisionDigest }) => decisionDigest === record.decisionDigest)
+        : status.exceptions?.some(({ decisionDigest }) => decisionDigest === record.decisionDigest);
+  if (!persisted) throw new Error('Policy lifecycle event requires the exact persisted policy record');
+  const personas = options.personas ?? [];
+  return publishLifecycleEventSafely(projectRoot, definition.event, {
+    sourceKey: `policy:${kind}:${reference}:${revision}`,
+    sourceRevision: revision,
+    scope: { intent: reference },
+    facts: {
+      status: kind === 'evaluation' ? record.governingOutcome : kind === 'review' ? record.decision : kind === 'exception' ? 'approved' : 'confirmed',
+      intentReference: reference,
+      evidenceDigest: revision,
+      ...(record.ruleId ? { ruleId: record.ruleId } : {}),
+    },
+    personas,
+    streamId: `intent:${reference}`,
+  });
+}
+
+function resultAfter(projectRoot, kind, record, options) {
+  const workspace = readPolicyWorkspace(projectRoot, { intentReference: record.intentReference ?? record.intent?.reference, personas: options.personas, stage: kind });
+  return { record, lifecycle: policyLifecycleEvent(projectRoot, kind, record, { personas: workspace.activePersonas }), workspace };
+}
+
+export function confirmPolicyFactsAction(projectRoot, input, options = {}) {
+  exact(input, actions.facts.allowed, 'Policy fact confirmation request');
+  return resultAfter(projectRoot, 'facts', confirmPolicyFacts(projectRoot, input, options), options);
+}
+
+export function evaluatePolicyDesignAction(projectRoot, input, options = {}) {
+  exact(input, actions.evaluation.allowed, 'Policy evaluation request');
+  return resultAfter(projectRoot, 'evaluation', evaluatePolicyDesign(projectRoot, input, options), options);
+}
+
+export function recordPolicyReviewAction(projectRoot, input, options = {}) {
+  exact(input, actions.review.allowed, 'Policy review request');
+  return resultAfter(projectRoot, 'review', recordPolicyReview(projectRoot, input, options), options);
+}
+
+export function recordPolicyExceptionAction(projectRoot, input, options = {}) {
+  exact(input, actions.exception.allowed, 'Policy exception request');
+  return resultAfter(projectRoot, 'exception', recordPolicyException(projectRoot, input, options), options);
+}

package/src/runtime/prototype-iterations.mjs

@@ -0,0 +1,235 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { atomicJson } from '../delivery-documents.mjs';
+import { projectPaths } from '../paths.mjs';
+import {
+  comparePrototypeReviews,
+  preparePrototypeCycleReview,
+  preparePrototypePlanReview,
+  prototypeFindingId,
+  readPrototypeReviewStatus,
+  recordPrototypeCycleReview,
+  recordPrototypePlanReview,
+} from '../prototype-iterations.mjs';
+import { runtimePaths } from './paths.mjs';
+import { selectPrototypeReviewPersonas } from './persona-engagement.mjs';
+
+const WORKSPACE_SCHEMA = 'ewai.prototype-iteration-workspace/v1';
+const slugPattern = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+
+function fail(message, statusCode = 409) {
+  const error = new Error(`Prototype iteration workspace: ${message}`);
+  error.statusCode = statusCode;
+  throw error;
+}
+
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${label} must be an object`, 400);
+  return value;
+}
+
+function knownFields(value, allowed, label) {
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) fail(`${label} has unknown field ${key}`, 400);
+}
+
+function safeSlug(value) {
+  const slug = String(value ?? '').trim();
+  if (!slugPattern.test(slug)) fail('delivery slug must be a bounded lowercase identifier', 400);
+  return slug;
+}
+
+function readJson(path, label) {
+  if (!existsSync(path)) fail(`${label} has not been prepared`);
+  if (lstatSync(path).isSymbolicLink()) fail(`${label} may not be a symbolic link`);
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    fail(`${label} is not valid JSON: ${error.message}`);
+  }
+}
+
+function resolveAssessmentReferences(submission) {
+  const request = structuredClone(object(submission, 'review submission'));
+  if (!Array.isArray(request.assessments)) return request;
+  request.assessments = request.assessments.map((assessment, index) => {
+    const item = object(assessment, `assessment ${index + 1}`);
+    const allowed = ['findingId', 'findingRef', 'disposition', 'rationale', 'modification', 'owner'];
+    knownFields(item, allowed, `assessment ${index + 1}`);
+    const findingId = item.findingId || (item.findingRef ? prototypeFindingId(item.findingRef) : '');
+    if (!findingId) fail(`assessment ${index + 1} requires findingId or findingRef`, 400);
+    const { findingRef: _findingRef, ...rest } = item;
+    return { ...rest, findingId };
+  });
+  return request;
+}
+
+function preparationFiles(projectRoot, slug) {
+  const folder = runtimePaths(projectRoot).prototypeIterationRoot(slug);
+  if (!existsSync(folder)) return [];
+  if (lstatSync(folder).isSymbolicLink()) fail('prototype preparation folder may not be a symbolic link');
+  return readdirSync(folder, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /^cycle-[1-3]-preparation\.json$/.test(entry.name))
+    .map((entry) => readJson(resolve(folder, entry.name), entry.name));
+}
+
+function validatePrototypeEntry(projectRoot, slug, entryPath) {
+  const project = projectPaths(projectRoot);
+  const deliveryRoot = resolve(project.buildRoot, slug);
+  const prototypeRoot = resolve(deliveryRoot, 'ui-design-assets/prototypes');
+  const candidate = resolve(deliveryRoot, String(entryPath ?? ''));
+  const rel = relative(prototypeRoot, candidate);
+  if (!entryPath || isAbsolute(String(entryPath)) || !rel || rel.startsWith('..') || isAbsolute(rel)) {
+    fail('prototype entry path must identify a file inside ui-design-assets/prototypes', 400);
+  }
+  if (!existsSync(candidate) || !lstatSync(candidate).isFile()) fail(`prototype entry path does not exist: ${entryPath}`, 400);
+  if (lstatSync(candidate).isSymbolicLink()) fail('prototype entry path may not be a symbolic link', 400);
+}
+
+function catalogue(options) {
+  return Array.isArray(options.personas) ? options.personas : Array.isArray(options.personaCatalogue) ? options.personaCatalogue : [];
+}
+
+export function preparePrototypePlanWorkspace(projectRoot, deliverySlug, input = {}, options = {}) {
+  const slug = safeSlug(deliverySlug);
+  const request = object(input, 'plan prepare request');
+  knownFields(request, ['intentDigest', 'designSystem', 'plan', 'signals', 'predecessorDigest'], 'plan prepare request');
+  const engagement = selectPrototypeReviewPersonas({
+    stage: 'plan',
+    signals: request.signals ?? [],
+    context: { deliverySlug: slug, plan: request.plan },
+  }, catalogue(options));
+  const preparation = preparePrototypePlanReview({
+    schema: 'ewai.prototype-plan-input/v1',
+    deliverySlug: slug,
+    intentDigest: request.intentDigest,
+    designSystem: request.designSystem,
+    plan: request.plan,
+    engagement,
+    predecessorDigest: request.predecessorDigest ?? '',
+  }, { now: options.now });
+  atomicJson(runtimePaths(projectRoot).prototypePlanPreparationPath(slug), preparation);
+  return {
+    schema: WORKSPACE_SCHEMA,
+    status: 'plan-review-prepared',
+    deliverySlug: slug,
+    preparation,
+    activePersonas: preparation.engagement.activePersonas,
+    personaAvailability: preparation.engagement.availability,
+    nextAction: 'record-plan-review',
+    authority: preparation.authority,
+  };
+}
+
+export function recordPrototypePlanWorkspaceReview(projectRoot, deliverySlug, input, options = {}) {
+  const slug = safeSlug(deliverySlug);
+  const preparation = readJson(runtimePaths(projectRoot).prototypePlanPreparationPath(slug), 'prototype plan review');
+  if (preparation.deliverySlug !== slug) fail('prepared plan belongs to a different delivery');
+  return recordPrototypePlanReview(projectRoot, preparation, resolveAssessmentReferences(input), options);
+}
+
+export function preparePrototypeCycleWorkspace(projectRoot, deliverySlug, input = {}, options = {}) {
+  const slug = safeSlug(deliverySlug);
+  const request = object(input, 'cycle prepare request');
+  knownFields(request, [
+    'planReviewDigest', 'cycleNumber', 'maxCycles', 'predecessorDigest', 'prototype',
+    'evidenceChannels', 'signals',
+  ], 'cycle prepare request');
+  const status = readPrototypeReviewStatus(projectRoot, slug);
+  const plan = status.planReviews.find(({ contentDigest }) => contentDigest === request.planReviewDigest);
+  if (!plan) fail('cycle preparation requires a recorded plan review digest');
+  const cycleNumber = Number(request.cycleNumber);
+  const predecessorDigest = String(request.predecessorDigest ?? '');
+  if (cycleNumber > 1) {
+    const predecessor = status.cycleReviews.find(({ contentDigest }) => contentDigest === predecessorDigest);
+    if (!predecessor) fail('cycle predecessor digest must identify a recorded earlier cycle');
+    if (predecessor.cycleNumber !== cycleNumber - 1) fail('cycle predecessor must be the immediately previous cycle');
+    if (status.currentCycleReview?.contentDigest !== predecessorDigest) fail('cycle predecessor must be the current cycle review');
+  } else if (status.cycleReviews.length) {
+    fail('cycle one cannot be prepared after recorded design cycles already exist');
+  }
+  validatePrototypeEntry(projectRoot, slug, request.prototype?.entryPath);
+  const engagement = selectPrototypeReviewPersonas({
+    stage: 'design',
+    signals: request.signals ?? [],
+    context: {
+      deliverySlug: slug,
+      prototype: request.prototype,
+      evidenceChannels: request.evidenceChannels,
+      planReviewDigest: request.planReviewDigest,
+    },
+  }, catalogue(options));
+  const preparation = preparePrototypeCycleReview({
+    schema: 'ewai.prototype-cycle-input/v1',
+    deliverySlug: slug,
+    planReviewDigest: request.planReviewDigest,
+    cycleNumber,
+    maxCycles: request.maxCycles ?? 2,
+    predecessorDigest,
+    prototype: request.prototype,
+    evidenceChannels: request.evidenceChannels,
+    engagement,
+  }, { now: options.now });
+  atomicJson(runtimePaths(projectRoot).prototypeCyclePreparationPath(slug, preparation.cycleNumber), preparation);
+  return {
+    schema: WORKSPACE_SCHEMA,
+    status: 'design-review-prepared',
+    deliverySlug: slug,
+    preparation,
+    activePersonas: preparation.engagement.activePersonas,
+    personaAvailability: preparation.engagement.availability,
+    nextAction: 'record-design-review',
+    authority: preparation.authority,
+  };
+}
+
+export function recordPrototypeCycleWorkspaceReview(projectRoot, deliverySlug, input, options = {}) {
+  const slug = safeSlug(deliverySlug);
+  const expected = String(input?.expectedPreparationDigest ?? '');
+  const preparation = preparationFiles(projectRoot, slug).find(({ preparationDigest }) => preparationDigest === expected);
+  if (!preparation) fail('no prepared design cycle matches the expected preparation digest');
+  if (preparation.deliverySlug !== slug) fail('prepared design cycle belongs to a different delivery');
+  return recordPrototypeCycleReview(projectRoot, preparation, resolveAssessmentReferences(input), options);
+}
+
+export function readPrototypeIterationWorkspace(projectRoot, deliverySlug, options = {}) {
+  const slug = safeSlug(deliverySlug);
+  const status = readPrototypeReviewStatus(projectRoot, slug);
+  const planPath = runtimePaths(projectRoot).prototypePlanPreparationPath(slug);
+  const planPreparation = existsSync(planPath) ? readJson(planPath, 'prototype plan review') : null;
+  const cyclePreparations = preparationFiles(projectRoot, slug).sort((left, right) => left.cycleNumber - right.cycleNumber);
+  const currentEngagement = status.currentCycleReview?.engagement
+    ?? cyclePreparations.at(-1)?.engagement
+    ?? status.currentPlanReview?.engagement
+    ?? planPreparation?.engagement
+    ?? null;
+  const availability = currentEngagement?.availability
+    ?? selectPrototypeReviewPersonas({ stage: 'plan' }, catalogue(options)).availability;
+  return {
+    schema: WORKSPACE_SCHEMA,
+    status: status.currentCycleReview?.nextAction
+      ?? status.currentPlanReview?.nextAction
+      ?? (planPreparation ? 'plan-review-prepared' : 'not-prepared'),
+    deliverySlug: slug,
+    planPreparation,
+    cyclePreparations,
+    planReviews: status.planReviews,
+    cycleReviews: status.cycleReviews,
+    currentPlanReview: status.currentPlanReview,
+    currentCycleReview: status.currentCycleReview,
+    activePersonas: currentEngagement?.activePersonas ?? [],
+    personaAvailability: availability,
+    authority: status.authority,
+  };
+}
+
+export function comparePrototypeWorkspaceReviews(projectRoot, deliverySlug, input = {}) {
+  const slug = safeSlug(deliverySlug);
+  const request = object(input, 'comparison request');
+  knownFields(request, ['leftDigest', 'rightDigest'], 'comparison request');
+  const status = readPrototypeReviewStatus(projectRoot, slug);
+  const reviews = [...status.planReviews, ...status.cycleReviews];
+  const left = reviews.find(({ contentDigest }) => contentDigest === request.leftDigest);
+  const right = reviews.find(({ contentDigest }) => contentDigest === request.rightDigest);
+  if (!left || !right) fail('comparison digests must identify recorded prototype reviews', 404);
+  return comparePrototypeReviews(left, right);
+}

package/src/runtime/provider-adapters.mjs

@@ -0,0 +1,163 @@
+import { accessSync, constants, createWriteStream, mkdirSync } from 'node:fs';
+import { delimiter, isAbsolute, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { CONTEXT_ESTIMATE_METHOD, estimateContextTokens } from './context-assembly.mjs';
+
+export const AFK_PROVIDERS = Object.freeze(['codex', 'claude', 'antigravity']);
+
+export function measureProviderPrompt(prompt) {
+  const measurement = estimateContextTokens(prompt);
+  return {
+    bytes: measurement.bytes,
+    estimatedTokens: measurement.estimatedTokens,
+    estimateMethod: CONTEXT_ESTIMATE_METHOD,
+  };
+}
+
+function nonNegativeInteger(value) {
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+export function normaliseProviderUsage(provider, usage) {
+  if (!usage || typeof usage !== 'object' || Array.isArray(usage)) return null;
+  const inputTokens = nonNegativeInteger(usage.inputTokens ?? usage.input_tokens);
+  const cachedInputTokens = nonNegativeInteger(
+    usage.cachedInputTokens ?? usage.cached_input_tokens ?? usage.cache_read_input_tokens,
+  );
+  const outputTokens = nonNegativeInteger(usage.outputTokens ?? usage.output_tokens);
+  if (inputTokens === null || outputTokens === null) return null;
+  return {
+    schema: 'ewai.provider-usage/v1',
+    provider: String(provider ?? ''),
+    inputTokens,
+    cachedInputTokens: cachedInputTokens ?? 0,
+    outputTokens,
+    source: 'provider-reported',
+  };
+}
+
+export function providerCommand(provider) {
+  return provider === 'antigravity' ? 'agy' : provider;
+}
+
+export function commandAvailable(command, env = process.env) {
+  const candidates = isAbsolute(command)
+    ? [command]
+    : String(env.PATH ?? '').split(delimiter).filter(Boolean).map((entry) => resolve(entry, command));
+  return candidates.some((candidate) => {
+    try {
+      accessSync(candidate, constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function claudeTools(task, mode) {
+  if (mode === 'review') return ['Read', 'Glob', 'Grep'];
+  const commands = (task?.allowed_commands ?? []).map((command) => `Bash(${command})`);
+  return ['Read', 'Edit', 'Write', 'Glob', 'Grep', ...commands];
+}
+
+export function buildProviderInvocation(provider, input = {}) {
+  if (!AFK_PROVIDERS.includes(provider)) throw new Error(`Unsupported AFK provider: ${provider}`);
+  const mode = input.mode === 'review' ? 'review' : 'implementation';
+  const cwd = resolve(input.cwd);
+  const model = String(input.model ?? '').trim();
+  const invocation = {
+    provider,
+    command: providerCommand(provider),
+    cwd,
+    prompt: String(input.prompt ?? ''),
+    timeoutMs: Number(input.timeoutMs ?? 45 * 60 * 1000),
+    mode,
+    task: input.task ?? null,
+    promptMeasurement: measureProviderPrompt(input.prompt ?? ''),
+    providerUsage: normaliseProviderUsage(provider, input.providerUsage),
+    args: [],
+  };
+
+  if (provider === 'codex') {
+    invocation.args = ['--ask-for-approval', 'never', 'exec', '--color', 'never', '--sandbox', mode === 'review' ? 'read-only' : 'workspace-write', '-C', cwd];
+    if (mode === 'implementation') invocation.args.splice(3, 0, '--json');
+    if (model) invocation.args.push('--model', model);
+    invocation.args.push('-');
+  } else if (provider === 'claude') {
+    invocation.args = [
+      '-p',
+      '--output-format', mode === 'review' ? 'text' : 'stream-json',
+      '--permission-mode', mode === 'review' ? 'plan' : 'dontAsk',
+      '--no-session-persistence',
+      '--allowedTools', claudeTools(input.task, mode).join(','),
+    ];
+    if (model) invocation.args.push('--model', model);
+    if (Number.isFinite(Number(input.maxBudgetUsd)) && Number(input.maxBudgetUsd) > 0) {
+      invocation.args.push('--max-budget-usd', String(input.maxBudgetUsd));
+    }
+  } else {
+    invocation.args = [
+      '--print', invocation.prompt,
+      '--output-format', mode === 'review' ? 'text' : 'stream-json',
+      '--mode', mode === 'review' ? 'plan' : 'accept-edits',
+      '--sandbox',
+    ];
+    if (mode === 'implementation') invocation.args.push('--dangerously-skip-permissions');
+    if (model) invocation.args.push('--model', model);
+  }
+  return invocation;
+}
+
+export function invokeProvider(invocation, options = {}) {
+  mkdirSync(resolve(invocation.logPath, '..'), { recursive: true });
+  const output = createWriteStream(invocation.logPath, { flags: 'a' });
+  const startedAt = Date.now();
+  const maxCapture = Number(options.maxCaptureBytes ?? 1024 * 1024);
+
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: invocation.cwd,
+      env: options.env ?? process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: false,
+    });
+    options.onStart?.(child.pid);
+    let captured = '';
+    let timedOut = false;
+    const capture = (chunk) => {
+      output.write(chunk);
+      captured = `${captured}${chunk.toString('utf8')}`.slice(-maxCapture);
+    };
+    child.stdout.on('data', capture);
+    child.stderr.on('data', capture);
+    child.once('error', (error) => {
+      output.end();
+      reject(error);
+    });
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 5_000).unref();
+    }, invocation.timeoutMs);
+    timeout.unref();
+    child.once('close', (exitCode, signal) => {
+      clearTimeout(timeout);
+      output.end();
+      resolvePromise({
+        provider: invocation.provider,
+        exitCode: exitCode ?? -1,
+        signal: signal ?? '',
+        timedOut,
+        durationMs: Date.now() - startedAt,
+        logPath: invocation.logPath,
+        output: captured,
+        promptMeasurement: invocation.promptMeasurement ?? measureProviderPrompt(invocation.prompt),
+        providerUsage: normaliseProviderUsage(
+          invocation.provider,
+          options.providerUsage ?? invocation.providerUsage,
+        ),
+      });
+    });
+    child.stdin.end(invocation.prompt);
+  });
+}