@davvidbaker/flambe-cli 0.1.4 → 0.1.5

package/README.md

@@ -74,3 +74,56 @@ processes only need their normal local Flambe connection settings.
 In `agent` mode, your current work AI reads the review returned by `flambe message`
 and submits its decision with `flambe decide <review-id> --file <decision.json>`.
 No separate model or inference API key is required.
+
+## Local Codex / Single Burner hooks
+
+With Single Burner running, put its printed connection values in the target
+project's `.env`, including `FLAMBE_RUNTIME_MODE=local_self_contained`. From
+that project root run:
+
+```sh
+flambe setup codex
+```
+
+This installs project-scoped Codex hooks and the bundled `flambe-cli` skill.
+It preserves unrelated hooks, backs up an existing `hooks.json` once, and keeps
+an existing custom skill rather than overwriting it. Restart local Codex, open
+`/hooks`, and review/trust the new definitions. Hook loading remains subject to
+project trust and workspace policy. No ChatGPT plugin, Platform organization,
+tunnel, or model API key is needed for this local route.
+
+Keep `flambe` available on PATH to the Codex process. Hooks use `flambe.cmd` on
+Windows and `flambe` on macOS/Linux, with no machine-specific checkout paths.
+If you installed the CLI while Codex was already open, restart the app so it can
+see the updated PATH.
+
+- Session start, resume, prompts, subagent start, and compaction restore context.
+- Tool hooks use a small cache, refresh local status at most once per 30 seconds
+  during ordinary work, and request a fresh stack check every ten tool calls or
+  90 seconds while tools continue. Explicit lifecycle checkpoints reset the
+  call counter; a timer does not run while the agent is idle.
+- Stop requests at most one reconciliation continuation after substantial tool
+  work without a verified checkpoint. It does not automatically close parents.
+- Interrupt records a pending local reconciliation reminder; it does not mutate
+  activities or prevent interruption.
+
+The agent still names/nests activities, decides when work changed, and submits
+requested reducer decisions. Hooks only send status requests to the configured
+numeric-loopback server. They do not call a model, inspect transcripts, or
+queue activity mutations. Missing configuration, an unavailable server, or an
+unidentifiable agent produces bounded feedback and permits work to continue.
+The local cache contains counters/fingerprints, not prompts, command text,
+credentials, or activity names. See [ADR-023](../docs/ADR-023-portable-local-codex-hooks.md).
+
+```sh
+flambe setup codex --check
+flambe setup codex --remove
+```
+
+`--check` inspects installed files and local connection configuration; it cannot
+confirm a live server, Codex trust, or workspace policy.
+`--remove` retains skills and unrelated hooks. For a live check, restart Codex,
+confirm these hooks are trusted in `/hooks`, then ask it to track a short local
+activity, request/submit an agent-mode review, and end or suspend the activity.
+Verify that the chart and that agent's lane reflect the result. A fresh install
+on the work laptop still needs this native Codex verification.

package/bin/flambe.mjs

@@ -3,7 +3,8 @@
 import { run } from '../src/cli.mjs';
 import { loadProjectEnv } from '../src/env.mjs';
 
-loadProjectEnv();
+// Hook input selects its installed project root; do not preload a nested .env.
+if (process.argv[2] !== 'hook') loadProjectEnv();
 
 try {
   await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davvidbaker/flambe-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "CLI for streaming coding-agent activity into Flambe",
   "type": "module",
   "bin": {
@@ -9,11 +9,14 @@
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "skills",
+    "scripts/prepare-skills.mjs"
   ],
   "scripts": {
     "test": "node --test",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "prepack": "node scripts/prepare-skills.mjs"
   },
   "engines": {
     "node": ">=22"

package/scripts/prepare-skills.mjs

@@ -0,0 +1,12 @@
+import {copyFileSync, existsSync, mkdirSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {dirname} from 'node:path';
+
+const source = fileURLToPath(new URL('../../.codex/skills/flambe-cli/SKILL.md', import.meta.url));
+const target = fileURLToPath(new URL('../skills/flambe-cli/SKILL.md', import.meta.url));
+if (existsSync(source)) {
+  mkdirSync(dirname(target), {recursive: true});
+  copyFileSync(source, target);
+} else if (!existsSync(target)) {
+  throw new Error('The CLI package is missing its canonical flambe-cli skill.');
+}

package/skills/flambe-cli/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: flambe-cli
+description: Track coding-agent work in a Flambe trace with the flambe CLI. Use when logging substantial or multi-step work in a project configured with FLAMBE_URL, FLAMBE_API_TOKEN, and FLAMBE_TRACE_ID.
+---
+
+# Flambe CLI
+
+Log semantic work units as a live flame chart — not commands, file opens, or hidden reasoning. Skip trivial questions. If `FLAMBE_URL`, `FLAMBE_API_TOKEN`, or `FLAMBE_TRACE_ID` is set neither in `.env` nor in the shell environment (Cloud Agent secrets arrive as environment variables), skip silently.
+
+Needs Node 22+ and `flambe` on `PATH`. If it is missing, `npm install -g @davvidbaker/flambe-cli`; in this repo without a global install, use `node cli/bin/flambe.mjs`. You do not need to pick a name: the reducer names each agent on its first request, the CLI remembers it (`~/.flambe/agent-names.json`) and prints `reducer named this agent "X"` on stderr once. `flambe whoami` shows your id, name, and platform. `FLAMBE_AGENT_PLATFORM` is the product you run on (`"Cursor Cloud"`, `"Codex"`; derived from the session when unset) and is shared by many agents; it is not your name. Set `FLAMBE_AGENT_NAME` only to override; never put `FLAMBE_AGENT_ID`, `FLAMBE_AGENT_NAME`, or `FLAMBE_AGENT_PLATFORM` in `.env`.
+
+## Think in a stack
+
+Always treat attention as a **call stack**, not a flat to-do list.
+
+You will often produce some progress on a parent goal, then go down a rabbit hole about one specific thing (a bug, a prerequisite, a design question, a test failure). That digression is a **push**: start a nested activity under the still-running parent. When the rabbit hole is done, **pop**: end the nested activity with the outcome, and continue the parent where you left off.
+
+- Leave parents running while you dig. Ending the parent when you dive deeper flattens the chart and loses the “come back up” story.
+- Nested steps belong under the workstream they serve — not as siblings of the top objective.
+- When attention moves to a true sibling of the current leaf, end the leaf first, then start the sibling under the same parent.
+- Use `--root` only for a genuinely new top-level workstream, not for every digression.
+- Keep the active stack truthful as work changes. Do not plan a detailed chart up front or reconstruct one afterward.
+
+## Local Codex hooks
+
+For a Single Burner project, run `flambe setup codex` from its root after setting
+its local connection values in `.env`. Setup merges project hooks into
+`.codex/hooks.json` and installs this skill if it is missing. Existing custom
+skills and unrelated hooks are retained. Restart local Codex and review/trust
+these hooks with `/hooks`; installed files alone do not prove they are running.
+Use `flambe setup codex --check` to inspect the files, and `--remove` to remove
+only Flambe's own hook handlers. Keep `flambe` on PATH; Windows hooks use
+`flambe.cmd` so PowerShell script policy does not select `flambe.ps1`.
+
+Hooks restore workflow context, request periodic stack checks, and can request
+one reconciliation continuation before a substantive turn ends. They make no
+inference calls or semantic activity changes. You still start/nest/end the real
+work and complete requested work-AI reviews. A turn ending does not mean its
+parent task ended. Missing servers or identity produce feedback without blocking
+ordinary work. Hooks require `local_self_contained`; they do not route to Cloud.
+
+## Commands
+
+```sh
+flambe start "Fix USERPROFILE resolution"     # prints id; nests under the current active activity
+flambe start "Add Windows support" --root     # new top-level workstream
+flambe end "$ID" "Resolved USERPROFILE on Windows"
+flambe suspend "$ID" "Waiting for product decision"   # only when explicitly tabling work
+flambe resume "$ID" "Decision received"
+flambe observe carbon 312.4 --unit gCO2eq/kWh --on 2026-09-04 --payload '{"source":"us-ba-mean"}'
+flambe message "Auth fix needs the session module refactored too; widening scope"   # ask the Reducer Agent
+```
+
+`observe` writes a user overlay (carbon, mood, …), not an activity. Same `kind` + `--on` date upserts and merges payload keys. Omit `--on` to always insert.
+
+**255-character hard limit on activity names and `--description`.** The column is `varchar(255)`. A longer value returns a 500 and can wedge the offline queue. Count before `start`. Prefer a short concrete name; put detail in the end/suspend/resume message (those are unbounded).
+
+Reuse this conversation's activity id when you already have one. Run `flambe status --active --json` only to find a matching open activity from this session; ignore unrelated active work. Do not fetch threads or categories to decide placement; that is the reducer's job.
+
+Every command is a proposal; the reducer owns the stack. Without `--parent`/`--root`, `start` nests under **your own** newest active activity (other agents' work is never your parent), puts a child on its parent's thread, and gives it the parent's categories; a new root gets its thread and categories chosen by the reducer a few seconds later. `FLAMBE_THREAD` (name, unique slug, or id) is sent as `--thread` when that flag is omitted; do not list threads and pick one by project name. Pass `--thread` / `--parent` / `--category` only when you are certain. Offline `offline-…` ids from `start` are valid for `end`. Do not retry queued operations. Offline results carry no immediate reducer output; nothing is dropped. Local `serve` always applies deterministic rules, including duplicate reuse, ancestor resumption, and descendant closure. Optional review is off by default; an explicitly configured server can ask the current work AI to review or call a separate model.
+
+## Read every result; the reducer may rewrite
+
+Any command (`start`, `end`, `suspend`, `resume`, `message`) may come back with `direction`, `reply`, and `actions_applied`, not only `message`. The reducer records what you proposed and then corrects the structure around it when needed: re-parent, rename, treat your `start` as a resume of an already-open same-name activity, resume a suspended ancestor before nesting under it, or close open descendants when you end a parent (`--force`). The CLI prints each rewrite on stderr (`reducer nested 43 under 42`, `actions`). The returned state is the truth: keep using the ids it gives you, do not undo a rewrite, and do not re-issue the proposal.
+
+The reducer may answer a proposal with a question in `reply`, usually when a name does not fit its ancestors. Answer before your next step: rename the activity, or reply with `flambe message`. The CLI reminds you on the next command if a question is still open; it never refuses.
+
+A returned `direction` is binding: act on it before doing more work. On `pause`, `stop`, or `escalate`, stop and surface the reply to David rather than deciding yourself. `direction -` or none means continue as you were. A model-judged `start` can take a few seconds; wait for it.
+
+## Review with the AI doing the work
+
+Review only at meaningful scope/approach decisions or when placement is uncertain.
+Routine lifecycle tracking uses deterministic local rules. Do not review every
+start/end, and do not request full history for routine bookkeeping. Work-AI
+review context contains the current path and this agent's open work. Compact
+lifecycle replies mark their state scope; omitted activities are not ended.
+
+When a local result contains `review` and `model_review.status: awaiting_decision`,
+you are the reviewer. This is the current work AI evaluating its own context,
+not independent approval. Do not start another model, ask for provider keys, or
+claim a separate reviewer approved your work.
+
+Read `review.instructions`, `review.context`, and `review.decision_schema`.
+Evaluate the user's intent, current path, and proposed scope. Choose concise
+assessment, direction, reply, rationale, and at most one permitted action.
+Write that decision as JSON and submit it with:
+
+```sh
+flambe decide <review.review_id> --file <decision.json>
+```
+
+`flambe message` returns the review JSON in this mode. Flagged starts normally
+print only a small review-available notice on stderr; request review only when
+scope or placement needs judgment. They include full review JSON only when the
+server explicitly enables automatic start reviews. Stdout remains the recorded id. Keep the same local
+connection, trace, and stable agent id for both steps. Ordinary
+lifecycle tracking continues to use start/end/suspend/resume.
+
+Complete a requested review before continuing substantive work. Follow the
+returned direction after submission; escalate unresolved human judgment with no
+actions and ask the user. Do not repeat the recorded start to request review.
+On `REDUCER_STATE_CHANGED` or `REVIEW_EXPIRED`, request a fresh review with
+`flambe message` for that activity, reassess it, and submit against the new id.
+Do not resubmit the old decision blindly. Identical retries of a completed
+submission return a receipt; `replayed: true` means no new action was applied.
+If the server lacks work-AI review support, report that instead of changing instances.
+
+## End of work
+
+When the work you were doing is finished, check limbo and scheduled activities before you stop. Run `flambe status --unstarted --json`. If something there is worth doing next, propose that candidate with `flambe message` and begin it only if the reply says continue. Do not begin it unasked, and do not ask David in chat.
+
+## Ask the reducer before you drift
+
+`flambe message "<update>"` is your own channel: it sends your update plus the live flame (open and suspended work, the path to the current activity, and ended work from the last 21 days) and answers with `assessment`, `direction`, `reply`, and at most one stack change. Message when you are about to:
+
+- widen scope beyond the activity you started
+- change approach after the plan stalled
+- end a root workstream
+- continue while suspecting the work has drifted from what David asked
+- answer a question the reducer asked
+
+Do not message for routine progress, and never instead of `start`/`end`. Defaults to your newest active activity; pass `--activity <id>` to target another. Needs a reachable server with model review configured (not queued). Local self-contained `serve` has optional review, off by default, including an `agent` mode that returns review context for you to evaluate. On `REDUCER_NOT_CONFIGURED`, do not retry or switch to a remote server; surface unresolved judgment to the user and continue deterministic logging. A lifecycle result with `model_review.status: failed` still recorded the activity: keep its returned id/state, surface the review failure, and do not repeat the start or retarget another instance.
+
+## What to record
+
+- Start a new activity when the goal or scope meaningfully changes (a specific implementation, a discovered prerequisite, a concrete bug, focused tests, verification) — that is a stack push.
+- Do not start an activity for committing or pushing. Those are wrap-up of the current leaf; mention them in the end-message if useful. Exception: the assigned work *is* getting code onto a remote.
+- Name the concrete action and object (`Fix USERPROFILE config resolution`), not `Investigate` / `Implement` / `Work on tests`. Stay well under 255 characters; do not compensate with a long name or `--description`.
+- End-message: the outcome, not `done`. That records a resolution. Omitting the message is a plain end. No secrets, tokens, or transcripts. Ending the leaf is the pop; then resume the parent mentally and in the log.

package/src/cli.mjs

@@ -28,6 +28,7 @@ const usage = `Usage:
   flambe whoami [--json]
   flambe message <text> [--activity <id>] [--json]
   flambe decide <review-id> --file <decision.json>
+  flambe setup codex [--check | --remove]
   flambe observe <kind> <value> [--unit <unit>] [--on <YYYY-MM-DD>] [--payload <json>] [--at <ISO-8601>]
   flambe serve [--port <n>] [--db <path>] [--static <dir>]
   flambe export [file] [--db <path>]
@@ -360,9 +361,43 @@ function formatReducerNote(note) {
   return `reducer: ${JSON.stringify(note)}\n`;
 }
 
-export async function run(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, client, questionsPath } = {}) {
+export async function run(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, stdin = process.stdin, client, questionsPath } = {}) {
   const [command, ...args] = argv;
 
+  if (command === 'hook' && args.length === 1 && args[0] === 'codex') {
+    const {readHookInput, runCodexHook} = await import('./codex-hook.mjs');
+    let output;
+    try { output = await runCodexHook(await readHookInput(stdin), {env}); }
+    catch { output = {systemMessage: 'Single Burner hook input could not be read; work may continue.'}; }
+    stdout.write(`${JSON.stringify(output)}\n`);
+    return;
+  }
+
+  if (command === 'setup') {
+    if (args[0] !== 'codex' || args.length > 2
+      || (args[1] !== undefined && !['--check', '--remove'].includes(args[1]))) {
+      throw new Error('Usage: flambe setup codex [--check | --remove]');
+    }
+    const {setupCodex} = await import('./codex-setup.mjs');
+    const action = args[1] === '--check' ? 'check' : args[1] === '--remove' ? 'remove' : 'install';
+    const result = setupCodex({action});
+    let localConnectionConfigured = false;
+    try {
+      localConnectionConfigured = env.FLAMBE_RUNTIME_MODE === 'local_self_contained' && Boolean(clientFromEnv(env));
+    } catch { /* Only report whether the config is usable; never echo credentials. */ }
+    if (action === 'check') stdout.write(`${JSON.stringify({...result, localConnectionConfigured})}\n`);
+    else if (action === 'remove') stdout.write(`Single Burner Codex hooks ${result.removed ? 'removed' : 'were not installed'}. Existing skills and unrelated hooks were retained.\n`);
+    else {
+      stdout.write(`Single Burner Codex hooks installed in ${result.root}\n`);
+      stdout.write(result.skillInstalled ? 'Installed the flambe-cli skill.\n' : 'Kept the existing flambe-cli skill.\n');
+      if (!result.skillMatches) stdout.write('The existing skill differs from the bundled version; review it for current work-AI review instructions.\n');
+      if (!localConnectionConfigured) stdout.write('Copy Single Burner connection values into this project .env, including FLAMBE_RUNTIME_MODE=local_self_contained, before using the hooks.\n');
+      stdout.write('Restart the local Codex session. Review and trust these project hooks with /hooks before relying on them. Workspace policy can restrict hooks.\n');
+      stdout.write('Run flambe setup codex --check to inspect installed files and connection configuration. This does not confirm Codex trust or live hook execution.\n');
+    }
+    return;
+  }
+
   if (!command || command === 'help' || command === '--help' || command === '-h') {
     stdout.write(`${usage}\n`);
     return;

package/src/codex-hook.mjs

@@ -0,0 +1,237 @@
+import {createHash} from 'node:crypto';
+import {existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {dirname, join, resolve} from 'node:path';
+import {setTimeout as delay} from 'node:timers/promises';
+import {agentIdentityFromEnv, clientFromEnv} from './client.mjs';
+import {loadProjectEnv} from './env.mjs';
+import {atomicWrite, hasFlambeHooks} from './codex-setup.mjs';
+import {assertRuntimeUrl} from './runtime.mjs';
+
+const RESTORE = new Set(['SessionStart', 'SubagentStart', 'PostCompact', 'UserPromptSubmit']);
+const EVENTS = new Set([...RESTORE, 'PreToolUse', 'PostToolUse', 'Stop', 'Interrupt']);
+const hash = text => createHash('sha256').update(text).digest('hex');
+const clean = value => String(value).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 160);
+const emptyState = () => ({workInTurn: 0, workSinceTracked: 0, callsSinceReminder: 0});
+
+function projectRoot(cwd) {
+  let directory = resolve(cwd);
+  for (;;) {
+    const path = join(directory, '.codex', 'hooks.json');
+    if (existsSync(path) && hasFlambeHooks(JSON.parse(readFileSync(path, 'utf8')))) return directory;
+    const parent = dirname(directory);
+    if (parent === directory || existsSync(join(directory, '.git'))) return null;
+    directory = parent;
+  }
+}
+
+function context(event, text) {
+  return {hookSpecificOutput: {hookEventName: event, additionalContext: text}};
+}
+
+function connectionWarning(event) {
+  const text = 'Single Burner hook could not verify the local connection. Check the running server and this project\'s .env, including FLAMBE_RUNTIME_MODE=local_self_contained. Work may continue; do not substitute Cloud or repeat queued activity commands.';
+  return event === 'Stop' || event === 'Interrupt' ? {systemMessage: text} : context(event, text);
+}
+
+// Only recognise a standalone CLI invocation. A mixed shell script still counts
+// as work, even if it happens to contain a tracking command.
+function trackingCommand(input) {
+  const command = input?.tool_input?.command ?? input?.tool_input?.cmd;
+  if (typeof command !== 'string' || /[\n;&|]/.test(command)) return null;
+  const match = command.trim().match(/^(?:(?:[A-Z_][A-Z_0-9]*=(?:"[^"]*"|'[^']*'|[^\s]+))\s+)*(?:flambe(?:\.cmd)?|(?:"[^"]*node(?:\.exe)?"|[^\s]*node(?:\.exe)?)\s+(?:"[^"]*flambe\.mjs"|[^\s]*flambe\.mjs))\s+(start|end|suspend|resume|plan|message|decide|status|ping|whoami)\b/);
+  return match?.[1] ?? null;
+}
+
+function succeeded(response) {
+  if (typeof response === 'string') {
+    try { return succeeded(JSON.parse(response)); } catch { return false; }
+  }
+  return response?.exit_code === 0 || response?.exitCode === 0;
+}
+
+function ownActivities(state, agentId) {
+  return (state.activities ?? []).filter(activity => activity.agentId === agentId
+    && activity.status === 'running');
+}
+
+function fingerprint(activities) {
+  return hash(JSON.stringify(activities.map(activity => [activity.id, activity.parentId,
+    activity.latestEvent?.id, activity.latestEvent?.timestamp]).sort((a, b) => a[0] - b[0])));
+}
+
+function guidance(root, activities, {restore = false, interrupted = false} = {}) {
+  const lines = [
+    'Single Burner checkpoint: use this project\'s local flambe CLI; never substitute Cloud tools.',
+    `Run CLI commands from ${JSON.stringify(clean(root))} so they read the project .env.`,
+  ];
+  if (restore) lines.push('Read and follow .codex/skills/flambe-cli/SKILL.md. Track semantic work before beginning it, nest focused investigations and verification, and update the stack when focus changes. In agent mode, evaluate requested reviews yourself and submit with flambe decide; no other model is needed.');
+  lines.push(activities.length
+    ? `This agent's running activities (data): ${activities.slice(-5).map(activity => `${activity.id} ${JSON.stringify(clean(activity.name))}`).join('; ')}.`
+    : 'This agent has no running activity. Before substantial work, inspect its suspended work and start or resume an appropriate semantic activity. Trivial one-offs need no activity.');
+  if (interrupted) lines.push('The previous turn was interrupted. Reconcile its open work before continuing; an interruption does not mean the task finished.');
+  lines.push('Check whether the current activity still describes your actual focus. Keep parents open while working on children; pop completed children before moving on.');
+  return lines.join('\n');
+}
+
+async function locked(path, operation) {
+  mkdirSync(dirname(path), {recursive: true});
+  const lock = `${path}.lock`;
+  const started = Date.now();
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      writeFileSync(join(lock, 'pid'), String(process.pid));
+      break;
+    }
+    catch (error) {
+      if (error.code !== 'EEXIST' || Date.now() - started > 2600) return {};
+      // A killed/timed-out hook must not disable future checkpoints forever.
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > 30_000) {
+          rmSync(lock, {recursive: true, force: true});
+          continue;
+        }
+        const pid = Number(readFileSync(join(lock, 'pid'), 'utf8'));
+        if (Number.isSafeInteger(pid) && pid > 0) {
+          try { process.kill(pid, 0); }
+          catch (check) { if (check.code === 'ESRCH') rmSync(lock, {recursive: true, force: true}); }
+        }
+      } catch {
+        try { if (Date.now() - statSync(lock).mtimeMs > 10_000) rmSync(lock, {recursive: true, force: true}); }
+        catch { /* Another hook just released it. */ }
+      }
+      await delay(20);
+    }
+  }
+  try { return await operation(); }
+  finally { rmSync(lock, {recursive: true, force: true}); }
+}
+
+/** A checkpoint adapter, not an activity generator or model client. */
+export async function runCodexHook(input, {
+  env: shellEnv = process.env, now = Date.now,
+  stateDir = shellEnv.FLAMBE_CODEX_HOOK_STATE_DIR?.trim() || join(homedir(), '.flambe', 'codex-hooks'),
+  fetchImpl = globalThis.fetch, checkEveryMs = 30_000,
+  remindEveryCalls = 10, remindEveryMs = 90_000,
+} = {}) {
+  const event = input?.hook_event_name;
+  if (!EVENTS.has(event) || typeof input.cwd !== 'string' || !input.session_id) return {};
+  if (event === 'Stop' && input.stop_hook_active) return {};
+  let root;
+  let env;
+  let identity;
+  try {
+    root = projectRoot(input.cwd);
+    if (!root) return {};
+    env = {...shellEnv};
+    loadProjectEnv({cwd: root, env});
+    if (!['FLAMBE_URL', 'FLAMBE_API_TOKEN', 'FLAMBE_TRACE_ID'].some(key => env[key])) return {};
+    if (env.FLAMBE_RUNTIME_MODE !== 'local_self_contained') return connectionWarning(event);
+    assertRuntimeUrl(env.FLAMBE_URL, 'local_self_contained');
+    identity = agentIdentityFromEnv(env);
+    if (!identity.agentId) {
+      return RESTORE.has(event) ? context(event,
+        'Single Burner: read .codex/skills/flambe-cli/SKILL.md. The hook could not derive this Codex agent\'s identity, so it did not inspect any activity stack. Check flambe whoami in the local Codex environment; do not reuse another agent\'s identity or put agent IDs in .env.') : {};
+    }
+  } catch { return connectionWarning(event); }
+  const key = hash(JSON.stringify([root, env.FLAMBE_URL, env.FLAMBE_TRACE_ID, identity.agentId, input.session_id]));
+  const path = join(stateDir, `${key}.json`);
+  try {
+    return await locked(path, async () => {
+      let state;
+      try { state = {...emptyState(), ...JSON.parse(readFileSync(path, 'utf8'))}; }
+      catch { state = emptyState(); }
+      const at = now();
+      const save = output => { atomicWrite(path, `${JSON.stringify(state)}\n`); return output; };
+      const turn = input.turn_id ?? state.turn ?? 'unknown';
+      if (turn !== state.turn || event === 'UserPromptSubmit') {
+        state.turn = turn;
+        delete state.stopTurn;
+        state.workInTurn = 0;
+        state.workSinceTracked = 0;
+        state.callsSinceReminder = 0;
+        state.missingWarned = false;
+      }
+      if (event === 'Interrupt') {
+        state.interrupted = true;
+        return save({});
+      }
+      const tracking = trackingCommand(input);
+      if (event === 'PostToolUse') {
+        if (tracking && !['status', 'ping', 'whoami'].includes(tracking) && succeeded(input.tool_response)) {
+          state.workSinceTracked = 0;
+          state.callsSinceReminder = 0;
+          state.remindedAt = at;
+          state.checkedAt = 0;
+        }
+        return save({});
+      }
+      if (event === 'PreToolUse') {
+        if (tracking) return save({});
+        const weight = /^(apply_patch|Edit|Write)$/.test(input.tool_name ?? '') ? 3 : 1;
+        state.workInTurn += weight;
+        state.workSinceTracked += weight;
+        state.callsSinceReminder++;
+        state.lastWorkAt = at;
+      }
+      if (event === 'Stop' && (state.workInTurn < 3 || state.workSinceTracked === 0 || state.stopTurn === turn)) return save({});
+      const restore = RESTORE.has(event);
+      const periodic = state.callsSinceReminder >= remindEveryCalls || at - (state.remindedAt ?? at) >= remindEveryMs;
+      const due = restore || periodic || event === 'Stop' || !state.checkedAt || at - state.checkedAt >= checkEveryMs;
+      let activities = [];
+      if (due) {
+        state.checkedAt = at;
+        try {
+          const client = clientFromEnv(env);
+          client.fetch = (url, options) => fetchImpl(url, {...options, signal: AbortSignal.timeout(1200)});
+          activities = ownActivities(await client.status({activeOnly: true}), identity.agentId);
+          const current = fingerprint(activities);
+          const latestChange = Math.max(0, ...activities.map(activity => Date.parse(activity.latestEvent?.timestamp) || 0));
+          if (state.fingerprint && state.fingerprint !== current
+            && ((!activities.length && state.hasActive) || latestChange >= (state.lastWorkAt ?? 0))) {
+            state.workSinceTracked = 0;
+            state.callsSinceReminder = 0;
+            state.remindedAt = at;
+          }
+          state.fingerprint = current;
+          state.available = true;
+          state.hasActive = activities.length > 0;
+        } catch {
+          state.available = false;
+          if (!state.warnedAt || at - state.warnedAt >= remindEveryMs || restore) {
+            state.warnedAt = at;
+            return save(connectionWarning(event));
+          }
+          return save({});
+        }
+      }
+      if (!state.available) return save({});
+      if (event === 'Stop') {
+        if (!state.workSinceTracked) return save({});
+        state.stopTurn = turn;
+        return save({decision: 'block', reason: guidance(root, activities)
+          + '\nBefore handing back, reconcile the work you actually did. End completed activities, suspend work waiting on the user, or explain why an activity remains running. Complete any requested reducer review. This is one checkpoint, not an instruction to invent work or end every open parent.'});
+      }
+      const firstUntracked = event === 'PreToolUse' && !state.missingWarned && !state.hasActive;
+      if (restore || firstUntracked || periodic) {
+        if (firstUntracked) state.missingWarned = true;
+        state.callsSinceReminder = 0;
+        state.remindedAt = at;
+        const interrupted = state.interrupted;
+        state.interrupted = false;
+        return save(context(event, guidance(root, activities, {restore, interrupted})));
+      }
+      return save({});
+    });
+  } catch { return connectionWarning(event); }
+}
+
+export async function readHookInput(stdin = process.stdin) {
+  let body = '';
+  for await (const chunk of stdin) {
+    body += chunk;
+    if (Buffer.byteLength(body) > 1024 * 1024) throw new Error('Hook input exceeds 1 MiB');
+  }
+  return JSON.parse(body);
+}

package/src/codex-setup.mjs

@@ -0,0 +1,104 @@
+import {existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync} from 'node:fs';
+import {dirname, join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {randomUUID} from 'node:crypto';
+
+export const HOOK_COMMAND = 'flambe hook codex';
+export const HOOK_COMMAND_WINDOWS = 'flambe.cmd hook codex';
+export const HOOK_EVENTS = ['SessionStart', 'SubagentStart', 'UserPromptSubmit', 'PostCompact', 'PreToolUse', 'PostToolUse', 'Stop', 'Interrupt'];
+
+export function managedHook(hook) {
+  return hook?.type === 'command' && hook.command === HOOK_COMMAND
+    && hook.commandWindows === HOOK_COMMAND_WINDOWS;
+}
+
+export function hasFlambeHooks(config) {
+  return Object.values(config?.hooks ?? {}).some(groups => Array.isArray(groups)
+    && groups.some(group => group.hooks?.some(managedHook)));
+}
+
+function readConfig(path) {
+  if (!existsSync(path)) return {hooks: {}};
+  let config;
+  try { config = JSON.parse(readFileSync(path, 'utf8')); }
+  catch { throw new Error('Cannot read .codex/hooks.json as JSON; existing hooks were not changed.'); }
+  if (!config || typeof config !== 'object' || Array.isArray(config)
+    || (config.hooks !== undefined && (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks)))
+    || Object.values(config.hooks ?? {}).some(groups => !Array.isArray(groups)
+      || groups.some(group => !group || !Array.isArray(group.hooks)))) {
+    throw new Error('Unsupported .codex/hooks.json structure; existing hooks were not changed.');
+  }
+  return config;
+}
+
+export function atomicWrite(path, text) {
+  mkdirSync(dirname(path), {recursive: true});
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, text, {mode: 0o600, flag: 'wx'});
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+export function bundledSkill() {
+  const bundled = fileURLToPath(new URL('../skills/flambe-cli/SKILL.md', import.meta.url));
+  const source = fileURLToPath(new URL('../../.codex/skills/flambe-cli/SKILL.md', import.meta.url));
+  return readFileSync(existsSync(bundled) ? bundled : source, 'utf8');
+}
+
+function withoutManagedHooks(config) {
+  const result = {...config, hooks: {...config.hooks}};
+  for (const [event, groups] of Object.entries(result.hooks)) {
+    result.hooks[event] = groups.flatMap(group => {
+      if (!group.hooks.some(managedHook)) return [group];
+      const hooks = group.hooks.filter(hook => !managedHook(hook));
+      return hooks.length ? [{...group, hooks}] : [];
+    });
+    if (!result.hooks[event].length) delete result.hooks[event];
+  }
+  return result;
+}
+
+export function setupCodex({cwd = process.cwd(), action = 'install', skill = bundledSkill()} = {}) {
+  const root = resolve(cwd);
+  const path = join(root, '.codex', 'hooks.json');
+  const skillPath = join(root, '.codex', 'skills', 'flambe-cli', 'SKILL.md');
+  const existing = readConfig(path);
+  const installedEvents = HOOK_EVENTS.filter(event => existing.hooks?.[event]?.some(group =>
+    group.hooks.some(managedHook)));
+  const skillExists = existsSync(skillPath);
+  if (action === 'check') return {
+    root, hooksPath: path, installed: installedEvents.length === HOOK_EVENTS.length,
+    installedEvents, skillExists,
+    skillMatches: skillExists && readFileSync(skillPath, 'utf8') === skill,
+  };
+  const config = withoutManagedHooks(existing);
+  if (action === 'remove') {
+    if (installedEvents.length) atomicWrite(path, `${JSON.stringify(config, null, 2)}\n`);
+    return {root, hooksPath: path, removed: installedEvents.length > 0, skillRetained: skillExists};
+  }
+  if (action !== 'install') throw new Error('Unknown Codex setup action');
+  for (const event of HOOK_EVENTS) {
+    config.hooks[event] ??= [];
+    config.hooks[event].push({hooks: [{
+      type: 'command', command: HOOK_COMMAND, commandWindows: HOOK_COMMAND_WINDOWS,
+      timeout: event === 'Interrupt' ? 3 : 5,
+      statusMessage: 'Single Burner tracking checkpoint', additionalContextLimit: 1800,
+    }]});
+  }
+  // Preserve custom/existing instructions. Never silently replace a skill.
+  if (!skillExists) atomicWrite(skillPath, skill);
+  const serialized = `${JSON.stringify(config, null, 2)}\n`;
+  const unchanged = existsSync(path) && readFileSync(path, 'utf8') === serialized;
+  if (!unchanged) {
+    if (existsSync(path)) {
+      const backup = `${path}.before-flambe`;
+      if (!existsSync(backup)) writeFileSync(backup, readFileSync(path), {flag: 'wx', mode: 0o600});
+    }
+    atomicWrite(path, serialized);
+  }
+  return {root, hooksPath: path, unchanged, skillInstalled: !skillExists,
+    skillMatches: !skillExists || readFileSync(skillPath, 'utf8') === skill};
+}