@dsh-cc/plugin-cc-codex-bridge 0.8.1

package/scripts/codex-rescue-run.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * §3.1 launcher for the codex-rescue-bridge.
+ *
+ *   codex-rescue-run.mjs [--last] -- <single-line prompt>
+ *   codex-rescue-run.mjs [--last] --prompt-file <path>
+ *
+ * Redirects CODEX_HOME to a per-cwd shadow home under the canonical tmpdir
+ * (§3.1 steps 1–4, scripts/lib/home.mjs), resolves and validates the Codex
+ * CLI, spawns `codex exec --sandbox danger-full-access ... -` with the prompt
+ * on stdin, and prints last-message.txt at the end.
+ */
+import { spawn } from 'node:child_process'
+import {
+  closeSync,
+  constants as fsConstants,
+  existsSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import os from 'node:os'
+import path from 'node:path'
+import { parseArgv } from './lib/argv.mjs'
+import { acquireLock, prepareHome, syncCredentials } from './lib/home.mjs'
+
+const USAGE =
+  'usage: codex-rescue-run.mjs [--last] -- <single-line prompt>\n' +
+  '       codex-rescue-run.mjs [--last] --prompt-file <path>'
+
+const die = (msg, code = 1) => {
+  const e = new Error(`codex-rescue: ${msg}`)
+  e.exitCode = code
+  throw e
+}
+
+/** Canonicalized outer writable roots: {cwd, tmpdir, /tmp} (§3.1 step 6). */
+function writableRoots() {
+  const roots = []
+  for (const p of [process.cwd(), os.tmpdir(), '/tmp']) {
+    try {
+      roots.push(realpathSync(p))
+    } catch {
+      /* absent root — nothing to confine against */
+    }
+  }
+  return roots
+}
+
+const outsideRoots = (p, roots) => !roots.some((r) => p === r || p.startsWith(r + path.sep))
+
+function resolveCodex(roots) {
+  for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
+    if (!dir) continue
+    let real
+    try {
+      real = realpathSync(path.join(dir, 'codex'))
+    } catch {
+      continue
+    }
+    // The executed binary must sit outside every canonicalized writable
+    // root: nothing the model can write may become the CLI (§3.1 step 6).
+    if (!outsideRoots(real, roots)) continue
+    return real
+  }
+  die('codex CLI not found on PATH outside the writable roots')
+}
+
+const PROMPT_CAP = 256 * 1024
+
+/**
+ * --prompt-file (§3.1 step 5): O_NOFOLLOW open, fstat regular-file, read
+ * from THAT same fd with the byte cap. The check→open ancestor-swap race is
+ * the §4 accepted residual — this channel is hygiene-only (prompt text the
+ * model could already read and inline itself), data egress into a networked
+ * model run, not an egress gate.
+ */
+function readPromptFile(p) {
+  let fd
+  try {
+    fd = openSync(p, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW)
+  } catch (e) {
+    die(`prompt-file unreadable: ${e.message}`)
+  }
+  try {
+    if (!fstatSync(fd).isFile()) die('prompt-file is not a regular file')
+    if (fstatSync(fd).size > PROMPT_CAP) die(`prompt-file exceeds the ${PROMPT_CAP}-byte cap`)
+    return readFileSync(fd).toString('utf8')
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/** Spawn codex with the prompt on a piped stdin, written then closed. */
+function runCodex(codex, args, env, promptText) {
+  return new Promise((resolve) => {
+    const child = spawn(codex, args, { env, stdio: ['pipe', 'inherit', 'inherit'] })
+    // Write the full prompt then CLOSE stdin — the EOF is the prompt
+    // terminator (§5 write/close EOF path). Child stdout/stderr inherit;
+    // CODEX_HOME lives only in this child env object, process.env is never
+    // mutated.
+    child.stdin.end(promptText)
+    child.on('error', (e) => {
+      console.error(`codex-rescue: spawn failed: ${e.message}`)
+      resolve(1) // never throw from an event callback — the finally must run
+    })
+    child.on('close', (code) => resolve(code ?? 1))
+  })
+}
+
+async function main() {
+  if (process.platform === 'win32') {
+    // The design's probes (§2) targeted POSIX; fail loud instead of guessing.
+    die('unsupported platform win32')
+  }
+
+  const roots = writableRoots()
+
+  // Self-assert at startup (§3.1 step 6, critic F1 belt): the interpreter
+  // must sit outside every writable root — one line of defense-in-depth
+  // against a mismatched/PATH-swapped node.
+  const selfNode = realpathSync(process.execPath)
+  if (!outsideRoots(selfNode, roots)) {
+    die('node interpreter sits inside a canonicalized writable root')
+  }
+
+  // Parse own argv with the shared grammar. Real argv has no shell quoting
+  // left: map each arg to { text, expansion: false }.
+  const launcherPath = realpathSync(fileURLToPath(import.meta.url))
+  const words = [
+    { text: selfNode, expansion: false },
+    { text: launcherPath, expansion: false },
+    ...process.argv.slice(2).map((a) => ({ text: a, expansion: false })),
+  ]
+  const parsed = parseArgv(words, { node: selfNode, launcher: launcherPath })
+  if (!parsed.ok) die(`invalid invocation (${parsed.reason})\n${USAGE}`, 2)
+  const { last, prompt } = parsed.value
+
+  const { H } = prepareHome({ cwd: process.cwd(), tmpdir: os.tmpdir() })
+  const releaseLock = acquireLock(H)
+  try {
+    syncCredentials(H)
+    const codex = resolveCodex(roots)
+    const promptText =
+      prompt.kind === 'inline' ? prompt.text : readPromptFile(prompt.path)
+
+    const args = [
+      'exec',
+      '--sandbox',
+      'danger-full-access',
+      '--cd',
+      realpathSync(process.cwd()),
+      '-o',
+      path.join(H, 'last-message.txt'),
+    ]
+    if (last) args.push('resume', '--last')
+    // The literal `-` selects stdin on BOTH shapes (fresh exec and
+    // `resume --last`, per the 0.153.4 help text): prompt content is always
+    // stdin data, so leading-dash prompts are never re-parsed as flags.
+    args.push('-')
+
+    const code = await runCodex(codex, args, { ...process.env, CODEX_HOME: H }, promptText)
+
+    const outFile = path.join(H, 'last-message.txt')
+    if (existsSync(outFile)) process.stdout.write(readFileSync(outFile))
+    return code
+  } finally {
+    releaseLock()
+  }
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code
+  },
+  (e) => {
+    console.error(e?.message ?? e)
+    process.exitCode = e?.exitCode ?? 1
+  },
+)

package/scripts/lib/argv.mjs

@@ -0,0 +1,368 @@
+/**
+ * §3.2-d pinned argv grammar for the codex-rescue-bridge (§5: one shared
+ * parser source for matcher and launcher; the exported FIXTURES table is
+ * the single fixture suite PR-2's hook tests reuse).
+ *
+ *   invocation := NODE LAUNCHER [--last] prompt
+ *   prompt     := '--prompt-file' PATH | '--' SINGLE_LINE_NONEMPTY_PROMPT
+ *
+ * Rules:
+ *   - NODE and LAUNCHER are expansion-free literal tokens byte-equal to the
+ *     registration-time canonical paths (a symlink literal, a tilde/glob/$VAR
+ *     expansion, or a PATH-resolved name never byte-equals a canonical
+ *     absolute literal — indirection dies here).
+ *   - `--last` appears at most once, only in the slot shown.
+ *   - the positional prompt is a single literal token, never empty, no
+ *     newline, and MAY start with `-` (it reaches Codex via stdin, so it is
+ *     data, never a flag).
+ *   - PATH for --prompt-file is non-empty; containment is checked at match
+ *     time by the PR-2 hook, not here.
+ *   - unknown shapes fail closed with a machine-readable `reason`.
+ */
+import { lexCommand } from './lexer.mjs'
+
+/** Example canonical anchor pair used by the shared fixture table. */
+export const CANONICAL_NODE = '/usr/local/bin/node'
+export const CANONICAL_LAUNCHER = '/opt/dsh-cc/cc-codex-bridge/scripts/codex-rescue-run.mjs'
+
+const fail = (reason) => ({ ok: false, layer: 'argv', reason })
+const ok = (value) => ({ ok: true, layer: 'argv', value })
+
+/**
+ * Parse a lexer-resolved argv (words with { text, expansion }) against the
+ * pinned grammar. `node`/`launcher` are the byte-pinned canonical anchors.
+ */
+export function parseArgv(argv, { node, launcher }) {
+  if (argv.length < 2) return fail('missing-anchor')
+  if (argv[0].expansion) return fail('expansion-in-argv0')
+  if (argv[1].expansion) return fail('expansion-in-argv1')
+  if (argv[0].text !== node) return fail('argv0-byte-mismatch')
+  if (argv[1].text !== launcher) return fail('argv1-byte-mismatch')
+  let i = 2
+  let last = false
+  if (argv[i] !== undefined && argv[i].text === '--last') {
+    last = true
+    i++
+  }
+  const rest = argv.slice(i)
+  if (rest.length === 0) return fail('missing-prompt')
+  if (rest[0].text === '--prompt-file') {
+    if (rest.length < 2 || rest[1].text === '') return fail('missing-prompt-file-path')
+    if (rest.length > 2) return fail('trailing-arguments')
+    return ok({ last, prompt: { kind: 'prompt-file', path: rest[1].text } })
+  }
+  if (rest[0].text !== '--') return fail('unexpected-token')
+  if (rest.length < 2) return fail('missing-prompt')
+  if (rest.length > 2) return fail('trailing-arguments')
+  const prompt = rest[1].text
+  if (prompt === '') return fail('empty-prompt')
+  if (prompt.includes('\n')) return fail('prompt-newline')
+  return ok({ last, prompt: { kind: 'inline', text: prompt } })
+}
+
+/**
+ * Full matcher pipeline: lex the raw bash command to exactly one simple
+ * command (§3.2-a), then pin its argv to the grammar (§3.2-d).
+ */
+export function matchInvocation(raw, { node = CANONICAL_NODE, launcher = CANONICAL_LAUNCHER } = {}) {
+  const lex = lexCommand(raw)
+  if (!lex.ok) return lex
+  return parseArgv(lex.argv, { node, launcher })
+}
+
+/**
+ * Shared fixture table (§5 one-shared-parser-source rule). Every row runs
+ * through matchInvocation; positive rows pin the normalized parse, negative
+ * rows carry `reason` = the violated rule. `layer` documents which layer
+ * rejects (or accepts) the row; lexer-layer rows fail regardless of anchors.
+ */
+export const FIXTURES = [
+  // ---- positive: pinned normalized shapes ----
+  {
+    name: 'inline prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "review the failing spec"`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: 'review the failing spec' } },
+  },
+  {
+    name: 'inline prompt with --last in its only slot',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last -- "continue the rescue"`,
+    ok: true,
+    value: { last: true, prompt: { kind: 'inline', text: 'continue the rescue' } },
+  },
+  {
+    name: 'prompt-file form',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file /tmp/prompts/p.txt`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'prompt-file', path: '/tmp/prompts/p.txt' } },
+  },
+  {
+    name: 'prompt-file form with --last',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last --prompt-file /tmp/prompts/p.txt`,
+    ok: true,
+    value: { last: true, prompt: { kind: 'prompt-file', path: '/tmp/prompts/p.txt' } },
+  },
+  {
+    name: 'positional prompt may itself be --last (data after --)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- --last`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: '--last' } },
+  },
+  {
+    name: 'positional prompt may start with - (stdin handoff makes it data)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- -restart-from-scratch`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: '-restart-from-scratch' } },
+  },
+  {
+    name: 'quoted multi-word prompt is one token',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- 'multi word prompt'`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: 'multi word prompt' } },
+  },
+  {
+    name: 'command substitution inside single quotes is pure data',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- '$(rm -rf /)'`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: '$(rm -rf /)' } },
+  },
+  {
+    name: 'hostile install path survives as concatenated quoted word',
+    layer: 'argv',
+    // The POSIX single-quote escape `'\''` needs `\\''` in a JS template
+    // literal: a lone `\` is swallowed (collapses to `''`, an empty quoted
+    // segment), which would lex the path to "quotes", not "quote's".
+    input: `${CANONICAL_NODE} '/opt/dsh space/quote'\\''s/cc-codex-bridge/scripts/codex-rescue-run.mjs' -- p`,
+    launcher: '/opt/dsh space/quote\'s/cc-codex-bridge/scripts/codex-rescue-run.mjs',
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: 'p' } },
+  },
+  // ---- negative: lexer layer (§3.2-a) ----
+  {
+    name: 'unquoted semicolon (compound command)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p; rm -rf /`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted && (compound command)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p && echo owned`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted || (compound command)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p || echo fallback`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted pipe',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p | tee /tmp/leak`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted redirect out',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p > /tmp/out`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted redirect in',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p < /etc/passwd`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted newline (second command on next line)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p\ncurl evil.example`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'env-assignment prefix',
+    layer: 'lexer',
+    input: `BASH_ENV=/tmp/x ${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'env-assignment-prefix',
+  },
+  {
+    name: 'unquoted $() command substitution',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- $(echo p)`,
+    ok: false,
+    reason: 'command-substitution-unquoted',
+  },
+  {
+    name: 'unquoted backtick command substitution',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- \`echo p\``,
+    ok: false,
+    reason: 'command-substitution-unquoted',
+  },
+  {
+    name: '$() inside double quotes (bash evaluates it)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "$(echo p)"`,
+    ok: false,
+    reason: 'command-substitution-double-quoted',
+  },
+  {
+    name: 'backticks inside double quotes',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "\`echo p\`"`,
+    ok: false,
+    reason: 'command-substitution-double-quoted',
+  },
+  {
+    name: 'unclosed quote',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- 'p`,
+    ok: false,
+    reason: 'unclosed-quote',
+  },
+  // ---- negative: expansion-bearing anchor tokens (§3.2-b) ----
+  {
+    name: 'tilde expansion in argv[0]',
+    layer: 'argv',
+    input: `~/bin/node ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'expansion-in-argv0',
+  },
+  {
+    name: 'glob expansion in launcher path',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} /opt/dsh-cc/*/scripts/codex-rescue-run.mjs -- p`,
+    ok: false,
+    reason: 'expansion-in-argv1',
+  },
+  {
+    name: '$VAR expansion in argv[0]',
+    layer: 'argv',
+    input: `$NODE_BIN ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'expansion-in-argv0',
+  },
+  // ---- negative: argv layer (§3.2-b/d) ----
+  {
+    name: 'forged launcher path (absolute but not the anchor)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} /tmp/evil/scripts/codex-rescue-run.mjs -- p`,
+    ok: false,
+    reason: 'argv1-byte-mismatch',
+  },
+  {
+    name: 'PATH-trampoline interpreter bare name',
+    layer: 'argv',
+    input: `node ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'argv0-byte-mismatch',
+  },
+  {
+    name: 'symlink-literal anchor (bytes differ from the canonical launcher)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} /tmp/link-to-codex-rescue-run.mjs -- p`,
+    ok: false,
+    reason: 'argv1-byte-mismatch',
+  },
+  {
+    name: 'duplicate --last',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last --last -- p`,
+    ok: false,
+    reason: 'unexpected-token',
+  },
+  {
+    name: 'misplaced --last after the prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p --last`,
+    ok: false,
+    reason: 'trailing-arguments',
+  },
+  {
+    name: 'misplaced --last alone (no prompt)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last`,
+    ok: false,
+    reason: 'missing-prompt',
+  },
+  {
+    name: 'no prompt at all',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER}`,
+    ok: false,
+    reason: 'missing-prompt',
+  },
+  {
+    name: 'empty positional prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- ""`,
+    ok: false,
+    reason: 'empty-prompt',
+  },
+  {
+    name: '-- with no prompt token',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --`,
+    ok: false,
+    reason: 'missing-prompt',
+  },
+  {
+    name: 'newline-bearing positional prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "line one\nline two"`,
+    ok: false,
+    reason: 'prompt-newline',
+  },
+  {
+    name: 'unknown flag before the prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --json -- p`,
+    ok: false,
+    reason: 'unexpected-token',
+  },
+  {
+    name: '--prompt-file without a path',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file`,
+    ok: false,
+    reason: 'missing-prompt-file-path',
+  },
+  {
+    name: '--prompt-file with empty path',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file ""`,
+    ok: false,
+    reason: 'missing-prompt-file-path',
+  },
+  {
+    name: '--prompt-file with trailing arguments',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file /tmp/p.txt -- q`,
+    ok: false,
+    reason: 'trailing-arguments',
+  },
+  {
+    name: 'positional prompt with trailing extra argument',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p extra`,
+    ok: false,
+    reason: 'trailing-arguments',
+  },
+]

package/scripts/lib/canonical.mjs

@@ -0,0 +1,99 @@
+/**
+ * canonical.mjs — the single arming/derivation source for the
+ * codex-rescue-bridge hooks (plan §9 S3, §5 anchor-lint "one source").
+ *
+ * Every hook (PreToolUse allow, SessionStart context) derives the canonical
+ * anchor pair and the refusal/arming verdict through THIS module only; the
+ * specs pin that no hook re-implements the derivation.
+ *
+ * Canonical anchors (§3.1): `realpath(process.execPath)` of the calling hook
+ * process plus the realpath of the sibling `scripts/codex-rescue-run.mjs`
+ * resolved from the hook's own `import.meta.url`. Refusal set (§3.2-e): the
+ * canonicalized session cwd plus the canonical tmp roots, unrealpathable
+ * entries skipped.
+ */
+import { realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+export const safeReal = (p) => {
+  try {
+    return realpathSync(p)
+  } catch {
+    return null
+  }
+}
+
+/** Containment against canonicalized roots (path-boundary aware). */
+export const inside = (p, roots) => p !== null && roots.some((root) => p === root || p.startsWith(root + '/'))
+
+/** POSIX single-quote escape: bytes inside the quotes are pure data. */
+export const posixSingleQuote = (s) => `'` + String(s).replaceAll(`'`, `'\\''`) + `'`
+
+/**
+ * Derive the canonical anchor pair from the CALLING hook's own location
+ * (pass that hook's `import.meta.url`). Returns null when either anchor is
+ * unrealpathable.
+ */
+export function deriveAnchors(hookUrl) {
+  const node = safeReal(process.execPath)
+  const launcher = safeReal(fileURLToPath(new URL('../scripts/codex-rescue-run.mjs', hookUrl)))
+  if (node === null || launcher === null) return null
+  return { node, launcher }
+}
+
+/** Refusal set (§3.2-e): session cwd plus canonical tmp roots. */
+export function refusalRoots(cwdRaw) {
+  return [safeReal(cwdRaw), safeReal(tmpdir()), safeReal('/tmp')].filter((p) => p !== null)
+}
+
+/**
+ * Arming predicate with machine-readable reasons. `hookUrl` is the calling
+ * hook's `import.meta.url`; `env` defaults to `process.env` (the hooks pass
+ * nothing and inherit it).
+ */
+export function arming(cwdRaw, { hookUrl, env = process.env } = {}) {
+  const anchors = deriveAnchors(hookUrl)
+  if (anchors === null) return { armed: false, reason: 'anchor-unrealpathable' }
+  const cwd = safeReal(typeof cwdRaw === 'string' && cwdRaw !== '' ? cwdRaw : process.cwd())
+  if (cwd === null) return { armed: false, reason: 'anchor-unrealpathable' }
+  const roots = refusalRoots(cwd)
+  if (inside(anchors.node, roots) || inside(anchors.launcher, roots)) {
+    return { armed: false, reason: 'anchor-under-writable-root' }
+  }
+  if (env.BASH_ENV) return { armed: false, reason: 'bash-env-set' }
+  if (env.ENV) return { armed: false, reason: 'env-set' }
+  return { armed: true, node: anchors.node, launcher: anchors.launcher, cwd }
+}
+
+/**
+ * The ARMED additionalContext block: the exact canonical invocation to type,
+ * both anchor paths POSIX single-quote-escaped so hostile install paths
+ * survive as pure data.
+ */
+export function armedText({ node, launcher }) {
+  const q = posixSingleQuote
+  return [
+    'cc-codex-bridge: the Codex rescue lane is ARMED. Use EXACTLY this canonical invocation for a rescue:',
+    `${q(node)} ${q(launcher)} -- 'the rescue prompt, single line'`,
+    'For a multi-line prompt, write the text to a file inside this workspace (or the canonical tmpdir), then run:',
+    `${q(node)} ${q(launcher)} --prompt-file 'the prompt file path'`,
+    'Add --last ONLY when the user explicitly asks to continue the previous rescue (it resumes the most recent rescue thread).',
+  ].join('\n')
+}
+
+/** The REFUSED additionalContext block: machine reason in plain words. */
+export function refusedText(reason) {
+  const words =
+    reason === 'anchor-under-writable-root'
+      ? "the plugin's launcher sits under this session's workspace, expected in dsh-cc repo dev sessions"
+      : reason === 'bash-env-set'
+        ? 'the ambient BASH_ENV variable is non-empty (shell-function takeover defense)'
+        : reason === 'env-set'
+          ? 'the ambient ENV variable is non-empty (shell-function takeover defense)'
+          : 'the plugin\'s canonical anchors could not be resolved in this environment'
+  return [
+    `cc-codex-bridge: the Codex rescue lane is NOT armed (reason: ${reason} — ${words}).`,
+    'Codex rescue today goes through the normal, approval-requiring path; do NOT guess or construct the bridge\'s canonical bash invocation manually.',
+  ].join('\n')
+}