kenaz 0.0.0-stage → 0.3.2

package/core/.formation/bifrost/HOOK_PARITY_VERIFICATION.md

@@ -0,0 +1,241 @@
+# Bifrost Hook Parity — Lifecycle Verification Matrix
+
+**Task**: TASK_1231  
+**Status**: Completion gate for the Bifrost hook parity series (TASK_1226–TASK_1232)  
+**Date**: 2026-04-17  
+
+This document defines the evidence required to close the Bifrost hook parity project.
+Each target lifecycle event must show positive firing evidence AND a documented failure
+signal for the missing-hook case. Resemblance at the architectural level is not
+sufficient — event-level proof is required.
+
+---
+
+## 1. Lifecycle Parity Matrix
+
+| # | Event | Owner File | Trigger Condition | Dispatch Mechanism | Canonical Payload Reference |
+|---|-------|-----------|-------------------|-------------------|----------------------------|
+| 1 | SessionStart | `session.js` | After `writeSignal()`, before `launchRelay()` spawns relay | `handleHookEvent(normalizeSessionStart())` via `require()` | `BIFROST_HOOK_LIFECYCLE.SessionStart` (task-bridge.js) |
+| 2 | UserPromptSubmit | `session.js` | After prompt assembly, before `relay.stdin.write(prompt)` | `handleHookEvent(normalizeUserPromptSubmit(prompt))` via `require()` | `BIFROST_HOOK_LIFECYCLE.UserPromptSubmit` (task-bridge.js) |
+| 3 | PreToolUse | `openai/relay.js` | Inside `translateEvent()`, after tool_id assignment, before `emit(tool_use)` | `handleHookEvent(normalizeToolEvent('PreToolUse', ...))` via `require()` | `BIFROST_HOOK_LIFECYCLE.PreToolUse` (task-bridge.js) |
+| 4 | PostToolUse | `openai/relay.js` | Inside `translateEvent()`, after `emitToolResult()` (or after `emit(tool_use)` when no result) | `handleHookEvent(normalizeToolEvent('PostToolUse', ...))` via `require()` | `BIFROST_HOOK_LIFECYCLE.PostToolUse` (task-bridge.js) |
+| 5 | Stop | `session.js` | In `relay.on('close')`, before reflex feedback block | `handleHookEvent(normalizeStop(code))` via `require()` | `BIFROST_HOOK_LIFECYCLE.Stop` (task-bridge.js) |
+
+**Dispatch mechanism across all events**: `require()` + `handleHookEvent()` (in-process, synchronous require, async call). NOT stdin-pipe. CGDD_EDGES mandates in-process for latency reasons.
+
+---
+
+## 2. Event-Level Verification Paths
+
+### 2.1 SessionStart
+
+**Files involved**: `.formation/bifrost/session.js` (lines ~368–388)
+
+**Positive firing check**:
+- Run: `node .formation/bifrost/session.js --specialist Ansuz --adapter openai 2>&1 | head -20`
+- **Expected stderr artifact**: `[bifrost] hook fired: SessionStart | specialist=Ansuz | session_id=null`
+- **Payload proof**: `hook_event_name === 'SessionStart'`, `started_at` is ISO-8601 timestamp, `sessionStartedAt` module-level variable is set (verified by Stop.started_at being non-null)
+- **Code evidence**: session.js line where `sessionStartedAt = ssPayload.started_at` precedes `dispatchBifrostHook('SessionStart', ssPayload)`
+
+**Missing-hook failure signal**:
+- If `dispatchBifrostHook('SessionStart', ssPayload)` call is absent: no `[bifrost] hook fired: SessionStart` line on stderr
+- `sessionStartedAt` will remain `null`, causing `Stop.started_at = null` — detectable by inspecting Stop payload
+- `task-bridge.handleHookEvent` is never called for SessionStart — `[bifrost] SessionStart hook error:` will NOT appear (silence indicates absence, not success)
+
+**Distinguishing from prompt injection**:
+- Hook fires from code path at line `dispatchBifrostHook('SessionStart', ssPayload)` — before any relay process is spawned
+- A prompt injector would need to execute code before the relay spawn, which is not possible via Codex output or stdin content
+- Timestamp of SessionStart `started_at` is set before `launchRelay()` — if the relay hasn't started yet, the timestamp proves the hook fired from the launcher, not from relay output
+
+**Distinguishing from stream resemblance**:
+- Stream-json events are emitted by relay.js on stdout; SessionStart is dispatched by session.js on stderr before relay is spawned
+- No stream-json event type corresponds to SessionStart — it has no Claude Code stream equivalent
+- Relay stdout is `inherit` (not captured by session.js), so relay output cannot trigger session.js hook calls
+
+---
+
+### 2.2 UserPromptSubmit
+
+**Files involved**: `.formation/bifrost/session.js` (line ~226)
+
+**Positive firing check**:
+- **Expected stderr artifact**: `[bifrost] hook fired: UserPromptSubmit | specialist=Ansuz | session_id=null`
+- **Payload proof**: `hook_event_name === 'UserPromptSubmit'`, `prompt` alias present (required by `maybeEmitReminder()`), `user_prompt` matches assembled prompt text
+- **Secondary observable**: if prompt contains planning keywords (e.g. "plan", "design", "implement"), `maybeEmitReminder()` emits a `system_reminder` block to stdout before relay receives the prompt — this is a downstream consumer side-effect that proves hook fired and was processed
+
+**Missing-hook failure signal**:
+- No `[bifrost] hook fired: UserPromptSubmit` line on stderr
+- `maybeEmitReminder()` never fires → no system-reminder output for planning prompts (detectable by observing stdout with a planning keyword in the prompt)
+- `relay.stdin.write(prompt)` executes regardless — relay starts normally — so missing hook is silent from relay's perspective
+
+**Distinguishing from prompt injection**:
+- Hook fires from `launchRelay()` code path, after `spawn()` but before `relay.stdin.write(prompt)` — the relay process is alive but has not yet received input
+- A Codex output-based injector cannot fire this hook — relay hasn't sent anything to Codex yet
+- The prompt string in the payload originates from `assemblePrompt()` (execSync output), not from relay stdout or stdin — injection via relay stream is structurally impossible here
+
+**Distinguishing from transcript replay**:
+- UserPromptSubmit fires exactly once per session.js invocation — not once per replay of a saved transcript
+- If replaying relay.js stdout logs manually, handleHookEvent is not called — only live relay.js execution calls dispatchBifrostHook
+
+---
+
+### 2.3 PreToolUse
+
+**Files involved**: `.formation/bifrost/openai/relay.js` (translateEvent, command_execution/file_edit/file_read/mcp_tool_call branches)
+
+**Supported tool classes**: `Bash` (command_execution), `Edit` (file_edit), `Read` (file_read), `mcp__<server>__<tool>` (mcp_tool_call)
+
+**Positive firing check**:
+- **Code evidence**: Each tool branch calls `dispatchBifrostHook('PreToolUse', ...)` BEFORE `emit(tool_use)` — confirmed by code reading at relay.js lines ~183, ~210, ~236, ~267
+- **Observable artifact**: relay.js `dispatchBifrostHook()` does NOT log success to stderr (unlike session.js). The only direct observable is an error line: `[relay] PreToolUse hook async error: ...`
+- **Indirect observable**: `capturedThreadId` is set in `thread.started` branch before any item.completed fires — if session_id in PreToolUse payload is non-null, it proves the hook wiring reaches into relay scope
+- **Ordering proof**: stream-json output sequence shows `tool_use` AFTER the hook dispatch call site — if tool_use appears in the stream, PreToolUse was already dispatched (because emit() call follows dispatchBifrostHook())
+
+**Missing-hook failure signal**:
+- If `dispatchBifrostHook('PreToolUse', ...)` is removed from a tool branch: `emit(tool_use)` still fires (downstream sees no change), `handleHookEvent` is not called for that tool class
+- PostToolUse may still fire for same tool if its call is retained — partial parity is a failure state
+- For TaskCreate/TaskUpdate hooks: PostToolUse is the active consumer; missing PreToolUse alone does not break task sync, but breaks the ordering invariant
+
+**Distinguishing from prompt injection**:
+- Dispatch occurs inside `translateEvent()` which is called only from `codex.stdout.on('data')` — requires live Codex JSONL output
+- A prompt injector inside the Codex context cannot call `dispatchBifrostHook()` in relay.js — hooks are called from relay's Node.js process, not from Codex's context
+- Codex output is parsed JSON (JSONL); PreToolUse fires from the parsed event type field (`event.item.type`), not from any text content — injecting text into Codex output that looks like tool use will not trigger the hook unless it's valid JSONL with the exact type field
+
+**Distinguishing from stream translation resemblance**:
+- PreToolUse fires BEFORE `emit(tool_use)` — the stream has not yet received the tool_use event when the hook fires
+- A system that only watches the stream output (stream translation) would observe `tool_use` AFTER the hook fires — causality is inverted if you derive hook firing from stream presence
+- The hook payload includes `tool_id` (relay-assigned unique id) which is generated at hook dispatch time, not read from the stream
+
+---
+
+### 2.4 PostToolUse
+
+**Files involved**: `.formation/bifrost/openai/relay.js` (after emitToolResult in each tool branch)
+
+**Positive firing check**:
+- **Code evidence**: Each tool branch calls `dispatchBifrostHook('PostToolUse', ...)` AFTER `emitToolResult()` — confirmed at relay.js lines ~203, ~229, ~255, ~289
+- **PostToolUse always fires**: even when `emitToolResult()` branch is skipped (e.g., no output present for command_execution), PostToolUse still fires — this is the PreToolUse/PostToolUse pairing invariant
+- **Active consumer observable**: `handleHookEvent()` in task-bridge.js routes `PostToolUse` to `createLinked()` (TaskCreate) and `syncStatus()` (TaskUpdate) — observable side-effect: task state changes in `.kenaz/tasks/` when Codex uses task-related tools
+- **Ordering proof**: PostToolUse payload includes `tool_response` field; PreToolUse payload for same `tool_id` does not — if you capture payloads in sequence, the presence of `tool_response` in the later payload confirms ordering
+
+**Missing-hook failure signal**:
+- If PostToolUse dispatch is removed: `task-bridge.createLinked()` and `syncStatus()` never fire — task creation/update via Codex sessions is silently broken
+- TaskCreate/TaskUpdate via Codex will appear to work (Codex edits files directly) but the hook-based sync path is dead
+- No stderr error unless hook itself throws — absence of task sync is the primary failure signal
+
+**Distinguishing from stream relay resemblance**:
+- PostToolUse fires AFTER `emitToolResult()` which emits the tool_result stream event — the stream is ahead of the hook fire
+- A stream-relay system reading stdout cannot trigger PostToolUse — it fires from relay.js code, not from parsing its own output
+- `tool_response` in PostToolUse payload comes from Codex's JSONL event (`event.item.output`, `.result`, `.content`, `.error`) — not from the emitted tool_result JSON
+
+---
+
+### 2.5 Stop
+
+**Files involved**: `.formation/bifrost/session.js` (relay.on('close') handler, lines ~233–238)
+
+**Positive firing check**:
+- **Expected stderr artifact**: `[bifrost] hook fired: Stop | specialist=Ansuz | session_id=null`
+- **Payload proof**: `hook_event_name === 'Stop'`, `ended_at` is ISO-8601 (non-null always), `started_at` is the value captured at SessionStart (`sessionStartedAt`)
+- **Ordering proof**: Stop fires before the reflex feedback block (logger/executor calls) — if Stop's stderr trace appears before `[bifrost] Reflex feedback logged`, ordering is correct
+- **Known limitation**: `total_cost_usd`, `num_turns`, `input_tokens`, `output_tokens` are always 0 — relay stdout is `inherit` (not piped), so the `turn.completed` result event from relay cannot be captured. This is documented and expected behavior, not a failure.
+
+**Missing-hook failure signal**:
+- If Stop dispatch is removed from `relay.on('close')`: no `[bifrost] hook fired: Stop` stderr line
+- `started_at` in any future session tracking will be null (since Stop is the event that would close session records)
+- Reflex feedback still fires (it follows the Stop dispatch call in the code) — so reflex is not a proxy for Stop
+
+**Distinguishing from prompt injection**:
+- Stop fires in `relay.on('close')` — a Node.js process event, not triggered by content
+- No content from Codex, relay stdout, or relay stderr can trigger `relay.on('close')` — only actual relay process termination does
+- `exit_code` in Stop payload comes from the OS process exit code, not from any content field
+
+**Distinguishing from transcript replay**:
+- Stop fires once per relay close event — not once per line of a replayed transcript
+- `sessionStartedAt` cross-dependency: if Stop fires but `sessionStartedAt` is null, it means SessionStart hook was not dispatched this session (structural wiring failure, not transcript replay)
+
+---
+
+## 3. Regression Coverage Table
+
+| Event | Positive Check Method | Positive Evidence Artifact | Missing-Hook Failure Signal | Notes |
+|-------|----------------------|---------------------------|----------------------------|-------|
+| SessionStart | Run session.js, grep stderr | `[bifrost] hook fired: SessionStart \| specialist=...` | No stderr trace; Stop.started_at=null | session.js logs success on stderr |
+| UserPromptSubmit | Run session.js with planning keyword | `[bifrost] hook fired: UserPromptSubmit \| specialist=...` + system-reminder on stdout | No stderr trace; no system-reminder even for planning prompts | session.js logs success on stderr |
+| PreToolUse | Run Codex session with tool use; check ordering | tool_use in stream AFTER dispatchBifrostHook() call site (code order); no error on stderr | No code-level evidence; PostToolUse pairing broken | relay.js silent on success — code order is the proof |
+| PostToolUse | Trigger TaskCreate/TaskUpdate via Codex; observe task state | Task created/updated in `.kenaz/tasks/` matching Codex intent | Task sync broken silently; no stderr error | Active consumer (createLinked/syncStatus) is the observable |
+| Stop | Run session.js to completion, grep stderr | `[bifrost] hook fired: Stop \| specialist=...` before reflex feedback lines | No stderr trace | session.js logs success on stderr |
+
+---
+
+## 4. Distinguishing True Hook Firing from False Confidence
+
+### 4.1 Prompt Injection
+
+**Definition**: An LLM output or injected context string that causes a system to believe a hook fired by mimicking hook output format or hook side-effects.
+
+**Why it cannot produce false positives in Bifrost hooks**:
+- Bifrost hooks fire from code paths in Node.js processes (session.js, relay.js) — not from parsing LLM output text
+- `dispatchBifrostHook()` is a function call in source code, not a conditional triggered by output content
+- The only way for a Codex output to trigger a hook is if it produces valid JSONL with the exact event type expected by `translateEvent()` — and even then, the hook fires from relay.js Node.js code, not from "inside" Codex
+
+**Test**: Inject a string `"[bifrost] hook fired: PreToolUse"` into Codex output. Result: relay.js will log `[relay] non-json: ...` (non-JSON line), translateEvent is not called, and no hook fires.
+
+### 4.2 Stream Relay Resemblance
+
+**Definition**: A downstream consumer mistaking stream-json events (tool_use, tool_result, result) for hook dispatch evidence because the formats look similar.
+
+**Why it causes false confidence without this matrix**:
+- relay.js emits `tool_use` events in the stream-json format — these look like Claude Code's tool events
+- Without knowing that PreToolUse fires BEFORE `emit(tool_use)`, one might assume tool_use presence = hook fired
+- The stream-json result event (type=result) looks like it could be the Stop trigger — but Stop fires from `relay.on('close')`, not from the result event
+
+**True indicator**: Hook dispatch call site in code is BEFORE or AFTER the stream emit call (depending on event). Causality is source-code-verified, not stream-observed.
+
+### 4.3 Transcript Replay
+
+**Definition**: Running an archived relay.js stdout log through a consumer that calls `translateEvent()` — or simply reading saved stream-json and concluding hooks fired.
+
+**Why it does not produce true hook fires**:
+- Hooks fire from `dispatchBifrostHook()` calls inside `translateEvent()` — if `translateEvent()` is called from a replay, hooks DO fire
+- This is the ONE legitimate risk: if someone replays a saved JSONL transcript through relay.js, hooks fire again for each replayed item
+- Mitigation: session_id (capturedThreadId) will be the original session's thread_id — a duplicate session_id signals replay vs. live session
+- For session.js hooks (SessionStart/UserPromptSubmit/Stop): these fire from process launch/close — a transcript replay of stream-json output does not re-invoke session.js
+
+---
+
+## 5. Parity Completion Gate
+
+The Bifrost hook parity project (TASK_1226–TASK_1232) is NOT closed until the following conditions are met:
+
+| Condition | Status | Verification Path |
+|-----------|--------|------------------|
+| SessionStart fires from session.js after writeSignal() | ✅ Implemented (TASK_1228) | grep stderr for `hook fired: SessionStart` |
+| UserPromptSubmit fires before relay.stdin.write() | ✅ Implemented (TASK_1228) | grep stderr for `hook fired: UserPromptSubmit` |
+| PreToolUse fires for Bash, Edit, Read, mcp__* | ✅ Implemented (TASK_1229) | code order: dispatchBifrostHook before emit in each branch |
+| PostToolUse fires after emitToolResult for all tool classes | ✅ Implemented (TASK_1229) | task sync side-effect; PostToolUse always paired with PreToolUse |
+| Stop fires in relay.on('close') before reflex feedback | ✅ Implemented (TASK_1230) | grep stderr for `hook fired: Stop` before `Reflex feedback` |
+| SessionStart fires from launch.js (interactive path) | ✅ Implemented (TASK_1230) | separate launch.js dispatchBifrostHook call |
+| Stop fires from launch.js (interactive path) | ✅ Implemented (TASK_1230) | launch.js codex.on('close') handler |
+| All events use in-process require() dispatch (not stdin-pipe) | ✅ Verified | CGDD_EDGES mandate; session.js and relay.js both use require() |
+| Hook failures never crash session or relay | ✅ Verified | both dispatchBifrostHook implementations catch all errors |
+
+**Open limitations (documented, not blocking)**:
+- relay.js `dispatchBifrostHook` does NOT log successful fires to stderr — PreToolUse/PostToolUse success is only observable via code order and downstream side-effects
+- Stop metrics (total_cost_usd, num_turns, tokens) are always 0 because relay stdout is `inherit` — piping relay stdout would break the passthrough to parent but would enable cost capture (CGDD documents this as acceptable)
+- SIGINT/SIGTERM handlers in session.js and launch.js do NOT fire Stop — signal handlers are synchronous and session may not have started
+
+---
+
+## 6. Evidence Artifacts by File
+
+| File | Hook Dispatch Call Sites | Observable Evidence |
+|------|-------------------------|---------------------|
+| `.formation/bifrost/session.js` | `dispatchBifrostHook('SessionStart', ...)` after writeSignal; `dispatchBifrostHook('UserPromptSubmit', ...)` in launchRelay(); `dispatchBifrostHook('Stop', ...)` in relay.on('close') | stderr: `[bifrost] hook fired: <event>` for each |
+| `.formation/bifrost/openai/relay.js` | `dispatchBifrostHook('PreToolUse', ...)` before emit; `dispatchBifrostHook('PostToolUse', ...)` after emitToolResult in 4 tool branches | task sync side-effects; no success stderr |
+| `.formation/bifrost/launch.js` | `dispatchBifrostHook('SessionStart', ...)` after writeOverride(); `dispatchBifrostHook('Stop', ...)` in codex.on('close') | stderr: `[bifrost] hook fired: <event>` |
+| `.specialist/tools/task-bridge.js` | `BIFROST_HOOK_LIFECYCLE` contract; `handleHookEvent()` consumer | maybeEmitReminder() for UserPromptSubmit; createLinked/syncStatus for PostToolUse |
+
+---
+
+*Generated by TASK_1231 (QA completion gate). All implementation verified against actual source code, not design intent.*

package/core/.formation/bifrost/README.md

@@ -0,0 +1,71 @@
+# Bifrost interactive Ansuz boot
+
+The interactive Codex launcher follows the lightweight startup used by Claude's
+`/Ansuz`: Ansuz defaults to the **elixir** persona and **fast** boot. The launcher
+uses the existing `ansuz-boot-fast.js` context banner instead of asking the agent
+to execute the Phase 0 ceremony. This change covers interactive
+`.formation/bifrost/launch.js`; headless dispatch and Agent Hub launches keep their
+existing contracts.
+
+Run these commands from the Kenaz core repository:
+
+```sh
+node .formation/bifrost/launch.js --specialist Ansuz
+node .formation/bifrost/launch.js --specialist Ansuz --full
+node .formation/bifrost/launch.js --specialist Ansuz --depth kernel
+```
+
+| Selection | Persona | Initialization |
+| --- | --- | --- |
+| Ansuz, no boot flags | elixir | fast context banner |
+| Ansuz, `--depth elixir` | elixir | fast context banner |
+| Ansuz, `--full` | kernel unless a depth is supplied | full Phase 0 checklist |
+| Ansuz, `--depth kernel` | kernel | full Phase 0 checklist |
+| Other specialists | kernel unless a depth is supplied | existing full behavior |
+
+Fast boot does not require ritual markers, rewritten mirrors, or Phase 0 gate
+entry/exit. The final bootstrap policy explicitly takes precedence over older
+Phase 0 ceremony wording inside the persona. It does not waive task tracking,
+scope, verification, or merge authorization.
+
+## Synapse availability
+
+The launcher probes MCP with a bounded timeout. In fast Ansuz mode, an offline,
+invalid, or incomplete response produces an explicit unavailable status and lets
+the session start for **read-only** local inspection and analysis. Recall must
+not be reported as successful. State-changing execution and work requiring the
+unavailable service remain deferred until the required checks can run.
+
+Explicit full mode and other specialists retain their MCP prerequisite. Starting
+in fast mode does not imply that the full ceremony can complete offline. The
+fast context banner can update its usual local session bookkeeping; read-only
+refers to the agent's task execution while the required service is unavailable.
+
+## Project and session boundaries
+
+Use `--project <absolute-path>` to bind a sub-project; the launcher passes the
+selected project to the boot command. `KENAZ_PROJECT_PATH` remains the fallback
+when no project flag is supplied.
+
+The launcher writes `AGENTS.override.md` when starting a new interactive session.
+Changes to the launcher do not rewrite a session already in progress. Do not run
+a second live launcher just to test the new instructions.
+
+The bootstrap text used by the launcher and by `sync.js` is shared in
+`shared/ansuz-boot-policy.js`. `AGENTS.md` is generated from `CLAUDE.md` and this
+translator; change the source policy instead of independently editing its guard.
+
+## Verification
+
+```sh
+node --test .formation/bifrost/shared/ansuz-boot-policy.test.js .formation/bifrost/launch.test.js
+```
+
+These focused tests exercise boot selection, generated instructions and MCP
+response handling with local fixtures/mocks. They must not launch Codex, run its
+setup, or replace the live `AGENTS.override.md` or user configuration.
+
+This stage does not change Phase 1-11 approval rules, verification outcomes,
+merge permissions, subagent routing, or cognitive reward scoring. Those changes
+need separate outcome-based evaluation; passing boot tests is not evidence that
+a shorter end-to-end workflow has equal task success.

package/core/.formation/bifrost/codex-doctor.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+// codex-doctor.js -- TASK_2379. Codex parity helpers: /kenaz custom prompt (same plugins/kenaz/scripts
+// as Claude), hook trust detection, delivery_mode. Honors CODEX_HOME (tests use a temp one).
+//   node codex-doctor.js [--install-prompts]      exit 1 when hooks are missing/untrusted
+const fs = require('fs');
+const path = require('path');
+
+const CORE = path.resolve(__dirname, '..', '..');
+const SHIM_REL = '.formation/bifrost/openai/codex-hook-shim.js';
+const EVENTS = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart', 'Stop'];
+const snake = (ev) => ev.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+const codexHome = () => process.env.CODEX_HOME
+  ? path.resolve(process.env.CODEX_HOME)
+  : path.join(process.env.USERPROFILE || process.env.HOME || '', '.codex');
+
+// One /kenaz prompt -> the single implementation (kenaz-mode.js; `ygg` is delegated by it to ygg.js).
+function promptText(core) {
+  const script = path.join(core || CORE, 'plugins', 'kenaz', 'scripts', 'kenaz-mode.js').split('\\').join('/');
+  return '---\ndescription: Kenaz mode (off|assist|full|status|init) or Yggdrasil (ygg join|status|leave)\nargument-hint: off|assist|full|status|init|ygg\n---\n'
+    + 'Run exactly this shell command from the current project directory and report its output, nothing else:\n\n'
+    + '`node "' + script + '" $ARGUMENTS`\n\n'
+    + 'With no argument it prints the current mode. Modes: full = everything; assist = silent bookkeeping only; off = every Kenaz hook exits immediately.\n';
+}
+
+// Codex >= ~0.15x dropped custom prompts (/prompts:x) for skills ($x); write both so old and new CLIs work.
+function skillText(core) {
+  const script = path.join(core || CORE, 'plugins', 'kenaz', 'scripts', 'kenaz-mode.js').split('\\').join('/');
+  return '---\nname: "kenaz"\ndescription: "Kenaz mode (off|assist|full|status|init) or Yggdrasil (ygg join|status|leave). Use only when the user invokes $kenaz."\n---\n\n'
+    + 'Run exactly this shell command from the current project directory, appending the words the user wrote after $kenaz (none = print the current mode), and report its output, nothing else:\n\n'
+    + '`node "' + script + '" <words after $kenaz>`\n\n'
+    + '`init` and `ygg ...` talk to kenaz-server on http://127.0.0.1:18080. The sandbox blocks network, so run the command with network access (request escalated permissions); otherwise it reports the server as unreachable even when it is running.\n\n'
+    + 'Modes: full = everything; assist = silent bookkeeping only; off = every Kenaz hook exits immediately.\n';
+}
+
+function writeIfChanged(f, text) {
+  if (fs.existsSync(f) && fs.readFileSync(f, 'utf8') === text) return 'unchanged';
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, text);
+  return 'written';
+}
+
+function installPrompts(core) {
+  const f = path.join(codexHome(), 'prompts', 'kenaz.md');
+  const skill = path.join(codexHome(), 'skills', 'kenaz', 'SKILL.md');
+  const a = writeIfChanged(f, promptText(core));
+  const b = writeIfChanged(skill, skillText(core));
+  return { file: f, skill, action: a === 'unchanged' && b === 'unchanged' ? 'unchanged' : 'written' };
+}
+
+// Per event: is our shim registered, and does codex hold a trusted_hash for it (hooks.state)?
+function hookTrust(configText) {
+  if (configText === undefined) {
+    try { configText = fs.readFileSync(path.join(codexHome(), 'config.toml'), 'utf8'); } catch { configText = ''; }
+  }
+  const text = configText.replace(/\\/g, '/');
+  const out = {};
+  for (const ev of EVENTS) out[ev] = { registered: false, trusted: false, pull: false };
+  const group = {}, handler = {};
+  let cur = null, g = 0, h = 0;
+  for (const line of text.split(/\r?\n/)) {
+    const gm = line.match(/^\s*\[\[hooks\.(\w+)\]\]/);
+    const hm = line.match(/^\s*\[\[hooks\.(\w+)\.hooks\]\]/);
+    if (gm) { const ev = gm[1]; group[ev] = (group[ev] === undefined ? -1 : group[ev]) + 1; handler[ev] = -1; cur = null; continue; }
+    if (hm) { const ev = hm[1]; handler[ev] = (handler[ev] === undefined ? -1 : handler[ev]) + 1; g = group[ev] || 0; h = handler[ev]; cur = ev; continue; }
+    if (/^\s*\[/.test(line)) { cur = null; continue; }
+    if (cur && out[cur] && line.includes(SHIM_REL)) {
+      out[cur].registered = true; out[cur].pull = /--pull\b/.test(line);
+      out[cur].key = snake(cur) + ':' + g + ':' + h;
+    }
+  }
+  for (const e of EVENTS) {
+    if (!out[e].key) continue;
+    const re = new RegExp('^\\s*\\[hooks\\.state\\.[\'"][^\\n]*:' + out[e].key + '[\'"]\\]\\s*\\n(?:[^\\[]*\\n)?\\s*trusted_hash\\s*=', 'm');
+    out[e].trusted = re.test(text);
+  }
+  return out;
+}
+
+// Same vocabulary TASK_2380 puts on /api/peer/status: push (app-server) | pull-on-prompt | none.
+// From config alone only pull-on-prompt vs none can be told; "push" is reported by the live session registry.
+function deliveryMode(trust) {
+  const u = trust.UserPromptSubmit;
+  return u.registered && u.trusted && u.pull ? 'pull-on-prompt' : 'none';
+}
+
+function diagnose() {
+  const trust = hookTrust();
+  const notes = [];
+  const unreg = EVENTS.filter((e) => !trust[e].registered);
+  const untrusted = EVENTS.filter((e) => trust[e].registered && !trust[e].trusted);
+  if (unreg.length) notes.push('Kenaz hooks not registered for: ' + unreg.join(', ') + '. Run: node .formation/bifrost/setup-codex.js');
+  if (untrusted.length) notes.push('Kenaz hooks registered but NOT trusted (' + untrusted.join(', ') + '); codex does not run them. Open codex, type /hooks, and trust the kenaz entries (re-trust after any change to the hook command).');
+  if (trust.UserPromptSubmit.registered && !trust.UserPromptSubmit.pull) notes.push('UserPromptSubmit hook lacks --pull, so independently opened codex sessions receive no peer mail. Remove the kenaz hook blocks from config.toml and re-run setup-codex.js.');
+  return { trust, delivery_mode: deliveryMode(trust), ok: notes.length === 0, notes };
+}
+
+module.exports = { promptText, skillText, installPrompts, hookTrust, deliveryMode, diagnose, SHIM_REL, EVENTS };
+
+if (require.main === module) {
+  if (process.argv.includes('--install-prompts')) console.log(JSON.stringify(installPrompts()));
+  const d = diagnose();
+  console.log('codex delivery_mode: ' + d.delivery_mode);
+  d.notes.forEach((n) => console.log('- ' + n));
+  process.exit(d.ok ? 0 : 1);
+}

package/core/.formation/bifrost/codex-doctor.test.js

@@ -0,0 +1,51 @@
+'use strict';
+// node --test .formation/bifrost/codex-doctor.test.js   (temp CODEX_HOME only; never the real ~/.codex)
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const D = require('./codex-doctor');
+
+const SHIM = path.join(__dirname, 'openai', 'codex-hook-shim.js');
+const cfg = (pull, trusted) => `[[hooks.UserPromptSubmit]]\n\n[[hooks.UserPromptSubmit.hooks]]\ntype = "command"\ncommand = 'node "C:/x/${D.SHIM_REL}"${pull ? ' --pull' : ''}'\n`
+  + (trusted ? `\n[hooks.state]\n\n[hooks.state.'C:\\Users\\u\\.codex\\config.toml:user_prompt_submit:0:0']\ntrusted_hash = "sha256:abc"\n` : '');
+
+test('untrusted hook is detected; trusted+pull gives pull-on-prompt', () => {
+  assert.strictEqual(D.hookTrust(cfg(true, false)).UserPromptSubmit.trusted, false);
+  assert.strictEqual(D.deliveryMode(D.hookTrust(cfg(true, false))), 'none');
+  const t = D.hookTrust(cfg(true, true));
+  assert.ok(t.UserPromptSubmit.registered && t.UserPromptSubmit.trusted);
+  assert.strictEqual(D.deliveryMode(t), 'pull-on-prompt');
+  assert.strictEqual(D.deliveryMode(D.hookTrust(cfg(false, true))), 'none'); // control: no --pull
+});
+
+test('installPrompts writes one /kenaz prompt pointing at kenaz-mode.js, idempotent', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cx-'));
+  process.env.CODEX_HOME = home;
+  assert.strictEqual(D.installPrompts().action, 'written');
+  assert.strictEqual(D.installPrompts().action, 'unchanged');
+  const t = fs.readFileSync(path.join(home, 'prompts', 'kenaz.md'), 'utf8');
+  assert.match(t, /plugins\/kenaz\/scripts\/kenaz-mode\.js" \$ARGUMENTS/);
+  const sk = fs.readFileSync(path.join(home, 'skills', 'kenaz', 'SKILL.md'), 'utf8'); // codex 0.15x+: skills ($kenaz), not prompts
+  assert.match(sk, /^---\nname: "kenaz"\n/);
+  assert.match(sk, /plugins\/kenaz\/scripts\/kenaz-mode\.js"/);
+  delete process.env.CODEX_HOME;
+});
+
+test('shim honours Kenaz mode: off silent, full control still runs', () => {
+  const run = (mode) => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cxp-'));
+    fs.mkdirSync(path.join(dir, '.kenaz'));
+    fs.writeFileSync(path.join(dir, '.kenaz', 'kenaz.yaml'), 'mode: ' + mode + '\n');
+    return spawnSync(process.execPath, [SHIM], {
+      input: JSON.stringify({ hook_event_name: 'SessionStart', cwd: dir }), encoding: 'utf8',
+      env: { ...process.env, KENAZ_MODE: '', KENAZ_PEER_PULL: '0' },
+    });
+  };
+  const off = run('off'), full = run('full');
+  assert.strictEqual(off.status, 0);
+  assert.strictEqual(off.stderr.includes('event='), false);
+  assert.ok(full.stderr.includes('event=SessionStart')); // control: hook does run when not off
+});