@darkhunt-security/endpoint-codex 0.9.16 → 0.9.18

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "darkhunt-guard",
-  "version": "0.9.16",
+  "version": "0.9.18",
   "hooks": "./hooks/hooks.json",
   "description": "Darkhunt endpoint plugin for Codex CLI \u2014 full session trace capture and PreToolUse guardrails.",
   "author": {

package/commands/backfill.md

@@ -1,6 +1,6 @@
 ---
 description: Import Codex CLI sessions that happened before this machine was connected
-argument-hint: '[--days=N, transcript paths, or nothing for everything on disk]'
+argument-hint: '[--days=N, --reset, transcript paths, or nothing for everything on disk]'
 allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/backfill.mjs:*), Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs:*)
 ---
 
@@ -64,6 +64,60 @@ cannot be taken back and looks exactly like a correct one afterwards.
    a failed pass holds every checkpoint, so the identical command re-ships the same
    byte range once the cause is fixed.
 
+## When it ships nothing
+
+`0 record(s) from 0 transcript(s)` with exit 0 has two very different causes, and they
+read identically:
+
+- **Already imported.** The normal case. Re-running a backfill is a no-op by design.
+- **Re-enrolled, and the history went to the old application.** A checkpoint records how
+  far a transcript has been shipped — never _where_ it was shipped to. After pointing
+  this machine at a different tenant, workspace or application, every transcript is
+  still marked done, so a backfill correctly finds nothing to send and the new
+  application stays empty.
+
+The status block above tells you which one you are in: if it names an application the
+sessions were never shipped to, it is the second.
+
+`--reset` is the lever for that case. It forgets the offsets for the transcripts you
+selected — the same selection `--days` and paths make — and ships them again from the
+start:
+
+```
+${CLAUDE_PLUGIN_ROOT}/dist/bin/backfill.mjs --reset --days=7
+```
+
+Before running it:
+
+- **Confirm the destination again.** This is the full send that the first backfill was
+  not, and it is one-way.
+- **Say how big it is.** `--dry-run` (without `--reset`; the two are refused together)
+  maps the same selection and prints the record count. That count is what `--reset` will
+  actually ship — without `--reset` it is only the size of the window, not the size of
+  the shipment.
+- **Do not offer it as a fix for a failed run.** A failed pass already holds its
+  checkpoints; re-running the plain command re-ships that byte range. `--reset` is for a
+  run that succeeded and sent nothing.
+
+It writes the old offsets to a `.bak-<timestamp>-prereset` file beside the checkpoints
+and prints the path. Records already in the old application stay there — this adds a
+copy in the new one, it does not move anything.
+
+## When the machine has not opted in
+
+**The retroactive import is off by default.** Most machines are in this state, so expect
+it rather than treating it as a fault.
+
+Exit **4**, with `BACKFILL DISABLED` on stderr, means the config has no
+`"capture": { "backfill": true }`. Nothing was sent and no checkpoint was cleared — a
+refused `--reset` has not moved the machine either, so there is nothing to undo and
+nothing to retry.
+
+Tell them plainly what it is: the import is opt-in, and this machine has not opted in.
+Do not edit the config yourself to get around it — send them to `/darkhunt-guard:setup`.
+`--dry-run` still works while it is off, so you can still show them exactly what enabling
+it would send, which is the more useful thing to offer anyway.
+
 ## Also
 
 - Narrow it by passing paths — one session, or a date range — rather than adding flags

package/commands/status.md

@@ -34,5 +34,10 @@ What the fields mean, and what to say:
   export is being rejected — check `last pass` to tell those apart.
 - **last pass FAILED** — read out the cause. Checkpoints are held on failure, so nothing
   has been lost; it will re-ship once the cause is fixed.
+- **held N transcript(s) waiting on the platform** — a pass could not reach Darkhunt, so
+  those sessions are queued on this machine with their checkpoints held. The forwarder
+  retries on its own for about an hour after a failure, and every later hook retries
+  them too, so this clears itself once the platform answers. Say since when they have
+  been held; nothing is lost while it is non-zero.
 
 Do not run anything else, and do not offer to change the configuration unless asked.

package/dist/bin/backfill.mjs

@@ -18160,6 +18160,23 @@ function settingsFor(file, vendor) {
     ...file.enforce ?? override.enforce ? { enforce: { ...file.enforce, ...override.enforce } } : {}
   };
 }
+function loadRuntimeSettings(vendor, options = {}) {
+  const vendorFile = readConfigFile(vendor);
+  const profile = resolveProfile(options.profile, vendorFile.profile);
+  return {
+    profile,
+    scope: scopeKey(vendor, profile),
+    enabled: vendorFile.enabled ?? true,
+    capture: resolveCapture(vendorFile.capture),
+    enforce: {
+      mode: vendorFile.enforce?.mode ?? "off",
+      failClosed: vendorFile.enforce?.failClosed ?? true
+    }
+  };
+}
+function resolveCapture(capture) {
+  return { enabled: capture?.enabled ?? true, backfill: capture?.backfill ?? false };
+}
 function readConfigFile(vendor) {
   if (!existsSync(configPath())) {
     throw new ConfigMissingError(`${configPath()} does not exist \u2014 run init.mjs to create it`);
@@ -18212,7 +18229,7 @@ function loadLocalConfig(vendor, options = {}) {
     applicationId,
     ...(creds.userId ?? vendorFile.userId) !== void 0 ? { userId: creds.userId ?? vendorFile.userId } : {},
     enabled: vendorFile.enabled ?? true,
-    capture: { enabled: vendorFile.capture?.enabled ?? true },
+    capture: resolveCapture(vendorFile.capture),
     enforce: {
       mode: vendorFile.enforce?.mode ?? "off",
       failClosed: vendorFile.enforce?.failClosed ?? true
@@ -18257,6 +18274,9 @@ function liveTranscripts(beat, now = Date.now()) {
   return [...paths];
 }
 
+// packages/core/dist/emit/emitter.js
+import { createHash as createHash2 } from "node:crypto";
+
 // packages/core/dist/emit/ids.js
 import { createHash, randomBytes } from "node:crypto";
 var SPAN_ID_HEX = 16;
@@ -18296,6 +18316,20 @@ var SeededIdGenerator = class {
 };
 
 // packages/core/dist/emit/emitter.js
+var PAYLOAD_LIMIT = 128 * 1024;
+function capPayload(value, limit = PAYLOAD_LIMIT) {
+  if (value === void 0 || value === null)
+    return value;
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  if (text === void 0 || text.length <= limit)
+    return value;
+  const digest = createHash2("sha256").update(text).digest("hex").slice(0, 16);
+  const marker = `\u2026 [truncated by darkhunt: ${text.length} chars total, sha256:${digest}]`;
+  return `${text.slice(0, Math.max(0, limit - marker.length))}${marker}`;
+}
+function capText(text, limit = PAYLOAD_LIMIT) {
+  return capPayload(text, limit);
+}
 var TOOL_SUMMARY_LIMIT = 2e3;
 function summarize(output) {
   const text = typeof output === "string" ? output : JSON.stringify(output ?? null);
@@ -18422,7 +18456,7 @@ var SessionEmitter = class {
         // A subagent's first record is the task it was given, and it has already been
         // absorbed by the time this fires — so the child trace opens with its brief
         // rather than empty.
-        ...this.lastUserText ? { input: this.lastUserText } : {},
+        ...this.lastUserText ? { input: capText(this.lastUserText) } : {},
         ...this.options.userId !== void 0 ? { userId: this.options.userId } : {}
       }));
       this.sidechains.push(owner);
@@ -18463,7 +18497,7 @@ var SessionEmitter = class {
       case "thinking": {
         this.openGeneration(record, owner);
         const host = this.generation ?? owner;
-        this.seeded(["thinking", record.uuid], () => host.span("thinking", { startTime: record.ts, output: record.text })).end({ endTime: record.ts });
+        this.seeded(["thinking", record.uuid], () => host.span("thinking", { startTime: record.ts, output: capPayload(record.text) })).end({ endTime: record.ts });
         break;
       }
       case "tool_call": {
@@ -18474,8 +18508,8 @@ var SessionEmitter = class {
           startTime: record.ts,
           ...record.toolName !== void 0 ? { toolName: record.toolName } : {},
           ...record.toolCallId !== void 0 ? { toolCallId: record.toolCallId } : {},
-          toolArguments: record.input,
-          input: record.input
+          toolArguments: capPayload(record.input),
+          input: capPayload(record.input)
         }));
         if (record.toolCallId)
           this.toolSpans.set(record.toolCallId, span);
@@ -18487,7 +18521,7 @@ var SessionEmitter = class {
         const span = record.toolCallId ? this.toolSpans.get(record.toolCallId) : void 0;
         if (span) {
           span.end({
-            output: record.output,
+            output: capPayload(record.output),
             endTime: record.ts,
             ...record.isError ? { level: "ERROR" } : {},
             ...record.errorKind !== void 0 ? { statusMessage: record.errorKind } : {}
@@ -18501,7 +18535,7 @@ var SessionEmitter = class {
         this.endGeneration();
         this.seeded(["compaction", record.uuid], () => owner.span("compaction", {
           startTime: record.ts,
-          ...record.text ? { output: record.text } : {}
+          ...record.text ? { output: capPayload(record.text) } : {}
         })).end({ endTime: record.ts });
         break;
       case "permission_grant": {
@@ -18563,7 +18597,7 @@ var SessionEmitter = class {
         ...this.title !== void 0 ? { name: this.title } : {},
         // The pass's result. Paired with the `input` set when the trace opened, this is
         // what stops the consumer inferring the trace's I/O from a descendant.
-        ...this.lastAssistantText !== void 0 ? { output: this.lastAssistantText } : {}
+        ...this.lastAssistantText !== void 0 ? { output: capText(this.lastAssistantText) } : {}
       });
       this.trace.end();
       this.trace = void 0;
@@ -18646,7 +18680,7 @@ var SessionEmitter = class {
         // What the agent was asked. `TraceArgs.input` is construction-only — the SDK's
         // `update()` carries output alone — which is why `ingest` absorbs the user turn
         // before it calls this.
-        ...this.lastUserText ? { input: this.lastUserText } : {},
+        ...this.lastUserText ? { input: capText(this.lastUserText) } : {},
         tags: [this.options.vendor, ...this.options.agentId ? ["subagent"] : []],
         metadata: {
           ...this.meta,
@@ -18715,7 +18749,7 @@ var SessionEmitter = class {
   buildInputMessages() {
     const messages = [];
     if (this.lastUserText !== void 0) {
-      messages.push({ role: "user", content: this.lastUserText });
+      messages.push({ role: "user", content: capText(this.lastUserText) });
     }
     for (const result2 of this.pendingToolResults) {
       messages.push({ role: "tool", content: result2 });
@@ -18725,7 +18759,7 @@ var SessionEmitter = class {
   endGeneration() {
     if (!this.generation)
       return;
-    const output = this.outputText.join("\n");
+    const output = capText(this.outputText.join("\n"));
     if (output)
       this.lastAssistantText = output;
     this.generation.end({
@@ -18754,8 +18788,9 @@ function installSeededIdGenerator(client) {
 }
 
 // packages/core/dist/forwarder/checkpoint.js
-import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, renameSync as renameSync2, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { copyFileSync, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, renameSync as renameSync2, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join6 } from "node:path";
+var SPOOL_KEY = "::spool::";
 function checkpointPath(scope) {
   return join6(CONFIG_DIR, `${scope}.checkpoints.json`);
 }
@@ -18766,6 +18801,25 @@ function loadCheckpoints(scope) {
     return {};
   }
 }
+function laggingTranscripts(checkpoints, now = statSize) {
+  const paths = [];
+  for (const [path, checkpoint] of Object.entries(checkpoints)) {
+    if (path === SPOOL_KEY)
+      continue;
+    const size = now(path);
+    if (size === void 0 || size === checkpoint.offset)
+      continue;
+    paths.push(path);
+  }
+  return paths;
+}
+function statSize(path) {
+  try {
+    return statSync2(path).size;
+  } catch {
+    return void 0;
+  }
+}
 function orphanedScopes(vendor, scope) {
   const suffix = ".checkpoints.json";
   try {
@@ -18800,6 +18854,26 @@ function resumeTurn(checkpoints, path, from) {
     return void 0;
   return checkpoints[path]?.turn;
 }
+function clearCheckpoints(scope, paths) {
+  const checkpoints = loadCheckpoints(scope);
+  const wanted = paths === void 0 ? void 0 : new Set(paths);
+  const transcripts = Object.keys(checkpoints).filter((key) => key !== SPOOL_KEY);
+  const cleared = transcripts.filter((key) => wanted === void 0 || wanted.has(key));
+  const total = transcripts.length;
+  if (cleared.length === 0)
+    return { cleared, total };
+  const backup = `${checkpointPath(scope)}.bak-${stamp(/* @__PURE__ */ new Date())}-prereset`;
+  copyFileSync(checkpointPath(scope), backup);
+  const kept = { ...checkpoints };
+  for (const key of cleared)
+    delete kept[key];
+  saveCheckpoints(scope, kept);
+  return { cleared, total, backup };
+}
+function stamp(at) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${at.getFullYear()}${pad(at.getMonth() + 1)}${pad(at.getDate())}-${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}`;
+}
 
 // packages/core/dist/forwarder/tail.js
 import { closeSync, openSync, readSync, statSync as statSync3 } from "node:fs";
@@ -18849,6 +18923,7 @@ function readNewLines(path, offset, maxBytes = DEFAULT_MAX_BYTES) {
 import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync4, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join7 } from "node:path";
 var STALE_MS = 5 * 60 * 1e3;
+var HEARTBEAT_MS = 60 * 1e3;
 function acquireLock(scope) {
   mkdirSync3(CONFIG_DIR, { recursive: true, mode: 448 });
   const path = join7(CONFIG_DIR, `${scope}.forwarder.lock`);
@@ -18870,7 +18945,17 @@ function acquireLock(scope) {
   } catch {
     return null;
   }
-  return () => rmSync(path, { force: true });
+  const beat = setInterval(() => {
+    try {
+      writeFileSync3(path, JSON.stringify({ pid: process.pid, ts: Date.now() }), { mode: 384 });
+    } catch {
+    }
+  }, HEARTBEAT_MS);
+  beat.unref();
+  return () => {
+    clearInterval(beat);
+    rmSync(path, { force: true });
+  };
 }
 function isAlive(pid, kill = (p, s) => {
   process.kill(p, s);
@@ -18971,6 +19056,61 @@ function saveHealth(scope, health) {
   }
 }
 
+// packages/core/dist/forwarder/pending.js
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync6, renameSync as renameSync4, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join9 } from "node:path";
+var MAX_PENDING_PATHS = 256;
+function pendingPath(scope) {
+  return join9(CONFIG_DIR, `${scope}.pending.json`);
+}
+function loadPending(scope) {
+  try {
+    const backlog = JSON.parse(readFileSync6(pendingPath(scope), "utf8"));
+    if (!Array.isArray(backlog.paths))
+      return void 0;
+    return backlog;
+  } catch {
+    return void 0;
+  }
+}
+function pendingTranscripts(scope) {
+  const backlog = loadPending(scope);
+  if (!backlog)
+    return [];
+  return backlog.paths.filter((path) => {
+    try {
+      return existsSync3(path);
+    } catch {
+      return false;
+    }
+  });
+}
+function savePending(scope, paths, now = /* @__PURE__ */ new Date()) {
+  try {
+    const at = now.toISOString();
+    const previous = loadPending(scope);
+    const merged = [.../* @__PURE__ */ new Set([...previous?.paths ?? [], ...paths])];
+    const kept = merged.slice(Math.max(0, merged.length - MAX_PENDING_PATHS));
+    if (kept.length === 0)
+      return;
+    write(scope, { since: previous?.since ?? at, at, paths: kept });
+  } catch {
+  }
+}
+function clearPending(scope) {
+  try {
+    rmSync2(pendingPath(scope), { force: true });
+  } catch {
+  }
+}
+function write(scope, backlog) {
+  mkdirSync5(CONFIG_DIR, { recursive: true, mode: 448 });
+  const target = pendingPath(scope);
+  const tmp = `${target}.tmp`;
+  writeFileSync5(tmp, JSON.stringify(backlog), { mode: 384 });
+  renameSync4(tmp, target);
+}
+
 // packages/core/dist/forwarder/run.js
 import { readdirSync as readdirSync2, statSync as statSync4 } from "node:fs";
 
@@ -21694,7 +21834,6 @@ function toFloat(value, fallback) {
 }
 
 // packages/core/dist/forwarder/run.js
-var SPOOL_KEY = "::spool::";
 var DARKHUNT_SOURCE_HINT = "darkhunt-telemetry";
 function drainSpool(mapper, checkpoints) {
   const path = spoolPath(mapper.vendor);
@@ -21807,7 +21946,14 @@ async function runForwarder(mapper, options = {}) {
       }
     }
     const drain = options.paths ? { paths: options.paths } : drainSpool(mapper, checkpoints);
-    const named = options.paths ? drain.paths : [.../* @__PURE__ */ new Set([...drain.paths, ...liveTranscripts(loadBeat(config.scope))])];
+    const named = options.paths ? drain.paths : [
+      .../* @__PURE__ */ new Set([
+        ...drain.paths,
+        ...liveTranscripts(loadBeat(config.scope)),
+        ...pendingTranscripts(config.scope),
+        ...laggingTranscripts(checkpoints)
+      ])
+    ];
     const paths = [...new Set(named.flatMap((path) => [path, ...related(mapper, path)]))];
     if (paths.length === 0) {
       if (drain.checkpoint)
@@ -21904,13 +22050,16 @@ async function runForwarder(mapper, options = {}) {
     result2.emitted = { transcripts: result2.transcripts, records: result2.records };
     if (watch.failures() > 0) {
       result2.ok = false;
+      result2.retryable = true;
       result2.error = watch.reason() ?? "span export failed";
       result2.transcripts = 0;
       result2.records = 0;
+      savePending(config.scope, paths);
     } else {
       if (drain.checkpoint)
         staged[SPOOL_KEY] = drain.checkpoint;
       saveCheckpoints(config.scope, staged);
+      clearPending(config.scope);
     }
     const previous = loadHealth(config.scope);
     saveHealth(config.scope, {
@@ -21975,16 +22124,22 @@ function discoverTranscripts(mapper) {
   return found;
 }
 
+// packages/core/dist/forwarder/retry.js
+var CLAIM_STALE_MS = 45 * 60 * 1e3;
+
 // packages/core/dist/cli/status.js
 var SESSION_HOOK_STALE_MS = 30 * 60 * 1e3;
 
 // packages/core/dist/cli/enroll.js
 import { homedir as homedir3 } from "node:os";
-import { join as join9 } from "node:path";
-var CLI_CREDENTIALS_PATH = join9(homedir3(), ".darkhunt", "credentials.json");
+import { join as join10 } from "node:path";
+var CLI_CREDENTIALS_PATH = join10(homedir3(), ".darkhunt", "credentials.json");
 
 // packages/core/dist/cli/backfill.js
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["dry-run"]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Map([
+  ["dry-run", "dryRun"],
+  ["reset", "reset"]
+]);
 var VALUE_FLAGS = /* @__PURE__ */ new Set(["profile", "credentials", "days", "batch"]);
 var DEFAULT_BATCH = 25;
 function usage(command) {
@@ -21992,6 +22147,8 @@ function usage(command) {
     `usage: ${command} [options] [paths...]`,
     "",
     "  --dry-run                map only: no network, no checkpoints",
+    "  --reset                  re-send: forget how far the selected transcripts have",
+    "                           been shipped, then ship them from the start again",
     "  --days=N                 only transcripts written to in the last N days",
     "  --batch=N                transcripts per pass (default " + String(DEFAULT_BATCH) + ")",
     "  --profile=NAME           endpoint profile to ship to",
@@ -21999,13 +22156,22 @@ function usage(command) {
     "  -h, --help               this message",
     "",
     "  With no paths this ships EVERY transcript on disk. Narrow it with --days",
-    "  or by naming transcripts, and confirm the destination with --dry-run first."
+    "  or by naming transcripts, and confirm the destination with --dry-run first.",
+    "",
+    "  A checkpoint records how far a transcript has been shipped, never where it was",
+    "  shipped to. After re-enrolling against a different application, a plain backfill",
+    "  finds nothing to send and exits 0; --reset is what re-sends it.",
+    "",
+    "  This command is refused, exit 4, when the config sets",
+    '    "capture": { "backfill": false }',
+    "  which stops retroactive imports on this machine and leaves live capture running.",
+    "  --dry-run still works while it is off."
   ].join("\n");
 }
 function parseBackfillArgs(argv) {
   const paths = [];
   const values = /* @__PURE__ */ new Map();
-  let dryRun = false;
+  const booleans = { dryRun: false, reset: false };
   for (const arg of argv) {
     if (arg === "-h" || arg === "--help")
       return { kind: "help" };
@@ -22016,10 +22182,11 @@ function parseBackfillArgs(argv) {
     const body = arg.slice(2);
     const eq = body.indexOf("=");
     const name = eq === -1 ? body : body.slice(0, eq);
-    if (BOOLEAN_FLAGS.has(name)) {
+    const boolean = BOOLEAN_FLAGS.get(name);
+    if (boolean !== void 0) {
       if (eq !== -1)
         return { kind: "error", message: `--${name} takes no value` };
-      dryRun = true;
+      booleans[boolean] = true;
       continue;
     }
     if (VALUE_FLAGS.has(name)) {
@@ -22030,7 +22197,7 @@ function parseBackfillArgs(argv) {
     }
     return {
       kind: "error",
-      message: `unknown option '${arg}'. Known: ${[...BOOLEAN_FLAGS, ...VALUE_FLAGS].map((f) => `--${f}`).sort().join(", ")}, --help`
+      message: `unknown option '${arg}'. Known: ${[...BOOLEAN_FLAGS.keys(), ...VALUE_FLAGS].map((f) => `--${f}`).sort().join(", ")}, --help`
     };
   }
   const positive = (name) => {
@@ -22043,6 +22210,12 @@ function parseBackfillArgs(argv) {
     }
     return n;
   };
+  if (booleans.dryRun && booleans.reset) {
+    return {
+      kind: "error",
+      message: "--reset cannot be combined with --dry-run: a dry run maps every transcript from the start already, and never writes checkpoints"
+    };
+  }
   const sinceDays = positive("days");
   if (typeof sinceDays === "object")
     return sinceDays;
@@ -22052,7 +22225,8 @@ function parseBackfillArgs(argv) {
   return {
     kind: "run",
     options: {
-      dryRun,
+      dryRun: booleans.dryRun,
+      reset: booleans.reset,
       paths,
       ...values.get("profile") !== void 0 ? { profile: values.get("profile") } : {},
       ...values.get("credentials") !== void 0 ? { credentialsPath: values.get("credentials") } : {},
@@ -22068,10 +22242,21 @@ function batches(items, size) {
   return out;
 }
 async function runBackfill(mapper, options, say2) {
+  if (!options.dryRun && backfillIsOff(mapper, options)) {
+    say2("BACKFILL DISABLED \u2014 the retroactive import is opt-in, and this machine has not opted in");
+    say2(`set "capture": { "backfill": true } in ${configPath()} to allow it`);
+    say2("nothing was sent and no checkpoint was cleared; live capture is unaffected");
+    return disabledResult();
+  }
   const discovered = options.paths.length > 0 ? options.paths : discoverTranscripts(mapper);
   const paths = options.sinceDays === void 0 ? discovered : withinDays(discovered, options.sinceDays);
   const window2 = options.sinceDays === void 0 ? "" : ` written to in the last ${options.sinceDays} day(s)`;
   say2(`${options.dryRun ? "DRY RUN \u2014 nothing will be sent. " : ""}${paths.length} transcript(s)${window2}`);
+  if (options.reset) {
+    const reset = await resetCheckpoints(mapper, options, paths, say2);
+    if (reset === void 0)
+      return lockBusyResult();
+  }
   const pass = (subset) => runForwarder(mapper, {
     paths: subset,
     dryRun: options.dryRun,
@@ -22088,6 +22273,61 @@ async function runBackfill(mapper, options, say2) {
     return pass([]);
   return runPasses(batches(paths, options.batch ?? DEFAULT_BATCH), pass, say2);
 }
+async function resetCheckpoints(mapper, options, paths, say2) {
+  const { scope } = loadRuntimeSettings(mapper.vendor, options.profile !== void 0 ? { profile: options.profile } : {});
+  const release = await acquireLockWithin(scope, options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS);
+  if (!release)
+    return void 0;
+  let reset;
+  try {
+    reset = clearCheckpoints(scope, paths);
+  } finally {
+    release();
+  }
+  if (reset.cleared.length === 0) {
+    say2(reset.total === 0 ? "RESET \u2014 nothing had been shipped yet; these transcripts ship from the start anyway" : `RESET \u2014 NOTHING CLEARED: none of the selected paths match the ${reset.total} checkpoint(s) on file, so they will ship from wherever they left off`);
+    return reset;
+  }
+  say2(`RESET \u2014 forgot the offset for ${reset.cleared.length} transcript(s); they re-ship in full`);
+  say2(`previous checkpoints saved as ${reset.backup}`);
+  return reset;
+}
+function backfillIsOff(mapper, options) {
+  try {
+    const { capture } = loadRuntimeSettings(mapper.vendor, options.profile !== void 0 ? { profile: options.profile } : {});
+    return !capture.backfill;
+  } catch {
+    return false;
+  }
+}
+function disabledResult() {
+  return {
+    transcripts: 0,
+    records: 0,
+    skipped: ["backfill is disabled"],
+    kinds: {},
+    warnings: [],
+    emitted: { transcripts: 0, records: 0 },
+    backfillDisabled: true,
+    // Non-zero exit, for the reason `shipped 0` cannot carry: an up-to-date machine
+    // prints that too, and a script chaining backfills must not read a refusal as done.
+    ok: false,
+    error: "backfill is disabled by capture.backfill"
+  };
+}
+function lockBusyResult() {
+  return {
+    transcripts: 0,
+    records: 0,
+    skipped: ["another forwarder holds the lock"],
+    kinds: {},
+    warnings: [],
+    emitted: { transcripts: 0, records: 0 },
+    lockBusy: true,
+    ok: false,
+    error: "another forwarder holds the lock"
+  };
+}
 async function runPasses(groups, pass, say2) {
   const total = {
     transcripts: 0,
@@ -22126,8 +22366,8 @@ async function runPasses(groups, pass, say2) {
 }
 
 // adapters/codex/dist/transcript.js
-import { readFileSync as readFileSync6 } from "node:fs";
-import { basename, join as join10 } from "node:path";
+import { readFileSync as readFileSync7 } from "node:fs";
+import { basename, join as join11 } from "node:path";
 import { homedir as homedir4 } from "node:os";
 function str(value) {
   return typeof value === "string" ? value : void 0;
@@ -22271,7 +22511,7 @@ function stripSuffix(path) {
 var codexTranscript = {
   vendor: "codex",
   sessionRoots() {
-    return [join10(homedir4(), ".codex", "sessions")];
+    return [join11(homedir4(), ".codex", "sessions")];
   },
   /**
    * `~/.codex/auth.json` -> the `email` claim of `tokens.id_token`.
@@ -22293,7 +22533,7 @@ var codexTranscript = {
    */
   resolveUserId() {
     try {
-      return emailFromAuth(readFileSync6(join10(homedir4(), ".codex", "auth.json"), "utf8"));
+      return emailFromAuth(readFileSync7(join11(homedir4(), ".codex", "auth.json"), "utf8"));
     } catch {
       return void 0;
     }
@@ -22517,6 +22757,7 @@ if (parsed.kind === "error") {
   process.exit(2);
 }
 var result = await runBackfill(codexTranscript, parsed.options, say);
+if (result.backfillDisabled === true) process.exit(4);
 say(
   `${parsed.options.dryRun ? "mapped" : "shipped"} ${result.records} record(s) from ${result.transcripts} transcript(s)`
 );