@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/worker/evidence.js

@@ -0,0 +1,288 @@
+'use strict';
+
+// Worker evidence records (IC-005, IC-006). CLI checks are declared by a reviewable checks file;
+// live-run evidence copies only the bounded, non-content fields from an ended worker record.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const readiness = require('./readiness.js');
+const { PROBE_STDOUT_MAX } = readiness;
+const { WORKER_CAPABILITIES, WORKER_OPTIONAL_CAPABILITIES } = require('../../registry/index.js');
+const { maskBody } = require('../mask.js');
+const { resultOfRun } = require('./supervisor.js');
+
+const CHECKS_SCHEMA = 'doflow-worker-checks-v1';
+const EVIDENCE_SCHEMA = 'doflow-worker-evidence-v1';
+const MAX_ARGV = 32;
+const MAX_ARG_CHARS = 200;
+const MAX_MATCHED_LINES = 20;
+const MATCHED_LINE_CHARS = 200;
+
+class WorkerEvidenceError extends Error {
+                       
+                         
+  constructor(code        , reason        , message        ) {
+    super(message);
+    this.name = 'WorkerEvidenceError';
+    this.code = code;
+    this.reason = reason;
+  }
+}
+
+function usage(reason        , message        )        {
+  throw new WorkerEvidenceError('usage', reason, message);
+}
+
+function refuse(reason        )        {
+  throw new WorkerEvidenceError('refused', reason, reason);
+}
+
+function argvProblem(argv     )                {
+  if (!Array.isArray(argv) || argv.some((item) => typeof item !== 'string')) return 'argv must be an array of strings';
+  if (argv.length > MAX_ARGV) return `argv must have at most ${MAX_ARGV} elements`;
+  if (argv.some((item) => item.length > MAX_ARG_CHARS)) return `argv elements must be at most ${MAX_ARG_CHARS} characters`;
+  if (argv.some((item) => item.includes('\0'))) return 'argv elements must not contain NUL';
+  return null;
+}
+
+/**
+ * FR-006 / NFR-001: a check may only ask for the version, for help, or for the feature list; never a model session.
+ * Exact shapes only: `--version`; plain subcommand words then one final `--help`/`-h`; `features list` then
+ * `--disable <name>` pairs. Any `--` element or free-text token fails every shape, because `codex exec -- --help`
+ * reads `--help` as the prompt.
+ */
+function freeArgv(argv          )          {
+  if (argv.length === 1 && argv[0] === '--version') return true;
+  const last = argv[argv.length - 1];
+  if ((last === '--help' || last === '-h') && argv.slice(0, -1).every((word) => /^[a-z][a-z-]*$/.test(word))) return true;
+  if (argv[0] !== 'features' || argv[1] !== 'list') return false;
+  const rest = argv.slice(2);
+  return rest.length % 2 === 0 && rest.every((token, index) => (index % 2 === 0 ? token === '--disable' : /^[a-z][a-z0-9_]*$/.test(token)));
+}
+
+function expression(value     , where        )         {
+  if (typeof value !== 'string' || value === '') usage('checks-invalid', `${where} must be a non-empty regular expression`);
+  try { return new RegExp(value); } catch (error     ) {
+    usage('checks-invalid', `${where} is not a valid regular expression: ${error?.message || String(error)}`);
+  }
+}
+
+function validateChecks(data     , harness        , worker     ) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) usage('checks-invalid', 'checks file must be a JSON object');
+  if (data.schema !== CHECKS_SCHEMA) usage('checks-invalid', `checks file schema must be '${CHECKS_SCHEMA}'`);
+  if (data.harness !== harness) usage('checks-invalid', `checks file harness '${data.harness}' does not match '${harness}'`);
+  if (!worker?.cli || worker.cli.status !== 'supported' || typeof worker.cli.binary !== 'string') {
+    usage('checks-invalid', `harness '${harness}' does not declare a supported CLI binary`);
+  }
+  if (data.binary !== worker.cli.binary) usage('checks-invalid', `checks file binary '${data.binary}' does not match harness '${harness}' binary '${worker.cli.binary}'`);
+  if (!data.version || typeof data.version !== 'object' || Array.isArray(data.version)) usage('checks-invalid', 'checks file needs a version check');
+  const versionArgvProblem = argvProblem(data.version.argv);
+  if (versionArgvProblem) usage('checks-invalid', `version.argv ${versionArgvProblem}`);
+  if (!freeArgv(data.version.argv)) usage('checks-invalid', `version.argv is not a free check (only --version, a subcommand path ending in --help/-h, or 'features list' with --disable pairs may run)`);
+  expression(data.version.expect, 'version.expect');
+  if (!Array.isArray(data.checks) || data.checks.length === 0) usage('checks-invalid', 'checks file needs at least one check');
+
+  const capabilities = new Set([
+    ...Object.keys(WORKER_CAPABILITIES),
+    ...Object.keys(WORKER_OPTIONAL_CAPABILITIES),
+  ]);
+  capabilities.delete('cli');
+  for (const [index, check] of data.checks.entries()) {
+    const where = `checks[${index}]`;
+    if (!check || typeof check !== 'object' || Array.isArray(check)) usage('checks-invalid', `${where} must be an object`);
+    if (typeof check.id !== 'string' || check.id === '') usage('checks-invalid', `${where}.id must be a non-empty string`);
+    const problem = argvProblem(check.argv);
+    if (problem) usage('checks-invalid', `${where}.argv ${problem}`);
+    if (!freeArgv(check.argv)) {
+      usage('checks-invalid', `check '${check.id}' (${where}) is not a free check: its argv must be exactly --version, subcommand words ending in --help or -h, or 'features list' with --disable <name> pairs`);
+    }
+    if (!Array.isArray(check.expect) || check.expect.length === 0) usage('checks-invalid', `${where}.expect must be a non-empty array`);
+    check.expect.forEach((pattern     , expectIndex        ) => expression(pattern, `${where}.expect[${expectIndex}]`));
+    if (!Array.isArray(check.establishes) || check.establishes.length === 0
+      || check.establishes.some((key     ) => typeof key !== 'string' || !capabilities.has(key))) {
+      usage('checks-invalid', `${where}.establishes must name worker capabilities other than 'cli'`);
+    }
+  }
+  return data;
+}
+
+function readChecks(file        , fsImpl     ) {
+  let data     ;
+  try {
+    if (!fsImpl.statSync(file).isFile()) usage('checks-invalid', `checks file '${file}' is not a regular file`);
+    data = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+  } catch (error     ) {
+    if (error instanceof WorkerEvidenceError) throw error;
+    usage('checks-invalid', `checks file '${file}' cannot be read: ${error?.code || error?.message || String(error)}`);
+  }
+  return data;
+}
+
+function lines(stdout     )           {
+  const value         = Buffer.isBuffer(stdout) ? stdout.toString('utf8') : String(stdout ?? '');
+  return value.split('\n').map((line        ) => line.replace(/\r$/, ''));
+}
+
+function runBounded(binary        , argv          , { env, cwd, spawnSyncImpl }     ) {
+  try {
+    return spawnSyncImpl(binary, argv, {
+      env,
+      cwd,
+      shell: false,
+      timeout: readiness.PROBE_TIMEOUT_MS,
+      maxBuffer: PROBE_STDOUT_MAX,
+      encoding: 'buffer',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error     ) {
+    return { status: null, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), error };
+  }
+}
+
+function matchedLines(outputLines          , patterns          )           {
+  const matches           = [];
+  for (const line of outputLines) {
+    if (!patterns.some((pattern) => pattern.test(line))) continue;
+    const safe = maskBody(line).text.slice(0, MATCHED_LINE_CHARS);
+    matches.push(safe);
+    if (matches.length >= MAX_MATCHED_LINES) break;
+  }
+  return matches;
+}
+
+function sorted(value     )      {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    const out                      = {};
+    for (const key of Object.keys(value).sort()) out[key] = sorted(value[key]);
+    return out;
+  }
+  return value;
+}
+
+function outPathAndCheck(out        , cwd        , fsImpl     )         {
+  if (typeof out !== 'string' || out === '') usage('out-required', '--out is required');
+  const target = path.resolve(cwd, out);
+  try {
+    if (fsImpl.existsSync(target)) usage('out-exists', `--out '${target}' already exists`);
+  } catch (error     ) {
+    if (error instanceof WorkerEvidenceError) throw error;
+    usage('out-unavailable', `--out '${target}' cannot be checked: ${error?.message || String(error)}`);
+  }
+  return target;
+}
+
+function writeRecord(record     , target        , fsImpl     ) {
+  try {
+    fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+    fsImpl.writeFileSync(target, `${JSON.stringify(sorted(record), null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+  } catch (error     ) {
+    if (error?.code === 'EEXIST') usage('out-exists', `--out '${target}' already exists`);
+    usage('out-write-failed', `evidence file '${target}' could not be written: ${error?.code || error?.message || String(error)}`);
+  }
+  return { disposition: 'recorded', path: target, establishes: record.establishes };
+}
+
+function dateValue(now     )         {
+  const value = typeof now === 'function' ? now() : now;
+  const date = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(date.getTime())) usage('clock-invalid', 'recordedAt clock is invalid');
+  return date.toISOString();
+}
+
+/** Runs a declared free-check file against the named harness binary and writes an IC-005 record. */
+function recordCliChecks({ checksFile, harness, worker, out, cwd = process.cwd(), env = process.env,
+  now = () => new Date(), platform = process.platform, fsImpl = fs, spawnSyncImpl = spawnSync }      = {}) {
+  const target = outPathAndCheck(out, cwd, fsImpl);
+  const checks = validateChecks(readChecks(path.resolve(cwd, String(checksFile)), fsImpl), harness, worker);
+  const binaryPath = readiness.findOnPath(checks.binary, env, platform);
+  if (!binaryPath) refuse('version-unmatched');
+
+  const versionExpect = expression(checks.version.expect, 'version.expect');
+  const versionResult = runBounded(binaryPath, checks.version.argv, { env, cwd, spawnSyncImpl });
+  const versionLines = lines(`${versionResult.stdout ?? ''}\n${versionResult.stderr ?? ''}`);
+  const versionMatch = versionLines.find((line) => versionExpect.test(line));
+  if (versionResult.status !== 0 || !versionMatch) refuse('version-unmatched');
+
+  const cliVersion = maskBody(versionMatch).text.slice(0, MATCHED_LINE_CHARS);
+  const recordedChecks = checks.checks.map((check     ) => {
+    const patterns = check.expect.map((pattern        , index        ) => expression(pattern, `check '${check.id}' expect[${index}]`));
+    const result = runBounded(binaryPath, check.argv, { env, cwd, spawnSyncImpl });
+    const outputLines = lines(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+    const allExpectationsMatched = patterns.every((pattern        ) => outputLines.some((line) => pattern.test(line)));
+    return {
+      id: check.id,
+      argv: [...check.argv],
+      exit: Number.isInteger(result.status) ? result.status : null,
+      expect: [...check.expect],
+      matched: matchedLines(outputLines, patterns),
+      result: result.status === 0 && allExpectationsMatched ? 'pass' : 'fail',
+      establishes: [...check.establishes],
+    };
+  });
+  const establishes = [...new Set(recordedChecks
+    .filter((check     ) => check.result === 'pass')
+    .flatMap((check     ) => check.establishes))].sort();
+  const record = {
+    schema: EVIDENCE_SCHEMA,
+    harness,
+    kind: 'cli-check',
+    recordedAt: dateValue(now),
+    binary: checks.binary,
+    cliVersion,
+    establishes,
+    checks: recordedChecks,
+    run: null,
+  };
+  return writeRecord(record, target, fsImpl);
+}
+
+/** Records an ended run without retaining prompt, environment, output or summary contents. */
+function recordLiveRun({ run, harness, worker, out, cwd = process.cwd(), now = () => new Date(), fsImpl = fs }      = {}) {
+  const target = outPathAndCheck(out, cwd, fsImpl);
+  if (!run) refuse('unknown-run');
+  if (run.phase !== 'ended') refuse('run-not-ended');
+  if (run.harness !== harness) refuse('harness-mismatch');
+  const stdoutBytes = Number(run.output?.stdout?.bytes);
+  if (!Number.isFinite(stdoutBytes) || stdoutBytes <= 0) refuse('no-output');
+  if (!run.report || !['success', 'failure', 'denied'].includes(run.report.status)) refuse('no-terminal-event');
+
+  const { resultOffered, withheld } = resultOfRun(run);
+  const edit = Boolean(run.edit);
+  const establishes = resultOffered
+    ? ['oneShot', 'structuredOutput', 'spawnDenial', edit ? 'isolatedEdit' : 'readOnly']
+    : [];
+  const record = {
+    schema: EVIDENCE_SCHEMA,
+    harness,
+    kind: 'live-run',
+    recordedAt: dateValue(now),
+    binary: run.recipe?.binary ?? run.descriptor?.cli?.binary ?? worker?.cli?.binary ?? null,
+    cliVersion: typeof run.cliVersion === 'string' ? run.cliVersion : '',
+    establishes,
+    checks: [],
+    run: {
+      runId: run.runId,
+      edit,
+      argvShape: run.recipe?.argvShape ?? [],
+      parser: run.recipe?.parser ?? run.report?.parser ?? null,
+      report: {
+        status: run.report.status,
+        reason: run.report.reason ?? null,
+        deniedCount: run.report.deniedCount ?? 0,
+        usage: run.report.usage ?? null,
+      },
+      isolation: edit ? run.isolation ?? null : null,
+      readOnly: edit ? null : run.readOnly ?? null,
+      resultOffered,
+      withheld,
+      stdoutBytes,
+      exit: Number.isInteger(run.process?.code) ? run.process.code : null,
+    },
+  };
+  return writeRecord(record, target, fsImpl);
+}
+
+module.exports = { recordCliChecks, recordLiveRun, WorkerEvidenceError, CHECKS_SCHEMA, EVIDENCE_SCHEMA };

package/src/runtime/worker/launch.js

@@ -0,0 +1,256 @@
+'use strict';
+
+// Feature 081 B.3 (IC-003, IC-012; DEC-030, DEC-037, DEC-045): the real launcher.
+//
+// `launchEnv` names the worker in the caller's environment: the caller's variables are inherited
+// unchanged (DEC-045), except for the five identity variables and DOFLOW_WORKER_RUN. The run segment of
+// the claim's run key is the worker's run, or, when that segment is the default `local`, the run
+// id without its `w-` prefix (DEC-037), so the worker always resolves to a launched identity and
+// its 078 unit `L.<run>.<lineage>.<token>` is unique to this run. A child run (082 IC-015) is
+// always run-scoped, so its unit differs from its granter's.
+//
+// `assembleArgv` builds the IC-003 argv: `readOnly`, `spawnDenial`, `structuredOutput` and
+// `oneShot` argv in that order (082 IC-014: an edit run puts `isolatedEdit` first in place of
+// `readOnly`). 120 IC-011 inserts `model` second only for a supported binding. The `{prompt}`,
+// `{lastMessageFile}` and `{model}` elements are replaced whole, never inside a longer string.
+// `argvShape` writes the prompt as `<prompt sha256:<hex> bytes:<n>>`, the output path as
+// `<last-message-file>` and the model as the original `{model}` placeholder.
+//
+// `launchWorker` runs IC-012 steps 1 to 5: the environment, the optional 078 grant, the launch
+// emission in process, the emission text before the brief, then `spawn` with no shell. It returns a
+// promise that resolves once the process has spawned and rejects on any throw or a spawn `error`
+// (for example ENOENT); the supervisor ends such a run `not-started`. No variable's value is stored,
+// and the emission text is never returned for storage.
+
+const crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+const { emitContext, utf8Bytes } = require('../context/arbitrate.js');
+const { grantSummary } = require('../context/summary-store.js');
+
+                                              
+/** 120 IC-011 / IC-012: the binding shape consumed by the recipe assembler. */
+                                                                                        
+
+/** IC-012: the names a launch may set, in the order the run record lists them. The first five are the
+ * identity contract; `DOFLOW_WORKER_RUN` (110) carries the worker run id `w-<12 hex>` and nothing else,
+ * so the worker's telemetry can name its own run. It is not part of the stored identity. */
+const WORKER_RUN_VAR = 'DOFLOW_WORKER_RUN';
+const ENV_SET = Object.freeze(['DOFLOW_RUN_ID', 'DOFLOW_LINEAGE_ID', 'DOFLOW_ATTEMPT', 'DOFLOW_SESSION_ROLE', 'DOFLOW_WORKTREE', WORKER_RUN_VAR]);
+const PROMPT_ELEMENT = '{prompt}';
+const LAST_MESSAGE_FILE_ELEMENT = '{lastMessageFile}';
+const MODEL_ELEMENT = '{model}';
+/** IC-003 prompt limits in bytes. argv is one under Linux MAX_ARG_STRLEN, which counts the NUL (DEC-062). */
+const PROMPT_LIMITS = Object.freeze({ argv: 131071, stdin: 1048576 });
+const DEFAULT_RUN = 'local';
+const RUN_ID = /^w-[0-9a-f]{12}$/;
+/** IC-003 / 120 IC-011: order of the run recipe's argv; model is conditional on its binding. */
+const RECIPE_ORDER = Object.freeze(['readOnly', 'model', 'spawnDenial', 'structuredOutput', 'oneShot']);
+/** 082 IC-014 / 120 IC-011: the order of an edit run's recipe argv. */
+const EDIT_RECIPE_ORDER = Object.freeze(['isolatedEdit', 'model', 'spawnDenial', 'structuredOutput', 'oneShot']);
+
+                          
+              
+                  
+                  
+                                    
+ 
+
+/** A caller error, not a refusal: exit 2 `usage` with `reason`. */
+class LaunchUsageError extends Error {
+                       
+                         
+  constructor(reason        , message        ) {
+    super(message);
+    this.name = 'LaunchUsageError';
+    this.code = reason;
+    this.reason = reason;
+  }
+}
+
+/** The five identity variables and the optional worker run id. The run id replaces (or removes) the
+ * caller's value; the caller's environment is never mutated. */
+function withIdentity(env     , identity                , execWorktree        , runId         )      {
+  if (runId !== undefined && !RUN_ID.test(runId)) throw new LaunchUsageError('run-id-malformed', `launch: run id must match ${RUN_ID}: ${runId}`);
+  const out      = {
+    ...env,
+    DOFLOW_RUN_ID: identity.run,
+    DOFLOW_LINEAGE_ID: identity.lineage,
+    DOFLOW_ATTEMPT: identity.attempt,
+    DOFLOW_SESSION_ROLE: 'worker',
+    DOFLOW_WORKTREE: execWorktree,
+  };
+  if (runId !== undefined) out[WORKER_RUN_VAR] = runId;
+  else delete out[WORKER_RUN_VAR];
+  // 120 IC-003: the primary declaration names the person's main session, never a worker.
+  delete out.DOFLOW_PRIMARY_HARNESS;
+  delete out.DOFLOW_PRIMARY_MODEL;
+  return out;
+}
+
+/** IC-012: the worker environment and identity from the claim's run key `<hash>/<run>/<lineage>`.
+ * `runScoped` (082 IC-015, a child run) takes the run id as the run whatever the claim's run is. */
+function launchEnv({ env, runKey, token, execWorktree, runId, runScoped = false }                                                                                                                )                                         {
+  const segments = String(runKey).split('/');
+  if (segments.length !== 3 || segments.some((s) => s === '')) throw new LaunchUsageError('run-key-malformed', `launchEnv: run key must be <hash>/<run>/<lineage>: ${runKey}`);
+  const [, claimRun, lineage] = segments;
+  let identity                ;
+  if (claimRun === DEFAULT_RUN || runScoped) {
+    if (!RUN_ID.test(runId)) throw new LaunchUsageError('run-id-malformed', `launchEnv: run id must match ${RUN_ID}: ${runId}`);
+    identity = { run: runId.slice(2), lineage, attempt: String(token), runSource: 'run-scoped' };
+  } else {
+    identity = { run: claimRun, lineage, attempt: String(token), runSource: 'claim' };
+  }
+  return { env: withIdentity(env, identity, execWorktree, runId), identity };
+}
+
+/** 120 IC-011: only a supported binding supplies a non-empty model element. */
+function boundModel(binding                      )                {
+  if (binding?.flag !== 'supported') return null;
+  if (typeof binding.model !== 'string' || binding.model.length === 0) {
+    throw new LaunchUsageError('model-invalid', 'assembleArgv: a supported model binding requires a non-empty model string');
+  }
+  return binding.model;
+}
+
+/** IC-003 / 120 IC-011: replace prompt, output path and bound model only as whole elements. */
+function assemble(recipe     , element        , edit = false, lastMessageFile         , binding                      )           {
+  const model = boundModel(binding);
+  const argv           = [];
+  for (const key of edit ? EDIT_RECIPE_ORDER : RECIPE_ORDER) {
+    if (key === 'model' && model === null) continue;
+    const entry = recipe?.[key];
+    if (!entry || entry.status !== 'supported' || !Array.isArray(entry.argv)) {
+      throw new LaunchUsageError('recipe-incomplete', `assembleArgv: worker '${key}' is not supported with an argv`);
+    }
+    argv.push(...entry.argv);
+  }
+  return argv.map((value) => {
+    if (value === LAST_MESSAGE_FILE_ELEMENT) {
+      if (lastMessageFile === undefined) {
+        throw new LaunchUsageError('last-message-file-missing', "assembleArgv: worker recipe needs a '{lastMessageFile}' output path");
+      }
+      return lastMessageFile;
+    }
+    if (value === MODEL_ELEMENT && model !== null) return model;
+    if (value === PROMPT_ELEMENT && recipe.oneShot.promptVia === 'argv') return element;
+    return value;
+  });
+}
+
+function promptVia(recipe     )                   {
+  return recipe?.oneShot?.promptVia === 'stdin' ? 'stdin' : 'argv';
+}
+
+/** IC-003: the worker argv for `prompt`; a prompt over its mode's limit is `prompt-too-large`.
+ * `edit` selects the edit recipe order (082 IC-014); 120 IC-011 optionally inserts the bound model. */
+function assembleArgv(recipe     , prompt        , edit = false, lastMessageFile         , binding                      )           {
+  const mode = promptVia(recipe);
+  const bytes = Buffer.byteLength(prompt, 'utf8');
+  if (bytes > PROMPT_LIMITS[mode]) {
+    throw new LaunchUsageError('prompt-too-large', `assembleArgv: the prompt is ${bytes} bytes; ${mode} mode allows ${PROMPT_LIMITS[mode]}`);
+  }
+  return assemble(recipe, prompt, edit, lastMessageFile, binding);
+}
+
+/** IC-003 / 120 IC-011: the stored shape hashes the prompt and preserves the model placeholder. */
+function argvShape(recipe     , prompt        , edit = false, binding                      )           {
+  const hex = crypto.createHash('sha256').update(prompt, 'utf8').digest('hex');
+  const shapeBinding                                  = boundModel(binding) === null
+    ? binding : { model: MODEL_ELEMENT, flag: 'supported' };
+  return assemble(recipe, `<prompt sha256:${hex} bytes:${Buffer.byteLength(prompt, 'utf8')}>`, edit, '<last-message-file>', shapeBinding);
+}
+
+/** IC-012 / data-model §1: the launch fields a run record stores. Names only, never a value. */
+function launchRecord(recipe     , identity                , prompt        , edit = false, binding                      ) {
+  return {
+    identity: { run: identity.run, lineage: identity.lineage, attempt: identity.attempt, runSource: identity.runSource },
+    recipe: {
+      binary: recipe.cli.binary,
+      argvShape: argvShape(recipe, prompt, edit, binding),
+      promptVia: promptVia(recipe),
+      parser: recipe.structuredOutput.parser,
+      profile: recipe.profile ?? null,
+    },
+    envSet: [...ENV_SET],
+    envInherited: true,
+  };
+}
+
+                         
+              
+                 
+                           
+                       
+           
+                  
+                                  
+                                                       
+                 
+                                                                              
+                           
+                                                                                                             
+                 
+                                                                    
+                                
+ 
+
+/** IC-012 steps 1 to 5. Resolves `{ child, env, launched: { reason, bytes } }` once the process has spawned. */
+function launchWorker({ recipe, prompt, identity, execWorktree, env, taskId, grant, edit = false, lastMessageFile, runId, binding }               )               {
+  return new Promise((resolve, reject) => {
+    const workerEnv = withIdentity(env, identity, execWorktree, runId);
+    if (grant) grantSummary({ ...grant, toRun: identity.run, toLineage: identity.lineage, env });
+    const emitted = emitContext({ event: 'launch', cwd: execWorktree, env: workerEnv, ...(taskId ? { taskId } : {}) });
+    const reason         = emitted.decision.reason;
+    // DEC-052: any returned text is delivered, a refused emission's included (it carries the pack and the pointer).
+    const delivered = typeof emitted.text === 'string' ? emitted.text : null;
+    const text = delivered !== null ? `${delivered}\n\n${prompt}` : prompt;
+    const launched = { reason, bytes: delivered !== null ? utf8Bytes(delivered) : 0 };
+    const argv = assembleArgv(recipe, text, edit, lastMessageFile, binding);
+    const viaStdin = promptVia(recipe) === 'stdin';
+    if (recipe?.structuredOutput?.parser) {
+      const { PARSERS } = require('./parsers.js');
+      if (!Object.hasOwn(PARSERS, recipe.structuredOutput.parser)) {
+        throw new LaunchUsageError('parser-unknown', `launchWorker: parser '${recipe.structuredOutput.parser}' is not in core PARSERS`);
+      }
+    }
+    let file = recipe.cli?.binary;
+    let spawnArgs = argv;
+    let spawnOptions      = {
+      cwd: execWorktree,
+      env: workerEnv,
+      detached: true,
+      shell: false,
+      stdio: [viaStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+    };
+    if (recipe.program && recipe.storeEntry) {
+      const { launchSpec } = require('../packages/programs.js');
+      const spec = launchSpec({
+        program: recipe.program,
+        storeEntry: recipe.storeEntry,
+        recipeArgv: argv,
+        cwd: execWorktree,
+        env: workerEnv,
+      });
+      file = spec.file;
+      spawnArgs = spec.args;
+      spawnOptions = {
+        ...spec.options,
+        detached: true,
+        stdio: [viaStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+      };
+    }
+    const child = spawn(file, spawnArgs, spawnOptions);
+    // Kept attached: a reject after the resolve is a no-op, and an early error never goes unhandled.
+    child.on('error', reject);
+    child.once('spawn', () => {
+      if (viaStdin) {
+        // A worker that exits before reading closes the pipe; its exit is what the supervisor records.
+        child.stdin.on('error', () => {});
+        child.stdin.end(text);
+      }
+      resolve({ child, env: workerEnv, launched });
+    });
+  });
+}
+
+module.exports = { ENV_SET, PROMPT_LIMITS, RECIPE_ORDER, EDIT_RECIPE_ORDER, LaunchUsageError, argvShape, assembleArgv, launchEnv, launchRecord, launchWorker };