@aiwg/cli 2026.10.8 → 2026.10.10

package/tools/ralph-external/lib/session-attempt.mjs

@@ -0,0 +1,85 @@
+// Classify native continuation and retain the original execution assumptions.
+import { randomUUID } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+
+const { qualificationDigest } = await importImpl(import.meta.url, 'models/qualification-digest.mjs');
+const validSession = value => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,255}$/.test(value);
+
+export function changedBindings(original, current) {
+  if (!original) return [];
+  return [...new Set([...Object.keys(original), ...Object.keys(current)])].sort()
+    .filter(key => qualificationDigest(original[key] ?? null) !== qualificationDigest(current[key] ?? null))
+    .map(key => ({ binding: key, previous: original[key] ?? null, current: current[key] ?? null }));
+}
+
+export function classifySessionAttempt(adapter, { sessionId, original, current, sessionValid = true } = {}) {
+  const changes = changedBindings(original, current ?? {});
+  const requested = sessionId !== null && sessionId !== undefined;
+  const reason = !requested ? 'no-session' : !adapter.hasCapability('sessionResume') ? 'resume-unsupported'
+    : !validSession(sessionId) || !sessionValid || !original ? 'invalid-session'
+      : changes.length ? 'bindings-changed' : 'session-bound';
+  return { kind: reason === 'session-bound' ? 'continuation' : 'fresh', reason,
+    requestedSessionId: validSession(sessionId) ? sessionId : null,
+    changes, originalBindings: original ?? null, bindings: current ?? {} };
+}
+
+export function persistCycleAttempt(owner, state, outputDir, attempt) {
+  state.currentAttempt = attempt;
+  owner.stateManager.save(state);
+  writeFileSync(join(outputDir, 'session-attempt.json'), JSON.stringify(attempt, null, 2), { mode: 0o600 });
+}
+
+export function prepareNativeAttempt(owner, state, options) {
+  const adapter = owner.providerAdapter;
+  // Resolve again even when a requested continuation cannot be used.
+  const model = adapter.mapModel(options.model);
+  const prior = state.sessionBinding;
+  const sessionId = prior?.sessionId ?? (state.currentIteration > 1 ? state.sessionId : null);
+  const bindings = { provider: adapter.getName(), model, sessionId,
+    policyDigest: qualificationDigest({ budget: options.budget, maxTurns: options.maxTurns,
+      mcpConfig: options.mcpConfig, tools: options.tools, thinking: options.thinking,
+      workingDir: options.workingDir }) };
+  const attempt = { attemptId: randomUUID(), previousAttemptId: state.currentAttempt?.attemptId ?? null,
+    ...adapter.classifySessionAttempt({ sessionId, original: prior?.originalBindings,
+      current: bindings, sessionValid: prior?.valid === true }), status: 'prepared' };
+  // Only Claude/Muse accept a caller-created session id. Other CLIs must
+  // report a native id before it can be used for continuation.
+  const nativeId = attempt.kind === 'continuation' ? sessionId
+    : ['claude', 'muse'].includes(adapter.getName()) ? randomUUID() : null;
+  attempt.bindings.sessionId = nativeId;
+  persistCycleAttempt(owner, state, options.outputDir, attempt);
+  return { ...options, model, sessionId: nativeId, resumeSession: attempt.kind === 'continuation' ? nativeId : null,
+    attempt };
+}
+
+export function finishNativeAttempt(owner, state, options, result) {
+  let sessionId = options.sessionId;
+  let reportedId = null;
+  let conflictingSession = false;
+  let providerFailed = false;
+  // Session ids are accepted only from this attempt's captured provider output.
+  for (const line of String(result.stdoutBuffer ?? '').split('\n')) {
+    try {
+      const event = JSON.parse(line);
+      const observed = owner.providerAdapter.observeHealthEvent(event, { kind: 'stdout' }, {});
+      providerFailed ||= observed?.kind === 'error' || observed?.kind === 'terminal' && observed.success === false;
+      const candidate = observed?.sessionId ?? event.session_id ?? event.sessionId ?? event.stream?.id;
+      if (validSession(candidate)) {
+        conflictingSession ||= reportedId !== null && reportedId !== candidate
+          || options.resumeSession != null && options.resumeSession !== candidate;
+        reportedId = candidate;
+        sessionId = candidate;
+      }
+    } catch { /* Non-JSON stdout has no native session binding. */ }
+  }
+  const bindings = { ...options.attempt.bindings, sessionId };
+  const valid = result.exitCode === 0 && !result.timedOut && !providerFailed && !conflictingSession && validSession(sessionId);
+  state.sessionBinding = { sessionId, valid,
+    originalBindings: options.attempt.kind === 'continuation' ? options.attempt.originalBindings : bindings };
+  options.attempt.status = 'finished';
+  options.attempt.bindings = bindings;
+  persistCycleAttempt(owner, state, options.outputDir, options.attempt);
+  result.attempt = options.attempt;
+}

package/tools/ralph-external/lib/strict-worker-json.mjs

@@ -0,0 +1,190 @@
+// Parse bounded worker JSON without accepting duplicate object keys.
+/**
+ * Thrown by {@link parseStrictWorkerJson} with a stable `code` so callers can
+ * map a scan failure to a specific contract-violation message without
+ * string-matching free-text.
+ */
+export class StrictJsonScanError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * RFC 8259 JSON parser used on every strict worker-final path (JSONL lines,
+ * `format: 'json'`, and the MCP `content[0].text`/top-level envelope) instead
+ * of `JSON.parse`. `JSON.parse` silently keeps the LAST value when an object
+ * repeats a member name — RFC 8259 §4 explicitly leaves this to the
+ * implementation, and V8 picks "last wins". That lets a forged worker final
+ * smuggle a second, hidden value past a first one: a trailing duplicate
+ * `"status":"completed"` can overwrite an earlier `"status":"failed"`, or a
+ * trailing duplicate `"type":"result"` can collapse a `"type":"message"`
+ * framing envelope into a bogus result in one line (#2890 BLOCKER 1+2).
+ *
+ * This scanner tracks member names per object independently at every
+ * nesting level (a sibling object may reuse a name the scanner already saw
+ * in its parent or an earlier sibling) and rejects any object that repeats
+ * one. Names are compared only after the scanner has fully decoded them —
+ * resolving `\"`, other single-character escapes, and `\uXXXX` escapes
+ * (including surrogate pairs, since JS string concatenation of two decoded
+ * UTF-16 code units forms the pair automatically) — so an escape-obfuscated
+ * collision (`"status"` vs `"status"`) is caught exactly like a literal
+ * one. A non-colliding unknown key, escaped or not, is left for the existing
+ * `additionalProperties: false` schema check to reject, unchanged.
+ *
+ * Nesting depth is bounded during the scan (not only afterward, by
+ * `boundedJson()`'s post-parse walk) so pathological depth fails fast with a
+ * clear `DEPTH` code instead of relying on a recursive-descent stack
+ * overflow to be caught as a generic syntax error.
+ *
+ * @param {string} text - Decoded JSON text (already UTF-8 validated by the caller)
+ * @param {number} maxDepth - Same bound as `WORKER_MAX_NESTING_DEPTH`; root value is depth 1
+ * @returns {unknown}
+ */
+export function parseStrictWorkerJson(text, maxDepth) {
+  const length = text.length;
+  let index = 0;
+
+  function fail(code, message) {
+    throw new StrictJsonScanError(code, `${message} (offset ${index})`);
+  }
+
+  function skipWhitespace() {
+    while (index < length) {
+      const code = text.charCodeAt(index);
+      if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) index += 1;
+      else break;
+    }
+  }
+
+  function parseValue(depth) {
+    skipWhitespace();
+    if (index >= length) fail('SYNTAX', 'Unexpected end of JSON input');
+    const code = text.charCodeAt(index);
+    if (code === 0x7b) return parseObject(depth);
+    if (code === 0x5b) return parseArray(depth);
+    if (code === 0x22) return parseString();
+    if (code === 0x2d || (code >= 0x30 && code <= 0x39)) return parseNumber();
+    if (text.startsWith('true', index)) { index += 4; return true; }
+    if (text.startsWith('false', index)) { index += 5; return false; }
+    if (text.startsWith('null', index)) { index += 4; return null; }
+    fail('SYNTAX', 'Unexpected token');
+  }
+
+  function parseObject(depth) {
+    if (depth > maxDepth) fail('DEPTH', 'Worker nesting depth exceeds bound');
+    index += 1; // {
+    const result = {};
+    const seen = new Set();
+    skipWhitespace();
+    if (text.charCodeAt(index) === 0x7d) { index += 1; return result; }
+    for (;;) {
+      skipWhitespace();
+      if (text.charCodeAt(index) !== 0x22) fail('SYNTAX', 'Expected object member name');
+      const key = parseString();
+      if (seen.has(key)) fail('DUPLICATE', `Duplicate object member name ${JSON.stringify(key)}`);
+      seen.add(key);
+      skipWhitespace();
+      if (text.charCodeAt(index) !== 0x3a) fail('SYNTAX', 'Expected colon after object member name');
+      index += 1;
+      // Define, never assign: assignment would invoke the inherited __proto__
+      // setter, hiding the member from own-key validation and diverging from
+      // JSON.parse, which creates an ordinary own property.
+      Object.defineProperty(result, key, { value: parseValue(depth + 1), enumerable: true, writable: true, configurable: true });
+      skipWhitespace();
+      const delimiter = text.charCodeAt(index);
+      if (delimiter === 0x2c) { index += 1; continue; }
+      if (delimiter === 0x7d) { index += 1; break; }
+      fail('SYNTAX', 'Expected , or } in object');
+    }
+    return result;
+  }
+
+  function parseArray(depth) {
+    if (depth > maxDepth) fail('DEPTH', 'Worker nesting depth exceeds bound');
+    index += 1; // [
+    const result = [];
+    skipWhitespace();
+    if (text.charCodeAt(index) === 0x5d) { index += 1; return result; }
+    for (;;) {
+      result.push(parseValue(depth + 1));
+      skipWhitespace();
+      const delimiter = text.charCodeAt(index);
+      if (delimiter === 0x2c) { index += 1; continue; }
+      if (delimiter === 0x5d) { index += 1; break; }
+      fail('SYNTAX', 'Expected , or ] in array');
+    }
+    return result;
+  }
+
+  function parseString() {
+    index += 1; // opening quote
+    let value = '';
+    for (;;) {
+      if (index >= length) fail('SYNTAX', 'Unterminated string');
+      const code = text.charCodeAt(index);
+      if (code === 0x22) { index += 1; return value; }
+      if (code === 0x5c) {
+        index += 1;
+        const escape = text[index];
+        if (escape === undefined) fail('SYNTAX', 'Unterminated escape sequence');
+        switch (escape) {
+          case '"': value += '"'; index += 1; break;
+          case '\\': value += '\\'; index += 1; break;
+          case '/': value += '/'; index += 1; break;
+          case 'b': value += '\b'; index += 1; break;
+          case 'f': value += '\f'; index += 1; break;
+          case 'n': value += '\n'; index += 1; break;
+          case 'r': value += '\r'; index += 1; break;
+          case 't': value += '\t'; index += 1; break;
+          case 'u': {
+            const hex = text.slice(index + 1, index + 5);
+            if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail('SYNTAX', 'Invalid unicode escape');
+            // Decoded code unit is appended as-is; two consecutive decoded
+            // surrogate halves recombine into one character automatically
+            // through normal JS UTF-16 string concatenation.
+            value += String.fromCharCode(parseInt(hex, 16));
+            index += 5;
+            break;
+          }
+          default: fail('SYNTAX', 'Invalid escape sequence');
+        }
+      } else if (code < 0x20) {
+        fail('SYNTAX', 'Unescaped control character in string');
+      } else {
+        value += text[index];
+        index += 1;
+      }
+    }
+  }
+
+  function parseNumber() {
+    const start = index;
+    if (text.charCodeAt(index) === 0x2d) index += 1;
+    if (text.charCodeAt(index) === 0x30) {
+      index += 1;
+    } else if (text.charCodeAt(index) >= 0x31 && text.charCodeAt(index) <= 0x39) {
+      index += 1;
+      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
+    } else fail('SYNTAX', 'Invalid number');
+    if (text.charCodeAt(index) === 0x2e) {
+      index += 1;
+      if (!(text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39)) fail('SYNTAX', 'Invalid number fraction');
+      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
+    }
+    if (text.charCodeAt(index) === 0x65 || text.charCodeAt(index) === 0x45) {
+      index += 1;
+      if (text.charCodeAt(index) === 0x2b || text.charCodeAt(index) === 0x2d) index += 1;
+      if (!(text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39)) fail('SYNTAX', 'Invalid number exponent');
+      while (text.charCodeAt(index) >= 0x30 && text.charCodeAt(index) <= 0x39) index += 1;
+    }
+    return Number(text.slice(start, index));
+  }
+
+  const result = parseValue(1);
+  skipWhitespace();
+  if (index !== length) fail('SYNTAX', 'Unexpected trailing characters after JSON value');
+  return result;
+}
+

package/tools/ralph-external/lib/worker-artifacts.mjs

@@ -0,0 +1,209 @@
+/** Materialize bounded artifacts; quarantine entries before checking ownership or removing them. */
+import { constants } from 'node:fs';
+import { open, mkdir, mkdtemp, lstat, readdir, unlink, rmdir, rename } from 'node:fs/promises';
+import path from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+
+const { validateWorkerArtifacts } = await importImpl(import.meta.url, 'serve/worker-artifacts.mjs');
+const directoryFlags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+
+export async function materializeWorkerArtifacts(invocation, runDir) {
+  const artifacts = validateWorkerArtifacts(invocation);
+  const targets = new Map(artifacts.map(artifact => [artifact.name, artifact.location === 'workspace-relative'
+    ? path.join(invocation.cwd, artifact.relativePath) : path.join(runDir, `artifact-${artifact.name}`)]));
+  const argv = invocation.argv.map(token => {
+    if (!token.includes('${artifact:')) return token;
+    const match = /^\$\{artifact:([A-Za-z0-9][A-Za-z0-9_-]{0,63})\}$/.exec(token);
+    if (!match || !targets.has(match[1])) throw new Error('Undeclared worker artifact placeholder');
+    return targets.get(match[1]);
+  });
+  const handles = [], created = [], directories = [], filenames = new Map();
+  let cleaned = false, quarantine, quarantinePath, sequence = 0;
+  const remember = (handle, filename) => { handles.push(handle); if (filename) filenames.set(handle, filename); return handle; };
+  // Linux can address relocated pinned parents. Other POSIX hosts use checked
+  // paths, retaining artifacts if a parent's identity cannot be recovered.
+  const childPath = (parent, name) => process.platform === 'linux'
+    ? `/proc/self/fd/${parent.fd}/${name}` : path.join(filenames.get(parent), name);
+  async function pinDirectory(filename) {
+    if (!path.isAbsolute(filename) || path.normalize(filename) !== filename || filename.includes('\0')) throw new Error('Invalid worker artifact root');
+    let directory = remember(await open('/', directoryFlags), '/');
+    for (const component of filename.split('/').filter(Boolean)) {
+      const target = childPath(directory, component), resolved = path.join(filenames.get(directory), component);
+      directory = remember(await open(target, directoryFlags), resolved);
+    }
+    return directory;
+  }
+  async function rewalk(cwd, chain) {
+    let directory = await pinDirectory(cwd);
+    if (!sameFile(await directory.stat({ bigint: true }), chain[0].stat)) throw new Error('cwd changed');
+    for (const entry of chain.slice(1)) {
+      const target = childPath(directory, entry.component), filename = path.join(filenames.get(directory), entry.component);
+      const next = remember(await open(target, directoryFlags), filename);
+      if (!sameFile(await next.stat({ bigint: true }), entry.stat)
+        || !sameFile(await lstat(target, { bigint: true }), entry.stat)) throw new Error('ancestor changed');
+      directory = next;
+    }
+    return directory;
+  }
+  async function workspaceParent(root, relativePath) {
+    let directory = root;
+    const rootStat = await root.stat({ bigint: true });
+    const quarantineStat = await quarantine.stat({ bigint: true });
+    if (rootStat.dev !== quarantineStat.dev) throw new Error('Worker artifact quarantine must be on the cwd filesystem');
+    const chain = [{ stat: rootStat }];
+    const components = relativePath.split('/').slice(0, -1);
+    for (const [i, component] of components.entries()) {
+      const target = childPath(directory, component);
+      const invocationDirectory = i === components.length - 1;
+      let made = false;
+      // Rewalk BEFORE mkdir too; a pinned parent alone is not cwd authority.
+      await rewalk(invocation.cwd, chain);
+      try { await mkdir(target, { mode: 0o700 }); made = true; }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        if (invocationDirectory) throw Object.assign(new Error('Worker artifact directory collision (existing entry preserved)'), { code: 'EEXIST' });
+      }
+      const before = await lstat(target, { bigint: true });
+      const next = remember(await open(target, directoryFlags), path.join(filenames.get(directory), component));
+      const stat = await next.stat({ bigint: true });
+      try {
+        if (!before.isDirectory() || !sameFile(before, stat)) throw new Error('directory substituted');
+        if (made && (await readdir(childPath(next, '.'))).length) throw new Error('new directory is not empty');
+        const checkedParent = await rewalk(invocation.cwd, chain);
+        if (!sameFile(await lstat(childPath(checkedParent, component), { bigint: true }), stat)
+          || !sameFile(await lstat(target, { bigint: true }), stat)) throw new Error('directory substituted');
+      } catch (cause) { throw new Error('Worker artifact path changed; directory identity verification failed (unproven entry retained)', { cause }); }
+      if (stat.dev !== quarantineStat.dev) throw new Error('Worker artifact quarantine must share every parent filesystem');
+      // Only the verified invocation directory is owned. Leave shared prefixes.
+      if (invocationDirectory) directories.push({ target, stat, parent: directory });
+      chain.push({ component, stat });
+      directory = next;
+    }
+    return { directory, chain };
+  }
+  async function verifyPath(cwd, chain, leaf, identity) {
+    try {
+      // Re-open cwd from / as well: a relocated cwd descriptor is not authority.
+      const directory = await rewalk(cwd, chain);
+      const file = remember(await open(childPath(directory, leaf), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK));
+      if (!sameFile(await file.stat({ bigint: true }), identity)) throw new Error('leaf changed');
+    } catch (cause) { throw new Error('Worker artifact path changed; containment verification failed', { cause }); }
+  }
+  async function quarantineEntry(entry, directory = false) {
+    if (process.platform !== 'linux') {
+      try {
+        const current = await pinDirectory(filenames.get(entry.parent));
+        if (!sameFile(await current.stat({ bigint: true }), await entry.parent.stat({ bigint: true }))) throw new Error('parent identity mismatch');
+      } catch (cause) { throw new Error('Worker artifact parent changed; artifact retained', { cause }); }
+    }
+    const captured = childPath(quarantine, `entry-${sequence++}`);
+    // The source can change up to rename; inspect only the privately captured entry.
+    await rename(entry.target, captured);
+    if (!sameFile(await lstat(captured, { bigint: true }), entry.stat)) {
+      throw new Error(`Worker artifact replacement preserved in quarantine: ${quarantinePath}/${path.basename(captured)}`);
+    }
+    if (directory) await rmdir(captured); else await unlink(captured);
+  }
+  const closeHandles = async () => {
+    const results = await Promise.allSettled(handles.reverse().map(handle => handle.close()));
+    const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+    if (errors.length) throw new AggregateError(errors, 'Worker artifact descriptor close failed');
+  };
+  const cleanup = async ({ confirmedStop = true } = {}) => {
+    if (cleaned) return;
+    cleaned = true;
+    if (!confirmedStop) {
+      await closeHandles();
+      return { status: 'retained', reason: 'stop-proof-uncertain', paths: [...targets.values()] };
+    }
+    const errors = [];
+    try {
+      for (const [entries, directory] of [[created, false], [directories, true]]) {
+        for (const entry of entries.reverse()) {
+          try { await quarantineEntry(entry, directory); }
+          catch (error) { if (error.code !== 'ENOENT') errors.push(error); }
+        }
+      }
+      if (quarantinePath) {
+        try { await rmdir(quarantinePath); }
+        catch (error) { if (error.code !== 'ENOTEMPTY') errors.push(error); }
+      }
+    } finally {
+      try { await closeHandles(); } catch (error) { errors.push(error); }
+    }
+    if (errors.length) throw new AggregateError(errors, `Worker artifact cleanup failed; preserved entries: ${quarantinePath}`);
+  };
+  try {
+    const run = await pinDirectory(runDir);
+    const stat = await run.stat();
+    if (stat.uid !== process.getuid() || (stat.mode & 0o077)) throw new Error('Worker artifact directory must be private and owned');
+    if (artifacts.length) {
+      quarantinePath = await mkdtemp(childPath(run, '.artifact-quarantine-'));
+      quarantine = remember(await open(quarantinePath, directoryFlags), path.join(runDir, path.basename(quarantinePath)));
+      // Keep the diagnostic path meaningful after descriptors close.
+      quarantinePath = path.join(runDir, path.basename(quarantinePath));
+    }
+    let workspace;
+    for (const artifact of artifacts) {
+      let parent = run, chain;
+      let leaf = `artifact-${artifact.name}`;
+      if (artifact.location === 'workspace-relative') {
+        if (!workspace) {
+          const { realBeneath } = await importImpl(import.meta.url, 'serve/worker-invocation-paths.js');
+          if (await realBeneath(invocation.cwd, runDir)) throw new Error('Worker artifact quarantine must be outside worker-writable cwd');
+          workspace = await pinDirectory(invocation.cwd);
+        }
+        ({ directory: parent, chain } = await workspaceParent(workspace, artifact.relativePath));
+        leaf = path.basename(artifact.relativePath);
+      }
+      const target = childPath(parent, leaf);
+      let handle;
+      try { handle = await open(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+      catch (error) {
+        if (error.code === 'EEXIST') throw Object.assign(new Error(`Worker artifact collision: ${targets.get(artifact.name)} (existing file preserved)`), { code: 'EEXIST' });
+        throw error;
+      }
+      // Keep the descriptor until cleanup so an unlinked inode cannot be reused.
+      remember(handle);
+      const identity = await handle.stat({ bigint: true });
+      created.push({ target, stat: identity, parent });
+      if (chain) await verifyPath(invocation.cwd, chain, leaf, identity);
+      await handle.writeFile(artifact.content); await handle.sync();
+      if (chain) await verifyPath(invocation.cwd, chain, leaf, identity);
+    }
+    return { argv, cleanup };
+  } catch (error) {
+    try { await cleanup(); } catch (cleanupError) { throw new AggregateError([error, cleanupError], `${error.message}; worker artifact creation and cleanup failed`); }
+    throw error;
+  }
+}
+
+/** Gate artifact removal on launcher-owned stop evidence and report retention. */
+export class WorkerArtifactLifecycle {
+  constructor(invocation, invocationId = invocation.invocationId) {
+    this.invocationId = invocationId;
+    this.invocation = invocation;
+    this.confirmedStop = true; // Materialization precedes any dispatch.
+    this.result = null;
+  }
+  spawning() { this.confirmedStop = false; }
+  observe(name, value) {
+    if (name !== 'exit.json') return;
+    this.confirmedStop = value.invocationId === this.invocationId && value.termination === 'confirmed';
+    this.result = value;
+    if (this.invocation.artifacts?.length) value.artifactCleanup = this.status();
+  }
+  status() {
+    return this.confirmedStop ? { status: 'eligible' }
+      : { status: 'retained', reason: 'stop-proof-uncertain' };
+  }
+  failure(error) {
+    if (this.invocation.artifacts?.length && !this.confirmedStop) error.artifactCleanup = this.status();
+  }
+  async finish(artifacts) {
+    if (this.result?.termination === 'uncertain') this.confirmedStop = false;
+    if (this.result && this.invocation.artifacts?.length) this.result.artifactCleanup = this.status();
+    return artifacts?.cleanup({ confirmedStop: this.confirmedStop });
+  }
+}

package/tools/ralph-external/lib/worker-final.mjs

@@ -0,0 +1,143 @@
+// Collect workerClaims candidates only after schema and on-disk artifact validation.
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+import { boundedPrivateRead, withWorkerPath } from './worker-inputs.mjs';
+import { parseStrictWorkerJson } from './strict-worker-json.mjs';
+
+const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const escapePointer = key => key.replace(/~/g, '~0').replace(/\//g, '~1');
+
+// The shared validator renders Ajv instancePath; required/additional fields
+// identify the child in params, rendered in its existing diagnostic text.
+function schemaDiagnostic(error) {
+  const match = /^(\/\S*) (must (?:have required|NOT have additional) propert(?:y|ies) '([^']+)'.*)$/.exec(error);
+  return match ? `${match[1] === '/' ? '' : match[1]}/${escapePointer(match[3])} ${match[2]}` : error;
+}
+
+async function artifactErrors(claims, workdir) {
+  const errors = [];
+  for (const [index, artifact] of claims.artifacts.entries()) {
+    const pointer = `/artifacts/${index}`;
+    const filename = resolve(workdir, artifact.path);
+    const within = relative(workdir, filename);
+    if (!within || within === '..' || within.startsWith('../') || isAbsolute(within) || artifact.path.includes('\0')) {
+      errors.push(`${pointer}/path Artifact must name a file beneath the worker tree`);
+      continue;
+    }
+    try {
+      // Pin every ancestor and refuse symlinks, hardlinks and special files.
+      const actual = await withWorkerPath(filename, async target => {
+        const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+          const before = await handle.stat({ bigint: true });
+          if (!before.isFile() || before.nlink !== 1n) throw new Error('Artifact must be an unaliased regular file');
+          const hash = createHash('sha256');
+          for await (const chunk of handle.createReadStream({ autoClose: false })) hash.update(chunk);
+          const after = await handle.stat({ bigint: true });
+          if (before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs) {
+            throw new Error('Artifact changed while hashing');
+          }
+          return `sha256:${hash.digest('hex')}`;
+        } finally { await handle.close(); }
+      });
+      if (actual !== artifact.digest) errors.push(`${pointer}/digest Artifact digest mismatch: expected ${artifact.digest}, actual ${actual}`);
+    } catch (error) {
+      errors.push(`${pointer}/path Cannot hash artifact in worker tree: ${error.message}`);
+    }
+  }
+  return errors;
+}
+
+export async function collectWorkerFinal({ path, workdir, driver, output, invocationId, result, inspect, handle, publish, outputFraming }) {
+  const { validateWorkerPayload, WORKER_MAX_JSON_BYTES, WORKER_MAX_NESTING_DEPTH, assertWorkerTerminal } =
+    await importImpl(import.meta.url, 'mission-protocol/index.js');
+  const scan = bytes => parseStrictWorkerJson(
+    new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes), WORKER_MAX_NESTING_DEPTH);
+  let finalBytes, extracted = false, parsedClaims, parseError;
+  const evidence = () => ({ invocationId, path, digest: finalBytes ? digest(finalBytes) : null,
+    source: extracted ? 'adapter-extraction' : 'worker-output', candidate: true, verified: false });
+  try {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > WORKER_MAX_JSON_BYTES) throw new Error('Invalid final output');
+    await inspect(path, 'file');
+    let claims;
+    if (stat.size === 0 && driver.extractFinal) {
+      claims = driver.extractFinal(output.toString('utf8'));
+      if (claims === null || claims === undefined || claims.success === false) throw new Error('Missing or unsuccessful final extraction');
+      const bytes = JSON.stringify({ invocationId, source: 'adapter-extraction', candidate: true, verified: false, result: claims });
+      if (Buffer.byteLength(bytes) > WORKER_MAX_JSON_BYTES) throw new Error('Final exceeds bound');
+      await handle.writeFile(bytes); extracted = true;
+    }
+    finalBytes = await boundedPrivateRead(path, WORKER_MAX_JSON_BYTES, inspect, true);
+    if (!finalBytes.length) throw new Error('Missing final output');
+    if (extracted) {
+      if (driver.parseWorkerFinal) {
+        try {
+          // The adapter owns framing (including text preambles) and strict
+          // decoding. Invoke it once with the launcher's actual exit status.
+          parsedClaims = await driver.parseWorkerFinal(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(output), {
+            format: outputFraming === 'jsonl' ? 'jsonl' : 'json', observation: { transport: 'shell',
+              status: result.exitCode === 0 && !result.errorCode && !result.timedOut ? 'completed' : 'failed',
+              termination: result.termination, exitCode: result.exitCode },
+            // Content validation precedes the independent terminal assertion
+            // below, so degraded termination cannot hide artifact mismatches.
+            assertTerminal: () => {},
+          });
+          claims = parsedClaims;
+        } catch (error) {
+          parseError = error;
+          // A decoded claims document must satisfy the schema. A non-claims
+          // text candidate retains exit-only evidence and a rejected strict
+          // parse; it can never authorize health completion or recovery.
+          if (/^Invalid workerClaims:|Duplicate worker JSON|nesting depth|byte bound/.test(error.message)) throw error;
+          claims = undefined;
+        }
+      } else {
+        // Without a strict adapter hook, scan original bytes before trusting
+        // synchronous extraction, which may have discarded duplicate keys.
+        if (outputFraming === 'jsonl') {
+          const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(output);
+          for (const line of text.split('\n')) if (line.trim()) scan(Buffer.from(line));
+        } else scan(output);
+      }
+    } else {
+      const decoded = scan(finalBytes);
+      claims = driver.extractFinal ? driver.extractFinal(finalBytes.toString('utf8')) : decoded;
+    }
+    if (!parseError) {
+      const validation = validateWorkerPayload('workerClaims', claims);
+      const errors = validation.errors.map(schemaDiagnostic);
+      if (validation.valid) errors.push(...await artifactErrors(claims, workdir));
+      if (errors.length) {
+        result.finalOutputErrors = errors;
+        throw new Error('Invalid workerClaims');
+      }
+    }
+  } catch (error) {
+    result.errorCode ??= 'FINAL_OUTPUT_INVALID';
+    // Preserve the existing missing/empty-final failure: there is no
+    // candidate document (and therefore no schema pointer) to record.
+    if (!finalBytes?.length) throw error;
+    // Adapter decoding uses assertValidWorkerPayload's existing rendered
+    // diagnostics; retain its pointers when validation fails inside it.
+    const schemaErrors = /^Invalid workerClaims: (.*)\.$/.exec(error.message)?.[1];
+    result.finalOutputErrors ??= schemaErrors ? schemaErrors.split('; ').map(schemaDiagnostic) : [`/ ${error.message}`];
+    await publish('final-evidence.json', { ...evidence(), terminalSuccess: false,
+      errorCode: 'FINAL_OUTPUT_INVALID', errors: result.finalOutputErrors });
+    throw error;
+  }
+  await publish('final-evidence.json', { ...evidence(),
+    terminalSuccess: result.exitCode === 0 && !result.timedOut && !result.errorCode });
+  // Reuse the adapter's content result without a second hook invocation.
+  // Keep the existing health path's terminal assertion independent of content.
+  const parseFinal = async (bytes, options) => {
+    if (!extracted) return driver.parseWorkerFinal(bytes, options);
+    if (parseError) throw parseError;
+    assertWorkerTerminal(options.observation);
+    return parsedClaims;
+  };
+  return { finalBytes, extracted, parseFinal };
+}