create-walle 0.10.0 → 0.10.2

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

@@ -39,35 +39,83 @@ async function readCursor(journalPath) {
   }
 }
 
-async function readRecords(journalPath, startOffset = 0) {
-  const handle = await fs.promises.open(journalPath, 'r');
-  let size;
-  let absoluteStart;
-  let buffer;
-  try {
-    size = (await handle.stat()).size;
-    absoluteStart = Math.min(size, Math.max(0, Number(startOffset) || 0));
-    buffer = Buffer.allocUnsafe(size - absoluteStart);
-    let bytesRead = 0;
-    while (bytesRead < buffer.length) {
-      const read = await handle.read(buffer, bytesRead, buffer.length - bytesRead, absoluteStart + bytesRead);
-      if (read.bytesRead === 0) break;
-      bytesRead += read.bytesRead;
+// I/O working set only: neither the record size nor the recovered records array is capped.
+const JOURNAL_READ_WINDOW_BYTES = 64 * 1024;
+
+async function closeAfterJournalFailure(handle, error) {
+  try { await handle.close(); }
+  catch (closeError) {
+    throw new AggregateError([error, closeError], 'Media journal operation and owned handle cleanup failed', { cause: error });
+  }
+}
+
+async function readJournalWindow(handle, journalPath, position, length) {
+  const buffer = Buffer.allocUnsafe(length);
+  let filled = 0;
+  // Fill one window even when the filesystem returns tiny short reads. Retaining a new 64KiB
+  // buffer for each few bytes of progress would amplify a long line's working set needlessly.
+  while (filled < length) {
+    const remaining = length - filled;
+    const { bytesRead } = await handle.read(buffer, filled, remaining, position + filled);
+    if (bytesRead === 0) {
+      throw Object.assign(new Error(`Media journal ${path.basename(journalPath)} ended before its captured length; recovery is required`),
+        { code: 'CTM_MEDIA_JOURNAL_TRUNCATED' });
     }
-    if (bytesRead !== buffer.length) buffer = buffer.subarray(0, bytesRead);
-  } finally {
-    await handle.close();
+    if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > remaining) {
+      throw Object.assign(new Error('Media journal read returned invalid byte progress'),
+        { code: 'CTM_MEDIA_JOURNAL_READ_INVALID' });
+    }
+    filled += bytesRead;
   }
+  return buffer;
+}
+
+async function frameJournalRecords(handle, journalPath, absoluteStart, size) {
   const records = [];
-  let lineStart = 0;
-  for (let index = 0; index < buffer.length; index += 1) {
-    if (buffer[index] !== 0x0a) continue;
-    const endOffset = absoluteStart + index + 1;
-    const raw = buffer.subarray(lineStart, index).toString('utf8').trim();
-    if (raw) records.push({ entry: JSON.parse(raw), startOffset: absoluteStart + lineStart, endOffset });
-    lineStart = index + 1;
+  let pieces = [];
+  let lineBytes = 0;
+  let lineStart = absoluteStart;
+  let position = absoluteStart;
+  while (position < size) {
+    const buffer = await readJournalWindow(handle, journalPath, position,
+      Math.min(JOURNAL_READ_WINDOW_BYTES, size - position));
+    let pieceStart = 0;
+    for (let index = 0; index < buffer.length; index += 1) {
+      if (buffer[index] !== 0x0a) continue;
+      pieces.push(buffer.subarray(pieceStart, index));
+      lineBytes += index - pieceStart;
+      const endOffset = position + index + 1;
+      const line = pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, lineBytes);
+      // Decode only after newline framing: split UTF-8 sequences survive read/window boundaries.
+      const raw = line.toString('utf8').trim();
+      if (raw) records.push({ entry: JSON.parse(raw), startOffset: lineStart, endOffset });
+      pieces = [];
+      lineBytes = 0;
+      lineStart = endOffset;
+      pieceStart = index + 1;
+    }
+    if (pieceStart < buffer.length) {
+      pieces.push(buffer.subarray(pieceStart));
+      lineBytes += buffer.length - pieceStart;
+    }
+    position += buffer.length;
   }
-  return { records, size, partialOffset: absoluteStart + lineStart };
+  return { records, size, partialOffset: lineStart };
+}
+
+async function readRecords(journalPath, startOffset = 0) {
+  const handle = await fs.promises.open(journalPath, 'r');
+  let parsed;
+  try {
+    const size = (await handle.stat()).size;
+    const absoluteStart = Math.min(size, Math.max(0, Number(startOffset) || 0));
+    parsed = await frameJournalRecords(handle, journalPath, absoluteStart, size);
+  } catch (error) {
+    await closeAfterJournalFailure(handle, error);
+    throw error;
+  }
+  await handle.close();
+  return parsed;
 }
 
 async function createMediaJournal(options = {}) {
@@ -80,7 +128,6 @@ async function createMediaJournal(options = {}) {
   const journalPath = path.join(root, `journal-${bootId}.jsonl`);
   const handle = await fs.promises.open(journalPath, 'a', 0o600);
   await fs.promises.chmod(journalPath, 0o600).catch(() => {});
-  await syncDirectory(root);
 
   const files = new Map();
   let op = Promise.resolve();
@@ -124,7 +171,14 @@ async function createMediaJournal(options = {}) {
       files.set(filePath, { cursor: offset, records: parsed.records, size: parsed.size });
     }
   }
-  await refresh();
+  try {
+    await syncDirectory(root);
+    await refresh();
+  } catch (error) {
+    // A failed constructor returns no journal whose close() the caller could invoke.
+    await closeAfterJournalFailure(handle, error);
+    throw error;
+  }
 
   function serialize(fn) {
     const next = op.then(fn, fn);
@@ -335,6 +389,9 @@ const { DRAFT_CANONICAL_FIELDS, DRAFT_STATE_VERSION_MAX, canonicalDraftProjectio
 
 module.exports = {
   createMediaJournal,
+  JOURNAL_READ_WINDOW_BYTES,
+  readCursor,
+  readJournalWindow,
   DRAFT_CANONICAL_FIELDS,
   DRAFT_STATE_VERSION_MAX,
   canonicalDraftProjection,

package/template/coding-task-manager/lib/media-store-options.js

@@ -1,5 +1,22 @@
 'use strict';
 
+function createMediaJournalProjector(runDbWorkerOp) {
+  return (entry, projection = {}) => {
+    const urgent = entry.projectionPriority === 'urgent' || projection.urgent;
+    const effectiveEntry = urgent && entry.projectionPriority !== 'urgent'
+      ? { ...entry, projectionPriority: 'urgent' }
+      : entry;
+    return runDbWorkerOp('runDbMutation', {
+      action: 'applyMediaJournalEntry',
+      args: [effectiveEntry],
+    }, {
+      priority: urgent ? 'urgent' : 'low',
+      requestClass: urgent ? 'user-blocking' : 'background',
+      timeoutMs: urgent ? 10_000 : 30_000,
+    });
+  };
+}
+
 function buildMediaStoreOptions({
   dataDir, bootId, registry, assertDraftOwner, runDbWorkerOp, onDrainProgress,
   currentOwnerId, isSameOwnerLineage,
@@ -25,21 +42,32 @@ function buildMediaStoreOptions({
     // drain progress with the load-pressure controller so the media journal participates
     // in the same producer-debt/freshness framework as read-pool-batch/provider-index above.
     onDrainProgress,
-    projectEntry: (entry, projection = {}) => {
-      const urgent = entry.projectionPriority === 'urgent' || projection.urgent;
-      const effectiveEntry = urgent && entry.projectionPriority !== 'urgent'
-        ? { ...entry, projectionPriority: 'urgent' }
-        : entry;
-      return runDbWorkerOp('runDbMutation', {
-        action: 'applyMediaJournalEntry',
-        args: [effectiveEntry],
-      }, {
-        priority: urgent ? 'urgent' : 'low',
-        requestClass: urgent ? 'user-blocking' : 'background',
-        timeoutMs: urgent ? 10_000 : 30_000,
-      });
-    },
+    projectEntry: createMediaJournalProjector(runDbWorkerOp),
   };
 }
 
-module.exports = { buildMediaStoreOptions };
+async function prepareMainMediaStore({
+  createStore, getDataDir, bootId, runDbWorkerOp, assertDraftOwner,
+  onDrainProgress, getCurrentOwnerId, isSameOwnerLineage,
+}) {
+  const registry = await runDbWorkerOp('loadMediaStoreRegistry', {}, {
+    // Listener activation depends on this registry. It is boot-critical
+    // maintenance, while the journal projections below remain background work.
+    priority: 'high',
+    requestClass: 'maintenance',
+    timeoutMs: 30_000,
+  });
+  return createStore(buildMediaStoreOptions({
+    dataDir: getDataDir(), bootId, registry, assertDraftOwner, runDbWorkerOp, onDrainProgress,
+    // WP-1 (docs/image-draft-event-ordering-and-verified-adoption-2026-10-14.html §6.4): the store
+    // is the single draft version allocator. It recovers the highest pending journal version and
+    // then applies verified owner-lineage normalization as one journaled mutation — the draft
+    // restamp was removed from db.js restampOwnerLineage so the two can never allocate concurrently.
+    // Review finding 9: getCurrentOwnerId delegates to the existing LAZY, MEMOIZED identity
+    // accessor only after the DB is open. It returns no invented hostname/port-derived identity.
+    // isSameOwnerLineage is the existing dbModule-free lineage snapshot, not a new DB boundary.
+    currentOwnerId: getCurrentOwnerId(), isSameOwnerLineage,
+  }));
+}
+
+module.exports = { buildMediaStoreOptions, createMediaJournalProjector, prepareMainMediaStore };

package/template/coding-task-manager/lib/migrations/v56-host-samples-and-machine-pool.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// WP-1 (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §5 D-4/D-7/D-11, §6.1, §8 WP-1,
+// §9 S-3): the machine-pool schema, in one migration because every piece of it lands with the same
+// reader (lib/host-stats.js today; WP-2/WP-3 for the pairing/self tables).
+//
+//   host_samples           D-11 — the box owns its own 24 h time series (one row per 60 s tick;
+//                                 ≤1440 rows/machine). No hub-side samples table exists.
+//   machine_self           D-4 rev 2 — this machine's OWN user settings (display name, favorite,
+//                                 hidden). Exactly one row, id = 1.
+//   machine_pairing_offers D-6 — the RFC 8628-shaped code a joining member redeems. The plaintext
+//                                 code is never stored, only its hash.
+//   machines.urls_json     P-1/P-4 rev 2 — the member's dialable URLs in dial order.
+//
+// Rev 2 deliberately has NO peer_credentials table: D-7 is one shared pool secret in
+// machine-pool.json, never in the DB.
+//
+// The shape follows v55-agent-origin-backfill.js: a narrow dependency object, idempotent SQL, and
+// the version stamp LAST so a failure leaves the ladder where it was. ALTER TABLE has no
+// `IF NOT EXISTS` in SQLite, so the column add is guarded by its own PRAGMA read — which also
+// makes a re-run (a restored snapshot, a partially upgraded file) a no-op rather than an error.
+
+const TABLES_DDL = `
+  CREATE TABLE IF NOT EXISTS host_samples (
+    at INTEGER PRIMARY KEY,
+    sample_json TEXT NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS machine_self (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    display_name TEXT NOT NULL DEFAULT '',
+    favorite INTEGER NOT NULL DEFAULT 0,
+    hidden INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0
+  );
+  CREATE TABLE IF NOT EXISTS machine_pairing_offers (
+    id TEXT PRIMARY KEY,
+    code_hash TEXT NOT NULL UNIQUE,
+    created_at INTEGER NOT NULL,
+    expires_at INTEGER NOT NULL,
+    redeemed_at INTEGER,
+    redeemed_by TEXT
+  );
+`;
+
+function _tableExists(db, table) {
+  try {
+    return !!db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
+  } catch {
+    return false; // expected: a handle that cannot read sqlite_master (pre-boot) has nothing to alter
+  }
+}
+
+function _tableHasColumn(db, table, column) {
+  try {
+    return db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === column);
+  } catch {
+    return false; // expected: no such table on an old/partial database -> nothing to alter
+  }
+}
+
+function migrateToV56({ getDb, setSchemaVersion, log = console } = {}) {
+  if (typeof getDb !== 'function' || typeof setSchemaVersion !== 'function') throw new TypeError('migration dependencies are required');
+  const db = getDb();
+  db.exec(TABLES_DDL);
+  // S-3: existing databases get the column by ALTER; db.js's machines CREATE literal carries the
+  // same column for a fresh file, and the two must stay in the same ordinal position.
+  let altered = 0;
+  if (_tableExists(db, 'machines') && !_tableHasColumn(db, 'machines', 'urls_json')) {
+    db.exec("ALTER TABLE machines ADD COLUMN urls_json TEXT NOT NULL DEFAULT '[]'");
+    altered = 1;
+  }
+  setSchemaVersion(56);
+  log.log(`[db] Schema migrated to v56 (host samples + machine pool): ${altered} column(s) added`);
+}
+
+module.exports = { migrateToV56 };

package/template/coding-task-manager/lib/mirror-feed-sanitize.js

@@ -151,9 +151,14 @@ function createHostedMirrorFeedCoalescer(options = {}) {
     clear();
     if (!buffer) return false;
     const batch = buffer;
+    // WP-4 (clock-free-tests-followups-r4-2026-10-24.html §5 R-9, §6.5): the batch's FIRST-byte
+    // time, not the drain time -- a held/buffered batch was received when its first byte arrived,
+    // and the hold is exactly the delay this stamp exists to expose. Captured before `startedAt`
+    // is cleared below.
+    const receivedAt = startedAt || now();
     buffer = '';
     startedAt = 0;
-    deliver(sanitizeAndCoalesceHostedMirrorFeed(batch, command()));
+    deliver(sanitizeAndCoalesceHostedMirrorFeed(batch, command()), { receivedAt });
     return true;
   };
   const arm = (ms, opts = {}) => {
@@ -174,7 +179,8 @@ function createHostedMirrorFeedCoalescer(options = {}) {
     const hasSyncControl = _hasSyncFrameControl(text);
     const hasRedrawControl = _hasCursorRedrawControl(text);
     if (!buffer && !hasSyncControl && !hasRedrawControl) {
-      deliver(sanitizeHostedMirrorFeed(text, command()));
+      // WP-4 (R-9, §6.5): the immediate path was never held, so its receipt time IS now.
+      deliver(sanitizeHostedMirrorFeed(text, command()), { receivedAt: now() });
       return true;
     }
     if (!startedAt) startedAt = now();
@@ -204,7 +210,10 @@ function createHostedMirrorFeedCoalescer(options = {}) {
     const prefix = buffer.slice(0, lastOff + SYNC_OFF.length);
     const trailing = buffer.slice(lastOff + SYNC_OFF.length);
     buffer = trailing;
-    deliver(sanitizeAndCoalesceHostedMirrorFeed(prefix, command()));
+    // WP-4 (R-9, §6.5): this prefix came out of the same buffer as flush()'s batch, so it carries
+    // the same first-byte time. `startedAt` is still live here when `trailing` is non-empty; the
+    // `|| now()` fallback only covers a zeroed clock.
+    deliver(sanitizeAndCoalesceHostedMirrorFeed(prefix, command()), { receivedAt: startedAt || now() });
     if (trailing) {
       // Keep startedAt running for the trailing incomplete fragment and re-arm the safety timer.
       arm(2000, { reset: true });

package/template/coding-task-manager/lib/model-execution-recipe-metadata.js

@@ -6,13 +6,24 @@ const RECIPE_KEYS = Object.freeze([
   'version', 'ctmSessionId', 'processGeneration', 'harness', 'providerThreadId',
   'routeId', 'wireModelId', 'profileFingerprint', 'factsRevision', 'transitionId',
 ]);
-const OPTIONAL_RECIPE_KEYS = Object.freeze(['sourceEnvironmentReference']);
+// `nativeConfigReceipt` is the Codex config.toml receipt read at launch (state + sha256). It rides
+// the recipe so a session ADOPTED from a surviving host after a CTM restart still proves which
+// config its process started under; without it a lead switch refuses source_config_policy_unqualified.
+const OPTIONAL_RECIPE_KEYS = Object.freeze(['sourceEnvironmentReference', 'nativeConfigReceipt']);
 const SOURCE_ENVIRONMENT_REFERENCES = new Set(['captured-empty', 'private-owner-required']);
 const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const CANONICAL_MODEL_ID_PATTERN = /^[A-Za-z0-9@][A-Za-z0-9@._:/+-]{0,255}$/;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 
+function validConfigReceipt(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  if (keys.length !== 2 || !keys.includes('state') || !keys.includes('sha256')) return false;
+  return (value.state === 'present' && typeof value.sha256 === 'string' && SHA256_PATTERN.test(value.sha256))
+    || (value.state === 'missing' && value.sha256 === null);
+}
+
 function boundedId(value) {
   return typeof value === 'string' && ID_PATTERN.test(value);
 }
@@ -37,6 +48,7 @@ function sanitizedRecipe(value, minimumGeneration = 1) {
       || RECIPE_KEYS.some((key) => !Object.hasOwn(value, key))) return undefined;
   if (Object.hasOwn(value, 'sourceEnvironmentReference')
       && !SOURCE_ENVIRONMENT_REFERENCES.has(value.sourceEnvironmentReference)) return undefined;
+  if (Object.hasOwn(value, 'nativeConfigReceipt') && !validConfigReceipt(value.nativeConfigReceipt)) return undefined;
   if (value.version !== 1 || !boundedId(value.ctmSessionId)
     || !Number.isSafeInteger(value.processGeneration) || value.processGeneration < minimumGeneration
     || !['codex-cli', 'claude-code'].includes(value.harness)
@@ -50,8 +62,9 @@ function sanitizedRecipe(value, minimumGeneration = 1) {
     || typeof value.factsRevision !== 'string' || !SHA256_PATTERN.test(value.factsRevision)) return undefined;
 
   if (value.transitionId !== null && !boundedId(value.transitionId)) return undefined;
-  return Object.fromEntries([...RECIPE_KEYS, ...(Object.hasOwn(value, 'sourceEnvironmentReference')
-    ? OPTIONAL_RECIPE_KEYS : [])].map((key) => [key, value[key]]));
+  return Object.fromEntries([...RECIPE_KEYS, ...OPTIONAL_RECIPE_KEYS.filter((key) => Object.hasOwn(value, key))]
+    .map((key) => [key, key === 'nativeConfigReceipt'
+      ? { state: value[key].state, sha256: value[key].sha256 } : value[key]]));
 }
 
 function modelExecutionRecipeFromEnv(env) {

package/template/coding-task-manager/lib/model-proxy/anthropic-face.js

@@ -92,6 +92,10 @@ function anthropicErrorType(kind) {
   if (kind === 'rate_limit_exceeded') return 'rate_limit_error';
   if (kind === 'insufficient_quota') return 'billing_error';
   if (kind === 'server_is_overloaded') return 'overloaded_error';
+  // WP-2 D-5: the two truthful refusal classes carry their own HTTP status (400 / 403), so the type
+  // must not collapse into api_error -- a permission denial is not an upstream fault.
+  if (kind === 'model_not_invocable') return 'invalid_request_error';
+  if (kind === 'model_access_denied') return 'permission_error';
   return 'api_error';
 }
 

package/template/coding-task-manager/lib/model-proxy/chat-response-translators.js

@@ -20,6 +20,9 @@ function createChatResponseTranslators({ normalizeUpstreamOutcome, firstString,
     if (kind === 'rate_limit_exceeded') return 'rate_limit_error';
     if (kind === 'insufficient_quota') return 'billing_error';
     if (kind === 'server_is_overloaded') return 'overloaded_error';
+    // WP-2 D-5: same two mappings as anthropic-face.js (HTTP 400 / 403 respectively).
+    if (kind === 'model_not_invocable') return 'invalid_request_error';
+    if (kind === 'model_access_denied') return 'permission_error';
     return 'api_error';
   }
 

package/template/coding-task-manager/lib/model-proxy/collaboration-codec.js

@@ -27,6 +27,12 @@
 // Nothing here reads or writes the upstream-native Responses body: a
 // `passthrough` route never calls this module at all.
 
+// node:crypto is used for sha256 ONLY (WP-3's handoff marker): a digest is a pure,
+// deterministic function of its argument, so this module stays free of randomness
+// -- no randomUUID/no randomBytes, and every call still returns the same value for
+// the same arguments.
+const crypto = require('node:crypto');
+
 // The reserved V2 collaboration namespace (Codex multi_agents_v2.rs) and the
 // older V1 one (multi_agent_v1). A call is only "readable plaintext" in the V2
 // namespace -- V1's `spawn_agent` is a different wire contract entirely.
@@ -449,6 +455,93 @@ function validateCollaborationInput(body) {
   });
 }
 
+// ── handed-off compaction drop (WP-3) ────────────────────────────────────
+//
+// A Codex lead whose history holds an OpenAI-encrypted `compaction` item cannot
+// replay that item to a routed (chat-translate) upstream: the ciphertext is bound
+// to its issuer and reads as garbage there. The handoff path therefore injects,
+// into the target thread, ONE developer message carrying a plaintext summary and
+// naming -- by SHA-256 of the ciphertext it replaces -- the exact compaction item
+// it stands for:
+//
+//   <ctm_handoff compaction_sha256="<64 lowercase hex>" source_model="<model>">
+//   …summary…
+//   </ctm_handoff>
+//
+// Codex then sends every subsequent request with BOTH the `compaction` item
+// (verbatim) and, later in `input`, that developer message. The pairing is the
+// whole contract: a compaction item is dropped IFF its own replacement is present
+// in the SAME request, at a LATER index. An unmatched compaction item is history
+// this route cannot read and stays exactly where it was, so `validateCollaborationInput`
+// keeps refusing it (fail-closed) rather than silently losing a turn.
+//
+// The drop is a COPY: the caller's body object and its `input` array are never
+// mutated, and the caller's own body reference is returned untouched when nothing
+// was dropped.
+
+const HANDOFF_MARKER_PREFIX = '<ctm_handoff compaction_sha256="';
+
+/** sha256 (utf8) of a ciphertext string, lowercase hex. */
+function ciphertextSha256(encryptedContent) {
+  return crypto.createHash('sha256').update(encryptedContent, 'utf8').digest('hex');
+}
+
+/** True for a `compaction` item whose own ciphertext is present and non-empty. */
+function isCiphertextCompaction(item) {
+  return isObject(item)
+    && item.type === 'compaction'
+    && typeof item.encrypted_content === 'string'
+    && item.encrypted_content.length > 0;
+}
+
+/**
+ * True for the handoff developer message that REPLACES the compaction item whose
+ * ciphertext hashes to `sha`.
+ *
+ * The shape is exact and deliberately narrow: a `message` item whose role is
+ * `developer`, whose `content` is an array, and whose FIRST part starts with the
+ * literal marker prefix. A bare string `content`, a second-part marker, a
+ * `role:'user'` message, a leading space before the marker or a marker for another
+ * ciphertext all fail here -- the marker is the pairing proof, so a near-miss must
+ * never be treated as one.
+ */
+function isHandoffMarkerFor(item, sha) {
+  if (!isObject(item) || item.type !== 'message' || item.role !== 'developer') return false;
+  if (!Array.isArray(item.content) || item.content.length === 0) return false;
+  const first = item.content[0];
+  if (!isObject(first) || first.type !== 'input_text' || typeof first.text !== 'string') return false;
+  return first.text.startsWith(`${HANDOFF_MARKER_PREFIX}${sha}"`);
+}
+
+/**
+ * Omit every `compaction` item whose handoff replacement is present LATER in the
+ * same `input`.
+ *
+ * @param {unknown} body a Responses request body
+ * @returns {{ok:true, body:object, droppedHandedOffCompactions:number}} `body` is
+ *   the caller's own object (same reference) whenever nothing was dropped.
+ */
+function dropHandedOffCompactions(body) {
+  const source = isObject(body) ? body : {};
+  const items = normalizeItems(source.input);
+  let droppedHandedOffCompactions = 0;
+  const kept = [];
+  for (let index = 0; index < items.length; index += 1) {
+    const item = items[index];
+    if (isCiphertextCompaction(item)) {
+      const sha = ciphertextSha256(item.encrypted_content);
+      let covered = false;
+      for (let later = index + 1; later < items.length; later += 1) {
+        if (isHandoffMarkerFor(items[later], sha)) { covered = true; break; }
+      }
+      if (covered) { droppedHandedOffCompactions += 1; continue; }
+    }
+    kept.push(item);
+  }
+  if (droppedHandedOffCompactions === 0) return { ok: true, body, droppedHandedOffCompactions };
+  return { ok: true, body: { ...source, input: kept }, droppedHandedOffCompactions };
+}
+
 // ── translated function-call constructor ─────────────────────────────────
 
 /** True only for a translated call Codex must read as readable plaintext args. */
@@ -488,6 +581,7 @@ function makeTranslatedFunctionCall(fields = {}) {
 
 module.exports = {
   validateCollaborationInput,
+  dropHandedOffCompactions,
   agentMessageToChat,
   makeTranslatedFunctionCall,
   isReadableCollaborationCall,