@basou/cli 0.39.0 → 0.40.0

package/dist/index.js

@@ -699,7 +699,6 @@ async function writeFileDurable(targetPath, content) {
 // src/lib/context-channel.ts
 var CODEX_TARGET_PATH = join3(homedir(), ".codex", "AGENTS.md");
 var ORIENTATION_MARKERS = { start: ORIENTATION_START, end: ORIENTATION_END };
-var ORIENTATION_MANAGED_NOTE = "<!-- Managed by basou: 'basou refresh' regenerates everything between the BASOU:ORIENTATION markers with the workspace's current position. This block is transient \u2014 it changes every refresh; do not edit it. -->";
 function buildTargetBody(existing, block, markers) {
   const wrapped = `${markers.start}
 ${block}${markers.end}
@@ -772,19 +771,6 @@ async function removeMarkerBlock(opts) {
   await writeFileDurable(target, newBody);
   return { removed: true };
 }
-async function syncOrientationChannel(opts) {
-  assertNoMarkerLine(opts.body, ORIENTATION_MARKERS);
-  const block = `${ORIENTATION_MANAGED_NOTE}
-
-${opts.body.replace(/\s+$/, "")}
-`;
-  return syncMarkerBlock({
-    target: opts.target ?? CODEX_TARGET_PATH,
-    markers: ORIENTATION_MARKERS,
-    block,
-    ...opts.dryRun === true ? { dryRun: true } : {}
-  });
-}
 async function clearOrientationChannel(opts) {
   return removeMarkerBlock({
     target: opts.target ?? CODEX_TARGET_PATH,
@@ -798,29 +784,17 @@ async function clearOrientationChannel(opts) {
     ...opts.dryRun === true ? { dryRun: true } : {}
   });
 }
-async function renderOrientationToCodexChannel(opts) {
-  const body = await readMarkdownFile(opts.orientationPath);
-  if (body === null) return null;
-  const { action } = await syncOrientationChannel({
-    body,
-    ...opts.channelPath !== void 0 ? { target: opts.channelPath } : {}
-  });
-  return {
-    action,
-    line: `codex channel: orientation ${action} in ${opts.channelPath ?? "~/.codex/AGENTS.md"}`
-  };
-}
 
 // src/commands/channel.ts
 function registerChannelCommand(program2) {
   const channel = program2.command("channel").description(
-    "Manage the user-global context faces basou renders into \u2014 files every project's AI tool auto-loads (~/.codex/AGENTS.md)"
+    "Manage the user-global context faces an AI tool auto-loads for every project (~/.codex/AGENTS.md): remove what an earlier basou rendered there"
   );
   channel.command("clear").argument(
     "<face>",
     "the face to clear: `codex` (the basou:orientation block in ~/.codex/AGENTS.md)"
   ).description(
-    "Remove basou's block from a user-global context face, so no workspace's position is left in a file that another project's tool reads"
+    "Remove the orientation block an older basou rendered into a user-global context face, so no workspace's position is left in a file that another project's tool reads"
   ).option("--dry-run", "Report whether a block would be removed without writing").option("--json", "Output the result as JSON").option("--target <path>", "Override the target file (intended for tests)").option("-v, --verbose", "Show error causes").action(async (face, opts) => {
     await runChannelClear(face, opts);
   });
@@ -859,7 +833,7 @@ async function doRunChannelClear(face, options) {
     console.log(`[dry-run] Would remove the basou:orientation block from ${label}.`);
   } else {
     console.log(
-      `Removed the basou:orientation block from ${label}. Nothing basou wrote remains in that file; the next opted-in \`basou refresh\` renders it again.`
+      `Removed the basou:orientation block from ${label}. Nothing basou wrote remains in that file, and nothing renders it again.`
     );
   }
   return result;
@@ -2267,340 +2241,226 @@ async function assertWorkspaceInitialized4(basouRoot) {
 }
 
 // src/commands/hook.ts
-import { open as open2, readFile as readFile2, stat as stat3 } from "fs/promises";
-import { homedir as homedir5 } from "os";
-import { join as join7 } from "path";
+import { open as open2, readFile as readFile3, realpath as realpath2, stat as stat4 } from "fs/promises";
+import { homedir as homedir7 } from "os";
+import { join as join9 } from "path";
 import { fileURLToPath } from "url";
 import {
+  buildSessionStartHookCommand,
   buildStopHookCommand,
   DEFAULT_STOP_HOOK_MIN_EDITS,
   evaluateStopHook,
+  findBasouSessionStartHook,
   findBasouStopHookCommand,
+  ORIENTATION_END as ORIENTATION_END2,
+  ORIENTATION_START as ORIENTATION_START2,
+  parseMarkers as parseMarkers2,
+  readMarkdownFile as readMarkdownFile5,
+  removeSessionStartHook,
   removeStopHook,
+  upsertSessionStartHook,
   upsertStopHook
 } from "@basou/core";
-var MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
-function registerHookCommand(program2) {
-  const hook = program2.command("hook").description(
-    "Claude Code hook handlers (read a hook payload on stdin, emit hook JSON on stdout)"
-  );
-  hook.command("stop").description(
-    "Stop-hook: when a substantive session recorded no decisions or next step, emit a non-blocking nudge to capture them. Reads the Stop hook JSON payload on stdin; never blocks and never fails the session."
-  ).option(
-    "--min-edits <n>",
-    `Minimum file edits before nudging on edits alone (default ${DEFAULT_STOP_HOOK_MIN_EDITS})`
-  ).option(
-    "--block",
-    "Opt-in enforcement: hold the agent in-turn (decision:block) instead of a non-blocking reminder"
-  ).option(
-    "--require-review",
-    "Opt-in review gate: also remind when a session shipped substantive code (push / PR / merge) without recording a review"
-  ).addHelpText("after", HOOK_STOP_HELP).action(async (options) => {
-    const minEdits = parseMinEdits(options.minEdits);
-    await runHookStop({
-      ...minEdits !== void 0 ? { minEdits } : {},
-      ...options.block === true ? { block: true } : {},
-      ...options.requireReview === true ? { requireReview: true } : {}
-    });
-  });
-  hook.command("install").description(
-    "Register the Stop hook in ~/.claude/settings.json (reproducible, idempotent). Default is advisory capture-only; --block opts into in-turn enforcement, --require-review opts into the review gate."
-  ).option("--block", "Register the blocking (opt-in enforcement) form instead of advisory").option("--require-review", "Register with the opt-in review gate enabled").option("--min-edits <n>", "Pass a custom file-edit threshold to the registered hook").option("--settings <path>", "Override the settings.json path (intended for tests)").option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (opts) => {
-    await runHookInstall(opts);
-  });
-  hook.command("uninstall").description(
-    "Remove the basou Stop hook from ~/.claude/settings.json (leaves other hooks intact)"
-  ).option("--settings <path>", "Override the settings.json path (intended for tests)").option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (opts) => {
-    await runHookUninstall(opts);
-  });
-  hook.command("status").description("Report whether the basou Stop hook is registered, and in which mode").option("--settings <path>", "Override the settings.json path (intended for tests)").option("-v, --verbose", "Show error causes").action(async (opts) => {
-    await runHookStatus(opts);
-  });
-}
-var HOOK_STOP_HELP = `
-Register this Stop hook reproducibly with 'basou hook install' (it writes the
-correct node-path command into ~/.claude/settings.json). 'basou hook uninstall'
-removes it; 'basou hook status' reports whether it is registered.
-
-On every turn end basou inspects the session transcript. If the session did
-content-substantive work but ran no capture verb ('basou decision capture' /
-'decision record' / 'note'), it reminds the agent to record the why / next step.
-Substantive = EITHER >= ${DEFAULT_STOP_HOOK_MIN_EDITS} file edits (default) OR a free-form AskUserQuestion
-answer (an uncaptured conversational decision). Read-only Bash (ls / grep /
-git status) does NOT count.
-
-With --require-review (opt-in, 'basou hook install --require-review') it also
-reminds when the session SHIPPED substantive code (git push / git merge /
-gh pr create|merge) without recording a review ('basou review record'). This
-gate is off by default; when on, its reminder is composed into the same
-envelope as the capture reminder.
 
-By default the reminder is non-blocking: Claude sees it and may act on it or
-stop. With --block (opt-in enforcement, 'basou hook install --block') it instead
-returns decision:block, holding the agent in-turn to act on the reminder; the
-'stop_hook_active' flag and Claude Code's own loop prevention bound it to a
-single turn. Either way the hook fails open: a bad payload or unreadable
-transcript exits cleanly with no output.
-`;
-async function runHookStop(options, ctx = {}) {
-  try {
-    await doRunHookStop(options, ctx);
-  } catch {
-  }
-}
-async function doRunHookStop(options, ctx) {
-  const readStdin = ctx.readStdin ?? defaultReadStdin;
-  const readTranscript = ctx.readTranscript ?? readTranscriptBounded;
-  const write = ctx.write ?? ((text) => void process.stdout.write(text));
-  const raw = await readStdin();
-  if (raw.trim().length === 0) return;
-  let payload;
-  try {
-    payload = JSON.parse(raw);
-  } catch {
-    return;
-  }
-  if (typeof payload !== "object" || payload === null) return;
-  const fields = payload;
-  if (fields.stop_hook_active === true) return;
-  const transcriptPath = typeof fields.transcript_path === "string" ? fields.transcript_path : "";
-  if (transcriptPath.length === 0) return;
-  let transcript;
-  try {
-    transcript = await readTranscript(transcriptPath);
-  } catch {
-    return;
-  }
-  const records = parseTranscript(transcript);
-  const evaluation = evaluateStopHook({
-    records,
-    // stop_hook_active was already handled by the early return above.
-    stopHookActive: false,
-    ...options.minEdits !== void 0 ? { minEdits: options.minEdits } : {}
-  });
-  const parts = [];
-  if (evaluation.kind === "nudge") parts.push(evaluation.additionalContext);
-  if (options.requireReview === true && evaluation.review.fires) {
-    parts.push(evaluation.review.additionalContext);
-  }
-  if (parts.length === 0) return;
-  const reason = parts.join("\n\n");
-  const payloadJson = options.block === true ? JSON.stringify({ decision: "block", reason }) : JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "Stop",
-      additionalContext: reason
-    }
-  });
-  write(`${payloadJson}
-`);
-}
-function parseTranscript(transcript) {
-  const records = [];
-  for (const line of transcript.split(/\r?\n/)) {
-    if (line.trim().length === 0) continue;
-    try {
-      const parsed = JSON.parse(line);
-      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-        records.push(parsed);
-      }
-    } catch {
-    }
-  }
-  return records;
+// src/lib/codex-hook-trust.ts
+import { createHash } from "crypto";
+var CODEX_DEFAULT_CONTEXT_LIMIT = 2500;
+var CODEX_DEFAULT_TIMEOUT_SECONDS = 600;
+function commandHandlerFields(handler) {
+  if (handler.type !== "command" || typeof handler.command !== "string") return null;
+  const out = { command: handler.command };
+  if (typeof handler.timeout === "number") out.timeout = handler.timeout;
+  if (typeof handler.async === "boolean") out.async = handler.async;
+  if (typeof handler.statusMessage === "string") out.statusMessage = handler.statusMessage;
+  if (typeof handler.additionalContextLimit === "number")
+    out.additionalContextLimit = handler.additionalContextLimit;
+  return out;
 }
-async function defaultReadStdin() {
-  if (process.stdin.isTTY === true) return "";
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(chunk);
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (typeof value === "object" && value !== null) {
+    const src = value;
+    const out = {};
+    for (const key of Object.keys(src).sort()) out[key] = canonicalize(src[key]);
+    return out;
   }
-  return Buffer.concat(chunks).toString("utf8");
+  return value;
 }
-async function readTranscriptBounded(path, maxBytes = MAX_TRANSCRIPT_BYTES) {
-  const { size } = await stat3(path);
-  if (size <= maxBytes) return readFile2(path, "utf8");
-  const handle = await open2(path, "r");
-  try {
-    const buffer = Buffer.alloc(maxBytes);
-    const { bytesRead } = await handle.read(buffer, 0, maxBytes, size - maxBytes);
-    const text = buffer.subarray(0, bytesRead).toString("utf8");
-    const firstNewline = text.indexOf("\n");
-    return firstNewline >= 0 ? text.slice(firstNewline + 1) : text;
-  } finally {
-    await handle.close();
+function computeCodexHookIdentityHash(input) {
+  const h = input.handler;
+  const normalized = {
+    type: "command",
+    command: h.command,
+    timeout: Math.max(1, h.timeout ?? CODEX_DEFAULT_TIMEOUT_SECONDS),
+    async: h.async ?? false
+  };
+  if (h.statusMessage !== void 0) normalized.statusMessage = h.statusMessage;
+  if (h.additionalContextLimit !== void 0 && h.additionalContextLimit !== CODEX_DEFAULT_CONTEXT_LIMIT) {
+    normalized.additionalContextLimit = h.additionalContextLimit;
+  }
+  const identity = { event_name: input.eventKey, hooks: [normalized] };
+  if (input.matcher !== void 0) identity.matcher = input.matcher;
+  const blob = JSON.stringify(canonicalize(identity));
+  return `sha256:${createHash("sha256").update(blob, "utf8").digest("hex")}`;
+}
+function codexHookStateKey(hooksPath, eventKey, groupIndex, handlerIndex) {
+  return `${hooksPath}:${eventKey}:${groupIndex}:${handlerIndex}`;
+}
+function tomlBasicString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function stripTomlComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (quote !== null) {
+      if (ch === "\\" && quote === '"') i++;
+      else if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === "#") {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+function readCodexHookState(configToml, key) {
+  const basicHeader = `[hooks.state.${tomlBasicString(key)}]`;
+  const literalHeader = key.includes("'") ? null : `[hooks.state.'${key}']`;
+  const lines = configToml.split(/\r?\n/);
+  const start = lines.findIndex((raw) => {
+    const l = stripTomlComment(raw).trim();
+    return l === basicHeader || literalHeader !== null && l === literalHeader;
+  });
+  if (start < 0) {
+    const mentioned = lines.some((raw) => raw.includes("hooks.state") && raw.includes(key));
+    return mentioned ? { kind: "unreadable", detail: "config.toml names this hook in a shape basou cannot read" } : { kind: "absent" };
+  }
+  const state = {};
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = stripTomlComment(lines[i] ?? "").trim();
+    if (line.startsWith("[")) break;
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(.+)$/.exec(line);
+    if (m === null) continue;
+    const [, k, rawValue] = m;
+    const v = (rawValue ?? "").trim();
+    if (k === "trusted_hash") {
+      const basic = /^"((?:[^"\\]|\\.)*)"$/.exec(v);
+      const literal = /^'([^']*)'$/.exec(v);
+      if (basic?.[1] !== void 0) state.trustedHash = basic[1].replace(/\\(.)/g, "$1");
+      else if (literal?.[1] !== void 0) state.trustedHash = literal[1];
+      else return { kind: "unreadable", detail: "trusted_hash is not a quoted string" };
+    } else if (k === "enabled") {
+      if (v === "true") state.enabled = true;
+      else if (v === "false") state.enabled = false;
+      else return { kind: "unreadable", detail: "enabled is not a boolean" };
+    }
+  }
+  return { kind: "found", state };
+}
+function judgeCodexHookTrust(lookup, currentHash) {
+  if (lookup.kind === "unreadable") return { status: "unknown", detail: lookup.detail };
+  if (lookup.kind === "absent") return { status: "untrusted" };
+  const { state } = lookup;
+  if (state.enabled === false) return { status: "disabled" };
+  if (state.trustedHash === void 0) return { status: "untrusted" };
+  return state.trustedHash === currentHash ? { status: "trusted" } : { status: "modified" };
+}
+function describeCodexHookTrust(trust) {
+  switch (trust.status) {
+    case "trusted":
+      return "trusted by Codex";
+    case "untrusted":
+      return "not yet trusted by Codex (review pending \u2014 it is skipped until you trust it)";
+    case "modified":
+      return "Codex's trust record does not match what basou computes for the installed hook \u2014 the hook changed since it was trusted, or Codex changed its hashing (review it again in Codex; it is skipped until re-trusted)";
+    case "disabled":
+      return "disabled in the Codex config (enabled = false)";
+    case "unknown":
+      return `trust state unknown (${trust.detail})`;
   }
 }
-function parseMinEdits(raw) {
-  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
-  return Number(raw);
-}
-var DEFAULT_CLAUDE_SETTINGS_PATH = join7(homedir5(), ".claude", "settings.json");
-function resolveCliEntry() {
-  return fileURLToPath(import.meta.url);
+
+// src/commands/orient.ts
+import {
+  assertBasouRootSafe as assertBasouRootSafe7,
+  basouPaths as basouPaths8,
+  findErrorCode as findErrorCode6,
+  renderOrientation as renderOrientation2,
+  writeMarkdownFile as writeMarkdownFile4
+} from "@basou/core";
+
+// src/lib/hosts-config.ts
+import { homedir as homedir5 } from "os";
+import { isAbsolute as isAbsolute2, join as join7, resolve as resolve4 } from "path";
+import { readYamlFile as readYamlFile4 } from "@basou/core";
+var DEFAULT_HOSTS_CONFIG_PATH = join7(homedir5(), ".basou", "hosts.yaml");
+function expandTilde2(p) {
+  if (p === "~") return homedir5();
+  if (p.startsWith("~/")) return join7(homedir5(), p.slice(2));
+  return p;
 }
-function normalizeInstallOptions(raw) {
-  const out = {};
-  if (raw.block === true) out.block = true;
-  if (raw.requireReview === true) out.requireReview = true;
-  if (raw.settings !== void 0) out.settings = raw.settings;
-  if (raw.dryRun === true) out.dryRun = true;
-  if (raw.verbose === true) out.verbose = true;
-  if (raw.minEdits !== void 0) {
-    const parsed = parseMinEdits(raw.minEdits);
-    if (parsed === void 0) {
-      throw new Error("--min-edits must be a non-negative integer.");
-    }
-    out.minEdits = parsed;
-  }
-  return out;
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-async function readSettings(path) {
+async function loadHostsConfig(configPath = DEFAULT_HOSTS_CONFIG_PATH) {
   let raw;
   try {
-    raw = await readFile2(path, "utf8");
+    raw = await readYamlFile4(configPath);
   } catch (error) {
-    if (error instanceof Error && error.code === "ENOENT") {
-      return { raw: null, parsed: void 0 };
+    if (error instanceof Error && error.message === "YAML file not found") {
+      return null;
+    }
+    if (error instanceof Error && error.message === "Failed to parse YAML content") {
+      throw new Error("~/.basou/hosts.yaml is not valid YAML.");
     }
     throw error;
   }
-  if (raw.trim().length === 0) return { raw, parsed: void 0 };
-  try {
-    return { raw, parsed: JSON.parse(raw) };
-  } catch (error) {
-    throw new Error(
-      "The Claude settings.json is not valid JSON. Fix it (or remove it) and retry.",
-      {
-        cause: error
-      }
-    );
-  }
-}
-async function backupSettingsOnce(path, raw) {
-  if (raw === null) return;
-  const bak = `${path}.basou-bak`;
-  try {
-    await stat3(bak);
-    return;
-  } catch (error) {
-    if (!(error instanceof Error && error.code === "ENOENT")) throw error;
+  if (!isRecord2(raw) || !Array.isArray(raw.hosts)) {
+    throw new Error("~/.basou/hosts.yaml must contain a 'hosts:' list.");
   }
-  await writeFileDurable(bak, raw);
-}
-async function runHookInstall(options, ctx = {}) {
-  try {
-    await doRunHookInstall(normalizeInstallOptions(options), ctx);
-  } catch (error) {
-    renderCliError(error, { verbose: isVerbose(options) });
-    process.exitCode = 1;
+  const seenPaths = /* @__PURE__ */ new Set();
+  const seenLabels = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const entry of raw.hosts) {
+    if (!isRecord2(entry) || typeof entry.label !== "string" || entry.label.trim().length === 0) {
+      throw new Error("Each host needs a non-empty string 'label'.");
+    }
+    const label = entry.label.trim();
+    if (typeof entry.path !== "string" || entry.path.trim().length === 0) {
+      throw new Error("Each host needs a non-empty string 'path'.");
+    }
+    const expanded = expandTilde2(entry.path.trim());
+    if (!isAbsolute2(expanded)) {
+      throw new Error("Host paths must be absolute (or start with '~').");
+    }
+    const abs = resolve4(expanded);
+    if (seenPaths.has(abs)) continue;
+    if (seenLabels.has(label)) {
+      throw new Error(`Duplicate host label '${label}'; each host needs a distinct label.`);
+    }
+    seenPaths.add(abs);
+    seenLabels.add(label);
+    result.push({ label, path: abs });
   }
-}
-async function doRunHookInstall(options, ctx = {}) {
-  const settingsPath = options.settings ?? DEFAULT_CLAUDE_SETTINGS_PATH;
-  const cliEntry = (ctx.resolveCliEntry ?? resolveCliEntry)();
-  const command = buildStopHookCommand({
-    cliEntry,
-    ...options.block === true ? { block: true } : {},
-    ...options.requireReview === true ? { requireReview: true } : {},
-    ...options.minEdits !== void 0 ? { minEdits: options.minEdits } : {}
-  });
-  const mode = describeHookMode({
-    block: options.block === true,
-    review: options.requireReview === true
-  });
-  await assertNotSymlink(settingsPath);
-  const { raw, parsed } = await readSettings(settingsPath);
-  const { settings, action } = upsertStopHook(parsed, command);
-  const newBody = `${JSON.stringify(settings, null, 2)}
-`;
-  if (raw !== null && newBody === raw) {
-    console.log(`The basou Stop hook is already registered (${mode}); no change.`);
-    return;
-  }
-  if (options.dryRun === true) {
-    console.log(`[dry-run] Would ${action} the basou Stop hook (${mode}).`);
-    return;
-  }
-  const recheck = await readSettings(settingsPath);
-  if (recheck.raw !== raw) {
-    throw new Error(
-      "The settings.json changed during install; aborting so a concurrent edit is not overwritten. Re-run 'basou hook install'."
-    );
-  }
-  await backupSettingsOnce(settingsPath, raw);
-  await writeFileDurable(settingsPath, newBody);
-  console.log(`${action === "installed" ? "Installed" : "Updated"} the basou Stop hook (${mode}).`);
-}
-async function runHookUninstall(options) {
-  try {
-    await doRunHookUninstall(normalizeInstallOptions(options));
-  } catch (error) {
-    renderCliError(error, { verbose: isVerbose(options) });
-    process.exitCode = 1;
-  }
-}
-async function doRunHookUninstall(options) {
-  const settingsPath = options.settings ?? DEFAULT_CLAUDE_SETTINGS_PATH;
-  await assertNotSymlink(settingsPath);
-  const { raw, parsed } = await readSettings(settingsPath);
-  if (raw === null) {
-    console.log("No settings.json; nothing to remove.");
-    return;
-  }
-  const { settings, action } = removeStopHook(parsed);
-  if (action === "absent") {
-    console.log("No basou Stop hook found; nothing removed.");
-    return;
-  }
-  const newBody = `${JSON.stringify(settings, null, 2)}
-`;
-  if (options.dryRun === true) {
-    console.log("[dry-run] Would remove the basou Stop hook from settings.json.");
-    return;
-  }
-  const recheck = await readSettings(settingsPath);
-  if (recheck.raw !== raw) {
-    throw new Error(
-      "The settings.json changed during uninstall; aborting so a concurrent edit is not overwritten. Re-run 'basou hook uninstall'."
-    );
-  }
-  await backupSettingsOnce(settingsPath, raw);
-  await writeFileDurable(settingsPath, newBody);
-  console.log("Removed the basou Stop hook from settings.json.");
-}
-async function runHookStatus(options) {
-  try {
-    await doRunHookStatus(normalizeInstallOptions(options));
-  } catch (error) {
-    renderCliError(error, { verbose: isVerbose(options) });
-    process.exitCode = 1;
-  }
-}
-async function doRunHookStatus(options) {
-  const settingsPath = options.settings ?? DEFAULT_CLAUDE_SETTINGS_PATH;
-  const { parsed } = await readSettings(settingsPath);
-  const command = findBasouStopHookCommand(parsed);
-  if (command === null) {
-    console.log("basou Stop hook: not registered. Run 'basou hook install' to register it.");
-    return;
-  }
-  const mode = describeHookMode({
-    block: / --block\b/.test(command),
-    review: / --require-review\b/.test(command)
-  });
-  console.log(`basou Stop hook: registered, ${mode}.`);
-}
-function describeHookMode(tiers) {
-  const enforcement = tiers.block ? "blocking (opt-in enforcement)" : "advisory (non-blocking)";
-  const gates = tiers.review ? "capture + review" : "capture";
-  return `${enforcement}, ${gates}`;
+  return result;
 }
 
+// src/lib/provenance-actions.ts
+import {
+  readMarkdownFile as readMarkdownFile4,
+  renderDecisions as renderDecisions2,
+  renderHandoff as renderHandoff2,
+  renderOrientation,
+  renderWithMarkers as renderWithMarkers3,
+  writeMarkdownFile as writeMarkdownFile3
+} from "@basou/core";
+
 // src/commands/import.ts
 import { createReadStream } from "fs";
-import { readdir, readFile as readFile3, rm, stat as stat4 } from "fs/promises";
+import { readdir, readFile as readFile2, rm, stat as stat3 } from "fs/promises";
 import { homedir as homedir6 } from "os";
-import { basename as basename3, dirname as dirname2, join as join8, resolve as resolve4 } from "path";
+import { basename as basename3, dirname as dirname2, join as join8, resolve as resolve5 } from "path";
 import { createInterface } from "readline";
 import {
   AGENT_INFRA_DIRS as AGENT_INFRA_DIRS2,
@@ -2670,10 +2530,10 @@ function resolveSourceRoots(args) {
   const { projectFlags, manifest, repoRoot, cwd } = args;
   let resolved;
   if (projectFlags.length > 0) {
-    resolved = projectFlags.map((p) => resolve4(cwd, p));
+    resolved = projectFlags.map((p) => resolve5(cwd, p));
   } else {
     const roots = manifest.import?.source_roots;
-    resolved = roots !== void 0 && roots.length > 0 ? roots.map((r) => resolve4(repoRoot, r)) : [repoRoot];
+    resolved = roots !== void 0 && roots.length > 0 ? roots.map((r) => resolve5(repoRoot, r)) : [repoRoot];
   }
   return [...new Set(resolved)];
 }
@@ -2996,7 +2856,7 @@ async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
 }
 async function pathExists(file) {
   try {
-    await stat4(file);
+    await stat3(file);
     return true;
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) return false;
@@ -3005,7 +2865,7 @@ async function pathExists(file) {
 }
 async function statSize(file) {
   try {
-    return (await stat4(file)).size;
+    return (await stat3(file)).size;
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) return void 0;
     throw error;
@@ -3091,7 +2951,7 @@ async function readFirstLine(file) {
 async function readJsonlRecords(file) {
   let buffer;
   try {
-    buffer = await readFile3(file);
+    buffer = await readFile2(file);
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) {
       throw new Error("Source log not found", { cause: error });
@@ -3220,569 +3080,1129 @@ async function assertWorkspaceInitialized5(basouRoot) {
   }
 }
 
-// src/commands/init.ts
-import { basename as basename4, relative, resolve as resolve5 } from "path";
-import {
-  appendBasouGitignore,
-  createManifest,
-  ensureBasouDirectory,
-  resolveRepositoryRoot as resolveRepositoryRoot7,
-  writeManifest
-} from "@basou/core";
-function collectValue(value, previous) {
-  return [...previous, value];
-}
-function registerInitCommand(program2) {
-  program2.command("init").description("Initialize a Basou workspace at the current Git repository root").option("--name <name>", "Workspace name (defaults to the repository directory name)").option("--project-name <name>", "Project display name").option("--project-description <description>", "Project description").option(
-    "--repo-url <url>",
-    "Deprecated and ignored (project.repository_url was removed); accepted for 0.x CLI stability, removed at 1.0"
-  ).option(
-    "--source-root <path>",
-    "Extra import source root, relative to the repo root (repeatable; aggregates sibling repos into this workspace)",
-    collectValue,
-    []
-  ).option(
-    "--local-only",
-    "Write a .basou/ full-exclude .gitignore block (keep the trail out of version control) instead of the default ignore+commit block"
-  ).option("-f, --force", "Overwrite an existing manifest").option("-v, --verbose", "Show error causes").action(async (options) => {
-    await runInit(options);
-  });
-}
-async function runInit(options, ctx = {}) {
-  try {
-    await doRunInit(options, ctx);
-  } catch (error) {
-    renderCliError(error, { verbose: isVerbose(options) });
-    process.exitCode = 1;
-  }
-}
-async function doRunInit(options, ctx) {
-  const cwd = ctx.cwd ?? process.cwd();
-  const repositoryRoot = await resolveRepositoryRootForInit(cwd);
-  const workspaceName = options.name ?? basename4(repositoryRoot);
-  if (options.repoUrl !== void 0) {
-    console.error(
-      "Warning: --repo-url is deprecated and ignored (project.repository_url was removed); the flag will be removed at 1.0."
-    );
-  }
-  const sourceRoots = (options.sourceRoot ?? []).map((p) => {
-    const rel = relative(repositoryRoot, resolve5(cwd, p));
-    return rel === "" ? "." : rel;
+// src/lib/provenance-actions.ts
+async function captureImportJson(fn) {
+  const stdout = [];
+  const originalLog = console.log;
+  const originalError = console.error;
+  console.log = ((...args) => {
+    stdout.push(args.map((a) => String(a)).join(" "));
   });
-  const paths = await ensureBasouDirectory(repositoryRoot);
-  const manifest = createManifest({
-    workspaceName,
-    ...options.projectName !== void 0 ? { projectName: options.projectName } : {},
-    ...options.projectDescription !== void 0 ? { projectDescription: options.projectDescription } : {},
-    ...sourceRoots.length > 0 ? { sourceRoots } : {}
+  console.error = (() => {
   });
-  await writeManifest(paths, manifest, { force: options.force === true });
   try {
-    await appendBasouGitignore(repositoryRoot, { localOnly: options.localOnly === true });
-  } catch (error) {
-    renderGitignoreWarning(error, isVerbose(options));
+    await fn();
+  } finally {
+    console.log = originalLog;
+    console.error = originalError;
   }
-  console.log(`Initialized Basou workspace: ${manifest.workspace.id}`);
-}
-function renderGitignoreWarning(error, verbose) {
-  const baseMessage = error instanceof Error ? error.message : String(error);
-  console.error(
-    `Warning: Could not update .gitignore (${baseMessage}). Add Basou's default .gitignore block manually.`
-  );
-  if (verbose && error instanceof Error) {
-    const label = extractCauseLabel(error);
-    if (label !== void 0) console.error(`Caused by: ${label}`);
+  for (let i = stdout.length - 1; i >= 0; i--) {
+    const line = stdout[i];
+    if (line === void 0) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed !== null && typeof parsed === "object" && "imported_count" in parsed) {
+        return parsed;
+      }
+    } catch {
+    }
   }
+  throw new Error("Import produced no parseable result");
 }
-async function resolveRepositoryRootForInit(cwd) {
+function readCount(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function isMissingSourceDir(error) {
+  if (!(error instanceof Error)) return false;
+  return error.message === "Claude transcript directory not found for project" || error.message === "Codex sessions directory not found";
+}
+async function runImport(adapter, fn) {
   try {
-    return await resolveRepositoryRoot7(cwd);
+    const json = await captureImportJson(fn);
+    return {
+      adapter,
+      status: "ran",
+      importedCount: readCount(json.imported_count),
+      replacedCount: readCount(json.replaced_count),
+      reimportedCount: readCount(json.reimported_count),
+      skippedNoAction: readCount(json.skipped_no_action),
+      skippedAlreadyImported: readCount(json.skipped_already_imported),
+      skippedLegacyUntracked: readCount(json.skipped_legacy_untracked),
+      skippedDecreased: readCount(json.skipped_decreased),
+      skippedDuplicate: readCount(json.skipped_duplicate),
+      skippedUnverifiable: readCount(json.skipped_unverifiable),
+      eventTotal: readCount(json.event_total),
+      dryRun: json.dry_run === true
+    };
   } catch (error) {
-    if (error instanceof Error && error.message === "Not a git repository") {
-      throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou init'.", {
-        cause: error
-      });
+    if (isMissingSourceDir(error)) {
+      return { adapter, status: "skipped", reason: "no source logs for this project" };
     }
     throw error;
   }
 }
-
-// src/commands/note.ts
-import {
-  acquireLock as acquireLock4,
-  appendEventToExistingSession as appendEventToExistingSession2,
-  assertBasouRootSafe as assertBasouRootSafe7,
-  basouPaths as basouPaths8,
-  createAdHocSessionWithEvent as createAdHocSessionWithEvent2,
-  findErrorCode as findErrorCode6,
-  readManifest as readManifest5,
-  resolveSessionId as resolveSessionId2
-} from "@basou/core";
-import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
-var NOTE_SUBCOMMAND_LOOKALIKES = /* @__PURE__ */ new Set([
-  "list",
-  "ls",
-  "show",
-  "get",
-  "add",
-  "new",
-  "edit",
-  "rm",
-  "remove",
-  "delete",
-  "help"
-]);
-var LABEL_BODY_MAX = 80;
-var LABEL_TRUNCATE_HEAD2 = LABEL_BODY_MAX - 3;
-function registerNoteCommand(program2) {
-  program2.command("note").description("Record a free-text note (orientation surfaces the latest as the next step)").argument("<body>", "Note text", parseBody).option(
-    "--session <session_id>",
-    "Attach to an existing session; otherwise an ad-hoc session is created"
-  ).option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").action(async (body, options) => {
-    await runNote(body, options);
+function importOptions(options) {
+  return {
+    all: true,
+    json: true,
+    ...options.project !== void 0 ? { project: options.project } : {},
+    ...options.force === true ? { force: true } : {},
+    ...options.dryRun === true ? { dryRun: true } : {}
+  };
+}
+function importClaudeCode(options, ctx) {
+  return runImport("claude-code", () => doRunImportClaudeCode(importOptions(options), ctx));
+}
+function importCodex(options, ctx) {
+  return runImport("codex", () => doRunImportCodex(importOptions(options), ctx));
+}
+async function regenerateHandoff(paths, nowIso, callbacks) {
+  const result = await renderHandoff2({ paths, nowIso, ...callbacks });
+  const existing = await readMarkdownFile4(paths.files.handoff);
+  await writeMarkdownFile3(
+    paths.files.handoff,
+    renderWithMarkers3(existing, result.body, "handoff.md")
+  );
+  return {
+    sessionCount: result.sessionCount,
+    taskCount: result.taskCount,
+    decisionCount: result.decisionCount,
+    pendingApprovalsCount: result.pendingApprovalsCount
+  };
+}
+async function regenerateDecisions(paths, nowIso, callbacks) {
+  const result = await renderDecisions2({ paths, nowIso, ...callbacks });
+  const existing = await readMarkdownFile4(paths.files.decisions);
+  await writeMarkdownFile3(
+    paths.files.decisions,
+    renderWithMarkers3(existing, result.body, "decisions.md")
+  );
+  return { decisionCount: result.decisionCount };
+}
+async function regenerateOrientation(paths, nowIso, callbacks) {
+  const result = await renderOrientation({ paths, nowIso, ...callbacks });
+  await writeMarkdownFile3(paths.files.orientation, `${result.body}
+`);
+  return {
+    sessionCount: result.sessionCount,
+    inFlightTaskCount: result.inFlightTaskCount,
+    pendingApprovalsCount: result.pendingApprovalsCount,
+    suspectCount: result.suspectCount
+  };
+}
+async function refreshAll(args) {
+  const { options, ctx, paths, nowIso } = args;
+  const dryRun = options.dryRun === true;
+  const claudeCode = await importClaudeCode(options, ctx);
+  const codex = await importCodex(options, ctx);
+  if (dryRun) {
+    const skipped = { status: "skipped", reason: "dry-run" };
+    return {
+      claudeCode,
+      codex,
+      handoff: skipped,
+      decisions: skipped,
+      orientation: skipped,
+      dryRun
+    };
+  }
+  const handoffCounts = await regenerateHandoff(paths, nowIso);
+  const decisionCounts = await regenerateDecisions(paths, nowIso);
+  const scoped = options.project !== void 0 && options.project.length > 0;
+  const orientationCounts = await regenerateOrientation(
+    paths,
+    nowIso,
+    scoped ? {} : {
+      staleness: {
+        newSessions: 0,
+        updatedSessions: 0,
+        unverifiableSessions: wouldBlock(claudeCode) + wouldBlock(codex)
+      }
+    }
+  );
+  return {
+    claudeCode,
+    codex,
+    handoff: { status: "generated", ...handoffCounts },
+    decisions: { status: "generated", ...decisionCounts },
+    orientation: { status: "generated", ...orientationCounts },
+    dryRun
+  };
+}
+function wouldImport(outcome) {
+  return outcome.status === "ran" ? outcome.importedCount : 0;
+}
+function wouldUpdate(outcome) {
+  return outcome.status === "ran" ? outcome.reimportedCount + outcome.replacedCount : 0;
+}
+function wouldBlock(outcome) {
+  return outcome.status === "ran" ? outcome.skippedUnverifiable : 0;
+}
+async function probeStaleness(args) {
+  try {
+    const dry = await refreshAll({
+      options: { dryRun: true },
+      ctx: args.ctx,
+      paths: args.paths,
+      nowIso: args.nowIso
+    });
+    return {
+      newSessions: wouldImport(dry.claudeCode) + wouldImport(dry.codex),
+      updatedSessions: wouldUpdate(dry.claudeCode) + wouldUpdate(dry.codex),
+      unverifiableSessions: wouldBlock(dry.claudeCode) + wouldBlock(dry.codex)
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/orient.ts
+function registerOrientCommand(program2) {
+  program2.command("orient").description("Show the workspace's current position (also writes .basou/orientation.md)").option("-q, --quiet", "Write the file without printing the body").option(
+    "--refresh",
+    "Import all adapters first (writes provenance), then show a guaranteed-fresh position; bare orient is read-only"
+  ).option("-v, --verbose", "Show error causes").action(async (opts) => {
+    await runOrient(opts);
   });
 }
-async function runNote(body, options, ctx = {}) {
+async function runOrient(options, ctx = {}) {
   try {
-    await doRunNote(body, options, ctx);
+    await doRunOrient(options, ctx);
   } catch (error) {
-    renderCliError(error, {
-      verbose: isVerbose(options),
-      classifiers: [failedToFinalizeClassifier]
-    });
+    renderCliError(error, { verbose: isVerbose(options) });
     process.exitCode = 1;
   }
 }
-async function doRunNote(body, options, ctx) {
-  if (body.trim().length === 0) {
-    throw new Error("Note body must not be empty");
-  }
-  const reserved = body.trim().toLowerCase();
-  if (NOTE_SUBCOMMAND_LOOKALIKES.has(reserved)) {
-    throw new Error(
-      `'basou note' records a free-text note and has no '${body.trim()}' subcommand. To record a note, pass its full text (e.g. \`basou note "<your note>"\`).`
+async function doRunOrient(options, ctx) {
+  const result = await renderOrientationForCwd(options, ctx);
+  if (options.quiet === true) {
+    console.log(
+      `Generated .basou/orientation.md (sessions: ${result.sessionCount}, in-flight tasks: ${result.inFlightTaskCount}, pending approvals: ${result.pendingApprovalsCount}, suspect: ${result.suspectCount})`
     );
+  } else {
+    console.log(result.body);
   }
+}
+async function renderOrientationForCwd(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
-  const repositoryRoot = await resolveBasouRootForCommand(cwd, "note");
+  const repositoryRoot = await resolveBasouRootForCommand(cwd, "orient");
+  return renderOrientationForRoot(repositoryRoot, options, ctx, { write: true });
+}
+async function renderOrientationForRoot(repositoryRoot, options, ctx, behaviour) {
   const paths = basouPaths8(repositoryRoot);
   await assertWorkspaceInitialized6(paths.root);
-  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
-  const occurredAt = now.toISOString();
-  if (options.session !== void 0) {
-    const sessionId = await resolveSessionId2(paths, options.session);
-    const sesId = sessionId;
-    const sessionLock = await acquireLock4(paths, "session", sesId);
-    let result;
-    try {
-      result = await appendEventToExistingSession2({
-        paths,
-        sessionId: sesId,
-        eventBuilder: (eventId) => buildNoteEvent({ eventId, sessionId: sesId, occurredAt, body })
-      });
-    } finally {
-      await sessionLock.release();
+  const nowIso = (ctx.nowProvider?.() ?? /* @__PURE__ */ new Date()).toISOString();
+  const probeCtx = { cwd: repositoryRoot };
+  if (ctx.claudeProjectsDir !== void 0) probeCtx.claudeProjectsDir = ctx.claudeProjectsDir;
+  if (ctx.codexSessionsDir !== void 0) probeCtx.codexSessionsDir = ctx.codexSessionsDir;
+  if (options.refresh === true) {
+    await refreshAll({ options: {}, ctx: probeCtx, paths, nowIso });
+  }
+  const staleness = await probeStaleness({ ctx: probeCtx, paths, nowIso });
+  let federatedRoots = [];
+  try {
+    const hosts = await loadHostsConfig(ctx.hostsConfigPath);
+    if (hosts !== null) {
+      federatedRoots = hosts.map((h) => ({ paths: basouPaths8(h.path), host: h.label }));
     }
-    printNoteResult(options, {
-      mode: "attached",
-      sessionId,
-      eventId: result.eventId,
-      sessionStatus: result.sessionStatus,
-      body
+  } catch (error) {
+    console.error(
+      `basou: ignoring ~/.basou/hosts.yaml (${error instanceof Error ? error.message : String(error)}); showing local sessions only.`
+    );
+  }
+  const result = await renderOrientation2({
+    paths,
+    nowIso,
+    staleness,
+    verbose: options.verbose === true,
+    federatedRoots,
+    onWarning: (w, sid) => printReplayWarning(w, sid),
+    onSessionSkip: (sid, reason) => printSessionSkip(sid, reason),
+    onTaskSkip: (taskId, reason) => printTaskSkip(taskId, reason),
+    onHostUnavailable: (host, error) => console.error(
+      `basou: host '${host}' mirror unreadable (${error instanceof Error ? error.message : String(error)}); skipping it.`
+    )
+  });
+  if (behaviour.write) await writeMarkdownFile4(paths.files.orientation, `${result.body}
+`);
+  return {
+    body: result.body,
+    sessionCount: result.sessionCount,
+    inFlightTaskCount: result.inFlightTaskCount,
+    pendingApprovalsCount: result.pendingApprovalsCount,
+    suspectCount: result.suspectCount
+  };
+}
+async function assertWorkspaceInitialized6(basouRoot) {
+  try {
+    await assertBasouRootSafe7(basouRoot);
+  } catch (error) {
+    if (findErrorCode6(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+
+// src/commands/hook.ts
+var MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
+function registerHookCommand(program2) {
+  const hook = program2.command("hook").description(
+    "Hook handlers for AI coding tools (Claude Code, Codex): read a hook payload on stdin, emit the tool's hook output on stdout"
+  );
+  hook.command("session-start").description(
+    "Codex SessionStart hook: print the current position of the workspace Codex was opened in (read from the payload's cwd) so Codex adds it to that session's context. Stays silent outside a basou workspace; never fails the session."
+  ).addHelpText("after", HOOK_SESSION_START_HELP).action(async () => {
+    await runHookSessionStart();
+  });
+  hook.command("stop").description(
+    "Stop-hook: when a substantive session recorded no decisions or next step, emit a non-blocking nudge to capture them. Reads the Stop hook JSON payload on stdin; never blocks and never fails the session."
+  ).option(
+    "--min-edits <n>",
+    `Minimum file edits before nudging on edits alone (default ${DEFAULT_STOP_HOOK_MIN_EDITS})`
+  ).option(
+    "--block",
+    "Opt-in enforcement: hold the agent in-turn (decision:block) instead of a non-blocking reminder"
+  ).option(
+    "--require-review",
+    "Opt-in review gate: also remind when a session shipped substantive code (push / PR / merge) without recording a review"
+  ).addHelpText("after", HOOK_STOP_HELP).action(async (options) => {
+    const minEdits = parseMinEdits(options.minEdits);
+    await runHookStop({
+      ...minEdits !== void 0 ? { minEdits } : {},
+      ...options.block === true ? { block: true } : {},
+      ...options.requireReview === true ? { requireReview: true } : {}
+    });
+  });
+  hook.command("install [target]").description(
+    "Register a basou hook (reproducible, idempotent). Target `claude` (default): the Stop hook in ~/.claude/settings.json \u2014 advisory capture-only by default; --block opts into in-turn enforcement, --require-review into the review gate. Target `codex`: the SessionStart hook in ~/.codex/hooks.json, which hands each Codex session the position of the workspace it was opened in. Codex asks you to review and trust a new hook once before it runs."
+  ).option(
+    "--block",
+    "claude: register the blocking (opt-in enforcement) form instead of advisory"
+  ).option("--require-review", "claude: register with the opt-in review gate enabled").option("--min-edits <n>", "claude: pass a custom file-edit threshold to the registered hook").option("--settings <path>", "claude: override the settings.json path (intended for tests)").option("--hooks <path>", "codex: override the hooks.json path (intended for tests)").option(
+    "--codex-config <path>",
+    "codex: override the Codex config.toml path (intended for tests)"
+  ).option(
+    "--codex-face <path>",
+    "codex: override the user-global AGENTS.md checked for a leftover block (intended for tests)"
+  ).option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (target, opts) => {
+    await dispatchHookTarget(target, opts, {
+      claude: () => runHookInstall(opts),
+      codex: () => runCodexHookInstall(opts)
+    });
+  });
+  hook.command("uninstall [target]").description(
+    "Remove a basou hook, leaving other hooks intact. Target `claude` (default): the Stop hook in ~/.claude/settings.json. Target `codex`: the SessionStart hook in ~/.codex/hooks.json."
+  ).option("--settings <path>", "claude: override the settings.json path (intended for tests)").option("--hooks <path>", "codex: override the hooks.json path (intended for tests)").option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (target, opts) => {
+    await dispatchHookTarget(target, opts, {
+      claude: () => runHookUninstall(opts),
+      codex: () => runCodexHookUninstall(opts)
     });
+  });
+  hook.command("status [target]").description(
+    "Report whether a basou hook is registered. Target `claude` (default): the Stop hook and its mode. Target `codex`: the SessionStart hook, and whether Codex has trusted it yet."
+  ).option("--settings <path>", "claude: override the settings.json path (intended for tests)").option("--hooks <path>", "codex: override the hooks.json path (intended for tests)").option(
+    "--codex-config <path>",
+    "codex: override the Codex config.toml path (intended for tests)"
+  ).option("-v, --verbose", "Show error causes").action(async (target, opts) => {
+    await dispatchHookTarget(target, opts, {
+      claude: () => runHookStatus(opts),
+      codex: () => runCodexHookStatus(opts)
+    });
+  });
+}
+async function dispatchHookTarget(target, options, handlers) {
+  const resolved = target ?? "claude";
+  if (resolved !== "claude" && resolved !== "codex") {
+    renderCliError(
+      new Error(`Unknown hook target '${target}'. Targets: claude (default), codex.`),
+      { verbose: isVerbose(options) }
+    );
+    process.exitCode = 1;
     return;
   }
-  const manifest = await readManifest5(paths);
-  const adHoc = await createAdHocSessionWithEvent2({
-    paths,
-    manifest,
-    label: buildAdHocLabel2(body),
-    occurredAt,
-    sessionSource: "human",
-    workingDirectory: repositoryRoot,
-    invocation: {
-      command: "basou note",
-      args: [body]
-    },
-    targetEventBuilders: [
-      (sessionId, eventId) => buildNoteEvent({ eventId, sessionId, occurredAt, body })
-    ]
+  await handlers[resolved]();
+}
+var HOOK_SESSION_START_HELP = `
+Register this hook reproducibly with 'basou hook install codex' (it writes the
+correct node-path command into ~/.codex/hooks.json). 'basou hook uninstall codex'
+removes it; 'basou hook status codex' reports whether it is registered and
+whether Codex has trusted it.
+
+Codex runs the hook when a session starts and passes the session's cwd on stdin.
+basou resolves the workspace from that cwd (a member repo resolves to its
+planning master, a workspace view to its master) and prints the workspace's
+current position \u2014 the same text as 'basou orient' \u2014 which Codex adds to that
+session's context as developer text. The position is computed at that moment
+from that cwd and stored nowhere: a Codex opened in another workspace gets that
+workspace's position, and one opened outside any basou workspace (or before the
+desktop app has bound a folder, when cwd is '/') gets nothing. That is how one
+user-global hook serves every workspace without any workspace's position ever
+being written where another workspace's session would read it.
+
+Codex trusts hooks by hash. A newly installed or changed hook is skipped until
+you review it: the interactive CLI asks at startup ("Hooks need review"), the
+desktop app lists it under Settings -> Hooks. Non-interactive 'codex exec' skips
+an untrusted hook silently.
+`;
+var HOOK_STOP_HELP = `
+Register this Stop hook reproducibly with 'basou hook install' (it writes the
+correct node-path command into ~/.claude/settings.json). 'basou hook uninstall'
+removes it; 'basou hook status' reports whether it is registered.
+
+On every turn end basou inspects the session transcript. If the session did
+content-substantive work but ran no capture verb ('basou decision capture' /
+'decision record' / 'note'), it reminds the agent to record the why / next step.
+Substantive = EITHER >= ${DEFAULT_STOP_HOOK_MIN_EDITS} file edits (default) OR a free-form AskUserQuestion
+answer (an uncaptured conversational decision). Read-only Bash (ls / grep /
+git status) does NOT count.
+
+With --require-review (opt-in, 'basou hook install --require-review') it also
+reminds when the session SHIPPED substantive code (git push / git merge /
+gh pr create|merge) without recording a review ('basou review record'). This
+gate is off by default; when on, its reminder is composed into the same
+envelope as the capture reminder.
+
+By default the reminder is non-blocking: Claude sees it and may act on it or
+stop. With --block (opt-in enforcement, 'basou hook install --block') it instead
+returns decision:block, holding the agent in-turn to act on the reminder; the
+'stop_hook_active' flag and Claude Code's own loop prevention bound it to a
+single turn. Either way the hook fails open: a bad payload or unreadable
+transcript exits cleanly with no output.
+`;
+async function runHookStop(options, ctx = {}) {
+  try {
+    await doRunHookStop(options, ctx);
+  } catch {
+  }
+}
+async function doRunHookStop(options, ctx) {
+  const readStdin = ctx.readStdin ?? defaultReadStdin;
+  const readTranscript = ctx.readTranscript ?? readTranscriptBounded;
+  const write = ctx.write ?? ((text) => void process.stdout.write(text));
+  const raw = await readStdin();
+  if (raw.trim().length === 0) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof payload !== "object" || payload === null) return;
+  const fields = payload;
+  if (fields.stop_hook_active === true) return;
+  const transcriptPath = typeof fields.transcript_path === "string" ? fields.transcript_path : "";
+  if (transcriptPath.length === 0) return;
+  let transcript;
+  try {
+    transcript = await readTranscript(transcriptPath);
+  } catch {
+    return;
+  }
+  const records = parseTranscript(transcript);
+  const evaluation = evaluateStopHook({
+    records,
+    // stop_hook_active was already handled by the early return above.
+    stopHookActive: false,
+    ...options.minEdits !== void 0 ? { minEdits: options.minEdits } : {}
   });
-  printNoteResult(options, {
-    mode: "ad-hoc",
-    sessionId: adHoc.sessionId,
-    eventId: adHoc.targetEventIds[0],
-    sessionStatus: "completed",
-    body
+  const parts = [];
+  if (evaluation.kind === "nudge") parts.push(evaluation.additionalContext);
+  if (options.requireReview === true && evaluation.review.fires) {
+    parts.push(evaluation.review.additionalContext);
+  }
+  if (parts.length === 0) return;
+  const reason = parts.join("\n\n");
+  const payloadJson = options.block === true ? JSON.stringify({ decision: "block", reason }) : JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "Stop",
+      additionalContext: reason
+    }
   });
+  write(`${payloadJson}
+`);
 }
-function buildNoteEvent(input) {
-  return {
-    schema_version: "0.1.0",
-    id: input.eventId,
-    session_id: input.sessionId,
-    occurred_at: input.occurredAt,
-    source: "local-cli",
-    type: "note_added",
-    body: input.body,
-    // `basou note` is the resume-hint command; mark it so orientation surfaces
-    // it as the next step and a plain `basou session note` annotation does not.
-    kind: "next_step"
-  };
+async function renderRegisteredWorkspacePosition(cwd, portfolioConfigPath = DEFAULT_PORTFOLIO_CONFIG_PATH) {
+  const root = await resolveBasouRootForCommand(cwd, "hook session-start", {
+    portfolioConfigPath
+  });
+  if (!await isRegisteredWorkspace(root, portfolioConfigPath)) {
+    throw new Error("The workspace is not registered in the portfolio; the hook stays silent.");
+  }
+  const rendered = await renderOrientationForRoot(root, {}, { cwd }, { write: false });
+  return { body: rendered.body };
 }
-function buildAdHocLabel2(body) {
-  const oneLine2 = body.replace(/\s+/g, " ").trim();
-  const truncated = oneLine2.length > LABEL_BODY_MAX ? `${oneLine2.slice(0, LABEL_TRUNCATE_HEAD2)}...` : oneLine2;
-  return `Ad-hoc note: ${truncated}`;
+async function isRegisteredWorkspace(root, portfolioConfigPath) {
+  let entries;
+  try {
+    entries = await loadPortfolioConfig(portfolioConfigPath);
+  } catch {
+    return false;
+  }
+  const rootReal = await realpath2(root).catch(() => root);
+  for (const entry of entries) {
+    const entryReal = await realpath2(entry.path).catch(() => null);
+    if (entryReal !== null && entryReal === rootReal) return true;
+  }
+  return false;
 }
-function parseBody(raw) {
-  if (raw.trim().length === 0) {
-    throw new InvalidArgumentError2("Note body must not be empty");
+async function runHookSessionStart(ctx = {}) {
+  try {
+    await doRunHookSessionStart(ctx);
+  } catch {
+  }
+}
+async function doRunHookSessionStart(ctx) {
+  const readStdin = ctx.readStdin ?? defaultReadStdin;
+  const write = ctx.write ?? ((text) => void process.stdout.write(text));
+  const render = ctx.render ?? ((cwd2) => renderRegisteredWorkspacePosition(cwd2, ctx.portfolioConfigPath));
+  const raw = await readStdin();
+  if (raw.trim().length === 0) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof payload !== "object" || payload === null) return;
+  const cwd = payload.cwd;
+  if (typeof cwd !== "string" || cwd.length === 0) return;
+  let body;
+  try {
+    body = (await render(cwd)).body;
+  } catch {
+    return;
   }
-  return raw;
+  if (body.trim().length === 0) return;
+  write(`${body.replace(/\s+$/, "")}
+`);
 }
-function printNoteResult(options, result) {
-  const sid = shortSessionId(result.sessionId);
-  if (options.json === true) {
-    console.log(
-      JSON.stringify({
-        event_id: result.eventId,
-        session_id: result.sessionId,
-        session_status: result.sessionStatus,
-        mode: result.mode,
-        body: result.body
-      })
-    );
-    return;
+function parseTranscript(transcript) {
+  const records = [];
+  for (const line of transcript.split(/\r?\n/)) {
+    if (line.trim().length === 0) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        records.push(parsed);
+      }
+    } catch {
+    }
   }
-  if (result.mode === "ad-hoc") {
-    console.log(`Recorded note ${result.eventId} in ad-hoc session ${sid}`);
-  } else {
-    console.log(`Recorded note ${result.eventId} in session ${sid} (${result.sessionStatus})`);
+  return records;
+}
+async function defaultReadStdin() {
+  if (process.stdin.isTTY === true) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
   }
+  return Buffer.concat(chunks).toString("utf8");
 }
-async function assertWorkspaceInitialized6(basouRoot) {
+async function readTranscriptBounded(path, maxBytes = MAX_TRANSCRIPT_BYTES) {
+  const { size } = await stat4(path);
+  if (size <= maxBytes) return readFile3(path, "utf8");
+  const handle = await open2(path, "r");
   try {
-    await assertBasouRootSafe7(basouRoot);
-  } catch (error) {
-    if (findErrorCode6(error, "ENOENT")) {
-      throw new Error("Workspace not initialized. Run 'basou init' first.");
-    }
-    throw error;
+    const buffer = Buffer.alloc(maxBytes);
+    const { bytesRead } = await handle.read(buffer, 0, maxBytes, size - maxBytes);
+    const text = buffer.subarray(0, bytesRead).toString("utf8");
+    const firstNewline = text.indexOf("\n");
+    return firstNewline >= 0 ? text.slice(firstNewline + 1) : text;
+  } finally {
+    await handle.close();
   }
 }
-
-// src/commands/orient.ts
-import {
-  assertBasouRootSafe as assertBasouRootSafe8,
-  basouPaths as basouPaths9,
-  findErrorCode as findErrorCode7,
-  renderOrientation as renderOrientation2,
-  writeMarkdownFile as writeMarkdownFile4
-} from "@basou/core";
-
-// src/lib/hosts-config.ts
-import { homedir as homedir7 } from "os";
-import { isAbsolute as isAbsolute2, join as join9, resolve as resolve6 } from "path";
-import { readYamlFile as readYamlFile4 } from "@basou/core";
-var DEFAULT_HOSTS_CONFIG_PATH = join9(homedir7(), ".basou", "hosts.yaml");
-function expandTilde2(p) {
-  if (p === "~") return homedir7();
-  if (p.startsWith("~/")) return join9(homedir7(), p.slice(2));
-  return p;
+function parseMinEdits(raw) {
+  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
+  return Number(raw);
 }
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+var DEFAULT_CLAUDE_SETTINGS_PATH = join9(homedir7(), ".claude", "settings.json");
+function resolveCliEntry() {
+  return fileURLToPath(import.meta.url);
 }
-async function loadHostsConfig(configPath = DEFAULT_HOSTS_CONFIG_PATH) {
+function normalizeInstallOptions(raw) {
+  const out = {};
+  if (raw.block === true) out.block = true;
+  if (raw.requireReview === true) out.requireReview = true;
+  if (raw.settings !== void 0) out.settings = raw.settings;
+  if (raw.hooks !== void 0) out.hooks = raw.hooks;
+  if (raw.codexConfig !== void 0) out.codexConfig = raw.codexConfig;
+  if (raw.codexFace !== void 0) out.codexFace = raw.codexFace;
+  if (raw.dryRun === true) out.dryRun = true;
+  if (raw.verbose === true) out.verbose = true;
+  if (raw.minEdits !== void 0) {
+    const parsed = parseMinEdits(raw.minEdits);
+    if (parsed === void 0) {
+      throw new Error("--min-edits must be a non-negative integer.");
+    }
+    out.minEdits = parsed;
+  }
+  return out;
+}
+async function readSettings(path) {
   let raw;
   try {
-    raw = await readYamlFile4(configPath);
+    raw = await readFile3(path, "utf8");
   } catch (error) {
-    if (error instanceof Error && error.message === "YAML file not found") {
-      return null;
-    }
-    if (error instanceof Error && error.message === "Failed to parse YAML content") {
-      throw new Error("~/.basou/hosts.yaml is not valid YAML.");
+    if (error instanceof Error && error.code === "ENOENT") {
+      return { raw: null, parsed: void 0 };
     }
     throw error;
   }
-  if (!isRecord2(raw) || !Array.isArray(raw.hosts)) {
-    throw new Error("~/.basou/hosts.yaml must contain a 'hosts:' list.");
+  if (raw.trim().length === 0) return { raw, parsed: void 0 };
+  try {
+    return { raw, parsed: JSON.parse(raw) };
+  } catch (error) {
+    throw new Error(
+      "The Claude settings.json is not valid JSON. Fix it (or remove it) and retry.",
+      {
+        cause: error
+      }
+    );
   }
-  const seenPaths = /* @__PURE__ */ new Set();
-  const seenLabels = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const entry of raw.hosts) {
-    if (!isRecord2(entry) || typeof entry.label !== "string" || entry.label.trim().length === 0) {
-      throw new Error("Each host needs a non-empty string 'label'.");
-    }
-    const label = entry.label.trim();
-    if (typeof entry.path !== "string" || entry.path.trim().length === 0) {
-      throw new Error("Each host needs a non-empty string 'path'.");
-    }
-    const expanded = expandTilde2(entry.path.trim());
-    if (!isAbsolute2(expanded)) {
-      throw new Error("Host paths must be absolute (or start with '~').");
-    }
-    const abs = resolve6(expanded);
-    if (seenPaths.has(abs)) continue;
-    if (seenLabels.has(label)) {
-      throw new Error(`Duplicate host label '${label}'; each host needs a distinct label.`);
-    }
-    seenPaths.add(abs);
-    seenLabels.add(label);
-    result.push({ label, path: abs });
+}
+async function backupSettingsOnce(path, raw) {
+  if (raw === null) return;
+  const bak = `${path}.basou-bak`;
+  try {
+    await stat4(bak);
+    return;
+  } catch (error) {
+    if (!(error instanceof Error && error.code === "ENOENT")) throw error;
   }
-  return result;
+  await writeFileDurable(bak, raw);
 }
-
-// src/lib/provenance-actions.ts
-import {
-  readMarkdownFile as readMarkdownFile4,
-  renderDecisions as renderDecisions2,
-  renderHandoff as renderHandoff2,
-  renderOrientation,
-  renderWithMarkers as renderWithMarkers3,
-  writeMarkdownFile as writeMarkdownFile3
-} from "@basou/core";
-async function captureImportJson(fn) {
-  const stdout = [];
-  const originalLog = console.log;
-  const originalError = console.error;
-  console.log = ((...args) => {
-    stdout.push(args.map((a) => String(a)).join(" "));
+async function runHookInstall(options, ctx = {}) {
+  try {
+    await doRunHookInstall(normalizeInstallOptions(options), ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunHookInstall(options, ctx = {}) {
+  const settingsPath = options.settings ?? DEFAULT_CLAUDE_SETTINGS_PATH;
+  const cliEntry = (ctx.resolveCliEntry ?? resolveCliEntry)();
+  const command = buildStopHookCommand({
+    cliEntry,
+    ...options.block === true ? { block: true } : {},
+    ...options.requireReview === true ? { requireReview: true } : {},
+    ...options.minEdits !== void 0 ? { minEdits: options.minEdits } : {}
   });
-  console.error = (() => {
+  const mode = describeHookMode({
+    block: options.block === true,
+    review: options.requireReview === true
   });
+  await assertNotSymlink(settingsPath);
+  const { raw, parsed } = await readSettings(settingsPath);
+  const { settings, action } = upsertStopHook(parsed, command);
+  const newBody = `${JSON.stringify(settings, null, 2)}
+`;
+  if (raw !== null && newBody === raw) {
+    console.log(`The basou Stop hook is already registered (${mode}); no change.`);
+    return;
+  }
+  if (options.dryRun === true) {
+    console.log(`[dry-run] Would ${action} the basou Stop hook (${mode}).`);
+    return;
+  }
+  const recheck = await readSettings(settingsPath);
+  if (recheck.raw !== raw) {
+    throw new Error(
+      "The settings.json changed during install; aborting so a concurrent edit is not overwritten. Re-run 'basou hook install'."
+    );
+  }
+  await backupSettingsOnce(settingsPath, raw);
+  await writeFileDurable(settingsPath, newBody);
+  console.log(`${action === "installed" ? "Installed" : "Updated"} the basou Stop hook (${mode}).`);
+}
+async function runHookUninstall(options) {
   try {
-    await fn();
-  } finally {
-    console.log = originalLog;
-    console.error = originalError;
+    await doRunHookUninstall(normalizeInstallOptions(options));
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
   }
-  for (let i = stdout.length - 1; i >= 0; i--) {
-    const line = stdout[i];
-    if (line === void 0) continue;
-    try {
-      const parsed = JSON.parse(line);
-      if (parsed !== null && typeof parsed === "object" && "imported_count" in parsed) {
-        return parsed;
-      }
-    } catch {
-    }
+}
+async function doRunHookUninstall(options) {
+  const settingsPath = options.settings ?? DEFAULT_CLAUDE_SETTINGS_PATH;
+  await assertNotSymlink(settingsPath);
+  const { raw, parsed } = await readSettings(settingsPath);
+  if (raw === null) {
+    console.log("No settings.json; nothing to remove.");
+    return;
+  }
+  const { settings, action } = removeStopHook(parsed);
+  if (action === "absent") {
+    console.log("No basou Stop hook found; nothing removed.");
+    return;
+  }
+  const newBody = `${JSON.stringify(settings, null, 2)}
+`;
+  if (options.dryRun === true) {
+    console.log("[dry-run] Would remove the basou Stop hook from settings.json.");
+    return;
+  }
+  const recheck = await readSettings(settingsPath);
+  if (recheck.raw !== raw) {
+    throw new Error(
+      "The settings.json changed during uninstall; aborting so a concurrent edit is not overwritten. Re-run 'basou hook uninstall'."
+    );
+  }
+  await backupSettingsOnce(settingsPath, raw);
+  await writeFileDurable(settingsPath, newBody);
+  console.log("Removed the basou Stop hook from settings.json.");
+}
+async function runHookStatus(options) {
+  try {
+    await doRunHookStatus(normalizeInstallOptions(options));
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
   }
-  throw new Error("Import produced no parseable result");
 }
-function readCount(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+async function doRunHookStatus(options) {
+  const settingsPath = options.settings ?? DEFAULT_CLAUDE_SETTINGS_PATH;
+  const { parsed } = await readSettings(settingsPath);
+  const command = findBasouStopHookCommand(parsed);
+  if (command === null) {
+    console.log("basou Stop hook: not registered. Run 'basou hook install' to register it.");
+    return;
+  }
+  const mode = describeHookMode({
+    block: / --block\b/.test(command),
+    review: / --require-review\b/.test(command)
+  });
+  console.log(`basou Stop hook: registered, ${mode}.`);
 }
-function isMissingSourceDir(error) {
-  if (!(error instanceof Error)) return false;
-  return error.message === "Claude transcript directory not found for project" || error.message === "Codex sessions directory not found";
+function describeHookMode(tiers) {
+  const enforcement = tiers.block ? "blocking (opt-in enforcement)" : "advisory (non-blocking)";
+  const gates = tiers.review ? "capture + review" : "capture";
+  return `${enforcement}, ${gates}`;
 }
-async function runImport(adapter, fn) {
+var DEFAULT_CODEX_FACE_PATH = join9(homedir7(), ".codex", "AGENTS.md");
+var LEFTOVER_FACE_NOTE = (label) => `${label} still carries an orientation block rendered by an earlier basou (0.39 or before); every Codex session on this machine reads it. \`basou channel clear codex\` removes it.`;
+async function faceHasLeftoverOrientationBlock(facePath) {
   try {
-    const json = await captureImportJson(fn);
-    return {
-      adapter,
-      status: "ran",
-      importedCount: readCount(json.imported_count),
-      replacedCount: readCount(json.replaced_count),
-      reimportedCount: readCount(json.reimported_count),
-      skippedNoAction: readCount(json.skipped_no_action),
-      skippedAlreadyImported: readCount(json.skipped_already_imported),
-      skippedLegacyUntracked: readCount(json.skipped_legacy_untracked),
-      skippedDecreased: readCount(json.skipped_decreased),
-      skippedDuplicate: readCount(json.skipped_duplicate),
-      skippedUnverifiable: readCount(json.skipped_unverifiable),
-      eventTotal: readCount(json.event_total),
-      dryRun: json.dry_run === true
-    };
+    const existing = await readMarkdownFile5(facePath);
+    if (existing === null) return false;
+    const section = parseMarkers2(existing, { start: ORIENTATION_START2, end: ORIENTATION_END2 });
+    return section.kind !== "no_markers";
+  } catch {
+    return false;
+  }
+}
+var DEFAULT_CODEX_HOOKS_PATH = join9(homedir7(), ".codex", "hooks.json");
+var DEFAULT_CODEX_CONFIG_PATH = join9(homedir7(), ".codex", "config.toml");
+async function readHooksFile(path) {
+  let raw;
+  try {
+    raw = await readFile3(path, "utf8");
   } catch (error) {
-    if (isMissingSourceDir(error)) {
-      return { adapter, status: "skipped", reason: "no source logs for this project" };
+    if (error instanceof Error && error.code === "ENOENT") {
+      return { raw: null, parsed: void 0 };
     }
     throw error;
   }
+  if (raw.trim().length === 0) return { raw, parsed: void 0 };
+  try {
+    return { raw, parsed: JSON.parse(raw) };
+  } catch (error) {
+    throw new Error("The Codex hooks.json is not valid JSON. Fix it (or remove it) and retry.", {
+      cause: error
+    });
+  }
 }
-function importOptions(options) {
-  return {
-    all: true,
-    json: true,
-    ...options.project !== void 0 ? { project: options.project } : {},
-    ...options.force === true ? { force: true } : {},
-    ...options.dryRun === true ? { dryRun: true } : {}
-  };
+var CODEX_TRUST_NOTE = "Codex reviews a new or changed hook once before running it: start `codex` in a terminal and trust it when asked (desktop app: Settings -> Hooks). Until then the hook is skipped silently.";
+async function runCodexHookInstall(options, ctx = {}) {
+  try {
+    await doRunCodexHookInstall(normalizeInstallOptions(options), ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
 }
-function importClaudeCode(options, ctx) {
-  return runImport("claude-code", () => doRunImportClaudeCode(importOptions(options), ctx));
+async function doRunCodexHookInstall(options, ctx = {}) {
+  const hooksPath = options.hooks ?? DEFAULT_CODEX_HOOKS_PATH;
+  const cliEntry = (ctx.resolveCliEntry ?? resolveCliEntry)();
+  const command = buildSessionStartHookCommand({ cliEntry });
+  await assertNotSymlink(hooksPath);
+  const { raw, parsed } = await readHooksFile(hooksPath);
+  const { hooksFile, action } = upsertSessionStartHook(parsed, command);
+  const newBody = `${JSON.stringify(hooksFile, null, 2)}
+`;
+  if (action === "unchanged" || raw !== null && newBody === raw) {
+    console.log("The basou Codex SessionStart hook is already registered; no change.");
+    await reportCodexHookState(hooksPath, hooksFile, options);
+    return;
+  }
+  if (options.dryRun === true) {
+    console.log(
+      `[dry-run] Would ${action === "installed" ? "install" : "update"} the basou Codex SessionStart hook in ${hooksPath}.`
+    );
+    return;
+  }
+  const recheck = await readHooksFile(hooksPath);
+  if (recheck.raw !== raw) {
+    throw new Error(
+      "The hooks.json changed during install; aborting so a concurrent edit is not overwritten. Re-run 'basou hook install codex'."
+    );
+  }
+  await backupSettingsOnce(hooksPath, raw);
+  await writeFileDurable(hooksPath, newBody);
+  console.log(
+    `${action === "installed" ? "Installed" : "Updated"} the basou Codex SessionStart hook in ${hooksPath}.`
+  );
+  await reportCodexHookState(hooksPath, hooksFile, options);
 }
-function importCodex(options, ctx) {
-  return runImport("codex", () => doRunImportCodex(importOptions(options), ctx));
+async function reportCodexHookState(hooksPath, hooksFile, options) {
+  const location = findBasouSessionStartHook(hooksFile);
+  if (location !== null) {
+    const trust = await codexHookTrustFor(hooksPath, location, options.codexConfig);
+    console.log(`Codex trust: ${describeCodexHookTrust(trust)}.`);
+    if (trust.status === "untrusted" || trust.status === "modified") console.log(CODEX_TRUST_NOTE);
+  }
+  const facePath = options.codexFace ?? DEFAULT_CODEX_FACE_PATH;
+  if (await faceHasLeftoverOrientationBlock(facePath)) {
+    console.log(LEFTOVER_FACE_NOTE(options.codexFace ?? "~/.codex/AGENTS.md"));
+  }
 }
-async function regenerateHandoff(paths, nowIso, callbacks) {
-  const result = await renderHandoff2({ paths, nowIso, ...callbacks });
-  const existing = await readMarkdownFile4(paths.files.handoff);
-  await writeMarkdownFile3(
-    paths.files.handoff,
-    renderWithMarkers3(existing, result.body, "handoff.md")
-  );
-  return {
-    sessionCount: result.sessionCount,
-    taskCount: result.taskCount,
-    decisionCount: result.decisionCount,
-    pendingApprovalsCount: result.pendingApprovalsCount
-  };
+async function runCodexHookUninstall(options) {
+  try {
+    await doRunCodexHookUninstall(normalizeInstallOptions(options));
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
 }
-async function regenerateDecisions(paths, nowIso, callbacks) {
-  const result = await renderDecisions2({ paths, nowIso, ...callbacks });
-  const existing = await readMarkdownFile4(paths.files.decisions);
-  await writeMarkdownFile3(
-    paths.files.decisions,
-    renderWithMarkers3(existing, result.body, "decisions.md")
-  );
-  return { decisionCount: result.decisionCount };
+async function doRunCodexHookUninstall(options) {
+  const hooksPath = options.hooks ?? DEFAULT_CODEX_HOOKS_PATH;
+  await assertNotSymlink(hooksPath);
+  const { raw, parsed } = await readHooksFile(hooksPath);
+  if (raw === null) {
+    console.log("No hooks.json; nothing to remove.");
+    return;
+  }
+  const { hooksFile, action } = removeSessionStartHook(parsed);
+  if (action === "absent") {
+    console.log("No basou Codex SessionStart hook found; nothing removed.");
+    return;
+  }
+  const newBody = `${JSON.stringify(hooksFile, null, 2)}
+`;
+  if (options.dryRun === true) {
+    console.log("[dry-run] Would remove the basou Codex SessionStart hook from hooks.json.");
+    return;
+  }
+  const recheck = await readHooksFile(hooksPath);
+  if (recheck.raw !== raw) {
+    throw new Error(
+      "The hooks.json changed during uninstall; aborting so a concurrent edit is not overwritten. Re-run 'basou hook uninstall codex'."
+    );
+  }
+  await backupSettingsOnce(hooksPath, raw);
+  await writeFileDurable(hooksPath, newBody);
+  console.log("Removed the basou Codex SessionStart hook from hooks.json.");
 }
-async function regenerateOrientation(paths, nowIso, callbacks) {
-  const result = await renderOrientation({ paths, nowIso, ...callbacks });
-  await writeMarkdownFile3(paths.files.orientation, `${result.body}
-`);
-  return {
-    sessionCount: result.sessionCount,
-    inFlightTaskCount: result.inFlightTaskCount,
-    pendingApprovalsCount: result.pendingApprovalsCount,
-    suspectCount: result.suspectCount
-  };
+async function runCodexHookStatus(options) {
+  try {
+    await doRunCodexHookStatus(normalizeInstallOptions(options));
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
 }
-async function refreshAll(args) {
-  const { options, ctx, paths, nowIso } = args;
-  const dryRun = options.dryRun === true;
-  const claudeCode = await importClaudeCode(options, ctx);
-  const codex = await importCodex(options, ctx);
-  if (dryRun) {
-    const skipped = { status: "skipped", reason: "dry-run" };
+async function doRunCodexHookStatus(options) {
+  const hooksPath = options.hooks ?? DEFAULT_CODEX_HOOKS_PATH;
+  const { parsed } = await readHooksFile(hooksPath);
+  const location = findBasouSessionStartHook(parsed);
+  if (location === null) {
+    console.log(
+      "basou Codex SessionStart hook: not registered. Run 'basou hook install codex' to register it."
+    );
+    const facePath = options.codexFace ?? DEFAULT_CODEX_FACE_PATH;
+    if (await faceHasLeftoverOrientationBlock(facePath)) {
+      console.log(LEFTOVER_FACE_NOTE(options.codexFace ?? "~/.codex/AGENTS.md"));
+    }
+    return;
+  }
+  const matcher = location.matcher ?? "(every source)";
+  console.log(
+    `basou Codex SessionStart hook: registered in ${hooksPath} (matcher: ${matcher}); speaks only for workspaces registered in ~/.basou/portfolio.yaml.`
+  );
+  await reportCodexHookState(hooksPath, parsed, options);
+}
+async function codexHookTrustFor(hooksPath, location, configPath) {
+  const fields = commandHandlerFields(location.handler);
+  if (fields === null)
+    return { status: "unknown", detail: "the installed handler is not a command hook" };
+  let configToml;
+  try {
+    configToml = await readFile3(configPath ?? DEFAULT_CODEX_CONFIG_PATH, "utf8");
+  } catch (error) {
+    if (error instanceof Error && error.code === "ENOENT") {
+      return { status: "untrusted" };
+    }
     return {
-      claudeCode,
-      codex,
-      handoff: skipped,
-      decisions: skipped,
-      orientation: skipped,
-      dryRun
+      status: "unknown",
+      detail: `could not read ${configPath ?? DEFAULT_CODEX_CONFIG_PATH}`
     };
   }
-  const handoffCounts = await regenerateHandoff(paths, nowIso);
-  const decisionCounts = await regenerateDecisions(paths, nowIso);
-  const scoped = options.project !== void 0 && options.project.length > 0;
-  const orientationCounts = await regenerateOrientation(
-    paths,
-    nowIso,
-    scoped ? {} : {
-      staleness: {
-        newSessions: 0,
-        updatedSessions: 0,
-        unverifiableSessions: wouldBlock(claudeCode) + wouldBlock(codex)
-      }
-    }
+  const key = codexHookStateKey(
+    hooksPath,
+    "session_start",
+    location.groupIndex,
+    location.handlerIndex
   );
-  return {
-    claudeCode,
-    codex,
-    handoff: { status: "generated", ...handoffCounts },
-    decisions: { status: "generated", ...decisionCounts },
-    orientation: { status: "generated", ...orientationCounts },
-    dryRun
-  };
+  const state = readCodexHookState(configToml, key);
+  const current = computeCodexHookIdentityHash({
+    eventKey: "session_start",
+    matcher: location.matcher,
+    handler: fields
+  });
+  return judgeCodexHookTrust(state, current);
 }
-function wouldImport(outcome) {
-  return outcome.status === "ran" ? outcome.importedCount : 0;
+
+// src/commands/init.ts
+import { basename as basename4, relative, resolve as resolve6 } from "path";
+import {
+  appendBasouGitignore,
+  createManifest,
+  ensureBasouDirectory,
+  resolveRepositoryRoot as resolveRepositoryRoot7,
+  writeManifest
+} from "@basou/core";
+function collectValue(value, previous) {
+  return [...previous, value];
 }
-function wouldUpdate(outcome) {
-  return outcome.status === "ran" ? outcome.reimportedCount + outcome.replacedCount : 0;
+function registerInitCommand(program2) {
+  program2.command("init").description("Initialize a Basou workspace at the current Git repository root").option("--name <name>", "Workspace name (defaults to the repository directory name)").option("--project-name <name>", "Project display name").option("--project-description <description>", "Project description").option(
+    "--repo-url <url>",
+    "Deprecated and ignored (project.repository_url was removed); accepted for 0.x CLI stability, removed at 1.0"
+  ).option(
+    "--source-root <path>",
+    "Extra import source root, relative to the repo root (repeatable; aggregates sibling repos into this workspace)",
+    collectValue,
+    []
+  ).option(
+    "--local-only",
+    "Write a .basou/ full-exclude .gitignore block (keep the trail out of version control) instead of the default ignore+commit block"
+  ).option("-f, --force", "Overwrite an existing manifest").option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runInit(options);
+  });
+}
+async function runInit(options, ctx = {}) {
+  try {
+    await doRunInit(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunInit(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForInit(cwd);
+  const workspaceName = options.name ?? basename4(repositoryRoot);
+  if (options.repoUrl !== void 0) {
+    console.error(
+      "Warning: --repo-url is deprecated and ignored (project.repository_url was removed); the flag will be removed at 1.0."
+    );
+  }
+  const sourceRoots = (options.sourceRoot ?? []).map((p) => {
+    const rel = relative(repositoryRoot, resolve6(cwd, p));
+    return rel === "" ? "." : rel;
+  });
+  const paths = await ensureBasouDirectory(repositoryRoot);
+  const manifest = createManifest({
+    workspaceName,
+    ...options.projectName !== void 0 ? { projectName: options.projectName } : {},
+    ...options.projectDescription !== void 0 ? { projectDescription: options.projectDescription } : {},
+    ...sourceRoots.length > 0 ? { sourceRoots } : {}
+  });
+  await writeManifest(paths, manifest, { force: options.force === true });
+  try {
+    await appendBasouGitignore(repositoryRoot, { localOnly: options.localOnly === true });
+  } catch (error) {
+    renderGitignoreWarning(error, isVerbose(options));
+  }
+  console.log(`Initialized Basou workspace: ${manifest.workspace.id}`);
 }
-function wouldBlock(outcome) {
-  return outcome.status === "ran" ? outcome.skippedUnverifiable : 0;
+function renderGitignoreWarning(error, verbose) {
+  const baseMessage = error instanceof Error ? error.message : String(error);
+  console.error(
+    `Warning: Could not update .gitignore (${baseMessage}). Add Basou's default .gitignore block manually.`
+  );
+  if (verbose && error instanceof Error) {
+    const label = extractCauseLabel(error);
+    if (label !== void 0) console.error(`Caused by: ${label}`);
+  }
 }
-async function probeStaleness(args) {
+async function resolveRepositoryRootForInit(cwd) {
   try {
-    const dry = await refreshAll({
-      options: { dryRun: true },
-      ctx: args.ctx,
-      paths: args.paths,
-      nowIso: args.nowIso
-    });
-    return {
-      newSessions: wouldImport(dry.claudeCode) + wouldImport(dry.codex),
-      updatedSessions: wouldUpdate(dry.claudeCode) + wouldUpdate(dry.codex),
-      unverifiableSessions: wouldBlock(dry.claudeCode) + wouldBlock(dry.codex)
-    };
-  } catch {
-    return null;
+    return await resolveRepositoryRoot7(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou init'.", {
+        cause: error
+      });
+    }
+    throw error;
   }
 }
 
-// src/commands/orient.ts
-function registerOrientCommand(program2) {
-  program2.command("orient").description("Show the workspace's current position (also writes .basou/orientation.md)").option("-q, --quiet", "Write the file without printing the body").option(
-    "--refresh",
-    "Import all adapters first (writes provenance), then show a guaranteed-fresh position; bare orient is read-only"
-  ).option("-v, --verbose", "Show error causes").action(async (opts) => {
-    await runOrient(opts);
+// src/commands/note.ts
+import {
+  acquireLock as acquireLock4,
+  appendEventToExistingSession as appendEventToExistingSession2,
+  assertBasouRootSafe as assertBasouRootSafe8,
+  basouPaths as basouPaths9,
+  createAdHocSessionWithEvent as createAdHocSessionWithEvent2,
+  findErrorCode as findErrorCode7,
+  readManifest as readManifest5,
+  resolveSessionId as resolveSessionId2
+} from "@basou/core";
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+var NOTE_SUBCOMMAND_LOOKALIKES = /* @__PURE__ */ new Set([
+  "list",
+  "ls",
+  "show",
+  "get",
+  "add",
+  "new",
+  "edit",
+  "rm",
+  "remove",
+  "delete",
+  "help"
+]);
+var LABEL_BODY_MAX = 80;
+var LABEL_TRUNCATE_HEAD2 = LABEL_BODY_MAX - 3;
+function registerNoteCommand(program2) {
+  program2.command("note").description("Record a free-text note (orientation surfaces the latest as the next step)").argument("<body>", "Note text", parseBody).option(
+    "--session <session_id>",
+    "Attach to an existing session; otherwise an ad-hoc session is created"
+  ).option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").action(async (body, options) => {
+    await runNote(body, options);
   });
 }
-async function runOrient(options, ctx = {}) {
+async function runNote(body, options, ctx = {}) {
   try {
-    await doRunOrient(options, ctx);
+    await doRunNote(body, options, ctx);
   } catch (error) {
-    renderCliError(error, { verbose: isVerbose(options) });
+    renderCliError(error, {
+      verbose: isVerbose(options),
+      classifiers: [failedToFinalizeClassifier]
+    });
     process.exitCode = 1;
   }
 }
-async function doRunOrient(options, ctx) {
+async function doRunNote(body, options, ctx) {
+  if (body.trim().length === 0) {
+    throw new Error("Note body must not be empty");
+  }
+  const reserved = body.trim().toLowerCase();
+  if (NOTE_SUBCOMMAND_LOOKALIKES.has(reserved)) {
+    throw new Error(
+      `'basou note' records a free-text note and has no '${body.trim()}' subcommand. To record a note, pass its full text (e.g. \`basou note "<your note>"\`).`
+    );
+  }
   const cwd = ctx.cwd ?? process.cwd();
-  const repositoryRoot = await resolveBasouRootForCommand(cwd, "orient");
+  const repositoryRoot = await resolveBasouRootForCommand(cwd, "note");
   const paths = basouPaths9(repositoryRoot);
   await assertWorkspaceInitialized7(paths.root);
-  const nowIso = (ctx.nowProvider?.() ?? /* @__PURE__ */ new Date()).toISOString();
-  const probeCtx = { cwd: repositoryRoot };
-  if (ctx.claudeProjectsDir !== void 0) probeCtx.claudeProjectsDir = ctx.claudeProjectsDir;
-  if (ctx.codexSessionsDir !== void 0) probeCtx.codexSessionsDir = ctx.codexSessionsDir;
-  if (options.refresh === true) {
-    await refreshAll({ options: {}, ctx: probeCtx, paths, nowIso });
-  }
-  const staleness = await probeStaleness({ ctx: probeCtx, paths, nowIso });
-  let federatedRoots = [];
-  try {
-    const hosts = await loadHostsConfig(ctx.hostsConfigPath);
-    if (hosts !== null) {
-      federatedRoots = hosts.map((h) => ({ paths: basouPaths9(h.path), host: h.label }));
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  if (options.session !== void 0) {
+    const sessionId = await resolveSessionId2(paths, options.session);
+    const sesId = sessionId;
+    const sessionLock = await acquireLock4(paths, "session", sesId);
+    let result;
+    try {
+      result = await appendEventToExistingSession2({
+        paths,
+        sessionId: sesId,
+        eventBuilder: (eventId) => buildNoteEvent({ eventId, sessionId: sesId, occurredAt, body })
+      });
+    } finally {
+      await sessionLock.release();
     }
-  } catch (error) {
-    console.error(
-      `basou: ignoring ~/.basou/hosts.yaml (${error instanceof Error ? error.message : String(error)}); showing local sessions only.`
-    );
+    printNoteResult(options, {
+      mode: "attached",
+      sessionId,
+      eventId: result.eventId,
+      sessionStatus: result.sessionStatus,
+      body
+    });
+    return;
   }
-  const result = await renderOrientation2({
+  const manifest = await readManifest5(paths);
+  const adHoc = await createAdHocSessionWithEvent2({
     paths,
-    nowIso,
-    staleness,
-    verbose: options.verbose === true,
-    federatedRoots,
-    onWarning: (w, sid) => printReplayWarning(w, sid),
-    onSessionSkip: (sid, reason) => printSessionSkip(sid, reason),
-    onTaskSkip: (taskId, reason) => printTaskSkip(taskId, reason),
-    onHostUnavailable: (host, error) => console.error(
-      `basou: host '${host}' mirror unreadable (${error instanceof Error ? error.message : String(error)}); skipping it.`
-    )
+    manifest,
+    label: buildAdHocLabel2(body),
+    occurredAt,
+    sessionSource: "human",
+    workingDirectory: repositoryRoot,
+    invocation: {
+      command: "basou note",
+      args: [body]
+    },
+    targetEventBuilders: [
+      (sessionId, eventId) => buildNoteEvent({ eventId, sessionId, occurredAt, body })
+    ]
   });
-  await writeMarkdownFile4(paths.files.orientation, `${result.body}
-`);
-  if (options.quiet === true) {
+  printNoteResult(options, {
+    mode: "ad-hoc",
+    sessionId: adHoc.sessionId,
+    eventId: adHoc.targetEventIds[0],
+    sessionStatus: "completed",
+    body
+  });
+}
+function buildNoteEvent(input) {
+  return {
+    schema_version: "0.1.0",
+    id: input.eventId,
+    session_id: input.sessionId,
+    occurred_at: input.occurredAt,
+    source: "local-cli",
+    type: "note_added",
+    body: input.body,
+    // `basou note` is the resume-hint command; mark it so orientation surfaces
+    // it as the next step and a plain `basou session note` annotation does not.
+    kind: "next_step"
+  };
+}
+function buildAdHocLabel2(body) {
+  const oneLine2 = body.replace(/\s+/g, " ").trim();
+  const truncated = oneLine2.length > LABEL_BODY_MAX ? `${oneLine2.slice(0, LABEL_TRUNCATE_HEAD2)}...` : oneLine2;
+  return `Ad-hoc note: ${truncated}`;
+}
+function parseBody(raw) {
+  if (raw.trim().length === 0) {
+    throw new InvalidArgumentError2("Note body must not be empty");
+  }
+  return raw;
+}
+function printNoteResult(options, result) {
+  const sid = shortSessionId(result.sessionId);
+  if (options.json === true) {
     console.log(
-      `Generated .basou/orientation.md (sessions: ${result.sessionCount}, in-flight tasks: ${result.inFlightTaskCount}, pending approvals: ${result.pendingApprovalsCount}, suspect: ${result.suspectCount})`
+      JSON.stringify({
+        event_id: result.eventId,
+        session_id: result.sessionId,
+        session_status: result.sessionStatus,
+        mode: result.mode,
+        body: result.body
+      })
     );
+    return;
+  }
+  if (result.mode === "ad-hoc") {
+    console.log(`Recorded note ${result.eventId} in ad-hoc session ${sid}`);
   } else {
-    console.log(result.body);
+    console.log(`Recorded note ${result.eventId} in session ${sid} (${result.sessionStatus})`);
   }
 }
 async function assertWorkspaceInitialized7(basouRoot) {
@@ -3920,7 +4340,7 @@ import {
   GENERATED_START,
   instructionMode,
   isGitNotFound,
-  parseMarkers as parseMarkers2,
+  parseMarkers as parseMarkers3,
   pathBasename,
   planArchive,
   planGitignore,
@@ -3928,7 +4348,7 @@ import {
   planRosterAdoption,
   planWorkspaceView,
   readManifest as readManifest6,
-  readMarkdownFile as readMarkdownFile5,
+  readMarkdownFile as readMarkdownFile6,
   reconcileSourceRoots,
   removeMarkerSection as removeMarkerSection2,
   renderAnchorStarter,
@@ -5362,7 +5782,7 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
   const canonicalName = basename5(real);
   let content;
   try {
-    content = await readMarkdownFile5(canonicalFileFor(anchorReal, canonicalName));
+    content = await readMarkdownFile6(canonicalFileFor(anchorReal, canonicalName));
   } catch {
     return {
       ...declared,
@@ -5382,7 +5802,7 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
       canonicalPresent: false
     };
   }
-  const section = parseMarkers2(content);
+  const section = parseMarkers3(content);
   return {
     ...declared,
     isAnchor: false,
@@ -5445,7 +5865,7 @@ function gatherViewPreset(repositoryRoot, anchorReal, viewName, roster) {
     }
     return { kind: "unreadable", canonicalName: viewName, viewName };
   }
-  const section = parseMarkers2(content);
+  const section = parseMarkers3(content);
   if (section.kind === "ok") {
     if (normalizeViewBlock(section.generated) === normalizeViewBlock(desiredBlock)) {
       return { kind: "in-sync", canonicalName: viewName, viewName };
@@ -5471,7 +5891,7 @@ async function applyViewPreset(anchorReal, outcome) {
   }
   if (isLink) throw new Error(`Canonical is a symlink in ${label}`);
   if (outcome.action === "create") mkdirSync(dirname3(file), { recursive: true });
-  const existing = await readMarkdownFile5(file);
+  const existing = await readMarkdownFile6(file);
   await writeMarkdownFile5(file, renderWithMarkers4(existing, outcome.block, label));
 }
 async function applyPresetPlan(anchorReal, plan) {
@@ -5485,7 +5905,7 @@ async function applyPresetPlan(anchorReal, plan) {
   }
   if (isLink) throw new Error(`Canonical is a symlink in ${label}`);
   if (plan.action === "create") mkdirSync(dirname3(file), { recursive: true });
-  const existing = await readMarkdownFile5(file);
+  const existing = await readMarkdownFile6(file);
   await writeMarkdownFile5(file, renderWithMarkers4(existing, plan.desiredBlock, label));
 }
 function presetFailureReason(error) {
@@ -5949,7 +6369,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
         });
       }
       if (content !== void 0 && content !== "") {
-        const section = parseMarkers2(content);
+        const section = parseMarkers3(content);
         if (section.kind === "ok" && canonicalShared) {
           items.push({
             kind: "canonical-block",
@@ -6078,7 +6498,7 @@ function applyRepoTeardown(repositoryRoot, manifest, plan) {
     }
     try {
       const content = readFileSync(fd, "utf8");
-      if (parseMarkers2(content).kind !== "ok") {
+      if (parseMarkers3(content).kind !== "ok") {
         changed(item.label);
         continue;
       }
@@ -6853,7 +7273,7 @@ function gatherViewRetrofit(repositoryRoot, anchorReal, viewPath, roster) {
     if (hasErrorCode(error) && error.code === "ENOENT") return { kind: "absent", viewName };
     return { kind: "unreadable", viewName };
   }
-  const section = parseMarkers2(content);
+  const section = parseMarkers3(content);
   if (section.kind === "ok") return { kind: "already-marked", viewName };
   if (section.kind === "no_markers") {
     const block = renderViewPresetBlock({
@@ -6874,7 +7294,7 @@ async function applyViewRetrofit(anchorReal, outcome) {
     isLink = false;
   }
   if (isLink) throw new Error(`Canonical is a symlink in ${label}`);
-  const existing = await readMarkdownFile5(file);
+  const existing = await readMarkdownFile6(file);
   await writeMarkdownFile5(file, seedMarkers(existing, outcome.block, label));
 }
 async function doRunProjectRetrofit(repo, options, ctx) {
@@ -7137,7 +7557,7 @@ function renderProjectRetrofit(result) {
 
 // src/commands/protocol.ts
 import { readFile as readFile4 } from "fs/promises";
-import { PROTOCOL_END, PROTOCOL_START, parseMarkers as parseMarkers3, readMarkdownFile as readMarkdownFile6 } from "@basou/core";
+import { PROTOCOL_END, PROTOCOL_START, parseMarkers as parseMarkers4, readMarkdownFile as readMarkdownFile7 } from "@basou/core";
 
 // src/lib/protocols-config.ts
 import { homedir as homedir8 } from "os";
@@ -7221,7 +7641,9 @@ var PROTOCOL_MARKERS = { start: PROTOCOL_START, end: PROTOCOL_END };
 var MANAGED_NOTE = "<!-- Managed by basou: 'basou protocol sync' regenerates everything between the BASOU:PROTOCOLS markers from ~/.basou/protocols.yaml. Manual edits inside the block are overwritten; edit the source files instead. -->";
 function registerProtocolCommand(program2) {
   const protocol = program2.command("protocol").description("Manage the basou-managed standing-protocol block in the global CLAUDE.md");
-  protocol.command("sync").description("Render declared protocols into the global CLAUDE.md (creates/updates the block)").option("--config <path>", "Path to protocols.yaml (default ~/.basou/protocols.yaml)").option("--target <path>", "Override the target file (intended for tests)").option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (opts) => {
+  protocol.command("sync").description(
+    "Render declared protocols into ~/.claude/CLAUDE.md (creates/updates the block). That file is user-global: Claude Code auto-loads it for every project on the machine, so what the protocols say is in the context of every workspace's sessions \u2014 keep workspace-specific facts out of them."
+  ).option("--config <path>", "Path to protocols.yaml (default ~/.basou/protocols.yaml)").option("--target <path>", "Override the target file (intended for tests)").option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (opts) => {
     await runProtocolSync(opts);
   });
   protocol.command("list").description("List declared protocols and whether the block is installed").option("--config <path>", "Path to protocols.yaml (default ~/.basou/protocols.yaml)").option("--target <path>", "Override the target file (intended for tests)").option("-v, --verbose", "Show error causes").action(async (opts) => {
@@ -7320,8 +7742,8 @@ async function doRunProtocolList(options) {
   const configPath = options.config ?? DEFAULT_PROTOCOLS_CONFIG_PATH;
   const target = options.target ?? DEFAULT_TARGET_PATH;
   const entries = await loadProtocolsConfig(configPath);
-  const existing = await readMarkdownFile6(target);
-  const installed = existing !== null && parseMarkers3(existing, PROTOCOL_MARKERS).kind === "ok";
+  const existing = await readMarkdownFile7(target);
+  const installed = existing !== null && parseMarkers4(existing, PROTOCOL_MARKERS).kind === "ok";
   console.log(`Declared protocols (${entries.length}):`);
   for (const entry of entries) {
     console.log(`  - ${entry.title ?? entry.source}`);
@@ -7356,21 +7778,6 @@ import {
 } from "@basou/core";
 import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
 
-// src/lib/channel-policy.ts
-function decideCodexChannel(manifest) {
-  if (manifest.policies?.confidential === true) return { write: false, reason: "confidential" };
-  if (manifest.channels?.codex === true) return { write: true };
-  return { write: false, reason: "not_enabled" };
-}
-function describeCodexChannelSkip(reason) {
-  switch (reason) {
-    case "confidential":
-      return "codex channel: skipped (confidential workspace \u2014 nothing is written to the user-global ~/.codex/AGENTS.md)";
-    case "not_enabled":
-      return "codex channel: skipped (this workspace has not opted in; the user-global ~/.codex/AGENTS.md is left untouched \u2014 see docs/spec/schemas.md \xA74.2)";
-  }
-}
-
 // src/commands/refresh-watch.ts
 import { readdir as readdir2, stat as stat5 } from "fs/promises";
 import { homedir as homedir9 } from "os";
@@ -7522,7 +7929,7 @@ function abortableSleep(ms, signal) {
 }
 function registerRefreshCommand(program2) {
   program2.command("refresh").description(
-    "Import all adapters for the project and regenerate handoff + decisions in one step"
+    "Import all adapters for the project and regenerate handoff + decisions in one step. Writes only inside the workspace's .basou/ \u2014 never to a user-global file another project's tool reads (a Codex session gets the position from the SessionStart hook; see `basou hook install codex`)."
   ).option(
     "--project <path>",
     "Source project path to import (repeatable; defaults to the manifest source roots, then the repository root)",
@@ -7653,47 +8060,23 @@ async function computeRefresh(options, ctx) {
 }
 async function doRunRefresh(options, ctx) {
   const { result, paths } = await computeRefresh(options, ctx);
-  const channel = options.dryRun === true ? { outcome: { status: "skipped", reason: "dry_run" }, line: null } : await syncCodexOrientationChannel(paths, ctx.codexChannelPath);
-  const reported = { ...result, codexChannel: channel.outcome };
+  const reported = { ...result, codexChannel: { status: "retired" } };
   if (options.json === true) {
     console.log(JSON.stringify(reported));
   } else {
     printRefreshSummary(result);
-    if (channel.line !== null) console.log(channel.line);
+    const line = await retiredChannelNotice(paths);
+    if (line !== null) console.log(line);
   }
   return reported;
 }
-async function syncCodexOrientationChannel(paths, channelPath) {
-  let decision;
-  try {
-    decision = decideCodexChannel(await readManifest7(paths));
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    return {
-      outcome: { status: "skipped", reason: "error", detail },
-      line: `codex channel: skipped (manifest could not be re-read, so the opt-in cannot be confirmed: ${detail})`
-    };
-  }
-  if (!decision.write) {
-    return {
-      outcome: { status: "skipped", reason: decision.reason },
-      line: describeCodexChannelSkip(decision.reason)
-    };
-  }
+async function retiredChannelNotice(paths) {
   try {
-    const rendered = await renderOrientationToCodexChannel({
-      orientationPath: paths.files.orientation,
-      ...channelPath !== void 0 ? { channelPath } : {}
-    });
-    if (rendered === null)
-      return { outcome: { status: "skipped", reason: "no_orientation" }, line: null };
-    return { outcome: { status: "written", action: rendered.action }, line: rendered.line };
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    return {
-      outcome: { status: "skipped", reason: "error", detail },
-      line: `codex channel skipped: ${detail}`
-    };
+    const manifest = await readManifest7(paths);
+    if (manifest.channels?.codex !== true) return null;
+    return "codex channel: retired \u2014 the manifest's channels.codex is ignored; a Codex session now receives this workspace's position from the SessionStart hook (see `basou hook status codex`), and nothing is written to the user-global ~/.codex/AGENTS.md";
+  } catch {
+    return null;
   }
 }
 function describeImport(outcome) {
@@ -8271,7 +8654,7 @@ function unattachedLines(u) {
 }
 
 // src/commands/run.ts
-import { mkdir as mkdir2 } from "fs/promises";
+import { mkdir as mkdir2, readFile as readFile6 } from "fs/promises";
 import { homedir as homedir11 } from "os";
 import { join as join14 } from "path";
 import {
@@ -8283,6 +8666,7 @@ import {
   codexAdapterMetadata,
   appendChainedEvent as coreAppendChainedEvent2,
   finalizeSessionYaml as finalizeSessionYaml2,
+  findBasouSessionStartHook as findBasouSessionStartHook2,
   getDiff,
   getSnapshot as getSnapshot2,
   overwriteYamlFile as overwriteYamlFile2,
@@ -8334,7 +8718,7 @@ function runCodex(args, options, ctx = {}) {
     resolveCommand: ctx.resolveCodexCommand ?? resolveCodexCommand,
     metadata: codexAdapterMetadata,
     transformArgs: (a) => ["-c", "shell_environment_policy.inherit=all", ...a],
-    preSpawn: syncCodexOrientationChannelPreSpawn
+    preSpawn: noteCodexHookStatusPreSpawn
   });
 }
 async function runTrackedTool(args, options, ctx, adapter) {
@@ -8701,24 +9085,25 @@ async function resolveRepositoryRootForRun(cwd) {
     throw error;
   }
 }
-async function syncCodexOrientationChannelPreSpawn(cwd, ctx) {
+async function noteCodexHookStatusPreSpawn(_cwd, ctx) {
+  const hooksPath = ctx.codexHooksPath ?? DEFAULT_CODEX_HOOKS_PATH;
+  let location;
   try {
-    const root = await resolveBasouRootForCommand(cwd, "run");
-    const paths = basouPaths15(root);
-    const decision = decideCodexChannel(await readManifest9(paths));
-    if (!decision.write) return describeCodexChannelSkip(decision.reason);
-    const rendered = await renderOrientationToCodexChannel({
-      orientationPath: paths.files.orientation,
-      ...ctx.codexChannelPath !== void 0 ? { channelPath: ctx.codexChannelPath } : {}
-    });
-    return rendered === null ? null : rendered.line;
-  } catch {
-    return null;
+    location = findBasouSessionStartHook2(JSON.parse(await readFile6(hooksPath, "utf8")));
+  } catch (error) {
+    if (!(error instanceof Error && error.code === "ENOENT")) return null;
+    location = null;
+  }
+  if (location === null) {
+    return "codex: the basou SessionStart hook is not registered, so this session starts without the workspace's position (`basou hook install codex` registers it once for every workspace)";
   }
+  const trust = await codexHookTrustFor(hooksPath, location, ctx.codexConfigPath);
+  if (trust.status === "trusted" || trust.status === "unknown") return null;
+  return `codex: the basou SessionStart hook is registered but ${describeCodexHookTrust(trust)}, so this session starts without the workspace's position`;
 }
 
 // src/commands/session.ts
-import { readFile as readFile6 } from "fs/promises";
+import { readFile as readFile7 } from "fs/promises";
 import { basename as basename6, isAbsolute as isAbsolute6, join as join15, relative as relative3 } from "path";
 import {
   acquireLock as acquireLock6,
@@ -9169,7 +9554,7 @@ async function doRunSessionImport(options, ctx) {
 }
 async function readInputFile(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile7(path, "utf8");
   } catch (error) {
     if (findErrorCode12(error, "ENOENT")) {
       throw new Error("Import source not found", { cause: error });
@@ -9286,7 +9671,7 @@ async function doRunSessionNote(sessionIdInput, options, ctx) {
 }
 async function readNoteFile(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile7(path, "utf8");
   } catch (error) {
     if (findErrorCode12(error, "ENOENT")) {
       throw new Error("Note source not found", { cause: error });
@@ -9607,7 +9992,7 @@ function formatVersionGateMessage(error) {
 }
 
 // src/commands/task.ts
-import { readFile as readFile7 } from "fs/promises";
+import { readFile as readFile8 } from "fs/promises";
 import { join as join16 } from "path";
 import {
   archiveTask,
@@ -10622,7 +11007,7 @@ function parsePositiveInt2(raw) {
 }
 async function readDescriptionFile(path) {
   try {
-    return await readFile7(path, "utf8");
+    return await readFile8(path, "utf8");
   } catch (error) {
     if (findErrorCode15(error, "ENOENT")) {
       throw new Error("Description source not found", { cause: error });
@@ -10826,7 +11211,7 @@ async function assertWorkspaceInitialized14(basouRoot) {
 
 // src/commands/view.ts
 import { spawn } from "child_process";
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { basename as basename9, resolve as resolve13 } from "path";
 import {
   assertBasouRootSafe as assertBasouRootSafe18,
@@ -11151,7 +11536,7 @@ function inertLines(result) {
 
 // src/lib/portfolio-safety.ts
 import { execFile } from "child_process";
-import { lstat as lstat2, realpath as realpath2 } from "fs/promises";
+import { lstat as lstat2, realpath as realpath3 } from "fs/promises";
 import { isAbsolute as isAbsolute7, join as join18, relative as relative4, resolve as resolve11 } from "path";
 import { promisify } from "util";
 import { readManifest as readManifest14 } from "@basou/core";
@@ -11161,7 +11546,7 @@ function errorCode(error) {
 }
 async function canonical(p) {
   try {
-    return await realpath2(p);
+    return await realpath3(p);
   } catch {
     return resolve11(p);
   }
@@ -11341,7 +11726,7 @@ import {
   loadTaskEntries as loadTaskEntries2,
   readAllEvents as readAllEvents2,
   readManifest as readManifest15,
-  readMarkdownFile as readMarkdownFile7,
+  readMarkdownFile as readMarkdownFile8,
   readSessionYaml as readSessionYaml3,
   readTaskFile as readTaskFile2,
   renderDecisions as renderDecisions3,
@@ -12393,7 +12778,7 @@ async function taskDetail(ws, taskId) {
   }
 }
 async function decisionsView(ws, nowProvider) {
-  const fromDisk = await readMarkdownFile7(ws.paths.files.decisions);
+  const fromDisk = await readMarkdownFile8(ws.paths.files.decisions);
   if (fromDisk !== null) {
     return { body: fromDisk, fromDisk: true };
   }
@@ -12416,7 +12801,7 @@ async function approvalsView(ws, nowProvider) {
   return { pending: await toViews(ids.pending), resolved: await toViews(ids.resolved) };
 }
 async function handoffView(ws, nowProvider) {
-  const fromDisk = await readMarkdownFile7(ws.paths.files.handoff);
+  const fromDisk = await readMarkdownFile8(ws.paths.files.handoff);
   if (fromDisk !== null) {
     return { body: fromDisk, fromDisk: true };
   }
@@ -12650,7 +13035,7 @@ async function buildWorkspaceEntry(repoRoot, ctx, labelOverride) {
   } catch (error) {
     const notFound = error instanceof Error && error.message === "YAML file not found";
     return {
-      key: `ws-${createHash("sha1").update(repoRoot).digest("hex").slice(0, 12)}`,
+      key: `ws-${createHash2("sha1").update(repoRoot).digest("hex").slice(0, 12)}`,
       label: labelOverride ?? basename9(repoRoot),
       paths,
       repoRoot,