create-agdf 0.20.1 → 0.30.0

package/lib/cli/parse-args.js

@@ -12,8 +12,8 @@ export class CliUsageError extends Error {
   }
 }
 
-const STEP_FIELD_FLAGS = new Map(["title", "route", "reason", "evidence", "source", "covers", "decision", "result", "risk", "next"]
-  .map((name) => [`--${name}`, name]));
+const STEP_FIELD_FLAGS = new Map(["title", "route", "reason", "evidence", "source", "covers", "decision", "result", "risk", "next", "reviewer", "reviewed"]
+  .map((name) => [`--${name}`, name]).concat([['--update-draft', 'updateDraft']]));
 
 function requiredValue(args, index, option) {
   const next = args[index + 1];
@@ -35,6 +35,7 @@ export function parseArgs(argv, dependencies = {}) {
   let dirInput = ".";
   let force = false;
   let json = false;
+  let native = false;
   let verbose = false;
   let guided = false;
   let details = false;
@@ -54,7 +55,9 @@ export function parseArgs(argv, dependencies = {}) {
   let intakeMode;
   let continueDelivery = false;
   let presentationId;
-  let operationId, assurance;
+  let documentServer;
+  let documentRequest = false;
+  let operationId, assurance, planId, sourceDigest, priority, pendingDigest, packageSelection;
   let revisionMode, sourceGate, previewDigest;
   let fixture;
   let persist = false;
@@ -73,6 +76,7 @@ export function parseArgs(argv, dependencies = {}) {
   let recoveryAction;
   let recoveryPreviewId;
   let recoveryConfirmation;
+  let closureFile, closureOutcome, successorRun, successorReference, closureConfirmation;
   const stepFields = {};
   let allActive = false;
   let scope;
@@ -86,7 +90,6 @@ export function parseArgs(argv, dependencies = {}) {
   let retireCockpit, restoreCockpit;
   let setupRequest;
   let controlDir;
-  let controlMigration;
   let targetSource;
   let primaryTarget;
   let workingDirectory = cwd;
@@ -101,8 +104,23 @@ export function parseArgs(argv, dependencies = {}) {
     if (!arg) continue;
     if (arg.startsWith("--")) flagCounts.set(arg, (flagCounts.get(arg) ?? 0) + 1);
     if (arg === "--help" || arg === "-h") return { kind: "help" };
+    if (arg === '--server') {
+      documentServer = requiredValue(args, i, arg); i++; continue;
+    }
+    if (arg === '--request') { documentRequest = true; continue; }
+    if (['--plan-id', '--source-digest', '--priority', '--pending-digest', '--package'].includes(arg)) {
+      if (flagCounts.get(arg) !== 1) throw new CliUsageError(`${arg} may not repeat`);
+      const value = requiredValue(args, i, arg); i++;
+      if (arg === '--plan-id') planId = value;
+      else if (arg === '--source-digest') sourceDigest = value;
+      else if (arg === '--priority') priority = value;
+      else if (arg === '--pending-digest') pendingDigest = value;
+      else packageSelection = value;
+      continue;
+    }
     if (arg === "--force") { force = true; continue; }
     if (arg === "--json") { json = true; continue; }
+    if (arg === '--native') { native = true; continue; }
     if (arg === "--verbose") { verbose = true; continue; }
     if (arg === "--guided") { guided = true; continue; }
     if (arg === "--details") { details = true; continue; }
@@ -134,19 +152,13 @@ export function parseArgs(argv, dependencies = {}) {
       continue;
     }
 
-    if (arg === "--control-dir" || arg === "--control-migration") {
+    if (arg === '--control-dir') {
       const next = requiredValue(args, i, arg);
-      if (arg === "--control-dir") {
-        if (!isAbsolute(next)) throw new CliUsageError("--control-dir requires an absolute repository path.");
-        controlDir = next;
-      } else {
-        if (!["inspect", "safe"].includes(next)) throw new CliUsageError("--control-migration must be inspect or safe.");
-        controlMigration = next;
-      }
-      i += 1;
-      continue;
+      if (!isAbsolute(next)) throw new CliUsageError('--control-dir requires an absolute repository path.');
+      controlDir = next; i += 1; continue;
     }
 
+
     if (arg === "--run") {
       runId = requiredValue(args, i, arg);
       i += 1;
@@ -171,6 +183,16 @@ export function parseArgs(argv, dependencies = {}) {
       continue;
     }
 
+    if (["--closure-file", "--outcome", "--successor-run", "--successor-ref", "--confirmation"].includes(arg)) {
+      const value = requiredValue(args, i, arg);
+      if (arg === "--closure-file") closureFile = resolve(cwd, value);
+      else if (arg === "--outcome") closureOutcome = value;
+      else if (arg === "--successor-run") successorRun = value;
+      else if (arg === "--successor-ref") successorReference = value;
+      else closureConfirmation = value;
+      i += 1;
+      continue;
+    }
     if (arg === '--retire-cockpit' || arg === '--restore-cockpit') {
       const value = requiredValue(args, i, arg);
       if (retireCockpit !== undefined || restoreCockpit !== undefined) throw new CliUsageError('Cockpit transition selector may not repeat');
@@ -335,17 +357,67 @@ export function parseArgs(argv, dependencies = {}) {
   }
 
   if (!target || !resolveCommand(target)) {
-    throw new CliUsageError(`Please choose one target: ${supportedCommandNames().join(", ")}.`, { showUsage: true });
+    throw new CliUsageError(`${target ? `Unknown command: ${target}. ` : ""}Please choose one target: ${supportedCommandNames().join(", ")}.`, { showUsage: true });
   }
   if (revisionMode && ["--dir", "--run", "--revision", "--operation", "--source-gate", "--evidence", "--preview-digest"].some(flag => flagCounts.get(flag) > 1)) {
     throw new CliUsageError("Source revision identity and evidence flags may not repeat");
   }
+  if (documentServer !== undefined && target !== 'render-document') throw new CliUsageError('--server requires render-document');
+  if (['project-state', 'operation-status'].includes(target)) {
+    const allowed = new Set(['--dir', '--json', '--language', '--lang', ...(target === 'operation-status' ? ['--module'] : [])]);
+    if ([...flagCounts].some(([flag, count]) => count !== 1 || !allowed.has(flag)))
+      throw new CliUsageError('Project reads accept only unique --dir, --json, --language and operation-status --module selectors.');
+  }
+  if (documentRequest && target !== 'render-document') throw new CliUsageError('--request requires render-document');
+  if (target === 'render-document') {
+    const allowed = new Set(['--dir', '--run', '--revision', '--gate', '--presentation', '--server', '--request']);
+    if ([...flagCounts].some(([flag, count]) => count !== 1 || !allowed.has(flag)))
+      throw new CliUsageError('render-document accepts only unique explicit document selectors and --server.');
+  }
+  if (target === "run-close" && ["--action", "--run", "--outcome", "--reason", "--successor-run", "--successor-ref", "--closure-file", "--preview-id", "--confirmation"].some(flag => flagCounts.get(flag) > 1)) {
+    throw new CliUsageError("run-close fields may not repeat");
+  }
+  if (target === 'run-close') {
+    if (!['preview', 'apply'].includes(recoveryAction)) throw new CliUsageError('run-close requires --action preview or apply.');
+    if (successorRun !== undefined && successorReference !== undefined) throw new CliUsageError('Choose one successor kind: --successor-run or --successor-ref.');
+    if (recoveryAction === 'preview' && !closureFile && (!runId || !closureOutcome || !stepFields.reason)) throw new CliUsageError('A closure preview requires --run, --outcome and --reason, or --closure-file.');
+    if (recoveryAction === 'apply' && (!recoveryPreviewId || !closureConfirmation)) throw new CliUsageError('A closure apply requires --preview-id and the exact --confirmation.');
+  }
   if ((retireCockpit !== undefined || restoreCockpit !== undefined)
     && ['--dir', '--surface', '--scope', '--evidence'].some(flag => flagCounts.get(flag) > 1)) {
     throw new CliUsageError('Cockpit transition identity and evidence flags may not repeat');
   }
 
   if (Object.hasOwn(commandGroupRoutes, target) && [...flagCounts.keys()].some(flag => !['--command-file', '--json'].includes(flag))) throw new CliUsageError('Bound command routes accept only --command-file and --json; no overriding envelope fields.');
+  if (target === 'planned') {
+    const common = ['--dir', '--action', '--json', '--language'];
+    const fields = {
+      list: [], inspect: ['--plan-id'], create: ['--evidence', '--priority', '--operation'],
+      replace: ['--plan-id', '--source-digest', '--evidence', '--operation'],
+      start: ['--plan-id', '--source-digest', '--operation'], status: ['--plan-id', '--operation'],
+    };
+    const allowed = new Set([...common, ...(fields[recoveryAction] ?? [])]);
+    if ([...flagCounts].some(([flag, count]) => count !== 1 || !allowed.has(flag)))
+      throw new CliUsageError('Planning accepts only the unique fields of its selected action.');
+  }
+  if (['run-create', 'run-present', 'run-approve', 'run-step', 'run-revise', 'run-close'].includes(target)) {
+    const common = ['--dir', '--working-directory', '--language', '--json', '--operation', '--assurance'];
+    const bound = ['--run', '--revision'];
+    const stepFlags = { ur: ['--title'], route: ['--route', '--reason'], review: ['--decision'], evidence: ['--reason', '--covers'],
+      artefact: ['--gate', '--reviewer', '--reviewed', '--update-draft'], closeout: ['--confirmation'] };
+    const fields = {
+      'run-create': ['--title'], 'run-present': [...bound, '--gate'],
+      'run-approve': [...bound, '--gate', '--presentation', '--response'],
+      'run-step': [...bound, '--step', '--evidence', ...(stepFlags[runStep] ?? [])],
+      'run-revise': [...bound, ...(revisionMode === 'inspect' ? ['--inspect'] : revisionMode
+        ? ['--' + revisionMode, '--source-gate', '--evidence', ...(revisionMode === 'apply' ? ['--preview-digest', '--confirmation'] : revisionMode === 'recover' ? ['--pending-digest'] : [])]
+        : ['--gate', '--confirmation'])],
+      'run-close': ['--action', ...(recoveryAction === 'apply' ? ['--preview-id', '--confirmation']
+        : closureFile ? ['--closure-file'] : ['--run', '--outcome', '--reason', '--successor-run', '--successor-ref'])],
+    };
+    const allowed = new Set([...common, ...fields[target]]);
+    if ([...flagCounts].some(([flag, count]) => count !== 1 || !allowed.has(flag))) throw new CliUsageError('Current Run commands accept only the unique fields of the selected operation.');
+  }
   return {
     kind: "command",
     options: {
@@ -355,6 +427,7 @@ export function parseArgs(argv, dependencies = {}) {
       dirInputAbsolute: dirExplicit && isAbsolute(dirInput),
       force,
       json,
+      ...(native ? { native: true } : {}),
       verbose,
       ...(guided ? { guided: true } : {}),
       ...(details ? { details: true } : {}),
@@ -374,7 +447,12 @@ export function parseArgs(argv, dependencies = {}) {
     tpAction,
       continueDelivery,
       presentationId,
+      ...(documentServer !== undefined ? { documentServer } : {}),
+      ...(documentRequest ? { documentRequest: true } : {}),
       ...(operationId !== undefined ? { operationId } : {}),
+      ...(planId !== undefined ? { planId } : {}), ...(sourceDigest !== undefined ? { sourceDigest } : {}),
+      ...(priority !== undefined ? { priority } : {}), ...(pendingDigest !== undefined ? { pendingDigest } : {}),
+      ...(packageSelection !== undefined ? { packageSelection } : {}),
       ...(assurance !== undefined ? { assurance } : {}),
       ...(revisionMode !== undefined ? { revisionMode } : {}),
       ...(sourceGate !== undefined ? { sourceGate } : {}),
@@ -393,6 +471,11 @@ export function parseArgs(argv, dependencies = {}) {
       recoveryAction,
       recoveryPreviewId,
       recoveryConfirmation,
+      ...(closureFile !== undefined ? { closureFile } : {}),
+      ...(closureOutcome !== undefined ? { closureOutcome } : {}),
+      ...(successorRun !== undefined ? { successorRun } : {}),
+      ...(successorReference !== undefined ? { successorReference } : {}),
+      ...(closureConfirmation !== undefined ? { closureConfirmation } : {}),
       stepFields,
       allActive,
       scope,
@@ -407,7 +490,6 @@ export function parseArgs(argv, dependencies = {}) {
       ...(restoreCockpit !== undefined ? { restoreCockpit } : {}),
       setupRequest,
       controlDir,
-      controlMigration,
       generatorModel,
       maxGeneratedCandidates,
       generationTimeoutMs,

package/lib/cli/planned-command.js

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { openSync, closeSync, fstatSync, lstatSync, readFileSync, constants } from 'node:fs';
+import { createRunCommandService } from '#agdf-core/control-state/run-command-service.js';
+import { createRunMaterialStore } from '#agdf-core/control-state/run-material.js';
+import { resolveControlCommandTarget } from '#agdf-core/control-state/approval-command-contract.js';
+import { planningId, inspectPlannedEntry, inspectPlannedOperation } from '#agdf-core/control-state/planned-entry.js';
+import { readPlannedInventory } from '#agdf-core/control-state/planned-inventory.js';
+import { pluginDefinition } from './runtime-context.js';
+
+function readUr(path) {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 131072) throw Error('planned_source_invalid');
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const actual = fstatSync(fd);
+    if (actual.ino !== stat.ino || actual.dev !== stat.dev || actual.size !== stat.size) throw Error('planned_source_changed');
+    const bytes = readFileSync(fd);
+    if (bytes.length > 131072) throw Error('planned_source_limit');
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } finally { closeSync(fd); }
+}
+export function executePlannedCli(options, io = console) {
+  const store = createRunMaterialStore();
+  try {
+    const root = resolveControlCommandTarget(options.dir), action = options.recoveryAction;
+    const emit = value => { io.log(JSON.stringify(value, null, 2)); return ['rejected', 'effect_unknown', 'recovery_required'].includes(value.outcome) ? 2 : 0; };
+    if (options.target === 'planned' && action === 'list') return emit(readPlannedInventory(root.root));
+    if (options.target === 'planned' && action === 'inspect') return emit(inspectPlannedEntry(root.root, options.planId));
+    if (action === 'status') return emit(inspectPlannedOperation(root.root, options.planId, options.operationId));
+    const operation_id = options.operationId ?? randomUUID();
+    const base = { schema_version: '1', presentation_language: options.language?.chat_language ?? 'en', working_directory: root.root,
+      primary_target: root.root, target_source: 'explicit_target', target_id: root.target_id, operation_id, assurance: 'cooperative_local' };
+    const scope = { plan_id: action === 'create' ? planningId(operation_id) : options.planId, expected_digest: action === 'create' ? null : options.sourceDigest };
+    const bound = { ...base, planning: scope };
+    if (action === 'start') {
+      const entry = inspectPlannedEntry(root.root, scope.plan_id);
+      return emit(createRunCommandService({ packageVersion: pluginDefinition.version })('agdf_run', { ...bound, command: { kind: 'run.create_from_planned', payload: { title: entry.title } } }));
+    }
+    const content = readUr(resolve(options.workingDirectory, options.stepFields.evidence)), bytes = Buffer.from(content);
+    const stage = payload => store.stage({ ...bound, operation_id: randomUUID(), command: { kind: 'planned_material.stage', payload } });
+    const started = stage({ action: 'begin', files: [{ slot: 'UR', bytes: bytes.length }] });
+    if (started.outcome !== 'accepted') return emit(started);
+    const transfer_id = started.family_result.transfer_id;
+    for (let offset = 0; offset < bytes.length; offset += 16384) {
+      const chunk = stage({ action: 'append', transfer_id, file: 0, offset, data: bytes.subarray(offset, offset + 16384).toString('base64') });
+      if (chunk.outcome !== 'accepted') return emit(chunk);
+    }
+    const sealed = stage({ action: 'seal', transfer_id }); if (sealed.outcome !== 'accepted') return emit(sealed);
+    const input = { ...bound, command: { kind: `planned_ur.${action}`, payload: { source: sealed.family_result.files[0].reference,
+      ...(options.priority ? { priority: options.priority } : {}) } } };
+    return emit(createRunCommandService({ packageVersion: pluginDefinition.version, materialGrants: store.grants(input) })('agdf_record', input));
+  } catch (error) { io.error(error.code ?? error.message); return 1; }
+  finally { store.close(); }
+}

package/lib/cli/project-init-command.js

@@ -0,0 +1,21 @@
+import { randomUUID } from 'node:crypto';
+import { createCoreServices } from '#agdf-core';
+import { resolveControlCommandTarget } from '#agdf-core/control-state/approval-command-contract.js';
+import { resources } from '../runtime/control-context.js';
+import { cliGitObservation } from '../control-evaluation/git-observation.js';
+
+// The convenience initializer uses the same complete command normalization,
+// original-operation capture and fixed seed owner as the MCP command.
+export function executeProjectInit(options, io = console) {
+  if (options.force) { io.error('AGDF_CANONICAL_INIT_FORCE_FORBIDDEN'); return 2; }
+  try {
+    const target = resolveControlCommandTarget(options.dir);
+    const input = { working_directory: options.workingDirectory, primary_target: target.root,
+      target_source: options.dirExplicit ? 'explicit_target' : 'current_repository', target_id: target.target_id,
+      operation_id: options.operationId ?? randomUUID(),
+      command: { kind: 'project.initialize', payload: options.languageExplicit ? { language: options.language.chat_language } : {} } };
+    const result = createCoreServices({ resources, observers: { gitObservation: cliGitObservation } }).command('agdf_project', input);
+    io.log(JSON.stringify(result, null, 2));
+    return ['accepted', 'already_applied'].includes(result.outcome) ? 0 : 2;
+  } catch (error) { io.error(error.code ?? error.message); return 2; }
+}

package/lib/cli/project-read-command.js

@@ -0,0 +1,35 @@
+import { createCoreServices } from '#agdf-core';
+import { resources, resolveConfiguredChatLanguage } from '../runtime/control-context.js';
+import { cliGitObservation } from '../control-evaluation/git-observation.js';
+
+// CLI syntax only. Target confirmation, facts and original-operation semantics
+// stay with the same inspect owner used by MCP.
+export function executeProjectRead(options, io = console) {
+  let language = options.language?.chat_language;
+  if (!options.languageExplicit) {
+    try { language = resolveConfiguredChatLanguage(options.dir); }
+    catch { /* Core still reports the invalid configuration and original receipt facts. */ }
+  }
+  const result = createCoreServices({ resources, observers: { gitObservation: cliGitObservation } }).inspect({
+    operation: options.target, workingDirectory: options.dir, targetSource: 'explicit_target', primaryTarget: options.dir,
+    presentationLanguage: language,
+    expectedVersion: resources.pluginDefinition.version, interactionLocales: resources.interactionLocales,
+    ...(options.contractModule ? { contractModule: options.contractModule } : {}),
+  });
+  if (options.json) io.log(JSON.stringify(result, null, 2));
+  else {
+    const report = result.report;
+    io.log(`AGDF ${options.target}: ${report?.status ?? result.outcome}`);
+    if (report?.target_id) io.log(`Target: ${report.target_id}`);
+    if (report?.operation_id) io.log(`Operation: ${report.operation_id}`);
+    if (report?.current_setup) io.log(`Current setup: ${report.current_setup}`);
+    if (report?.plan) io.log(`Plan: ${report.plan.file_count} files; ${report.plan.plan_digest}`);
+    if (report?.receipt?.receipt_digest) io.log(`Receipt: ${report.receipt.receipt_digest}`);
+    if (report?.reason) io.log(`Reason: ${report.reason}`);
+    if (report?.recovery?.instruction) io.log(`Recovery: ${report.recovery.instruction}`);
+    if (report?.next_calls?.length) io.log(`Next: ${JSON.stringify(report.next_calls)}`);
+    if (result.host_action?.text) io.log(result.host_action.text);
+  }
+  return result.outcome === 'inspect_result' && result.report?.available === true
+    && !['blocked', 'unavailable', 'incomplete'].includes(result.report.status) ? 0 : 2;
+}

package/lib/cli/run-command-aliases.js

@@ -0,0 +1,116 @@
+import { renderSourceRevision } from '#agdf-core/interaction-presentation.js';
+import { interactionLocales } from './runtime-context.js';
+import { resolveMcpInput } from '#agdf-core/mcp-input-resolution.js';
+import { withInputResolution } from '#agdf-core/control-state/input-resolution.js';
+import { commandGroupDefinition } from '#agdf-core/control-state/run-command-schema.js';
+import { inspectRunInputResolution } from '#agdf-core/control-state/run-input-resolution.js';
+import { randomUUID } from 'node:crypto';
+import { openSync, closeSync, constants, fstatSync, lstatSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createCoreServices } from '#agdf-core';
+import { createRunMaterialStore } from '#agdf-core/control-state/run-material.js';
+import { resolveControlCommandTarget, digest } from '#agdf-core/control-state/approval-command-contract.js';
+import { canonicalRunText, artefactFileDigest } from '#agdf-core/control-state/run-seal.js';
+import { inspectRunOperation } from '#agdf-core/control-state/run-operation-status.js';
+import { inspectSourceRevision } from '#agdf-core/control-state/run-revision.js';
+import { runDocumentPath } from '#agdf-core/control-state/run-identity.js';
+import { resources } from '../runtime/control-context.js';
+import { cliGitObservation } from '../control-evaluation/git-observation.js';
+
+function sourceText(options, limit = 131072) {
+  const supplied = options.stepFields?.evidence;
+  if (!supplied) throw Error('A bounded source file is required: --evidence <path>.');
+  const path = resolve(options.workingDirectory, supplied), before = lstatSync(path);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > limit) throw Error('source_invalid');
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = fstatSync(fd), bytes = readFileSync(fd);
+    if (stat.ino !== before.ino || stat.dev !== before.dev || stat.size !== before.size || bytes.length > limit) throw Error('source_changed');
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } finally { closeSync(fd); }
+}
+function printResult(result, options, io, identity) {
+  if (options.target === 'run-revise' && !options.json) {
+    const shown = result.outcome === 'already_applied' ? { ...result, outcome: 'replayed' } : result.family_result ?? result;
+    io.log(renderSourceRevision(shown, interactionLocales, options.language.chat_language, identity).markdown);
+  } else io.log(JSON.stringify(result, null, 2));
+}
+export function executeRunAlias(options, io = console) {
+  const store = createRunMaterialStore();
+  try {
+    const target = resolveControlCommandTarget(options.dir), fields = options.stepFields ?? {};
+    const input = { working_directory: options.workingDirectory, primary_target: target.root,
+      target_source: options.dirExplicit ? 'explicit_target' : 'current_repository', target_id: target.target_id,
+      operation_id: options.operationId ?? randomUUID(), ...(options.assurance !== undefined ? { assurance: options.assurance } : {}), ...(options.languageExplicit ? { presentation_language: options.language.chat_language } : {}),
+      ...(options.runId ? { run_id: options.runId, expected_revision_id: options.revisionId } : {}) };
+    const services = grants => createCoreServices({ resources, observers: { gitObservation: cliGitObservation, materialGrants: grants } });
+    const normalize = (group, original, action) => {
+      const selected = resolveMcpInput(commandGroupDefinition(group), original, { defaults: resources.defaults, lookupOriginal: inspectRunInputResolution });
+      return withInputResolution(selected.resolution, () => action(selected.arguments), selected.original);
+    };
+    const emit = result => {
+      printResult(result, options, io, { target: target.root, runId: options.runId, operationId: input.operation_id, revisionId: options.revisionId });
+      return ['accepted', 'already_applied', 'preview', 'historical', 'recovered'].includes(result.outcome) ? 0 : 2;
+    };
+    const material = (slot, content) => {
+      // The Core digest binds canonical content, not an expiring transfer UUID.
+      // A recorded original operation needs no new transfer or stale admission;
+      // the Core still checks its exact logical request before acknowledging it.
+      const observed = options.runId ? inspectRunOperation(target.root, { runId: options.runId, operationId: input.operation_id, targetId: input.target_id }) : null;
+      if (observed?.status === 'recorded') return { material_id: randomUUID(), digest: digest(canonicalRunText(content)) };
+      const bytes = Buffer.from(content), stage = payload => normalize('agdf_record', { ...input,
+        operation_id: randomUUID(), command: { kind: 'material.stage', payload } }, value => store.stage(value));
+      const started = stage({ action: 'begin', files: [{ slot, bytes: bytes.length }] });
+      if (started.outcome !== 'accepted') throw Object.assign(Error(started.reason ?? 'material_unavailable'), { result: started });
+      const transfer_id = started.family_result.transfer_id;
+      for (let offset = 0; offset < bytes.length; offset += 16384) {
+        const part = stage({ action: 'append', transfer_id, file: 0, offset, data: bytes.subarray(offset, offset + 16384).toString('base64') });
+        if (part.outcome !== 'accepted') throw Object.assign(Error(part.reason ?? 'material_unavailable'), { result: part });
+      }
+      const sealed = stage({ action: 'seal', transfer_id });
+      if (sealed.outcome !== 'accepted') throw Object.assign(Error(sealed.reason ?? 'material_unavailable'), { result: sealed });
+      return sealed.family_result.files[0].reference;
+    };
+    let group, command;
+    if (options.target === 'run-create') { group = 'agdf_run'; command = { kind: 'run.create', payload: { title: fields.title } }; }
+    else if (options.target === 'run-present') { group = 'agdf_prepare'; command = { kind: 'presentation.prepare', payload: { gate: options.gate } }; }
+    else if (options.target === 'run-approve') { group = 'agdf_approve'; command = { kind: 'approval.record', payload: { gate: options.gate, presentation_id: options.presentationId, response: options.response } }; }
+    else if (options.target === 'run-step') {
+      const step = options.runStep, slot = step === 'artefact' ? options.gate : ({ ur: 'UR', route: 'Brownfield Review', review: 'CR', evidence: 'EVIDENCE', closeout: 'OR' })[step];
+      if (!slot) throw Error('step_invalid');
+      const source = material(slot, sourceText(options));
+      if (step === 'artefact') { group = 'agdf_record'; command = { kind: 'artefact.record', payload: { gate: options.gate, material: source,
+        reviewer: fields.reviewer, reviewed: fields.reviewed === 'true', update_draft: fields.updateDraft === 'true' } }; }
+      else if (step === 'closeout') { group = 'agdf_closeout'; command = { kind: 'closeout.record', payload: { or: source, confirmation: options.closureConfirmation } }; }
+      else { group = 'agdf_record'; command = { kind: 'step.record', payload: { step, source,
+        ...(step === 'ur' ? { title: fields.title } : step === 'route' ? { reason: fields.reason, route: fields.route }
+          : step === 'review' ? { decision: fields.decision } : { reason: fields.reason, covers: fields.covers }) } }; }
+    } else if (options.target === 'run-revise') {
+      group = 'agdf_revise';
+      if (options.revisionMode === 'inspect') return emit(inspectSourceRevision(target.root, { runId: options.runId, operationId: input.operation_id, revisionId: options.revisionId }));
+      if (options.revisionMode) command = { kind: `source_revision.${options.revisionMode}`, payload: {
+        source_gate: options.sourceGate, proposal: material('EVIDENCE', sourceText(options)),
+        ...(options.revisionMode === 'apply' ? { preview_digest: options.previewDigest, confirmation: options.closureConfirmation }
+          : options.revisionMode === 'recover' ? { recovery_revision_id: options.revisionId, pending_digest: options.pendingDigest } : {}) } };
+      else { const path = runDocumentPath(options.runId, 'PRD.md'); command = { kind: 'prd_revision.reopen', payload: {
+        prd: { path, digest: artefactFileDigest(target.root, path) }, confirmation: options.closureConfirmation } }; }
+    } else if (options.target === 'run-close') {
+      delete input.run_id; delete input.expected_revision_id;
+      group = 'agdf_closeout';
+      const entries = options.closureFile ? JSON.parse(sourceText({ ...options, stepFields: { evidence: options.closureFile } }, 65536)).entries
+        : [{ run_id: options.runId, outcome: options.closureOutcome, reason: fields.reason,
+          ...(options.successorRun ? { successor_run: options.successorRun } : options.successorReference ? { successor_reference: options.successorReference } : {}) }];
+      command = { kind: `closure.${options.recoveryAction}`, payload: options.recoveryAction === 'apply'
+        ? { preview_id: options.recoveryPreviewId, confirmation: options.closureConfirmation } : { entries } };
+    } else throw Error('command_unsupported');
+    const bound = { ...input, command };
+    return emit(normalize(group, bound, value => services(store.grants(value)).command(group, value)));
+  } catch (error) {
+    const identity = { target: options.dir, runId: options.runId, operationId: options.operationId, revisionId: options.revisionId };
+    if (error.result) printResult(error.result, options, io, identity);
+    else if (options.target === 'run-revise' && !options.json) printResult({ outcome: 'rejected', reason: error.code ?? error.message }, options, io, identity);
+    else io.error(error.code ?? error.message);
+    return 2;
+  }
+  finally { store.close(); }
+}

package/lib/cli/runtime-context.js

@@ -1,60 +1,2 @@
-import process from "node:process";
-import {
-  canonicalizeLanguageTag,
-} from "#agdf-core/interaction-presentation.js";
-
-import { configuredLanguage, interactionLocales } from "../runtime/control-context.js";
 export { packageRoot, generatedRoot, pluginDefinition, interactionLocales, configuredLanguage, resolveConfiguredChatLanguage } from "../runtime/control-context.js";
-
-export function canonicalizeDetectedSystemLocale(value) {
-  if (typeof value !== "string") return "";
-  const candidate = value.trim().split(":", 1)[0];
-  if (!candidate || /^(?:C|POSIX)(?:\.|$)/iu.test(candidate)) return "";
-  const withoutModifier = candidate.split("@", 1)[0];
-  const withoutEncoding = withoutModifier.split(".", 1)[0];
-  return canonicalizeLanguageTag(withoutEncoding.replaceAll("_", "-"));
-}
-
-export function detectSystemLocale(env = process.env) {
-  const envLocale = env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE || "";
-  if (envLocale) return envLocale;
-  try {
-    return Intl.DateTimeFormat().resolvedOptions().locale || "";
-  } catch {
-    return "";
-  }
-}
-
-export function resolveLanguagePreference(explicitLanguage, env = process.env) {
-  const explicit = configuredLanguage(explicitLanguage);
-  if (explicit) {
-    return {
-      artifact_language: explicit,
-      chat_language: explicit,
-      runtime_language: "en",
-      source: "parameter",
-      detected_locale: detectSystemLocale(env) || "unknown",
-    };
-  }
-
-  const detectedLocale = detectSystemLocale(env);
-  const detectedTag = canonicalizeDetectedSystemLocale(detectedLocale);
-  const detected = configuredLanguage(detectedTag) || "en";
-  return {
-    artifact_language: detected,
-    chat_language: detected,
-    runtime_language: "en",
-    source: detectedLocale ? "system_locale" : "default",
-    detected_locale: detectedLocale || "unknown",
-  };
-}
-
-export function languageConfigContent(languagePreference) {
-  return `${JSON.stringify({
-    artifact_language: languagePreference.artifact_language,
-    chat_language: languagePreference.chat_language,
-    runtime_language: languagePreference.runtime_language,
-    source: languagePreference.source,
-    detected_locale: languagePreference.detected_locale,
-  }, null, 2)}\n`;
-}
+export { canonicalizeDetectedSystemLocale, detectSystemLocale, resolveLanguagePreference, languageConfigContent } from "#agdf-core/resources/language-preference.js";