@darkhunt-security/endpoint-codex 0.9.0 → 0.9.3

package/.codex-plugin/plugin.json

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

package/README.md

@@ -6,9 +6,17 @@ Capture is on by default. **Enforcement ships off** and is enabled per rule.
 
 ## Install
 
+Codex manages plugins from the CLI, not from a slash command — `/plugin …` is Claude
+Code's. Run these in a terminal:
+
+```
+codex plugin marketplace add darkhunt-security/darkhunt
+codex plugin add darkhunt-guard@darkhunt
+```
+
+Then, in Codex:
+
 ```
-/plugin marketplace add darkhunt-security/darkhunt-telemetry-ts
-/plugin install darkhunt-guard@darkhunt
 /darkhunt-guard:setup
 ```
 
@@ -21,6 +29,33 @@ anything ships.
 Capture starts on your **next** Codex CLI session — hooks are loaded when a session
 starts.
 
+### If you configured this machine from the dashboard instead
+
+The dashboard renders a ready-made `~/.darkhunt/endpoint-config.json` to paste into your
+own terminal. That is the whole setup on Claude Code; on Codex it is half of it. Codex
+resolves a hook `command` as an absolute path or a PATH name, and the install directory
+carries the plugin version, so this plugin's hooks are PATH launchers that something has
+to write. Enrolment writes them; a pasted config cannot. Run this once after pasting it:
+
+```
+"$(ls -d ~/.codex/plugins/cache/*/darkhunt-guard/*/dist/bin | sort -V | tail -1)"/install-hooks.mjs
+```
+
+`/darkhunt-guard:status` reports the launchers, so you never have to take this on trust —
+a machine missing them looks perfectly configured everywhere else and captures nothing.
+
+## Upgrade
+
+```
+codex plugin add darkhunt-guard@darkhunt
+```
+
+Re-adding re-resolves the published version. The new one loads on your **next** Codex
+CLI session, and the launchers need no attention — they resolve the newest installed
+version at run time. `/darkhunt-guard:status` prints the version actually running,
+which is the only reliable answer: an update that resolved against a registry without
+the new version reports success and changes nothing.
+
 ## What it captures
 
 The session transcript, mapped to spans: user and assistant messages, thinking blocks,
@@ -46,10 +81,11 @@ Two rules constrain it, both deliberate:
 
 ## Commands
 
-|                          |                                                                    |
-| ------------------------ | ------------------------------------------------------------------ |
-| `/darkhunt-guard:setup`  | Connect this machine. Re-runnable; shows current state first.      |
-| `/darkhunt-guard:status` | Is capture actually working? Routing, hook activity, shipping lag. |
+|                            |                                                                                   |
+| -------------------------- | --------------------------------------------------------------------------------- |
+| `/darkhunt-guard:setup`    | Connect this machine. Re-runnable; shows current state first.                     |
+| `/darkhunt-guard:status`   | Is capture actually working? Routing, launchers, hook activity, shipping lag.     |
+| `/darkhunt-guard:backfill` | Import Codex CLI sessions from before this machine was connected. Dry-runs first. |
 
 Both lanes fail silently by design — correct for the agent, unhelpful for whoever
 operates it — so `status` is where the truth lives.

package/commands/backfill.md

@@ -0,0 +1,73 @@
+---
+description: Import Codex CLI sessions that happened before this machine was connected
+argument-hint: '[--days=N, 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:*)
+---
+
+Ship transcripts that the capture lane never saw — sessions from before the plugin was
+installed, or from a stretch where hooks were not firing. On Codex the usual cause of
+the second is missing launchers, so read the `launchers` line below before assuming the
+gap has stopped growing.
+
+Where this machine is currently pointed:
+
+!`${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs 2>&1 || true`
+
+Paths or flags the user gave: $ARGUMENTS
+
+If they asked for a window in words — "the last week", "since Monday", "this month" —
+translate it to `--days=N` rather than asking them to phrase it as a flag. `--days`
+selects on when a transcript was **last written to**, so a session opened three weeks
+ago and worked in yesterday is inside a 7-day window. Say that if the count surprises
+them.
+
+## The one hard rule
+
+**Dry-run first, and get the destination confirmed before you ship.** A backfill is one
+command that moves a person's entire local history into a tenant. Checkpoints make a
+re-run harmless; they do nothing about a run aimed at the wrong application, which
+cannot be taken back and looks exactly like a correct one afterwards.
+
+## What to do
+
+1. Map without sending. Nothing leaves the machine and no checkpoint moves:
+
+   ```
+   ${CLAUDE_PLUGIN_ROOT}/dist/bin/backfill.mjs --dry-run $ARGUMENTS
+   ```
+
+   With no window and no paths this is the machine's entire history, which on a working
+   machine is routinely tens of thousands of records. If they have not said how far back
+   they want, offer `--days=7` before offering all of it.
+
+   Report the transcript count and the record count. `records` excludes `session_meta`,
+   so it will not equal the sum of the per-kind lines — say so if you quote both.
+
+2. Put the destination to them **before** shipping, reading it from the status block
+   above: endpoint, tenant, workspace, application. Ask them to confirm that is where
+   this history belongs. Two things make this worth a sentence rather than a nod:
+
+   - Both endpoints share `~/.darkhunt/endpoint-config.json`. Unless it carries an
+     `endpoints.codex` override, these sessions land in the same application as the
+     Claude Code ones.
+   - Volume. A first backfill on a working machine is routinely tens of thousands of
+     records, all attributed to that one application.
+
+   If they want them separated, stop and tell them to set
+   `endpoints.claude-code.applicationId` first — after a partial run the checkpoints
+   have moved and the records already sent stay where they went.
+
+3. Only on a yes, run the same command without `--dry-run`. It can take a while on a
+   large history; let it finish rather than re-running it.
+
+4. Report what it printed. On a non-zero exit, say plainly that **nothing was lost**:
+   a failed pass holds every checkpoint, so the identical command re-ships the same
+   byte range once the cause is fixed.
+
+## Also
+
+- Narrow it by passing paths — one session, or a date range — rather than adding flags
+  this command does not have: `backfill.mjs ~/.codex/sessions/2026/08/31/rollout-*.jsonl`.
+- This is a CLI, not a hook: it may use the network, and it does not depend on whether
+  hooks are firing. A machine whose capture is broken can still backfill.
+- Do not offer to change the configuration here. Send them to `/darkhunt-guard:setup`.

package/commands/setup.md

@@ -1,6 +1,6 @@
 ---
 description: Connect this machine to Darkhunt — capture Codex CLI sessions and enforce policy
-allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/enroll.mjs:*), Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs:*)
+allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/enroll.mjs:*), Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs:*), Bash(pbpaste:*), Bash(wl-paste:*), Bash(xclip:*), Bash(powershell.exe:*)
 ---
 
 Set up the Darkhunt endpoint plugin on this machine.
@@ -11,62 +11,76 @@ Current state:
 
 ## The one hard rule
 
-**Never ask the user for their API key, and never accept one in this conversation.**
+**Never write the user's API key into your reply, into a file, or into a command's
+arguments.** It is an unscoped tenant credential. Everything in this session goes to the
+model provider, onto disk in the transcript, and — since this plugin captures sessions —
+into the trace data itself. An argument is visible in the process list too.
 
-A Darkhunt API key is an unscoped tenant credential. Anything in this session is sent to
-the model provider, written to the transcript on disk, kept in context for every later
-turn, and handed to subagents — and this plugin then ships that transcript to Darkhunt,
-so a key pasted here ends up in the captured trace data too. Enrollment finds the key
-itself, or the user runs one command in their own terminal. There is no third option,
-and no amount of user insistence makes pasting it here correct.
+You do not need the key's value to do this job. Read it from the clipboard straight into
+the command's stdin, so it never becomes text you have seen.
 
 ## What to do
 
-**If the status above printed a profile, tenant and workspace**, this machine is already
-enrolled. Show the tenant, workspace, application and endpoint, and ask whether they want
-to re-enroll against a different one. Do not re-run enrollment unless they say yes.
+**If the status above shows a profile, tenant and workspace**, this machine is already
+enrolled. Report the tenant, workspace, application and endpoint, and ask whether they
+want to re-enroll somewhere else. Do nothing further unless they say yes.
 
-**Otherwise**, run:
+**Otherwise**, enroll it:
 
-```
-${CLAUDE_PLUGIN_ROOT}/dist/bin/enroll.mjs
-```
+1. Ask the user to copy their Darkhunt API key — the **Copy** button beside it in the
+   dashboard, under the application's Connect step or **Settings → Security → API Keys**.
+   Ask them to tell you when it is copied. Do not ask them to paste it.
 
-It looks for a key in `$DARKHUNT_API_KEY`, then in the credentials `darkhunt-cli enroll`
-wrote. Then react to the exit code:
+2. Pipe the clipboard into enrollment. Pick the reader for their platform — `pbpaste` on
+   macOS, `wl-paste` or `xclip -o -selection clipboard` on Linux,
+   `powershell.exe -NoProfile -Command Get-Clipboard` on Windows:
 
-- **Exit 0** — done. Show the user exactly what it printed: endpoint, tenant, workspace,
-  application, and which key it used. Ask them to confirm this is where they expect their
-  sessions to go. This matters — a config routing to the wrong tenant looks identical to
-  a correct one from everywhere else, and this summary is the only place the mistake is
-  visible.
+   ```
+   pbpaste | ${CLAUDE_PLUGIN_ROOT}/dist/bin/enroll.mjs --apiKey=-
+   ```
 
-- **Exit 3 — no key.** Do **not** ask for one. Tell the user to run this in their own
-  terminal, outside this session:
+   Add `--apiBaseUrl=<url>` if they are on a Darkhunt other than `api.darkhunt.ai`.
 
-  ```
-  darkhunt-cli enroll --api-key <key>
-  ```
+3. React to the exit code:
 
-  Their key is in the dashboard under **Settings → Security → API Keys**. Once that
-  succeeds, run the enroll command above again — it will pick the key up. If they do not
-  have `darkhunt-cli`, they can instead `export DARKHUNT_API_KEY=<key>` in the shell they
-  launched Codex CLI from, and restart the session.
+   - **0** — done. Show exactly what it printed: endpoint, tenant, workspace,
+     application. Ask them to confirm that is where they expect their sessions to go. A
+     config aimed at the wrong tenant looks identical to a correct one everywhere else,
+     and this summary is the only place the mistake is visible.
 
-- **Exit 2 — a choice is needed.** The key reaches more than one tenant, workspace or
-  application, and the options are listed. Show them by name, ask which one, then re-run
-  adding the chosen id — `--tenantId=`, `--workspaceId=` or `--applicationId=` — keeping
-  any already resolved. Repeat until it succeeds; there can be up to three rounds.
+   - **2** — the key reaches more than one tenant, workspace or application, and the
+     options are listed. Show them by name, ask which, then re-run the same piped command
+     with the chosen id added (`--tenantId=`, `--workspaceId=` or `--applicationId=`),
+     keeping any already settled. Up to three rounds.
 
-- **Any other exit** — show the error. Do not retry with different arguments hoping it
-  passes.
+   - **1 with "stdin was empty"** — the clipboard did not hold the key. Ask them to copy
+     it again, then retry. Do not ask them to paste it here instead.
 
-Finally, tell them capture begins on their **next** Codex CLI session, because hooks
-are loaded when a session starts, and that `/darkhunt-guard:status` shows whether it is
-working.
+   - **1 with "rejected"** — the clipboard held something that is not a valid key. Same
+     remedy.
+
+   - **3** — no key was found at all, which should not happen on this path. Do not ask
+     for the key here. Send them to the dashboard instead: the application's Connect step
+     renders a ready-made block that writes `~/.darkhunt/endpoint-config.json` with every
+     value already filled in, to paste into their own terminal. That block writes
+     credentials only, so it must be followed by:
+
+     ```
+     ${CLAUDE_PLUGIN_ROOT}/dist/bin/install-hooks.mjs
+     ```
+
+     Then re-run the status command above to confirm both halves took.
+
+4. Tell them capture begins on their **next** Codex CLI session — hooks load when a
+   session starts — and that `/darkhunt-guard:status` shows whether it is working.
+
+   If the status output reports a launcher problem, run
+   `${CLAUDE_PLUGIN_ROOT}/dist/bin/install-hooks.mjs` and read what it prints. Codex
+   resolves this plugin's hook commands by PATH name, so a machine with correct
+   credentials and no launchers on `PATH` is configured and capturing nothing.
 
 ## Also
 
-- Do not edit `~/.darkhunt/endpoint-config.json` by hand — enrollment writes it at 0600,
-  and a file with looser permissions is refused at load.
+- Do not edit `~/.darkhunt/endpoint-config.json` by hand. Enrollment writes it at 0600
+  and a looser mode is refused at load.
 - Enforcement ships **off**. Setup does not turn it on, and you should not offer to.

package/commands/status.md

@@ -1,6 +1,6 @@
 ---
-description: Is Darkhunt capture actually working? Shows routing, hook activity and shipping lag
-allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs:*)
+description: Is Darkhunt capture actually working? Shows routing, launchers, hook activity and shipping lag
+allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs:*), Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/install-hooks.mjs:*)
 ---
 
 !`${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs 2>&1 || true`
@@ -15,6 +15,13 @@ What the fields mean, and what to say:
   `/darkhunt-guard:setup`. Nothing is being captured, and nothing is being blocked.
 - **tenant / workspace / application** — where sessions are being sent. Worth reading
   aloud: a wrong destination looks exactly like a right one everywhere else.
+- **launchers PROBLEM** — the failure with no other symptom. Codex resolves this
+  plugin's hook commands by PATH name (`darkhunt-codex-spool`, `darkhunt-codex-guard`),
+  so a machine whose config is perfect but whose launchers are missing, stale, or in a
+  directory that is not on `PATH` captures nothing and reports nothing wrong anywhere
+  else. Missing or stale is fixed by running
+  `${CLAUDE_PLUGIN_ROOT}/dist/bin/install-hooks.mjs`; a `PATH` problem is theirs to fix
+  in their shell profile, and the line says which it is.
 - **user … [from agent]** — traces are attributed to the signed-in Codex CLI account.
   `[from config]` means a value someone typed in, which on a shared machine is likely to
   be the wrong person.

package/dist/bin/backfill.mjs

@@ -18295,6 +18295,7 @@ function summarize(output) {
     return text;
   return `${text.slice(0, TOOL_SUMMARY_LIMIT)}\u2026 [truncated, ${text.length} chars]`;
 }
+var RESUMED_USER_TEXT_LIMIT = 4e3;
 var SessionEmitter = class {
   client;
   options;
@@ -18321,10 +18322,26 @@ var SessionEmitter = class {
   constructor(client, options) {
     this.client = client;
     this.options = options;
+    if (options.resumeTurn) {
+      this.lastUserText = options.resumeTurn.userText;
+      this.userTurnOpen = options.resumeTurn.open;
+    }
   }
   get recordCount() {
     return this.count;
   }
+  /**
+   * The turn still in flight, for the forwarder to hand to the next pass. Read after
+   * `finish()` — a turn is only settled once the pass has ended everything it opened.
+   */
+  get turn() {
+    const text = this.lastUserText;
+    const carried = text !== void 0 && text.length > RESUMED_USER_TEXT_LIMIT ? `${text.slice(0, RESUMED_USER_TEXT_LIMIT)}\u2026 [truncated, ${text.length} chars]` : text;
+    return {
+      ...carried !== void 0 ? { userText: carried } : {},
+      open: this.userTurnOpen
+    };
+  }
   /**
    * Create a span under a seed derived from the record. Scoped by session id, so two
    * sessions sharing a record uuid cannot collide, and by a discriminator, so the
@@ -18580,6 +18597,11 @@ function resumeOffset(checkpoints, path) {
     return 0;
   return previous.offset;
 }
+function resumeTurn(checkpoints, path, from) {
+  if (from <= 0)
+    return void 0;
+  return checkpoints[path]?.turn;
+}
 
 // packages/core/dist/forwarder/tail.js
 import { closeSync, openSync, readSync, statSync as statSync3 } from "node:fs";
@@ -18737,7 +18759,7 @@ function saveHealth(scope, health) {
 }
 
 // packages/core/dist/forwarder/run.js
-import { readdirSync as readdirSync2 } from "node:fs";
+import { readdirSync as readdirSync2, statSync as statSync4 } from "node:fs";
 
 // node_modules/@darkhunt-security/telemetry/dist/client.js
 init_esm();
@@ -21597,12 +21619,14 @@ async function runForwarder(mapper, options = {}) {
       for (const path of paths2) {
         try {
           const from = resumeOffset(checkpoints, path);
+          const carried = resumeTurn(checkpoints, path, from);
           const emitter = new SessionEmitter(client, {
             sessionId: mapper.sessionIdFor(path),
             vendor: mapper.vendor,
             passKey: String(from),
             ...ids !== void 0 ? { ids } : {},
-            ...userId !== void 0 ? { userId } : {}
+            ...userId !== void 0 ? { userId } : {},
+            ...carried !== void 0 ? { resumeTurn: carried } : {}
           });
           let cursor = from;
           let reached = from;
@@ -21628,7 +21652,12 @@ async function runForwarder(mapper, options = {}) {
           if (ingested === 0)
             continue;
           await emitter.finish();
-          staged[path] = { offset: reached, size: fileSize };
+          const turn = emitter.turn;
+          staged[path] = {
+            offset: reached,
+            size: fileSize,
+            ...turn.userText !== void 0 || turn.open ? { turn } : {}
+          };
           result2.transcripts++;
           result2.records += emitter.recordCount;
           if (watch.failures() > 0)
@@ -21665,6 +21694,19 @@ async function runForwarder(mapper, options = {}) {
     release();
   }
 }
+function withinDays(paths2, days) {
+  if (!Number.isFinite(days) || days <= 0) {
+    throw new RangeError(`--days must be a positive number of days, got ${days}`);
+  }
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1e3;
+  return paths2.filter((path) => {
+    try {
+      return statSync4(path).mtimeMs >= cutoff;
+    } catch {
+      return true;
+    }
+  });
+}
 function discoverTranscripts(mapper) {
   const found = [];
   const walk = (dir) => {
@@ -21843,10 +21885,21 @@ var flag = (n) => {
 };
 var profile = flag("profile");
 var credentialsPath2 = flag("credentials");
-var paths = explicit.length > 0 ? explicit : discoverTranscripts(codexTranscript);
+var sinceDays;
+if (flag("days") !== void 0) {
+  sinceDays = Number(flag("days"));
+  if (!Number.isFinite(sinceDays) || sinceDays <= 0) {
+    process.stderr.write(`darkhunt: --days must be a positive number, got '${flag("days")}'
+`);
+    process.exit(1);
+  }
+}
+var discovered = explicit.length > 0 ? explicit : discoverTranscripts(codexTranscript);
+var paths = sinceDays === void 0 ? discovered : withinDays(discovered, sinceDays);
+var window2 = sinceDays === void 0 ? "" : ` written to in the last ${sinceDays} day(s)`;
 var say = (m) => process.stderr.write(`darkhunt: ${m}
 `);
-say(`${dryRun ? "DRY RUN \u2014 nothing will be sent. " : ""}${paths.length} transcript(s)`);
+say(`${dryRun ? "DRY RUN \u2014 nothing will be sent. " : ""}${paths.length} transcript(s)${window2}`);
 var result = await runForwarder(codexTranscript, { paths, dryRun, profile, credentialsPath: credentialsPath2 });
 say(
   `${dryRun ? "mapped" : "shipped"} ${result.records} record(s) from ${result.transcripts} transcript(s)`

package/dist/bin/enroll.mjs

@@ -52,6 +52,14 @@ var SPOOL_DIR = join4(CONFIG_DIR, "spool");
 // packages/core/dist/runtime/beat.js
 var BEAT_LIVE_MS = 30 * 60 * 1e3;
 
+// packages/core/dist/runtime/guard.js
+async function readStdin(stream) {
+  const chunks = [];
+  for await (const chunk of stream)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
 // packages/core/dist/forwarder/tail.js
 var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
 var LINE_CEILING = 64 * 1024 * 1024;
@@ -998,18 +1006,18 @@ function init(argv) {
   const cfgPath = configPath();
   const existingConfig = readJson(cfgPath) ?? {};
   const existingCreds = separateFile ? readJson(credsPath) : existingConfig;
-  const apiKey = flags["apiKey"] ?? process.env["DARKHUNT_API_KEY"] ?? existingCreds?.apiKey;
+  const apiKey2 = flags["apiKey"] ?? process.env["DARKHUNT_API_KEY"] ?? existingCreds?.apiKey;
   const tenantId = flags["tenantId"] ?? process.env["DARKHUNT_TENANT_ID"] ?? existingCreds?.tenantId;
   const apiBaseUrl = flags["apiBaseUrl"] ?? process.env["DARKHUNT_API_BASE_URL"] ?? existingCreds?.apiBaseUrl ?? "https://api.darkhunt.ai";
   const workspaceId = flags["workspaceId"] ?? process.env["DARKHUNT_WORKSPACE_ID"] ?? existingCreds?.workspaceId;
   const applicationId = flags["applicationId"] ?? process.env["DARKHUNT_APPLICATION_ID"] ?? existingCreds?.applicationId;
   const userId = flags["userId"] ?? existingCreds?.userId;
-  assertPresent("apiKey", apiKey, "DARKHUNT_API_KEY");
+  assertPresent("apiKey", apiKey2, "DARKHUNT_API_KEY");
   assertPresent("tenantId", tenantId, "DARKHUNT_TENANT_ID");
   assertPresent("workspaceId", workspaceId, "DARKHUNT_WORKSPACE_ID");
   assertPresent("applicationId", applicationId, "DARKHUNT_APPLICATION_ID");
   const credentials = {
-    apiKey,
+    apiKey: apiKey2,
     apiBaseUrl,
     tenantId,
     workspaceId,
@@ -1115,7 +1123,8 @@ function resolveKey(explicit, cliCredentialsPath) {
       return {
         apiKey: cli.apiKey,
         source: "darkhunt-cli",
-        ...typeof cli.apiBaseUrl === "string" ? { apiBaseUrl: cli.apiBaseUrl } : {}
+        ...typeof cli.apiBaseUrl === "string" ? { apiBaseUrl: cli.apiBaseUrl } : {},
+        ...typeof cli.tenantId === "string" && cli.tenantId !== "" ? { tenantId: cli.tenantId } : {}
       };
     }
   } catch {
@@ -1124,10 +1133,10 @@ function resolveKey(explicit, cliCredentialsPath) {
 }
 var MAX_LISTED = 15;
 var DEFAULT_API_BASE_URL = "https://api.darkhunt.ai";
-async function get(base, apiKey, path) {
+async function get(base, apiKey2, path) {
   let res;
   try {
-    res = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${apiKey}` } });
+    res = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${apiKey2}` } });
   } catch (err) {
     throw new EnrollError(`cannot reach ${base}: ${err.message}`);
   }
@@ -1164,18 +1173,54 @@ function resolve2(kind, options, chosen) {
   throw new AmbiguousError(kind, options);
 }
 var CLI_CREDENTIALS_PATH = join5(homedir3(), ".darkhunt", "credentials.json");
+function idsFromEnv() {
+  const read = (name) => {
+    const value = process.env[name];
+    return value !== void 0 && value.trim() !== "" ? value : void 0;
+  };
+  const tenantId = read("DARKHUNT_TENANT_ID");
+  const workspaceId = read("DARKHUNT_WORKSPACE_ID");
+  const applicationId = read("DARKHUNT_APPLICATION_ID");
+  return {
+    ...tenantId !== void 0 ? { tenantId } : {},
+    ...workspaceId !== void 0 ? { workspaceId } : {},
+    ...applicationId !== void 0 ? { applicationId } : {}
+  };
+}
+async function accessibleTenants(base, apiKey2, candidates, recorded) {
+  const known = candidates.find((c) => c.id === recorded);
+  if (known)
+    return [known];
+  if (candidates.length <= 1)
+    return candidates;
+  const reachable = await Promise.all(candidates.map(async (c) => {
+    try {
+      await get(base, apiKey2, `/workflow-manager/api/t/${c.id}/workspaces`);
+      return c;
+    } catch {
+      return void 0;
+    }
+  }));
+  const usable = reachable.filter((c) => c !== void 0);
+  return usable.length > 0 ? usable : candidates;
+}
 async function enroll(options) {
+  const env = idsFromEnv();
+  const chosen = {
+    ...env,
+    ...Object.fromEntries(Object.entries(options).filter(([, v]) => v !== void 0))
+  };
   const key = resolveKey(options.apiKey, CLI_CREDENTIALS_PATH);
-  const { apiKey } = key;
+  const { apiKey: apiKey2 } = key;
   const base = (options.apiBaseUrl ?? key.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
-  const me = await get(base, apiKey, "/user-management/api/me");
-  const tenantId = resolve2("tenant", toChoices(list(me.tenants)), options.tenantId);
-  const workspaces = toChoices(list(await get(base, apiKey, `/workflow-manager/api/t/${tenantId}/workspaces`)));
-  const workspaceId = resolve2("workspace", workspaces, options.workspaceId);
-  const applications = toChoices(list(await get(base, apiKey, `/workflow-manager/api/t/${tenantId}/workspaces/${workspaceId}/applications`)));
-  const applicationId = resolve2("application", applications, options.applicationId);
+  const me = await get(base, apiKey2, "/user-management/api/me");
+  const tenantId = resolve2("tenant", await accessibleTenants(base, apiKey2, toChoices(list(me.tenants)), key.tenantId), chosen.tenantId ?? key.tenantId);
+  const workspaces = toChoices(list(await get(base, apiKey2, `/workflow-manager/api/t/${tenantId}/workspaces`)));
+  const workspaceId = resolve2("workspace", workspaces, chosen.workspaceId);
+  const applications = toChoices(list(await get(base, apiKey2, `/workflow-manager/api/t/${tenantId}/workspaces/${workspaceId}/applications`)));
+  const applicationId = resolve2("application", applications, chosen.applicationId);
   const result = init([
-    `--apiKey=${apiKey}`,
+    `--apiKey=${apiKey2}`,
     `--apiBaseUrl=${base}`,
     `--tenantId=${tenantId}`,
     `--workspaceId=${workspaceId}`,
@@ -1193,14 +1238,92 @@ async function enroll(options) {
   };
 }
 
+// adapters/codex/bin/lib/launchers.mjs
+import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { join as join6 } from "node:path";
+var LAUNCHERS = {
+  "darkhunt-codex-spool": "spool.mjs",
+  "darkhunt-codex-guard": "guard.mjs"
+};
+var BIN_DIR = join6(homedir4(), ".local", "bin");
+var script = (target) => `#!/bin/sh
+# Installed by darkhunt endpoint-plugins. Resolves the newest installed
+# plugin version at run time; do not hard-code a version here.
+D=$(ls -d "$HOME"/.codex/plugins/cache/*/darkhunt-guard/*/dist/bin 2>/dev/null | sort -V | tail -1)
+[ -n "$D" ] || exit 0
+exec "$D/${target}" "$@"
+`;
+function installLaunchers(binDir = BIN_DIR) {
+  mkdirSync2(binDir, { recursive: true });
+  const installed = [];
+  for (const [name, target] of Object.entries(LAUNCHERS)) {
+    const path = join6(binDir, name);
+    writeFileSync2(path, script(target), { mode: 493 });
+    chmodSync2(path, 493);
+    installed.push(path);
+  }
+  return installed;
+}
+function launcherState(binDir = BIN_DIR, path = process.env["PATH"] ?? "") {
+  const missing = [];
+  const stale = [];
+  for (const [name, target] of Object.entries(LAUNCHERS)) {
+    const file = join6(binDir, name);
+    if (!existsSync2(file)) {
+      missing.push(name);
+      continue;
+    }
+    let body = "";
+    try {
+      body = readFileSync3(file, "utf8");
+    } catch {
+    }
+    if (body !== script(target)) stale.push(name);
+  }
+  return { binDir, missing, stale, onPath: path.split(":").includes(binDir) };
+}
+function launcherWarnings(state) {
+  const lines = [];
+  if (state.missing.length > 0) {
+    lines.push(
+      `hook launchers missing: ${state.missing.join(", ")} \u2014 hooks cannot run.`,
+      `  install them:  install-hooks.mjs`
+    );
+  }
+  if (state.stale.length > 0) {
+    lines.push(
+      `hook launchers are not the ones this version writes: ${state.stale.join(", ")}.`,
+      `  refresh them:  install-hooks.mjs`
+    );
+  }
+  if (!state.onPath) {
+    lines.push(
+      `${state.binDir} is not on PATH \u2014 hooks will not run.`,
+      `  add it:  export PATH="${state.binDir}:$PATH"  in your shell profile, then open a new terminal.`
+    );
+  }
+  return lines;
+}
+
 // adapters/codex/bin/enroll.mjs
 var flag = (name) => {
   const arg = process.argv.slice(2).find((a) => a.startsWith(`--${name}=`));
   return arg ? arg.slice(name.length + 3) : void 0;
 };
+var apiKey = flag("apiKey");
+if (apiKey === "-") {
+  apiKey = (await readStdin(process.stdin)).trim();
+  if (apiKey === "") {
+    process.stderr.write(
+      "darkhunt: --apiKey=- was given but stdin was empty.\n  Copy your API key first, then pipe it in \u2014 e.g. `pbpaste | enroll.mjs --apiKey=-`.\n"
+    );
+    process.exit(1);
+  }
+}
 try {
   const r = await enroll({
-    ...flag("apiKey") !== void 0 ? { apiKey: flag("apiKey") } : {},
+    ...apiKey !== void 0 ? { apiKey } : {},
     ...flag("apiBaseUrl") !== void 0 ? { apiBaseUrl: flag("apiBaseUrl") } : {},
     ...flag("tenantId") !== void 0 ? { tenantId: flag("tenantId") } : {},
     ...flag("workspaceId") !== void 0 ? { workspaceId: flag("workspaceId") } : {},
@@ -1211,6 +1334,7 @@ try {
     environment: "$DARKHUNT_API_KEY",
     "darkhunt-cli": "the key darkhunt-cli enrolled"
   };
+  const launchers = installLaunchers();
   process.stdout.write(
     `darkhunt: enrolled${r.email ? ` as ${r.email}` : ""} using ${KEY_SOURCE[r.keySource]}
   endpoint     ${r.apiBaseUrl}
@@ -1218,9 +1342,16 @@ try {
   workspace    ${r.workspaceId}
   application  ${r.applicationId}
   config       ${r.configPath} (0600)
-  capture: on   enforce: off
+` + launchers.map((p) => `  launcher     ${p}
+`).join("") + `  capture: on   enforce: off
 `
   );
+  const warnings = launcherWarnings(launcherState());
+  if (warnings.length > 0) {
+    process.stdout.write(`
+${warnings.map((l) => `darkhunt: WARNING ${l}
+`).join("")}`);
+  }
 } catch (err) {
   if (err instanceof MissingKeyError) {
     process.stderr.write(

package/dist/bin/forwarder.mjs

@@ -18295,6 +18295,7 @@ function summarize(output) {
     return text;
   return `${text.slice(0, TOOL_SUMMARY_LIMIT)}\u2026 [truncated, ${text.length} chars]`;
 }
+var RESUMED_USER_TEXT_LIMIT = 4e3;
 var SessionEmitter = class {
   client;
   options;
@@ -18321,10 +18322,26 @@ var SessionEmitter = class {
   constructor(client, options) {
     this.client = client;
     this.options = options;
+    if (options.resumeTurn) {
+      this.lastUserText = options.resumeTurn.userText;
+      this.userTurnOpen = options.resumeTurn.open;
+    }
   }
   get recordCount() {
     return this.count;
   }
+  /**
+   * The turn still in flight, for the forwarder to hand to the next pass. Read after
+   * `finish()` — a turn is only settled once the pass has ended everything it opened.
+   */
+  get turn() {
+    const text = this.lastUserText;
+    const carried = text !== void 0 && text.length > RESUMED_USER_TEXT_LIMIT ? `${text.slice(0, RESUMED_USER_TEXT_LIMIT)}\u2026 [truncated, ${text.length} chars]` : text;
+    return {
+      ...carried !== void 0 ? { userText: carried } : {},
+      open: this.userTurnOpen
+    };
+  }
   /**
    * Create a span under a seed derived from the record. Scoped by session id, so two
    * sessions sharing a record uuid cannot collide, and by a discriminator, so the
@@ -18580,6 +18597,11 @@ function resumeOffset(checkpoints, path) {
     return 0;
   return previous.offset;
 }
+function resumeTurn(checkpoints, path, from) {
+  if (from <= 0)
+    return void 0;
+  return checkpoints[path]?.turn;
+}
 
 // packages/core/dist/forwarder/tail.js
 import { closeSync, openSync, readSync, statSync as statSync3 } from "node:fs";
@@ -18737,7 +18759,7 @@ function saveHealth(scope, health) {
 }
 
 // packages/core/dist/forwarder/run.js
-import { readdirSync as readdirSync2 } from "node:fs";
+import { readdirSync as readdirSync2, statSync as statSync4 } from "node:fs";
 
 // node_modules/@darkhunt-security/telemetry/dist/client.js
 init_esm();
@@ -21597,12 +21619,14 @@ async function runForwarder(mapper, options = {}) {
       for (const path of paths) {
         try {
           const from = resumeOffset(checkpoints, path);
+          const carried = resumeTurn(checkpoints, path, from);
           const emitter = new SessionEmitter(client, {
             sessionId: mapper.sessionIdFor(path),
             vendor: mapper.vendor,
             passKey: String(from),
             ...ids !== void 0 ? { ids } : {},
-            ...userId !== void 0 ? { userId } : {}
+            ...userId !== void 0 ? { userId } : {},
+            ...carried !== void 0 ? { resumeTurn: carried } : {}
           });
           let cursor = from;
           let reached = from;
@@ -21628,7 +21652,12 @@ async function runForwarder(mapper, options = {}) {
           if (ingested === 0)
             continue;
           await emitter.finish();
-          staged[path] = { offset: reached, size: fileSize };
+          const turn = emitter.turn;
+          staged[path] = {
+            offset: reached,
+            size: fileSize,
+            ...turn.userText !== void 0 || turn.open ? { turn } : {}
+          };
           result.transcripts++;
           result.records += emitter.recordCount;
           if (watch.failures() > 0)

package/dist/bin/init.mjs

@@ -2,11 +2,6 @@
 import { createRequire as __dhCreateRequire } from 'node:module';
 const require = __dhCreateRequire(import.meta.url);
 
-// adapters/codex/bin/init.mjs
-import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { join as join6 } from "node:path";
-
 // packages/core/dist/config/local.js
 import { join as join3 } from "node:path";
 
@@ -1083,30 +1078,75 @@ import { homedir as homedir3 } from "node:os";
 import { join as join5 } from "node:path";
 var CLI_CREDENTIALS_PATH = join5(homedir3(), ".darkhunt", "credentials.json");
 
-// adapters/codex/bin/init.mjs
-var LAUNCHERS = { "darkhunt-codex-spool": "spool.mjs", "darkhunt-codex-guard": "guard.mjs" };
+// adapters/codex/bin/lib/launchers.mjs
+import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { join as join6 } from "node:path";
+var LAUNCHERS = {
+  "darkhunt-codex-spool": "spool.mjs",
+  "darkhunt-codex-guard": "guard.mjs"
+};
 var BIN_DIR = join6(homedir4(), ".local", "bin");
-function installLaunchers() {
-  mkdirSync2(BIN_DIR, { recursive: true });
-  const installed = [];
-  for (const [name, target] of Object.entries(LAUNCHERS)) {
-    const path = join6(BIN_DIR, name);
-    writeFileSync2(
-      path,
-      `#!/bin/sh
+var script = (target) => `#!/bin/sh
 # Installed by darkhunt endpoint-plugins. Resolves the newest installed
 # plugin version at run time; do not hard-code a version here.
 D=$(ls -d "$HOME"/.codex/plugins/cache/*/darkhunt-guard/*/dist/bin 2>/dev/null | sort -V | tail -1)
 [ -n "$D" ] || exit 0
 exec "$D/${target}" "$@"
-`,
-      { mode: 493 }
-    );
+`;
+function installLaunchers(binDir = BIN_DIR) {
+  mkdirSync2(binDir, { recursive: true });
+  const installed = [];
+  for (const [name, target] of Object.entries(LAUNCHERS)) {
+    const path = join6(binDir, name);
+    writeFileSync2(path, script(target), { mode: 493 });
     chmodSync2(path, 493);
     installed.push(path);
   }
   return installed;
 }
+function launcherState(binDir = BIN_DIR, path = process.env["PATH"] ?? "") {
+  const missing = [];
+  const stale = [];
+  for (const [name, target] of Object.entries(LAUNCHERS)) {
+    const file = join6(binDir, name);
+    if (!existsSync2(file)) {
+      missing.push(name);
+      continue;
+    }
+    let body = "";
+    try {
+      body = readFileSync2(file, "utf8");
+    } catch {
+    }
+    if (body !== script(target)) stale.push(name);
+  }
+  return { binDir, missing, stale, onPath: path.split(":").includes(binDir) };
+}
+function launcherWarnings(state) {
+  const lines = [];
+  if (state.missing.length > 0) {
+    lines.push(
+      `hook launchers missing: ${state.missing.join(", ")} \u2014 hooks cannot run.`,
+      `  install them:  install-hooks.mjs`
+    );
+  }
+  if (state.stale.length > 0) {
+    lines.push(
+      `hook launchers are not the ones this version writes: ${state.stale.join(", ")}.`,
+      `  refresh them:  install-hooks.mjs`
+    );
+  }
+  if (!state.onPath) {
+    lines.push(
+      `${state.binDir} is not on PATH \u2014 hooks will not run.`,
+      `  add it:  export PATH="${state.binDir}:$PATH"  in your shell profile, then open a new terminal.`
+    );
+  }
+  return lines;
+}
+
+// adapters/codex/bin/init.mjs
 try {
   const r = init(process.argv.slice(2));
   const launchers = installLaunchers();
@@ -1118,10 +1158,11 @@ try {
 `).join("") + `  capture: on   enforce: off
 `
   );
-  if (!(process.env["PATH"] ?? "").split(":").includes(BIN_DIR)) {
+  const warnings = launcherWarnings(launcherState());
+  if (warnings.length > 0) {
     process.stdout.write(`
-darkhunt: WARNING ${BIN_DIR} is not on PATH \u2014 hooks will not run.
-`);
+${warnings.map((l) => `darkhunt: WARNING ${l}
+`).join("")}`);
   }
 } catch (err) {
   process.stderr.write(`darkhunt: ${err.message}

package/dist/bin/install-hooks.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { createRequire as __dhCreateRequire } from 'node:module';
+const require = __dhCreateRequire(import.meta.url);
+
+// adapters/codex/bin/lib/launchers.mjs
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var LAUNCHERS = {
+  "darkhunt-codex-spool": "spool.mjs",
+  "darkhunt-codex-guard": "guard.mjs"
+};
+var BIN_DIR = join(homedir(), ".local", "bin");
+var script = (target) => `#!/bin/sh
+# Installed by darkhunt endpoint-plugins. Resolves the newest installed
+# plugin version at run time; do not hard-code a version here.
+D=$(ls -d "$HOME"/.codex/plugins/cache/*/darkhunt-guard/*/dist/bin 2>/dev/null | sort -V | tail -1)
+[ -n "$D" ] || exit 0
+exec "$D/${target}" "$@"
+`;
+function installLaunchers(binDir = BIN_DIR) {
+  mkdirSync(binDir, { recursive: true });
+  const installed2 = [];
+  for (const [name, target] of Object.entries(LAUNCHERS)) {
+    const path = join(binDir, name);
+    writeFileSync(path, script(target), { mode: 493 });
+    chmodSync(path, 493);
+    installed2.push(path);
+  }
+  return installed2;
+}
+function launcherState(binDir = BIN_DIR, path = process.env["PATH"] ?? "") {
+  const missing = [];
+  const stale = [];
+  for (const [name, target] of Object.entries(LAUNCHERS)) {
+    const file = join(binDir, name);
+    if (!existsSync(file)) {
+      missing.push(name);
+      continue;
+    }
+    let body = "";
+    try {
+      body = readFileSync(file, "utf8");
+    } catch {
+    }
+    if (body !== script(target)) stale.push(name);
+  }
+  return { binDir, missing, stale, onPath: path.split(":").includes(binDir) };
+}
+function launcherWarnings(state) {
+  const lines = [];
+  if (state.missing.length > 0) {
+    lines.push(
+      `hook launchers missing: ${state.missing.join(", ")} \u2014 hooks cannot run.`,
+      `  install them:  install-hooks.mjs`
+    );
+  }
+  if (state.stale.length > 0) {
+    lines.push(
+      `hook launchers are not the ones this version writes: ${state.stale.join(", ")}.`,
+      `  refresh them:  install-hooks.mjs`
+    );
+  }
+  if (!state.onPath) {
+    lines.push(
+      `${state.binDir} is not on PATH \u2014 hooks will not run.`,
+      `  add it:  export PATH="${state.binDir}:$PATH"  in your shell profile, then open a new terminal.`
+    );
+  }
+  return lines;
+}
+
+// adapters/codex/bin/install-hooks.mjs
+var installed = installLaunchers();
+process.stdout.write(
+  `darkhunt: hook launchers installed
+` + installed.map((p) => `  ${p}
+`).join("")
+);
+var warnings = launcherWarnings(launcherState());
+if (warnings.length > 0) {
+  process.stdout.write(`
+${warnings.map((l) => `darkhunt: ${l}
+`).join("")}`);
+}
+process.stdout.write(`
+capture starts on your NEXT Codex CLI session.
+`);

package/dist/bin/status.mjs

@@ -2,6 +2,11 @@
 import { createRequire as __dhCreateRequire } from 'node:module';
 const require = __dhCreateRequire(import.meta.url);
 
+// adapters/codex/bin/status.mjs
+import { readFileSync as readFileSync7 } from "node:fs";
+import { dirname, join as join11 } from "node:path";
+import { fileURLToPath } from "node:url";
+
 // packages/core/dist/config/local.js
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join as join3 } from "node:path";
@@ -1318,17 +1323,87 @@ var codexTranscript = {
   }
 };
 
+// adapters/codex/bin/lib/launchers.mjs
+import { chmodSync, existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join10 } from "node:path";
+var LAUNCHERS = {
+  "darkhunt-codex-spool": "spool.mjs",
+  "darkhunt-codex-guard": "guard.mjs"
+};
+var BIN_DIR = join10(homedir5(), ".local", "bin");
+var script = (target) => `#!/bin/sh
+# Installed by darkhunt endpoint-plugins. Resolves the newest installed
+# plugin version at run time; do not hard-code a version here.
+D=$(ls -d "$HOME"/.codex/plugins/cache/*/darkhunt-guard/*/dist/bin 2>/dev/null | sort -V | tail -1)
+[ -n "$D" ] || exit 0
+exec "$D/${target}" "$@"
+`;
+function launcherState(binDir = BIN_DIR, path = process.env["PATH"] ?? "") {
+  const missing = [];
+  const stale = [];
+  for (const [name, target] of Object.entries(LAUNCHERS)) {
+    const file = join10(binDir, name);
+    if (!existsSync3(file)) {
+      missing.push(name);
+      continue;
+    }
+    let body = "";
+    try {
+      body = readFileSync6(file, "utf8");
+    } catch {
+    }
+    if (body !== script(target)) stale.push(name);
+  }
+  return { binDir, missing, stale, onPath: path.split(":").includes(binDir) };
+}
+function launcherWarnings(state) {
+  const lines = [];
+  if (state.missing.length > 0) {
+    lines.push(
+      `hook launchers missing: ${state.missing.join(", ")} \u2014 hooks cannot run.`,
+      `  install them:  install-hooks.mjs`
+    );
+  }
+  if (state.stale.length > 0) {
+    lines.push(
+      `hook launchers are not the ones this version writes: ${state.stale.join(", ")}.`,
+      `  refresh them:  install-hooks.mjs`
+    );
+  }
+  if (!state.onPath) {
+    lines.push(
+      `${state.binDir} is not on PATH \u2014 hooks will not run.`,
+      `  add it:  export PATH="${state.binDir}:$PATH"  in your shell profile, then open a new terminal.`
+    );
+  }
+  return lines;
+}
+
 // adapters/codex/bin/status.mjs
 try {
   const s = status("codex", codexTranscript);
   const n = (x) => x.toLocaleString();
   console.log(`darkhunt endpoint status \u2014 codex`);
+  const root = join11(dirname(fileURLToPath(import.meta.url)), "..", "..");
+  let installed = "unknown";
+  try {
+    installed = JSON.parse(readFileSync7(join11(root, "package.json"), "utf8")).version;
+  } catch {
+  }
+  console.log(`  plugin       ${installed}   ${root}`);
   console.log(`  profile      ${s.profile}  ->  ${s.baseUrl}`);
   console.log(`  tenant       ${s.tenantId}   workspace ${s.workspaceId}`);
   console.log(
     `  user         ${s.userId ?? "(none \u2014 traces are unattributed)"}` + (s.userIdSource === "none" ? "" : `  [from ${s.userIdSource}]`)
   );
   console.log(`  capture      ${s.capture ? "ON" : "OFF"}      enforce ${s.enforce}`);
+  const launchers = launcherState();
+  const launcherProblems = launcherWarnings(launchers);
+  console.log(
+    `  launchers    ${launcherProblems.length === 0 ? `OK  (${launchers.binDir}, on PATH)` : "PROBLEM"}`
+  );
+  for (const line of launcherProblems) console.log(`               ${line}`);
   console.log(
     `  hook events  ${s.spoolEvents}${s.spoolLastAt ? "  last " + s.spoolLastAt : "  (no session hook has ever fired)"}`
   );

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@darkhunt-security/endpoint-codex",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "type": "module",
   "description": "Darkhunt endpoint adapter for Codex CLI: hook codec, rollout transcript mapper, plugin manifest.",
+  "bin": {
+    "endpoint-codex": "dist/bin/enroll.mjs"
+  },
   "files": [
     "dist/bin",
     "hooks",
@@ -10,8 +13,8 @@
     ".codex-plugin"
   ],
   "devDependencies": {
-    "@darkhunt-security/endpoint-contracts": "0.9.0",
-    "@darkhunt-security/endpoint-core": "0.9.0"
+    "@darkhunt-security/endpoint-contracts": "0.9.1",
+    "@darkhunt-security/endpoint-core": "0.9.1"
   },
   "publishConfig": {
     "access": "public",