@bragi-gmbh/codebus 1.2.0

package/dist/kit/graph-publish.mjs

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+/**
+ * graph-publish.mjs — SP-B build-ticket "Lane 2" CI-caller rollout kit.
+ *
+ * Runs in the reusable workflow (.github/workflows/graphify-publish.yml) on
+ * every push-to-main. Implements the spec's two non-negotiables:
+ *   - SHA-identity: graph_head_report is ALWAYS called first, before the
+ *     build even starts, so the hub learns about a new tip even if the
+ *     build subsequently fails.
+ *   - Honest failure: a failed build or failed validation EXITS NON-ZERO.
+ *     This deliberately does NOT follow the older scripts/graphify-ci.mjs
+ *     pattern of "exit 0 to not block CI" — that pattern predates the 0050
+ *     graph-knowledge freshness contract, where a build failure is supposed
+ *     to leave the repo honestly STALE (via the already-reported head)
+ *     rather than pretend nothing happened. A red CI check is the correct,
+ *     visible signal.
+ *
+ * Round-1 review (PR #33, CB-MSG-005318) fixes applied here:
+ *   1 BLOCKER  — no more SUPABASE_SERVICE_ROLE_KEY / GRAPH_REPO_ID. This
+ *     script now authenticates with a per-repo, per-scope bearer token
+ *     (GRAPH_INGEST_TOKEN) via the anon-executable *_with_token RPCs
+ *     (0059_graph_ingest_tokens.sql) — repo_id is resolved server-side FROM
+ *     the token, never supplied by this script. A compromised token can
+ *     only ever act as the one repo_id/scope it was minted for.
+ *   3 MAJOR    — every subprocess call uses execFileSync with an argument
+ *     ARRAY (never string interpolation into a shell command), and
+ *     GRAPHIFY_REPO_ROOT is resolved + verified to stay under
+ *     GITHUB_WORKSPACE (or cwd, for local runs) before anything touches it
+ *     — an absolute path or a `..`-escaping value is rejected outright.
+ *   9 MAJOR    — no residual service-role-shaped credential lives in this
+ *     script's env at all now; SUPABASE_ANON_KEY is not sensitive (it is
+ *     the public client key).
+ *
+ * Round-15 review finding 1 (CONFIRMED, MAJOR): round-13's fix
+ * (.github/workflows/graphify-publish.yml checking the caller out into a
+ * dedicated `repo/` subdirectory, a SIBLING of `.codebus-kit/`, specifically
+ * so graphify could never traverse into the kit) was bypassable through
+ * GRAPHIFY_REPO_ROOT itself — this script validated the resolved root
+ * against GITHUB_WORKSPACE (the shared ANCESTOR of both `repo/` and
+ * `.codebus-kit/`), not against `repo/` itself, so `GRAPHIFY_REPO_ROOT=..`
+ * resolved right back to the workspace root (still "inside" that wider
+ * boundary) and `../.codebus-kit` resolved directly onto the kit —
+ * silently recreating the exact traversal the round-13 fix believed it had
+ * closed. Fixed with a SECOND, narrower boundary — GRAPHIFY_ROOT_BOUNDARY
+ * — that the workflow now sets to the caller's own `repo/` checkout
+ * directory; containment is checked against THAT, not GITHUB_WORKSPACE,
+ * and (a caller's own checkout is fully attacker-controlled content, so a
+ * planted symlink cannot be ruled out) using the REAL, symlink-resolved
+ * filesystem paths on both sides of the comparison, not merely the
+ * lexically-normalized ones `resolve()`/`relative()` alone produce.
+ *
+ * Usage:
+ *   node scripts/graph-publish.mjs
+ *
+ * Required env:
+ *   SUPABASE_URL, SUPABASE_ANON_KEY — the public API endpoint + anon key
+ *     (not sensitive; matches every other Supabase client in this repo).
+ *   GRAPH_INGEST_TOKEN — this repo's 'ingest'-scoped token, minted via
+ *     graph_ingest_token_mint by a workspace admin/curator and stored as a
+ *     GitHub Environment secret (see graphify-publish-codebus.yml).
+ *
+ * Optional env / flags:
+ *   GITHUB_SHA, GITHUB_RUN_ID, GITHUB_WORKFLOW_REF, GITHUB_REPOSITORY,
+ *   GITHUB_WORKSPACE — supplied automatically by GitHub Actions; falls back
+ *     to `git rev-parse HEAD` / cwd / synthetic values for local runs.
+ *   GRAPHIFY_REPO_ROOT — repo subdirectory to build, RELATIVE to
+ *     GITHUB_WORKSPACE (default: "."). Resolved and verified to stay inside
+ *     GRAPHIFY_ROOT_BOUNDARY (round-15 review finding 1) — never accept
+ *     this as an unvalidated absolute path.
+ *   GRAPHIFY_ROOT_BOUNDARY — the directory GRAPHIFY_REPO_ROOT must resolve
+ *     inside of (round-15 review finding 1); set by the reusable workflow
+ *     to the caller's own checkout directory (`repo/`), which is narrower
+ *     than — and a sibling of, never an ancestor shared with — `.codebus-
+ *     kit/`. Falls back to GITHUB_WORKSPACE (this script's original, wider
+ *     boundary) when unset, for backward compatibility with any caller or
+ *     local run that hasn't set it.
+ *   --artifact-path <file>   — skip running `graphify`, load this JSON file
+ *                              as the artifact instead (script-level testing
+ *                              against a fixture, per the build ticket).
+ *   --skip-build             — same effect, reads graphify-out/graph.json
+ *                              as-is without re-running graphify.
+ *   --dry-run                — do everything except the final
+ *                              graph_ingest_with_token call (still reports
+ *                              the head and still validates).
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve, relative, isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createClient } from "@supabase/supabase-js";
+
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(name);
+const opt = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+const DRY_RUN = flag("--dry-run");
+const SKIP_BUILD = flag("--skip-build") || !!opt("--artifact-path");
+const ARTIFACT_PATH_OVERRIDE = opt("--artifact-path");
+
+function die(msg) {
+  console.error(`FATAL: ${msg}`);
+  process.exit(1);
+}
+
+function section(title) {
+  console.log("");
+  console.log(`=== ${title} ===`);
+}
+
+// Round-1 review finding 3: GRAPHIFY_REPO_ROOT is a workflow_call INPUT —
+// resolve it against the checkout root and verify the result stays INSIDE
+// the allowed boundary before it ever reaches a subprocess argument or a
+// filesystem call. An absolute path or a `..`-escaping relative path is
+// rejected outright, not sanitized/best-effort-fixed.
+//
+// Round-15 review finding 1 (CONFIRMED, MAJOR): the boundary this function
+// checks against is DELIBERATELY narrower than GITHUB_WORKSPACE whenever
+// GRAPHIFY_ROOT_BOUNDARY is set (see the file header) — checking against
+// GITHUB_WORKSPACE alone let `GRAPHIFY_REPO_ROOT=..` resolve right back to
+// the workspace root (still "inside" that wider boundary) and
+// `../.codebus-kit` resolve directly onto the sibling kit checkout,
+// silently recreating the traversal round-13's directory-separation fix
+// believed it had closed. Exported for scripts/test/graph-publish.validate.
+// test.mjs (guarded below by the same import.meta.url check
+// scripts/graph-trust-sample.mjs already established, so importing this
+// module for that test does not itself run the CLI).
+// Throws a plain Error (never calls die()/process.exit itself) — this
+// keeps the function a pure, in-process-testable unit, matching the same
+// convention scripts/graph-trust-sample.mjs's own validateMinGradable()
+// already established (that one throws too, for the identical reason:
+// scripts/test/*.validate.test.mjs needs to assert a rejection without the
+// test runner's own process getting killed by a process.exit() inside the
+// function under test). main()'s own caller below converts any thrown
+// error from this function into the SAME "FATAL: <message>" die() output
+// as before this refactor — nothing about the CLI's actual observable
+// behavior (message text, exit code 1) changed, only that the failure is
+// now surfaced via a normal thrown Error rather than an in-function
+// process.exit().
+export function resolveRepoRoot() {
+  const workspaceRoot = process.env.GITHUB_WORKSPACE || process.cwd();
+  const boundaryRaw = process.env.GRAPHIFY_ROOT_BOUNDARY || workspaceRoot;
+  const raw = process.env.GRAPHIFY_REPO_ROOT || ".";
+  if (isAbsolute(raw)) {
+    throw new Error(`GRAPHIFY_REPO_ROOT must be a path relative to the checkout root, got an absolute path: ${raw}`);
+  }
+  const resolved = resolve(workspaceRoot, raw);
+
+  // Round-15 review finding 1: containment is checked against the REAL
+  // (symlink-resolved) filesystem paths on BOTH sides, not merely the
+  // lexically-normalized ones `resolve()`/`relative()` alone would compare
+  // — the caller's own checkout is fully attacker-controlled content, so a
+  // planted symlink that is lexically "inside" the boundary but actually
+  // points elsewhere on disk must not be trusted at face value.
+  let realResolved;
+  try {
+    realResolved = realpathSync(resolved);
+  } catch {
+    throw new Error(`GRAPHIFY_REPO_ROOT ("${raw}") resolves to a path that does not exist: ${resolved}`);
+  }
+  let realBoundary;
+  try {
+    realBoundary = realpathSync(boundaryRaw);
+  } catch {
+    throw new Error(`GRAPHIFY_ROOT_BOUNDARY does not exist: ${boundaryRaw}`);
+  }
+
+  const rel = relative(realBoundary, realResolved);
+  if (rel === "") return realResolved; // the boundary itself
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`GRAPHIFY_REPO_ROOT ("${raw}") resolves outside the allowed checkout boundary (${realBoundary}): ${realResolved}`);
+  }
+  return realResolved;
+}
+
+async function main() {
+  section("graph-publish: SP-B rollout-kit CI caller");
+
+  let repoRoot;
+  try {
+    repoRoot = resolveRepoRoot();
+  } catch (e) {
+    die(e.message);
+  }
+  const supabaseUrl = process.env.SUPABASE_URL;
+  const anonKey = process.env.SUPABASE_ANON_KEY;
+  const ingestToken = process.env.GRAPH_INGEST_TOKEN;
+
+  // Fail closed: every one of these is load-bearing. Missing config is
+  // refused, never silently skipped (house rule, sp-b-knowledge-layer.md
+  // §B.2 preamble).
+  if (!supabaseUrl) die("SUPABASE_URL is required");
+  if (!anonKey) die("SUPABASE_ANON_KEY is required");
+  if (!ingestToken) die("GRAPH_INGEST_TOKEN is required (this repo's ingest-scoped token — mint via graph_ingest_token_mint)");
+
+  let commitSha = process.env.GITHUB_SHA;
+  if (!commitSha) {
+    try {
+      commitSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf-8" }).trim();
+    } catch {
+      die("could not resolve commit sha (no GITHUB_SHA and `git rev-parse HEAD` failed)");
+    }
+  }
+  const runId = process.env.GITHUB_RUN_ID || `local-${Date.now()}`;
+  const workflowRef = process.env.GITHUB_WORKFLOW_REF || process.env.GITHUB_REPOSITORY || "local";
+
+  console.log(`repo root:    ${repoRoot}`);
+  console.log(`commit sha:   ${commitSha}`);
+  console.log(`run_id:       ${runId}`);
+  console.log(`workflow_ref: ${workflowRef}`);
+  console.log(`dry-run:      ${DRY_RUN}`);
+  console.log(`skip-build:   ${SKIP_BUILD}`);
+
+  const supabase = createClient(supabaseUrl, anonKey, { auth: { persistSession: false } });
+
+  // ── Step 1: report the head FIRST, unconditionally, before any build
+  // work happens. This is what makes freshness honest even when step 2
+  // fails below — the hub already knows main advanced. Token-scoped: no
+  // repo_id is sent, it's resolved server-side from GRAPH_INGEST_TOKEN.
+  section("Step 1: graph_head_report_with_token (authoritative tip, before build)");
+  {
+    const { error } = await supabase.rpc("graph_head_report_with_token", {
+      p_token: ingestToken,
+      p_sha: commitSha,
+      p_run_id: String(runId),
+    });
+    if (error) die(`graph_head_report_with_token failed: ${error.message} (nothing downstream can be trusted if the tip itself was never recorded)`);
+    console.log(`✓ head reported: sha=${commitSha}`);
+  }
+
+  // ── Step 2: build (unless testing against a fixture/existing artifact).
+  section("Step 2: graphify build");
+  const graphJsonPath = join(repoRoot, "graphify-out", "graph.json");
+  if (!SKIP_BUILD) {
+    try {
+      execFileSync("which", ["graphify"], { stdio: "ignore" });
+    } catch {
+      die("graphify command not found (install via: pip install graphifyy)");
+    }
+    try {
+      execFileSync("graphify", ["update", repoRoot, "--force"], { stdio: "inherit", cwd: repoRoot });
+      console.log("✓ graphify build succeeded");
+    } catch (err) {
+      // HONEST FAILURE: exit non-zero. The head was already reported in
+      // Step 1, so graph_status will correctly go STALE after grace
+      // instead of silently keeping last-good presented as current.
+      die(`graphify build failed (${err.message}). Head sha ${commitSha} was already reported — the repo will honestly go STALE after the configured grace period rather than silently serve a stale artifact as current.`);
+    }
+  } else {
+    console.log(`(--skip-build/--artifact-path given: not invoking graphify)`);
+  }
+
+  const artifactPath = ARTIFACT_PATH_OVERRIDE || graphJsonPath;
+  if (!existsSync(artifactPath)) {
+    die(`artifact not found at ${artifactPath}`);
+  }
+  let artifact;
+  try {
+    artifact = JSON.parse(readFileSync(artifactPath, "utf-8"));
+  } catch (err) {
+    die(`failed to parse artifact JSON at ${artifactPath}: ${err.message}`);
+  }
+  const nodeCount = artifact.nodes?.length ?? 0;
+  const edgeCount = (artifact.links ?? artifact.edges ?? []).length;
+  const hyperedgeCount = (artifact.hyperedges ?? artifact.graph?.hyperedges ?? []).length;
+  console.log(`artifact: ${artifactPath}`);
+  console.log(`  nodes=${nodeCount} edges=${edgeCount} hyperedges=${hyperedgeCount}`);
+
+  // ── Step 3: resolve the current vocab version (never hardcode — the
+  // vocabulary is the versioned artifact, per B.2.3). graph_vocab_current()
+  // is anon-executable (vocab is not repo-scoped/sensitive; SECURITY
+  // DEFINER bypasses the graph_vocab_read RLS policy's "any AUTHENTICATED
+  // agent" bar, which anon does not clear).
+  section("Step 3: resolve current vocab_version");
+  let vocabVersion;
+  {
+    const { data, error } = await supabase.rpc("graph_vocab_current");
+    if (error) die(`failed to resolve current vocab_version: ${error.message}`);
+    if (!data) die("no graph_vocab row has is_current=true — cannot publish without a current vocabulary version");
+    vocabVersion = data;
+    console.log(`✓ current vocab_version: ${vocabVersion}`);
+  }
+
+  // ── Step 4: pre-validate LOCALLY (same validation shape the ingest RPC
+  // itself uses — graph_ingest_validate_anon nests a call straight through
+  // to 0050's graph_ingest_validate, the exact function graph_ingest_artifact
+  // calls internally) so a schema problem is reported as a clearly-labeled
+  // VALIDATION failure, distinct from an INGEST failure, before we ever
+  // attempt to publish. Calling graph_ingest_validate DIRECTLY as anon does
+  // not work — it is a plain (non-definer) function, so its own internal
+  // graph_vocab read still runs under anon's insufficient privileges;
+  // graph_ingest_validate_anon is a thin SECURITY DEFINER wrapper added
+  // specifically so this pre-check needs no broader credential either.
+  section("Step 4: validate artifact against vocab (graph_ingest_validate_anon)");
+  {
+    const { error } = await supabase.rpc("graph_ingest_validate_anon", {
+      p_vocab_version: vocabVersion,
+      p_artifact: artifact,
+    });
+    if (error) die(`VALIDATION FAILED: ${error.message}`);
+    console.log("✓ artifact validates against the current vocabulary");
+  }
+
+  if (DRY_RUN) {
+    console.log("");
+    console.log("=== DRY-RUN: skipping graph_ingest_with_token ===");
+    process.exit(0);
+  }
+
+  // ── Step 5: publish. Atomic on the DB side: a rejection here leaves
+  // last-good serving completely untouched (0050's own guarantee), and
+  // (finding 2) the exact validated artifact is persisted content-addressed
+  // in the SAME transaction as promotion.
+  section("Step 5: graph_ingest_with_token (publish)");
+  {
+    const { data, error } = await supabase.rpc("graph_ingest_with_token", {
+      p_token: ingestToken,
+      p_source_sha: commitSha,
+      p_vocab_version: vocabVersion,
+      p_run_id: String(runId),
+      p_workflow_ref: workflowRef,
+      p_artifact: artifact,
+    });
+    if (error) die(`INGEST FAILED: ${error.message}`);
+
+    console.log(`status:    ${data.status}`);
+    console.log(`promoted:  ${data.promoted}`);
+    console.log(`version:   ${data.version_id}`);
+    console.log(`nodes/edges: ${data.node_count}/${data.edge_count}`);
+
+    if (data.status === "quarantined") {
+      console.log("");
+      console.log("⚠ QUARANTINED: this version was NOT promoted (poisoning-guard sanity delta tripped).");
+      console.log("  Last-good stays serving. A curator/owner must review before this can be promoted.");
+      console.log("  (This is a successful, honest CI run — the guard did its job — not a build failure.)");
+    } else if (data.status === "noop_already_ingested") {
+      console.log("");
+      console.log("(idempotent no-op: this sha was already ingested)");
+    } else if (data.promoted) {
+      console.log("");
+      console.log("✓ promoted to serving (artifact persisted content-addressed, finding 2)");
+    }
+  }
+
+  console.log("");
+  console.log("=== SUCCESS ===");
+}
+
+// Round-11 review finding (CONFIRMED, MAJOR): the previous check compared
+// `import.meta.url` (a properly percent-ENCODED URL — Node encodes spaces
+// as %20, '#' as %23, '%' as %25, and on Windows produces a
+// `file:///C:/...`-shaped URL) against `file://${process.argv[1]}`, a raw
+// filesystem path concatenated onto a `file://` prefix with NO encoding at
+// all. For any invocation path containing a space, '#', '%', or run on
+// Windows, the two strings can never be equal even when this IS the
+// directly-executed entry script — the guard silently evaluates false,
+// `main()` never runs, and the process exits 0 having done nothing. Since
+// `.github/workflows/graphify-publish.yml` invokes this exact script (via
+// the CLI's shipped `dist/kit/graph-publish.mjs` copy, or the checked-out
+// `.codebus-kit/scripts/graph-publish.mjs` copy) with `node <path>`, a
+// silent no-op here means `graph_head_report_with_token` is never called,
+// the build never runs, and validate/ingest never happen — while `codebus
+// repo connect --build` (cli/src/commands/repo.ts), which already minted
+// the token and transitioned pending -> ci_wired before spawning this
+// process, sees only the exit code (0) and falsely reports success. Fixed
+// by comparing two properly normalized URLs instead of a URL against a raw
+// path: `pathToFileURL(...).href` applies the SAME percent-encoding rules
+// `import.meta.url` itself was produced with (and produces the correct
+// `file:///C:/...` shape on Windows), so both sides of the comparison are
+// now in the same representation. `realpathSync` on `process.argv[1]`
+// first (symlink-resolved, matching this file's own
+// GRAPHIFY_ROOT_BOUNDARY containment check above, and
+// resolveTrustedGraphPublishScript's identical convention in
+// cli/src/commands/repo.ts) handles the case where the invoked path is a
+// symlink — Node's own ESM loader resolves `import.meta.url` to the
+// REAL underlying file, so comparing against the un-resolved argv[1] would
+// reintroduce an equivalent false-negative for a symlinked invocation.
+// Wrapped in a try/catch since `process.argv[1]` is not guaranteed to name
+// an existing path in every embedding context (e.g. `node -e`); any
+// failure there simply means "this is not a direct file invocation",
+// exactly like the string comparison it replaces.
+//
+// scripts/graph-trust-sample.mjs established the ORIGINAL (buggy) form of
+// this guard; fixed there too, identically, in the same round.
+let isMainModule = false;
+try {
+  isMainModule = pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
+} catch {
+  // process.argv[1] does not resolve to a real path — not a direct
+  // file invocation; isMainModule stays false, matching the old guard's
+  // behavior for the same case.
+}
+if (isMainModule) {
+  main().catch((err) => {
+    die(err.stack || err.message || String(err));
+  });
+}

package/dist/mail-latency.js

@@ -0,0 +1,120 @@
+// Shared by doctor.ts and checkin.ts (delivery gap #8): under Claude Code,
+// checkin deliberately skips auto-arming a watch window because the Stop hook
+// already surfaces mail at turn boundaries — but that hook is opt-in
+// (`codebus install claude`), identity-gated, and only fires at turn
+// boundaries. If NEITHER the Stop hook nor a live/recent watch window is
+// present, mail latency for that agent is genuinely unbounded: nothing pulls
+// new mail until a human happens to poll. Both doctor and checkin must flag
+// this loudly rather than silently assuming "checkin ran, so we're fine".
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { workspaceId } from "./client.js";
+export function stopHookInstalled() {
+    try {
+        const s = JSON.parse(readFileSync(join(homedir(), ".claude", "settings.json"), "utf8"));
+        return JSON.stringify(s?.hooks?.Stop ?? []).includes("codebus tick");
+    }
+    catch {
+        return false;
+    }
+}
+// RC3: Codex's native lifecycle-hooks engine (codex-rs/hooks; Feature::CodexHooks,
+// stage Stable, default_enabled true) is a genuine turn-boundary hook, not the
+// older fire-and-forget `notify` shim most blog posts describe. Its Stop event
+// carries the same `stop_hook_active` loop-guard field Claude Code's Stop hook
+// does, and a handler can return `{"decision":"block","reason":"..."}` on
+// stdout to feed `reason` back as the NEXT user prompt — verified against
+// codex-rs/hooks/src/events/stop.rs, which is functionally identical to Claude
+// Code's Stop-hook contract. `codebus install codex` wires exactly the same
+// `codebus tick --hook` command Claude's Stop hook runs into
+// ~/.codex/hooks.json (Stop event) — this checks whether that wiring is present.
+// A hook event is genuinely wired only when one of its groups carries a command
+// handler whose `command` is EXACTLY `cmd`. A substring match over the serialized
+// JSON (the earlier approach) is fooled by any unrelated hook whose description
+// or command merely CONTAINS the text — that both reports false coverage (checkin
+// skips its watch fallback, doctor claims bounded delivery) and makes the
+// installer refuse to add the real hook (ai-review finding). Shape of a hook
+// event: [ { hooks: [ { type: "command", command: "..." } ] } ].
+export function hookEventHasCommand(hookEvent, cmd) {
+    if (!Array.isArray(hookEvent))
+        return false;
+    return hookEvent.some((group) => !!group && typeof group === "object" && Array.isArray(group.hooks) &&
+        group.hooks.some((h) => !!h && typeof h === "object" &&
+            h.type === "command" &&
+            h.command === cmd));
+}
+export function codexHooksInstalled() {
+    try {
+        const s = JSON.parse(readFileSync(join(homedir(), ".codex", "hooks.json"), "utf8"));
+        return hookEventHasCommand(s?.hooks?.Stop, "codebus tick --hook");
+    }
+    catch {
+        return false;
+    }
+}
+// Review MAJOR finding #5: a Claude Stop hook being INSTALLED (present in
+// ~/.claude/settings.json) is a machine-wide fact — it says nothing about
+// whether THIS process is actually running inside a Claude Code session. The
+// hook only fires for turns Claude Code itself drives; a Codex session or a
+// plain shell in the same directory never triggers it no matter how it's
+// configured. `CLAUDECODE` is set by Claude Code itself for every session it
+// runs (already relied on by checkin.ts's auto-arm-watch branch) — the one
+// reliable signal that the hook could possibly apply to the current process.
+export function inClaudeCodeSession() {
+    return !!process.env.CLAUDECODE;
+}
+// Codex's analogue of CLAUDECODE: CODEX_THREAD_ID is injected by the Codex CLI
+// into every subprocess it spawns for the active thread — shell-tool calls and
+// hook commands alike (codex-rs/protocol/src/shell_environment.rs:
+// CODEX_THREAD_ID_ENV_VAR; codex-rs/core/src/exec_env.rs — "injected when a
+// thread id is provided, even when ..."). It is the one reliable signal that a
+// Codex Stop hook installed in ~/.codex/hooks.json could possibly be firing
+// FOR this process, exactly as CLAUDECODE is for Claude Code above.
+export function inCodexSession() {
+    return !!process.env.CODEX_THREAD_ID;
+}
+// Generous relative to the standing loop's own re-arm cadence (directives.ts
+// REARM: 280s) — a watch window arms itself well inside this before going stale.
+export const WATCH_ARM_FRESHNESS_MS = 10 * 60 * 1000;
+// Best-effort: `codebus watch` logs a session_log(kind='watch') row on arm
+// (0048). There is no durable "a process is still blocked in watch" truth
+// available from SQL, so freshness of the last arm is the closest signal.
+// Review MAJOR finding #5: scoped to the SELECTED workspace — an agent that
+// belongs to multiple workspaces previously had a watch armed in workspace A
+// count as coverage for workspace B, which it never watched.
+export async function watchRecentlyArmed(ctx, freshnessMs = WATCH_ARM_FRESHNESS_MS) {
+    try {
+        const ws = await workspaceId(ctx);
+        const { data } = await ctx.supabase
+            .from("session_log")
+            .select("created_at, agents!inner(slug)")
+            .eq("kind", "watch")
+            .eq("workspace_id", ws)
+            .eq("agents.slug", ctx.agentSlug)
+            .order("created_at", { ascending: false })
+            .limit(1);
+        const row = (data ?? [])[0];
+        if (!row)
+            return false;
+        return Date.now() - new Date(row.created_at).getTime() < freshnessMs;
+    }
+    catch {
+        return false;
+    }
+}
+// True delivery coverage for THIS process: either it's actually running
+// inside a Claude Code session with the Stop hook installed (the hook WILL
+// fire for it), or a watch window is live/recently armed for the selected
+// workspace. A hook merely being installed somewhere on the machine does not
+// count when the current process is Codex/a plain shell — that hook can
+// never fire for a process Claude Code isn't driving (review MAJOR finding #5).
+export async function hasDeliveryCoverage(ctx) {
+    const viaHook = (inClaudeCodeSession() && stopHookInstalled()) || (inCodexSession() && codexHooksInstalled());
+    const viaWatch = ctx ? await watchRecentlyArmed(ctx) : false;
+    return { ok: viaHook || viaWatch, viaHook, viaWatch };
+}
+export const MAIL_LATENCY_WARNING = "mail latency unbounded: no Stop hook installed (codebus install claude, or codebus install codex) and no watch " +
+    "armed (codebus watch --mine --first --timeout 280000). Without one of these, new mail sits until " +
+    "someone happens to poll — install the hook for your tool, or keep a watch window armed.";
+//# sourceMappingURL=mail-latency.js.map

package/dist/mail-latency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-latency.js","sourceRoot":"","sources":["../src/mail-latency.ts"],"names":[],"mappings":"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"}