@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/dispatch/envelope.js

@@ -0,0 +1,276 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Handoff and result envelopes (feature 082, IC-010, IC-011, IC-012).
+ *
+ *   - `buildHandoff` and `buildResult` are pure: every list arrives as input, so no git call, file
+ *     read or environment read happens here (DEC-005). Neither envelope carries a transcript, an
+ *     environment value or a verification argv (NFR-006).
+ *   - `undeclared` is the changed paths, rename and copy sources included, outside the task's
+ *     `files:` after trimming and dropping a leading `./` (DEC-033). The normalization is this
+ *     module's own copy of `task-graph.ts`'s private `normalizeFile`, so that 080 file stays
+ *     byte-identical (DEC-059).
+ *   - `writeEnvelope` writes canonical JSON (keys sorted, no whitespace), so the file's byte size is
+ *     the bound it checks: 16384 for a handoff, 32768 for a result (DEC-027). Over the bound, lists
+ *     are cut in IC-012's fixed order, each to the longest prefix that fits, the tail going to a
+ *     sidecar named by an `overflow` entry; then `task.text` or `summary` is cut on a UTF-8
+ *     boundary. Every write is a temporary file in the same directory, then a rename.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { maskLine } = require('../mask.js');
+
+const ENVELOPE_DIR = 'dispatch-envelopes';
+const BOUNDS                         = { handoff: 16384, result: 32768 };
+/** IC-012: the cut order, each list cut to its longest fitting prefix before the next is touched. */
+const CUT_ORDER                           = {
+  handoff: ['sources', 'deltas.changes', 'acceptance'],
+  result: ['changes', 'undeclared', 'evidence', 'blockers'],
+};
+const TEXT_BYTES = 2000;
+const CUT_MARK = '[cut]';
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)*$/;
+
+/** IC-010: the fixed loop rules every handoff begins with, in this order. */
+const FIXED_CONSTRAINTS = [
+  'edit only inside worktree.path',
+  'leave worktree.branch checked out',
+  'do not push, fetch or change git config',
+  'write nothing outside the worktree',
+  'spawn children only through dispatch --action spawn within grant',
+];
+
+/** IC-012: JSON with object keys sorted at every level and no whitespace; 080's `canonicalJson`
+ * (`task-run.ts`, not exported), copied. */
+function canonical(value     )         {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}
+
+/** DEC-059: a `files:` entry compared after trimming and dropping a leading `./` (copy of
+ * `task-graph.ts`'s module-private `normalizeFile`). */
+function normalizeFile(file        ) {
+  return String(file).trim().replace(/^(\.\/)+/, '');
+}
+
+/** The longest prefix of `text` that is at most `maxBytes` UTF-8 bytes and ends on a character. */
+function cutUtf8(text        , maxBytes        )         {
+  const buf = Buffer.from(String(text), 'utf8');
+  if (buf.length <= maxBytes) return String(text);
+  let end = Math.max(0, maxBytes);
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end -= 1;
+  return buf.subarray(0, end).toString('utf8');
+}
+
+function bytesOf(value     )         {
+  return Buffer.byteLength(canonical(value), 'utf8');
+}
+
+/** IC-010: the repository-relative artifact whose index carries an acceptance id. */
+function acceptanceSource(slug        , id        )         {
+  const base = `agent-docs/doflow/${slug}`;
+  return /^IC-/.test(id) ? `${base}/design/specs.md` : `${base}/intention/requirement.md`;
+}
+
+/** IC-010. `input.acceptance` is the task's acceptance ids; every other list is taken as given. */
+function buildHandoff(input     ) {
+  const task = input.task || {};
+  const files = Array.isArray(task.files) ? task.files.map(String) : [];
+  const writeSet = files.length ? `files: ${files.join(', ')}` : 'files: none declared';
+  return {
+    schema: 'doflow-handoff-v1',
+    dispatchId: input.dispatchId,
+    dispatchRunId: input.dispatchRunId,
+    slug: input.slug,
+    mode: input.mode,
+    task: {
+      id: task.id,
+      phase: task.phase,
+      owner: task.owner == null ? null : task.owner,
+      text: cutUtf8(maskLine(task.text == null ? '' : task.text).text, TEXT_BYTES),
+      files,
+      dependsOn: Array.isArray(task.dependsOn) ? task.dependsOn.map(String) : [],
+    },
+    constraints: [...FIXED_CONSTRAINTS, writeSet],
+    acceptance: (input.acceptance || []).map((id        ) => ({ id: String(id), source: acceptanceSource(input.slug, String(id)) })),
+    sources: (input.sources || []).map((s     ) => ({ path: s.path, sha256: s.sha256 == null ? null : s.sha256 })),
+    deltas: {
+      runBase: input.deltas && input.deltas.runBase,
+      attemptBase: input.deltas && input.deltas.attemptBase,
+      changes: ((input.deltas && input.deltas.changes) || []).map((c     ) => ({
+        path: c.path, change: c.change, dispatchId: c.dispatchId == null ? null : c.dispatchId,
+      })),
+    },
+    budget: {
+      reserveTokens: input.budget && input.budget.reserveTokens != null ? input.budget.reserveTokens : null,
+      attemptSeconds: input.budget && input.budget.attemptSeconds != null ? input.budget.attemptSeconds : null,
+      attempts: { used: input.budget.attempts.used, limit: input.budget.attempts.limit },
+    },
+    grant: input.grant ? { depth: input.grant.depth, children: input.grant.children, tokens: input.grant.tokens } : null,
+    worktree: { path: input.worktree.path, branch: input.worktree.branch, base: input.worktree.base },
+    report: {
+      parser: input.report && input.report.parser ? input.report.parser : null,
+      spawn: input.report && Array.isArray(input.report.spawn) ? input.report.spawn.map(String) : null,
+    },
+    overflow: [],
+  };
+}
+
+/** IC-011: changed paths, rename and copy sources included, outside the task's normalized files. */
+function undeclaredChanges(changes       , files       )           {
+  const declared = new Set((files || []).map(normalizeFile).filter(Boolean));
+  const out           = [];
+  const seen = new Set        ();
+  for (const change of changes) {
+    for (const p of [change.from, change.path]) {
+      if (p == null) continue;
+      const file = normalizeFile(p);
+      if (!file || declared.has(file) || seen.has(file)) continue;
+      seen.add(file);
+      out.push(file);
+    }
+  }
+  return out;
+}
+
+/** IC-011. `input.files` is the task's declared `files:`; `changes` come from git, computed by the
+ * caller over the attempt commit. `summary` arrives masked and is cut to 2000 bytes here. */
+function buildResult(input     ) {
+  const changes = (input.changes || []).map((c     ) => ({ path: c.path, change: c.change, from: c.from == null ? null : c.from }));
+  return {
+    schema: 'doflow-result-v1',
+    dispatchId: input.dispatchId,
+    task: input.task,
+    token: input.token,
+    epoch: input.epoch,
+    mode: input.mode,
+    outcome: input.outcome,
+    staleReason: input.staleReason == null ? null : input.staleReason,
+    failureClass: input.failureClass == null ? null : input.failureClass,
+    summary: cutUtf8(input.summary == null ? '' : String(input.summary), TEXT_BYTES),
+    status: input.status,
+    base: input.base,
+    commit: input.commit == null ? null : input.commit,
+    changes,
+    undeclared: undeclaredChanges(changes, input.files),
+    evidence: (input.evidence || []).map((e     ) => ({ id: e.id, kind: 'test-result', exitCode: e.exitCode == null ? null : e.exitCode })),
+    blockers: (input.blockers || []).map(String),
+    usage: { tokens: input.usage.tokens, basis: input.usage.basis, source: input.usage.source },
+    workerRun: input.workerRun
+      ? { id: input.workerRun.id, output: input.workerRun.output ? { stdout: input.workerRun.output.stdout, stderr: input.workerRun.output.stderr } : null }
+      : null,
+    isolation: input.isolation ? { status: input.isolation.status, reasons: (input.isolation.reasons || []).map(String) } : null,
+    overflow: [],
+  };
+}
+
+function getList(value     , list        )        {
+  return list.split('.').reduce((node     , key        ) => node[key], value);
+}
+
+function setList(value     , list        , items       ) {
+  const keys = list.split('.');
+  const last = keys.pop()          ;
+  keys.reduce((node     , key        ) => node[key], value)[last] = items;
+}
+
+/** Writes `text` to `file` through a temporary file in the same directory, then a rename. */
+function writeAtomic(file        , text        ) {
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* the original error is the one reported */ }
+    throw err;
+  }
+}
+
+/**
+ * IC-012. Writes `value` (a built envelope) to `<stateRoot>/dispatch-envelopes/<dispatchId>.<kind>.json`
+ * in canonical form within its bound, sidecars first. Returns `{ path, pointer, bytes, overflow,
+ * sidecars }`; `pointer` and each sidecar pointer are relative to `stateRoot`.
+ */
+function writeEnvelope({ stateRoot, dispatchId, kind, value }                                                                     ) {
+  if (!(kind in BOUNDS)) throw new TypeError(`unknown envelope kind '${kind}'`);
+  if (typeof dispatchId !== 'string' || !SAFE_ID.test(dispatchId)) throw new TypeError(`invalid dispatch id '${dispatchId}'`);
+  const bound = BOUNDS[kind];
+  const envelope = JSON.parse(canonical(value));
+  if (!Array.isArray(envelope.overflow)) envelope.overflow = [];
+  const sidecars                                                         = [];
+
+  for (const list of CUT_ORDER[kind]) {
+    if (bytesOf(envelope) <= bound) break;
+    const items = getList(envelope, list);
+    if (!items.length) continue;
+    const pointer = `${ENVELOPE_DIR}/${dispatchId}.${list.replace(/\./g, '-')}.json`;
+    const entry = { list, pointer, total: items.length, kept: 0 };
+    envelope.overflow.push(entry);
+    const fits = (k        ) => {
+      setList(envelope, list, items.slice(0, k));
+      entry.kept = k;
+      return bytesOf(envelope) <= bound;
+    };
+    // Longest fitting prefix: size grows with the prefix length, so a binary search finds it.
+    let lo = 0;
+    let hi = items.length;
+    while (lo < hi) {
+      const mid = Math.ceil((lo + hi) / 2);
+      if (fits(mid)) lo = mid; else hi = mid - 1;
+    }
+    fits(lo);
+    sidecars.push({ list, pointer, items: items.slice(lo) });
+  }
+
+  if (bytesOf(envelope) > bound) {
+    const holder = kind === 'handoff' ? envelope.task : envelope;
+    const field = kind === 'handoff' ? 'text' : 'summary';
+    const mark = kind === 'result' ? CUT_MARK : '';
+    const original = String(holder[field]);
+    const fits = (n        ) => {
+      holder[field] = cutUtf8(original, n) + mark;
+      return bytesOf(envelope) <= bound;
+    };
+    let lo = 0;
+    let hi = Buffer.byteLength(original, 'utf8');
+    while (lo < hi) {
+      const mid = Math.ceil((lo + hi) / 2);
+      if (fits(mid)) lo = mid; else hi = mid - 1;
+    }
+    if (!fits(lo)) throw new Error(`${kind} envelope for ${dispatchId} exceeds ${bound} bytes with every list and its text cut`);
+  }
+
+  const dir = path.join(stateRoot, ENVELOPE_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  for (const sidecar of sidecars) writeAtomic(path.join(stateRoot, sidecar.pointer), canonical(sidecar.items));
+  const text = canonical(envelope);
+  const file = path.join(dir, `${dispatchId}.${kind}.json`);
+  writeAtomic(file, text);
+  return {
+    path: file,
+    pointer: `${ENVELOPE_DIR}/${dispatchId}.${kind}.json`,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    overflow: envelope.overflow,
+    sidecars: sidecars.map((s) => s.pointer),
+  };
+}
+
+module.exports = {
+  ENVELOPE_DIR,
+  BOUNDS,
+  CUT_ORDER,
+  FIXED_CONSTRAINTS,
+  canonical,
+  normalizeFile,
+  cutUtf8,
+  buildHandoff,
+  buildResult,
+  writeEnvelope,
+};

package/src/runtime/dispatch/grants.js

@@ -0,0 +1,310 @@
+'use strict';
+
+// Feature 082 C.2 (IC-033 declaration, request and status; DEC-008, DEC-028, DEC-041, DEC-051,
+// DEC-062): spawn grants and the `spawn` action. Run directly by Node native type-stripping.
+//
+//   - `validateGrant` checks `dispatch start --spawn-grant` against `--reserve-tokens`; `copyGrant`
+//     gives the copy each subagent dispatch carries, with its own `used` counters.
+//   - `requestSpawn` runs IC-033's refusals in order. Steps 1 to 3 and every read (the prompt, the
+//     080 run's control, real paths) happen before the lock; steps 4 to 10 and the request's record
+//     run inside one `mutateDispatch`, so a refusal writes nothing. The prompt copy
+//     `dispatch-envelopes/<d-id>.c<n>.prompt.txt` is written after that lock, by temp file then
+//     rename: this is one of the three dispatch modules allowed a direct fs write (IC-037).
+//   - `spawnStatus` runs steps 1 to 4 over an unlocked read and reports a request of the caller's
+//     own dispatch.
+//
+// Launching the child is the loop's (IC-033 launch, C.3): it moves a request from `requested` to
+// `launched` or `refused`, records `childRunId` and the child's `identity`, and sets `endState`
+// (and `report`) when the child run ends. A request counts toward `grant.children` until it is
+// `refused` or has an `endState`. Spawns a harness makes through its own subagent tool are
+// invisible here; only this action is bounded (DEC-008).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { readTaskState } = require('../task-state.js');
+const { storeFile: attemptStoreFile } = require('../task-attempts.js');
+const { resolveIdentity } = require('../context/identity.js');
+const { projectRoot } = require('../lifecycle/root.js');
+const { storeFileFor, readDispatch, mutateDispatch, DispatchStoreError } = require('./store.js');
+const { ENVELOPE_DIR } = require('./envelope.js');
+
+const MAX_DEPTH = 1;
+const MAX_CHILDREN = 4;
+const GRANT_KEYS = Object.freeze(['depth', 'children', 'tokens']);
+const WORKTREE_DIR = 'dispatch-worktrees';
+const REQUEST_ID = /^(d-[0-9a-f]{12})\.c([1-9][0-9]*)$/;
+const WHOLE = /^[0-9]+$/;
+
+                                              
+                                                                   
+
+function usage(message        ) {
+  return new DispatchStoreError('usage', message);
+}
+
+/** A whole number given as an integer or a `^[0-9]+$` string, else null. */
+function whole(value     )                {
+  if (Number.isInteger(value) && value >= 0) return value;
+  if (typeof value === 'string' && WHOLE.test(value)) {
+    const n = Number(value);
+    if (Number.isSafeInteger(n)) return n;
+  }
+  return null;
+}
+
+/**
+ * IC-033 declaration. `grant` is the `--spawn-grant` JSON text or its parsed object; returns
+ * `{ depth, children, tokens }`, or throws `usage` (exit 2). `depth` 0 or 1, `children` 0 to 4,
+ * `tokens` a whole number no larger than `reserveTokens`; a run started without `--reserve-tokens`
+ * can grant no tokens, since the carve has nothing to be carved from.
+ */
+function validateGrant(grant     , reserveTokens      = null)        {
+  let value = grant;
+  if (typeof grant === 'string') {
+    try { value = JSON.parse(grant); } catch { throw usage('--spawn-grant is not valid JSON'); }
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw usage('--spawn-grant must be a JSON object {depth, children, tokens}');
+  const extra = Object.keys(value).filter((k) => !GRANT_KEYS.includes(k));
+  if (extra.length) throw usage(`--spawn-grant has unknown field '${extra[0]}'`);
+  const { depth, children, tokens } = value;
+  if (depth !== 0 && depth !== 1) throw usage(`--spawn-grant depth must be 0 or ${MAX_DEPTH}`);
+  if (!Number.isInteger(children) || children < 0 || children > MAX_CHILDREN) throw usage(`--spawn-grant children must be 0 to ${MAX_CHILDREN}`);
+  if (!Number.isSafeInteger(tokens) || tokens < 0) throw usage('--spawn-grant tokens must be a whole number');
+  const reserve = reserveTokens == null ? null : whole(reserveTokens);
+  if (reserveTokens != null && reserve === null) throw usage('--reserve-tokens must be a whole number');
+  if (tokens > (reserve ?? 0)) throw usage(`--spawn-grant tokens ${tokens} exceeds --reserve-tokens ${reserve ?? 'absent'}`);
+  return { depth, children, tokens };
+}
+
+/** DEC-051: the grant a dispatch carries, its own counters at zero; null for a main-session
+ * dispatch or a run with no grant. */
+function copyGrant(runGrant              , mode        ) {
+  if (!runGrant || mode !== 'subagent') return null;
+  return { depth: runGrant.depth, children: runGrant.children, tokens: runGrant.tokens, used: { children: 0, tokens: 0 } };
+}
+
+function real(p        )         {
+  try { return fs.realpathSync.native(p); } catch { return path.resolve(p); }
+}
+
+function refused(reason        , extra                      = {}) {
+  return { disposition: 'refused', reason, ...extra };
+}
+
+/** Steps 1 and 2: the caller's identity, or a refusal. */
+function callerOf(env     , cwd        )      {
+  const id = resolveIdentity(env, { cwd, sessionId: '' });
+  if (id.role !== 'worker') return { refusal: refused('not-worker-session') };
+  if (id.lineageKind !== 'launched' || !env.DOFLOW_WORKTREE) return { refusal: refused('identity-incomplete') };
+  return { caller: { run: id.run, lineage: id.lineage, attempt: id.attempt, worktree: real(env.DOFLOW_WORKTREE) } };
+}
+
+function sameIdentity(a     , b     )          {
+  return !!a && a.run === b.run && a.lineage === b.lineage && String(a.attempt) === String(b.attempt);
+}
+
+/** The child worktree a request names (IC-016), real path when it exists. */
+function childWorktree(root        , requestId        )         {
+  return real(path.join(root, '.doflow', 'state', WORKTREE_DIR, requestId));
+}
+
+/** Real paths of every dispatch's attempt worktree and every request's child worktree (keyed
+ * `child:<id>`), read before the lock so `decide` does no I/O. */
+function realPaths(store     , root        )                      {
+  const out = new Map();
+  for (const d of Object.values(store.dispatches)         ) {
+    const p = d.attempt && d.attempt.worktree;
+    if (typeof p === 'string' && !out.has(p)) out.set(p, real(p));
+  }
+  for (const id of Object.keys(store.spawnRequests)) out.set(`child:${id}`, childWorktree(root, id));
+  return out;
+}
+
+function liveChild(request     )          {
+  return request.state !== 'refused' && request.endState == null;
+}
+
+/**
+ * Step 4. Every non-ended dispatch whose recorded worker identity equals the caller's and whose
+ * attempt worktree is the caller's by real path, plus, with `children`, every live request of a
+ * non-ended dispatch whose child worktree is the caller's (matched so step 5 can name it). The
+ * worktree is part of the match: two workers of one launched main session share run, lineage and
+ * attempt (DEC-041).
+ */
+function matchCaller(store     , caller     , paths                     , root        , children         ) {
+  const childPath = (id        ) => paths.get(`child:${id}`) ?? path.join(root, '.doflow', 'state', WORKTREE_DIR, id);
+  const matches                                                          = [];
+  for (const d of Object.values(store.dispatches)         ) {
+    if (d.phase === 'ended' || !sameIdentity(d.workerIdentity, caller)) continue;
+    const p = d.attempt && d.attempt.worktree;
+    if (typeof p !== 'string' || (paths.get(p) ?? path.resolve(p)) !== caller.worktree) continue;
+    matches.push({ dispatchId: d.dispatchId, requestId: null });
+  }
+  if (!children) return matches;
+  for (const r of Object.values(store.spawnRequests)         ) {
+    const granter = store.dispatches[r.granterDispatchId];
+    if (!granter || granter.phase === 'ended' || !liveChild(r)) continue;
+    if (r.identity && !sameIdentity(r.identity, caller)) continue;
+    if (childPath(r.requestId) !== caller.worktree) continue;
+    matches.push({ dispatchId: r.granterDispatchId, requestId: r.requestId });
+  }
+  return matches;
+}
+
+/** The next `<d-id>.c<n>` for a granter: one past the highest `n` it has used. */
+function nextRequestId(store     , dispatchId        )         {
+  let n = 0;
+  for (const id of Object.keys(store.spawnRequests)) {
+    const m = REQUEST_ID.exec(id);
+    if (m && m[1] === dispatchId) n = Math.max(n, Number(m[2]));
+  }
+  return `${dispatchId}.c${n + 1}`;
+}
+
+/** The 080 run's `control`, read without a lock before the dispatch lock (IC-006 allows no read
+ * inside it); null when the ledger or the run is absent. */
+function runControl(root        , slug        , runKey     , fsImpl     )                {
+  if (typeof runKey !== 'string') return null;
+  let ledger     ;
+  try { ledger = readTaskState(fsImpl, attemptStoreFile(root, slug)); } catch { return null; }
+  const run = ledger && ledger.runs && Object.prototype.hasOwnProperty.call(ledger.runs, runKey) ? ledger.runs[runKey] : null;
+  return run && typeof run.control === 'string' ? run.control : null;
+}
+
+/**
+ * IC-033 request: `dispatch --action spawn --slug --prompt-file --reserve-tokens`. Returns
+ * `{ disposition: 'spawn-requested', requestId, state: 'requested' }`, or `{ disposition: 'refused',
+ * reason, ... }` (exit 1) with nothing written; throws `usage` (exit 2) for a bad flag or an
+ * unreadable prompt file.
+ */
+function requestSpawn({ slug, promptFile, reserveTokens, env = process.env, cwd = process.cwd(), root, fsImpl = fs, now = new Date() }     ) {
+  storeFileFor(root ?? '.', slug); // step 0: validates the slug
+  if (typeof promptFile !== 'string' || promptFile === '') throw usage('--prompt-file is required for --action spawn');
+  const reserve = whole(reserveTokens);
+  if (reserve === null) throw usage('--reserve-tokens must be a whole number for --action spawn');
+
+  const who = callerOf(env, cwd);
+  if (who.refusal) return who.refusal;
+  const caller = who.caller;
+  const base = real(root ?? projectRoot(cwd));
+  const storeFile = storeFileFor(base, slug);
+
+  const seen = readDispatch(storeFile, fsImpl);
+  if (!seen.run) return refused('no-dispatch-run');
+
+  let prompt        ;
+  try { prompt = fsImpl.readFileSync(path.resolve(cwd, promptFile)); } catch (err     ) {
+    throw usage(`--prompt-file '${promptFile}' cannot be read: ${err && err.code ? err.code : err}`);
+  }
+  const promptSha256 = crypto.createHash('sha256').update(prompt).digest('hex');
+  const control = runControl(base, slug, seen.run.runKey, fsImpl);
+  const paths = realPaths(seen, base);
+
+  // The copy, so the worker may delete its own file (which would otherwise count as a change of its
+  // attempt). Written before the lock under a temporary name and renamed to its request's name in the
+  // write that records the request, so no `requested` record is ever seen without its prompt (RT-16).
+  const dir = path.join(base, '.doflow', 'state', ENVELOPE_DIR);
+  const staged = path.join(dir, `.spawn.${process.pid}.${crypto.randomBytes(4).toString('hex')}.prompt.tmp`);
+  fsImpl.mkdirSync(dir, { recursive: true });
+  try {
+    fsImpl.writeFileSync(staged, prompt, { mode: 0o600 });
+  } catch (err) {
+    try { fsImpl.rmSync(staged, { force: true }); } catch { /* the original error is the one reported */ }
+    throw err;
+  }
+  let copyError      = null;
+
+  let result      = null;
+  try {
+    result = mutateDispatch(storeFile, (store     ) => {
+      const no = (reason        , extra                      ) => ({ write: false, result: refused(reason, extra) });
+      if (!store.run) return no('no-dispatch-run');
+      const matches = matchCaller(store, caller, paths, base, true);
+      if (matches.length === 0) return no('no-matching-dispatch');
+      if (matches.length > 1) return no('identity-ambiguous', { dispatchIds: matches.map((m) => m.dispatchId).sort() });
+      const [{ dispatchId, requestId: childOf }] = matches;
+      if (childOf) return no('depth-exceeded', { limit: MAX_DEPTH, requestId: childOf });
+      const d = store.dispatches[dispatchId];
+      if (d.phase !== 'launched') return no('granter-not-running', { dispatchId, phase: d.phase });
+      if (control === 'paused') return no('run-paused', { dispatchId });
+      if (control !== 'running' || store.run.state === 'cancelling' || store.run.state === 'cancelled') return no('run-cancelled', { dispatchId });
+      const grant = d.grant;
+      if (!grant || grant.depth !== MAX_DEPTH) return no('spawning-denied', { dispatchId });
+      const active = (Object.values(store.spawnRequests)         ).filter((r) => r.granterDispatchId === dispatchId && liveChild(r)).length;
+      if (active >= grant.children) return no('concurrency-exceeded', { dispatchId, limit: grant.children });
+      const used = grant.used || { children: 0, tokens: 0 };
+      const remaining = grant.tokens - used.tokens;
+      if (reserve > remaining) return no('budget-exceeded', { dispatchId, remaining });
+
+      const requestId = nextRequestId(store, dispatchId);
+      // One rename inside the lock, so the prompt exists before the record does; a failed rename
+      // writes nothing and spends nothing.
+      try { fsImpl.renameSync(staged, path.join(dir, `${requestId}.prompt.txt`)); } catch (err) {
+        copyError = err;
+        return { write: false, result: null };
+      }
+      store.spawnRequests[requestId] = {
+        requestId,
+        granterDispatchId: dispatchId,
+        prompt: `${ENVELOPE_DIR}/${requestId}.prompt.txt`,
+        promptSha256,
+        reserveTokens: reserve,
+        requestedAt: now.toISOString(),
+        state: 'requested',
+        reason: null,
+        childRunId: null,
+        identity: null,
+        endState: null,
+        report: null,
+      };
+      d.grant = { ...grant, used: { children: used.children + 1, tokens: used.tokens + reserve } };
+      return { write: true, result: { disposition: 'spawn-requested', requestId, state: 'requested' } };
+    }, fsImpl);
+  } finally {
+    if (!result || result.disposition !== 'spawn-requested') {
+      try { fsImpl.rmSync(staged, { force: true }); } catch { /* a refusal is still the answer */ }
+    }
+  }
+  if (copyError) throw copyError;
+  return result;
+}
+
+/**
+ * IC-033 status: `dispatch --action spawn --slug --request-id`. Steps 1 to 4 over an unlocked read;
+ * `{ disposition: 'spawn-status', requestId, state, childRunId, endState, report }` for a request
+ * of the caller's own dispatch, else a refusal (`unknown-request` for any other request id).
+ */
+function spawnStatus({ slug, requestId, env = process.env, cwd = process.cwd(), root, fsImpl = fs }     ) {
+  storeFileFor(root ?? '.', slug);
+  if (typeof requestId !== 'string' || !REQUEST_ID.test(requestId)) throw usage(`--request-id '${requestId}' is not '<d-id>.c<n>'`);
+  const who = callerOf(env, cwd);
+  if (who.refusal) return who.refusal;
+  const base = real(root ?? projectRoot(cwd));
+  const store = readDispatch(storeFileFor(base, slug), fsImpl);
+  if (!store.run) return refused('no-dispatch-run');
+  const matches = matchCaller(store, who.caller, realPaths(store, base), base, false);
+  if (matches.length === 0) return refused('no-matching-dispatch');
+  if (matches.length > 1) return refused('identity-ambiguous', { dispatchIds: matches.map((m) => m.dispatchId).sort() });
+  const request = Object.prototype.hasOwnProperty.call(store.spawnRequests, requestId) ? store.spawnRequests[requestId] : null;
+  if (!request || request.granterDispatchId !== matches[0].dispatchId) return refused('unknown-request', { requestId });
+  return {
+    disposition: 'spawn-status',
+    requestId,
+    state: request.state,
+    childRunId: request.childRunId ?? null,
+    endState: request.endState ?? null,
+    report: request.report ?? null,
+  };
+}
+
+module.exports = {
+  MAX_DEPTH,
+  MAX_CHILDREN,
+  REQUEST_ID,
+  WORKTREE_DIR,
+  validateGrant,
+  copyGrant,
+  requestSpawn,
+  spawnStatus,
+};