create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/lib/machine-self.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// WP-2a (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §5 D-4 rev 2, §6.2, §9 S-25):
+// the machine's OWN user settings (display name override, favorite, hidden).
+//
+// D-4: settings live on the machine they describe. Every other member reads them from this
+// machine's manifest/stats probe, so every primary and every device shows the same values. The
+// registry's `enabled` column stays a per-primary local switch and is unrelated.
+//
+// This module is a small in-memory CACHE over the one-row `machine_self` table (v56). The manifest
+// builder is pure and runs on the identity/ETag path, so it must never read the DB: server.js
+// loads this cache once at boot and the POST /api/machine-self handler updates it on every write.
+
+let _deps = { db: null };
+let _cache = { displayName: '', favorite: false, hidden: false, updatedAt: 0 };
+
+function configure({ db } = {}) {
+  _deps = { db };
+}
+
+function _applyRow(row) {
+  const source = row && typeof row === 'object' ? row : {};
+  _cache = {
+    displayName: String(source.displayName || source.display_name || '').slice(0, 80),
+    favorite: Number(source.favorite || 0) === 1,
+    hidden: Number(source.hidden || 0) === 1,
+    updatedAt: Number(source.updatedAt || source.updated_at || 0) || 0,
+  };
+  return _cache;
+}
+
+/** Boot read. A missing/errored row keeps the defaults ('' / false / false) — never throws. */
+async function load() {
+  const db = _deps.db;
+  if (!db || typeof db.getMachineSelf !== 'function') return current();
+  try {
+    _applyRow(await db.getMachineSelf());
+  } catch {
+    // expected: pre-migration / pre-boot handle has no machine_self row — defaults are the truth
+  }
+  return current();
+}
+
+/** The manifest/ETag read: synchronous, allocation-free, no DB. */
+function current() {
+  return { ..._cache };
+}
+
+/** D-4 write: only the given fields change; the row's full shape comes back from the op. */
+async function setSelf(patch = {}, at = Date.now()) {
+  const db = _deps.db;
+  const result = await db.setMachineSelf({
+    displayName: patch.displayName,
+    favorite: patch.favorite,
+    hidden: patch.hidden,
+    at,
+  });
+  return _applyRow(result);
+}
+
+/** Test seam: the cache is module state and must never leak between tests. */
+function _resetForTests() {
+  _cache = { displayName: '', favorite: false, hidden: false, updatedAt: 0 };
+}
+
+module.exports = { configure, load, current, setSelf, _resetForTests };

package/template/coding-task-manager/lib/main-thread-lint-exemptions.json

@@ -22,6 +22,10 @@
       "key": "lib/native-history-control.js\tprocess-launch\tspawn(\tconst child = spawn(source.executablePath, ['app-server', ...args], {",
       "justification": "Provider-history WP-4: starts the owned Codex app-server control child with CTM_PROCESS_ROLE=ctm-native-history-control. The async RPC is limited to one transition, bounded frames/deadlines, abort-driven termination and awaited close; it is not a synchronous filesystem/process probe or an unowned detached spawn."
     },
+    {
+      "key": "lib/codex-source-handoff.js\tprocess-launch\tspawn(\tchild = spawn(executablePath, [...HANDOFF_APP_SERVER_ARGS], { cwd: source.workingDirectory,",
+      "justification": "Codex lead history handoff WP-2 (D-5/D-6): starts one owned Codex app-server with CTM_PROCESS_ROLE=ctm-source-handoff for an ephemeral fork of the source thread and ONE handoff turn. Async JSON-RPC through the same createBoundedRpc as native-history-control (bounded frames, 240 s deadline, abort-driven termination, awaited close in finally); it runs only when a provider switch must cover a sealed compaction, never on a request hot path."
+    },
     {
       "key": "lib/native-subagent-review-page.js\tsync-api\topenSync(\tvfd = fileOps.openSync(t.transcriptPath);",
       "justification": "Owner-reviewed native-subagent-review WP-0: bounded logical-path source identity recheck, closed in finally. The selected-child reader is a worker-only adapter; WP-1 routes production execution exclusively through readNativeSubagentReview in workers/read-pool-worker.js. One body read is capped at 128 KiB plus at most 1024 fence bytes, and each request's compressed/decoded archive ledger is capped at 4 MiB. No primary request handler calls the reader synchronously."
@@ -62,6 +66,10 @@
       "key": "lib/approval-scope.js\tsync-api\tfs.lstatSync(\treturn fs.lstatSync(stripped).isSymbolicLink();",
       "justification": "WP-2 fix round 1 (C2: `rm -rf` through a symlink deletes the real target): checks whether a RECURSIVE rm's leaf target is itself a symlink before counting it as an in-scope scratch delete. One lstat per recursive rm clause, wrapped in try/catch (missing path -> not a symlink), same bounded synchronous approval-decision path."
     },
+    {
+      "key": "lib/approval-scope.js\tsync-api\tfs.lstatSync(\treturn { stat: fs.lstatSync(p) };",
+      "justification": "Dangling-symlink scope (docs/spark-umask-private-group-and-dangling-symlink-scope-2026-10-24.html D-5): an lstat that does NOT follow the link, used only on the existsSync-miss path of resolveDeepestExisting to tell a dangling symlink from a plain missing component while walking one write target to its deepest real ancestor during an approval decision. Bounded to 64 walk steps plus a 40-restart symlink budget; same synchronous approval-decision path as the other approval-scope.js rows. ENOENT continues the walk; any other error fails closed (null resolution, out of scope)."
+    },
     {
       "key": "lib/approval-scope.js\tsync-api\tfs.statSync(\ttry { return fs.statSync(p).isDirectory(); } catch { /* expected: does not exist */ return false; }",
       "justification": "WP-2 fix round 1 (I5: a cp/mv destination that is an existing directory is itself a protected-path check target via dest/basename(src)): one stat per cp destination argument, wrapped in try/catch, same bounded synchronous approval-decision path."
@@ -2058,10 +2066,6 @@
       "key": "server.js\tsync-api\tfs.existsSync(\texists: fs.existsSync(globalRules),",
       "justification": "Pre-existing main-thread site migrated from the preserved baseline; tracked for burn-down."
     },
-    {
-      "key": "server.js\tsync-api\tfs.existsSync(\texists: fs.existsSync(projectPath),",
-      "justification": "Pre-existing main-thread site migrated from the preserved baseline; tracked for burn-down."
-    },
     {
       "key": "server.js\tsync-api\tfs.existsSync(\texists: fs.existsSync(userRules),",
       "justification": "Pre-existing main-thread site migrated from the preserved baseline; tracked for burn-down."
@@ -2753,6 +2757,54 @@
     {
       "key": "lib/harness-model-profile.js\tprocess-launch\texecFile(\texecFile(file, args, options, (error, stdout, stderr) => {",
       "justification": "Codex harness version qualification WP-1 (D-2): the lead-model profile MEASURES the installed Codex instead of matching a version literal -- one async `codex debug models` (and one `--version`) per (binary fingerprint, catalog sha) pair, cached in-process and deduped in flight (T-3), run only when a lead switches model or a Codex lead launches, never per request or per keystroke. Async callback form so the hermetic preload's execFile wrapper keeps the {stdout, stderr} shape."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.mkdirSync(\tfs.mkdirSync(dir, { recursive: true, mode: 0o700 });",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-1/D-2): ensureProxyDir runs once per spawn on CTM's main thread (the 0700 oauth-proxy/ directory must exist before the spawn-time log fd below is opened) and once per record publication inside the PROXY process; never a request path. Same dir+mode shape as host-registry.js's ensureHostRegistryDir."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.writeFileSync(\tfs.writeFileSync(tmp, text, { mode: 0o600, flag: 'wx' });",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-2): the atomic 0600 publication (nonce tmp with flag 'wx', then rename -- host-registry.js's shape). On CTM's main thread it runs exactly once per spawn, for writeAdminSecret, which must precede the synchronous spawn so a CTM that dies between spawn and exit still leaves a readable secret for the next boot's adoption; writeInstanceRecord runs in the proxy process, not CTM."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.renameSync(\tfs.renameSync(tmp, target);",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-2): the rename half of the same atomic publication -- once per spawn on CTM's main thread (admin secret), once per listen in the proxy process (instance record); never a request path."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.unlinkSync(\tfs.unlinkSync(target);",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-4/D-5): reaping a stale instance record or admin secret -- once per rejected adoption decision, once per explicit stop(), once per torn-record read at boot; one unlink of a tiny file, never a request path."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.readFileSync(\traw = fs.readFileSync(instanceRecordPath(dataDir), 'utf8');",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-4): start() decides adopt-vs-spawn SYNCHRONOUSLY (six callers and the boot log read its return value) from one <=1 KiB JSON record, once per boot and once per crash-recovery restart; the HTTP half of the decision is async."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.readFileSync(\traw = fs.readFileSync(adminSecretPath(dataDir), 'utf8');",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-4): one <=80-byte read of the admin secret per adoption, and adoption happens at most once per boot; never a request path."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.openSync(\tconst fd = fs.openSync(target, 'a');",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-1): the descriptor the child's stdout/stderr are bound to is opened immediately before the synchronous spawn, once per proxy generation -- the same shape host-registry.js's _openHostLogFd is exempted for (a detached+unref'd child must not inherit CTM's pipes: an orphan dies with EPIPE on its second write)."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.renameSync(\tfs.renameSync(target, `${target}${LOG_ROTATE_SUFFIX}`);",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-1): log rotation is one rename at >64 MiB, decided from the fd just opened, once per spawn; the previous generation stays readable at .1."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\tfs.openSync(\treturn fs.openSync(target, 'a');",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-1): the re-open after rotation -- once per spawn, only when the 64 MiB ceiling was crossed."
+    },
+    {
+      "key": "lib/model-proxy/proxy-instance-record.js\tsync-api\texecFileSync(\treturn execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: PS_TIMEOUT_MS })",
+      "justification": "Model-proxy survival WP-1 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-4): ps is the authority that a recorded pid is still THIS proxy before it is adopted or SIGTERMed (a recycled pid must never be signalled, and a dead proxy's pid is free for the OS to hand out). Runs once per boot/crash-recovery start() and once per explicit stop() of an adopted proxy, bounded by a 2 s timeout; never a request path."
+    },
+    {
+      "key": "lib/model-proxy/handoff.js\tprocess-launch\tspawn(\tchild = spawn(process.execPath, [PROXY_SCRIPT], {",
+      "justification": "Model-proxy survival WP-2 (docs/model-proxy-survives-ctm-restart-2026-10-22.html D-7 step 3): the upgrade handoff spawns the successor proxy from THIS file's own path on disk -- detached, its own log descriptor, one IPC channel, and exactly ONCE per process (the admin route answers 409 already_draining to every later caller). It is a spawn of a detached long-lived proxy (the same shape lib/oauth-proxy-supervisor.js's spawn is exempted for), not a request-path child, and it runs in the PROXY process rather than CTM's main thread."
+    },
+    {
+      "key": "lib/session-create/delegate-worker.js\tsync-api\tfs.readFileSync(\tconst bytes = fs.readFileSync(filePath);",
+      "justification": "Lead-cost routing round 2 D-3 (docs/lead-cost-routing-round2-2026-10-24.html §6.2): getWorkerStatus() counts the distinct file:line citations of the text its report_source names -- one read of the worker's own report or --output-last-message file (tens of KB, capped at WORKER_REPORT_TEXT_CAP_BYTES for counting) per status/wait read of a TERMINAL worker only (non-terminal statuses read nothing), not a hot loop; synchronous for the same reason the report_present fs.existsSync and last-message fs.statSync exemptions above are: getWorkerStatus's §6.2 contract returns synchronously."
     }
   ]
 }

package/template/coding-task-manager/lib/media-journal-control-reader.js

@@ -0,0 +1,473 @@
+'use strict';
+
+// READ-ONLY recovery reader for the media journal's terminal draft request cancellations.
+//
+// It preserves lib/media-journal.js's framing contract exactly: an LF-delimited line is decoded with
+// its own StringDecoder, JS-trimmed at both ends, blank lines are skipped, and a committed non-blank
+// line that is not valid JSON FAILS the read -- it is never skipped. What it adds is that only the
+// five root fields this lane owns are ever materialized, so an unselected multi-megabyte value costs
+// one 64KiB window instead of a tree.
+//
+// Two bounded positional passes on ONE read-only FileHandle per file: a framing pass finds each LF
+// and the exact byte range JS-trim keeps, then a parse pass re-reads just that range through the raw
+// stream-json lexer (validation) and its Assembler (selected values only). Lexer, selector and IO
+// errors all propagate; nothing is swallowed. Doubled IO, bounded content memory.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { StringDecoder } = require('node:string_decoder');
+
+// Both are ESM-only, BSD-3-Clause packages; Node 25.2.1's require(esm) is what lets this CJS module
+// use their public exports (never a private prototype path).
+const { jsonParser } = require('stream-json/core/parser.js');
+const { Assembler } = require('stream-json/assembler.js');
+const { none, isMany, getManyValues } = require('stream-chain/core');
+
+const { JOURNAL_READ_WINDOW_BYTES, readCursor, readJournalWindow } = require('./media-journal');
+
+// The canonical kind this lane exists for, compared exactly as the SQL validator compares it.
+const TERMINAL_DRAFT_REQUEST_CANCEL = 'terminal-draft-request-cancel';
+
+// The five root fields this lane owns. A published entry carries these and only these; a field the
+// record lacks stays missing, so the real validator decides whether an incomplete cancellation is
+// usable.
+const CONTROL_ROOT_FIELDS = ['journalId', 'kind', 'sessionId', 'clientRequestId', 'tsMs'];
+
+const JOURNAL_FILE_NAME = /^journal-.*\.jsonl$/;
+const LF_BYTE = 0x0a;
+const READER_CLOSED = 'CTM_MEDIA_JOURNAL_READER_CLOSED';
+
+// Packed values are deliberately OFF: the raw lexer then emits start/…Chunk/end frames, so an
+// unselected string or number is validated without ever being concatenated into a value.
+const RAW_PARSER_OPTIONS = Object.freeze({
+  packKeys: false,
+  packStrings: false,
+  packNumbers: false,
+  jsonStreaming: false,
+});
+
+// Bounded positional window reader shared by both passes: never a whole-file and never a whole-line
+// read, and never more than one window in flight beyond the caller's own buffer.
+async function readWindowRange({ handle, filePath, from, to, checkpoint, onWindow }) {
+  let position = from;
+  while (position < to) {
+    await checkpoint();
+    const window = await readJournalWindow(handle, filePath, position,
+      Math.min(JOURNAL_READ_WINDOW_BYTES, to - position));
+    await checkpoint();
+    await onWindow(window, position);
+    position += window.length;
+  }
+}
+
+// Narrow the live root-field candidates against one key chunk. Candidates are compared character by
+// character, so an unknown key of any length is rejected without ever being concatenated into a
+// string, and a key longer than the longest field literal is rejected outright.
+function narrowFieldCandidates(selector, chunk) {
+  const offset = selector.fieldOffset;
+  const next = [];
+  for (const field of selector.fieldCandidates) {
+    if (field.length < offset + chunk.length) continue;
+    let matches = true;
+    for (let index = 0; index < chunk.length; index += 1) {
+      if (field.charCodeAt(offset + index) !== chunk.charCodeAt(index)) { matches = false; break; }
+    }
+    if (matches) next.push(field);
+  }
+  selector.fieldOffset = offset + chunk.length;
+  selector.fieldCandidates = next.length ? next : null;
+}
+
+// Selector for ONE record: tracks the root object, the nesting depth and the five root field
+// literals, and assembles ONLY the selected root values. Every other token is consumed for
+// validation and dropped, so an unselected value of any size or depth is never materialized.
+class ControlRecordSelector {
+  constructor() {
+    this.entry = {};
+    this.depth = 0;
+    this.rootIsObject = false;
+    this.fieldCandidates = null;
+    this.fieldOffset = 0;
+    this.field = null;
+    this.selection = null;
+  }
+
+  accept(token) {
+    const name = token.name;
+
+    // A selected root value is open: every token belongs to it until the value completes.
+    if (this.selection) {
+      this.pack(token);
+      switch (name) {
+        case 'startObject':
+        case 'startArray':
+          this.depth += 1;
+          break;
+        case 'endObject':
+        case 'endArray':
+          this.depth -= 1;
+          // The selected value started as a child of the root object, so its own container closing
+          // returns the depth to 1; a container nested inside it returns to 2 or deeper.
+          if (this.depth === 1) this.finishSelection();
+          break;
+        case 'endString':
+        case 'endNumber':
+          if (this.selection.type === 'scalar') this.finishSelection();
+          break;
+        default:
+          break;
+      }
+      return;
+    }
+
+    switch (name) {
+      case 'startObject':
+      case 'startArray':
+        if (this.depth === 0) {
+          // A root container: an array root has no field names, so it can never be a cancellation.
+          this.rootIsObject = name === 'startObject';
+          this.depth = 1;
+          return;
+        }
+        if (this.depth === 1 && this.field !== null) this.beginSelection(name, token);
+        this.depth += 1;
+        return;
+      case 'endObject':
+      case 'endArray':
+        this.depth -= 1;
+        return;
+      case 'startKey':
+        this.field = null;
+        if (this.depth === 1 && this.rootIsObject) {
+          this.fieldCandidates = CONTROL_ROOT_FIELDS;
+          this.fieldOffset = 0;
+        }
+        return;
+      case 'endKey': {
+        if (!this.fieldCandidates) return;
+        const offset = this.fieldOffset;
+        this.field = this.fieldCandidates.find(field => field.length === offset) || null;
+        this.fieldCandidates = null;
+        return;
+      }
+      case 'stringChunk':
+        // Key text arrives as stringChunk framed by startKey/endKey (this library has no keyChunk);
+        // an unselected value's text is validated by the lexer and dropped here.
+        if (this.fieldCandidates) narrowFieldCandidates(this, token.value);
+        return;
+      case 'startString':
+      case 'startNumber':
+        if (this.depth === 1 && this.field !== null) this.beginSelection('scalar', token);
+        return;
+      case 'trueValue':
+      case 'falseValue':
+      case 'nullValue':
+        if (this.depth === 1 && this.field !== null) {
+          this.beginSelection('scalar', token);
+          this.finishSelection();
+        }
+        return;
+      default:
+        return;
+    }
+  }
+
+  beginSelection(type, token) {
+    this.selection = {
+      type,
+      field: this.field,
+      assembler: new Assembler(),
+      inKey: false,
+      keyParts: null,
+      scalar: null,
+    };
+    this.field = null;
+    this.pack(token);
+  }
+
+  finishSelection() {
+    const { field, assembler } = this.selection;
+    this.selection = null;
+    // A duplicate root key keeps the LAST value, exactly like JSON.parse.
+    this.entry[field] = assembler.current;
+  }
+
+  // Bridges the raw lexer's frames into the packed tokens the upstream Assembler consumes:
+  // startString/…/endString -> stringValue, startNumber/…/endNumber -> numberValue,
+  // startKey/…/endKey -> keyValue. Structural and literal tokens pass straight through.
+  pack(token) {
+    const selection = this.selection;
+    switch (token.name) {
+      case 'startKey':
+        selection.inKey = true;
+        selection.keyParts = [];
+        return;
+      case 'endKey':
+        selection.inKey = false;
+        selection.assembler.consume({ name: 'keyValue', value: selection.keyParts.join('') });
+        selection.keyParts = null;
+        return;
+      case 'startString':
+        selection.scalar = { name: 'stringValue', parts: [] };
+        return;
+      case 'startNumber':
+        selection.scalar = { name: 'numberValue', parts: [] };
+        return;
+      case 'stringChunk':
+      case 'numberChunk':
+        if (selection.inKey) selection.keyParts.push(token.value);
+        else if (selection.scalar) selection.scalar.parts.push(token.value);
+        return;
+      case 'endString':
+      case 'endNumber': {
+        const scalar = selection.scalar;
+        selection.scalar = null;
+        selection.assembler.consume({ name: scalar.name, value: scalar.parts.join('') });
+        return;
+      }
+      default:
+        selection.assembler.consume(token);
+        return;
+    }
+  }
+}
+
+// Same global order as the journal's own pendingEntries(): durable timestamp, then file path, then
+// the record's own byte offset. Applied ONCE, after the whole IO snapshot has been scanned.
+function compareControlRecords(a, b) {
+  return Number(a.entry.tsMs || 0) - Number(b.entry.tsMs || 0)
+    || a.filePath.localeCompare(b.filePath)
+    || a.startOffset - b.startOffset;
+}
+
+function createMediaJournalControlReader(options = {}) {
+  const directory = String(options.directory || '');
+  const assertCurrent = options.assertCurrent;
+  if (!directory) throw new TypeError('Media journal control reader requires a directory');
+  if (typeof assertCurrent !== 'function') throw new TypeError('Media journal control reader requires an assertCurrent function');
+  const root = path.resolve(directory);
+
+  // Owned resource ledger: the ACTUAL FileHandle objects this reader opened and has not positively
+  // closed -- never file descriptors and never pids.
+  const owned = new Set();
+  const releases = new Map();
+  let readOp = null;
+  let closeOp = null;
+  let retired = false;
+
+  function closedError(message) {
+    return Object.assign(new Error(message || 'Media journal control reader is closed'), { code: READER_CLOSED });
+  }
+
+  // The one boundary check: a retired reader stops a pending read before the next await and again
+  // before any byte is read or any token is processed or published.
+  async function checkpoint() {
+    if (retired) throw closedError('Media journal control reader was closed while reading');
+    await assertCurrent();
+    if (retired) throw closedError('Media journal control reader was closed while reading');
+  }
+
+  // One close attempt per handle per call, joined (never duplicated) while an attempt is in flight.
+  // A close that cannot be confirmed leaves the object in the ledger; it is never retried in a loop.
+  function release(handle) {
+    const inFlight = releases.get(handle);
+    if (inFlight) return inFlight;
+    const attempt = Promise.resolve().then(() => handle.close()).then(
+      () => { owned.delete(handle); return { ok: true }; },
+      error => ({ ok: false, error }),
+    ).finally(() => { releases.delete(handle); });
+    releases.set(handle, attempt);
+    return attempt;
+  }
+
+  // Second pass: re-read exactly one committed record's trimmed byte range and assemble only the
+  // root fields this lane owns. Validation is the library lexer's job; a syntax error propagates.
+  async function parseControlRecord(handle, filePath, from, to) {
+    const selector = new ControlRecordSelector();
+    const decoder = new StringDecoder('utf8');
+    const lexer = jsonParser(RAW_PARSER_OPTIONS);
+    const accept = (out) => {
+      if (out === none) return;
+      if (isMany(out)) {
+        for (const token of getManyValues(out)) selector.accept(token);
+        return;
+      }
+      selector.accept(out);
+    };
+    await readWindowRange({
+      handle,
+      filePath,
+      from,
+      to,
+      checkpoint,
+      onWindow: (window) => {
+        const text = decoder.write(window);
+        if (text) accept(lexer(text));
+      },
+    });
+    const tail = decoder.end();
+    if (tail) accept(lexer(tail));
+    // The single flush, at the known committed LF the range was framed against.
+    accept(lexer(none));
+    return selector.entry;
+  }
+
+  // First pass: find every LF, track the exact byte range JS-trim would keep, and hand each
+  // discovered record straight to the parse pass -- no array of boundaries, no whole-line buffer.
+  async function frameControlRecords(handle, filePath, start, size, results) {
+    let decoder = new StringDecoder('utf8');
+    let lineStart = start;
+    let hasContent = false;
+    let leadingTrimBytes = 0;
+    let trailingTrimBytes = 0;
+
+    // Trim runs are reconstructed from complete decoded chunks: a whitespace character is never
+    // split across chunks (the decoder holds incomplete sequences), and only REMOVED whitespace is
+    // ever measured in bytes, so a replacement character is never counted as trimmed.
+    const noteText = (text) => {
+      if (!text) return;
+      const leading = text.length - text.trimStart().length;
+      if (leading === text.length) {
+        // All trim whitespace: it extends the leading run while no content has been seen, and the
+        // trailing run afterwards.
+        if (hasContent) trailingTrimBytes += Buffer.byteLength(text, 'utf8');
+        else leadingTrimBytes += Buffer.byteLength(text, 'utf8');
+        return;
+      }
+      if (!hasContent) {
+        leadingTrimBytes += Buffer.byteLength(text.slice(0, leading), 'utf8');
+        hasContent = true;
+      }
+      const trailing = text.length - text.trimEnd().length;
+      trailingTrimBytes = Buffer.byteLength(text.slice(text.length - trailing), 'utf8');
+    };
+
+    await readWindowRange({
+      handle,
+      filePath,
+      from: start,
+      to: size,
+      checkpoint,
+      onWindow: async (window, windowStart) => {
+        let pieceStart = 0;
+        for (let index = 0; index < window.length; index += 1) {
+          if (window[index] !== LF_BYTE) continue;
+          noteText(decoder.write(window.subarray(pieceStart, index)));
+          noteText(decoder.end());
+          const lfOffset = windowStart + index;
+          if (hasContent) {
+            // The trimmed range this LF commits. Reported offsets stay the raw line span below, so
+            // the journal cursor contract is unchanged.
+            const entry = await parseControlRecord(handle, filePath,
+              lineStart + leadingTrimBytes, lfOffset - trailingTrimBytes);
+            if (String(entry.kind || '').trim() === TERMINAL_DRAFT_REQUEST_CANCEL) {
+              results.push({ entry, filePath, startOffset: lineStart, endOffset: lfOffset + 1 });
+            }
+          }
+          decoder = new StringDecoder('utf8');
+          lineStart = lfOffset + 1;
+          hasContent = false;
+          leadingTrimBytes = 0;
+          trailingTrimBytes = 0;
+          pieceStart = index + 1;
+        }
+        // An unterminated tail is decoded but never committed: no LF, no record, no flush.
+        noteText(decoder.write(window.subarray(pieceStart)));
+      },
+    });
+  }
+
+  async function scanJournalFile(filePath, results) {
+    await checkpoint();
+    const handle = await fs.promises.open(filePath, 'r');
+    owned.add(handle);
+    let failed = false;
+    let failure;
+    try {
+      await checkpoint();
+      // The ONE captured length for this file: every window is clamped to it, so bytes appended
+      // after this snapshot are never claimed as consumed.
+      const { size } = await handle.stat();
+      await checkpoint();
+      const cursor = await readCursor(filePath);
+      await checkpoint();
+      const start = Math.min(size, Math.max(0, Number(cursor) || 0));
+      await frameControlRecords(handle, filePath, start, size, results);
+    } catch (error) {
+      failed = true;
+      failure = error;
+    }
+    // The reader owns this handle either way: released exactly once, here.
+    const closed = await release(handle);
+    if (failed) {
+      if (!closed.ok) {
+        throw new AggregateError([failure, closed.error],
+          'Media journal control read and owned handle cleanup both failed', { cause: failure });
+      }
+      throw failure;
+    }
+    if (!closed.ok) throw closed.error;
+  }
+
+  async function read() {
+    await checkpoint();
+    if (readOp) return readOp;
+    const operation = (async () => {
+      await checkpoint();
+      let names;
+      try {
+        names = await fs.promises.readdir(root);
+      } catch (error) {
+        // A directory that has never existed is the empty journal; every other IO failure is not.
+        if (error?.code === 'ENOENT') { await checkpoint(); return []; }
+        throw error;
+      }
+      await checkpoint();
+      const results = [];
+      for (const name of names.filter(name => JOURNAL_FILE_NAME.test(name)).sort()) {
+        await checkpoint();
+        await scanJournalFile(path.join(root, name), results);
+      }
+      await checkpoint();
+      return results.sort(compareControlRecords);
+    })();
+    // A failed scan stays the reader's answer: a later read() re-delivers THIS failure instead of
+    // opening a second handle beside one whose close may not have been confirmed. Only close() ever
+    // touches a real handle again.
+    readOp = operation.then((ordered) => {
+      if (retired) throw closedError();
+      return ordered;
+    });
+    return readOp;
+  }
+
+  function close() {
+    retired = true;
+    if (closeOp) return closeOp;
+    closeOp = (async () => {
+      const pending = readOp;
+      if (pending) {
+        try {
+          await pending;
+        } catch (readError) {
+          // The read caller already receives this failure; close reports only unconfirmed handles.
+          void readError;
+        }
+      }
+      readOp = null;
+      const failures = [];
+      for (const handle of [...owned]) {
+        const closed = await release(handle);
+        if (!closed.ok) failures.push(closed.error);
+      }
+      if (failures.length) {
+        throw new AggregateError(failures, 'Media journal control reader left unconfirmed descriptors');
+      }
+    })().finally(() => { closeOp = null; });
+    return closeOp;
+  }
+
+  return { read, close };
+}
+
+module.exports = { createMediaJournalControlReader };