@basou/cli 0.38.0 → 0.40.0

package/dist/index.js

@@ -632,10 +632,217 @@ function printNoApprovals(options) {
   }
 }
 
+// src/lib/context-channel.ts
+import { homedir } from "os";
+import { join as join3 } from "path";
+import {
+  ORIENTATION_END,
+  ORIENTATION_START,
+  parseMarkers,
+  readMarkdownFile,
+  removeMarkerSection
+} from "@basou/core";
+
+// src/lib/durable-write.ts
+import { randomUUID } from "crypto";
+import { lstat, open, rename, stat, unlink as unlink2 } from "fs/promises";
+import { basename, dirname, join as join2 } from "path";
+async function assertNotSymlink(targetPath) {
+  try {
+    const st = await lstat(targetPath);
+    if (st.isSymbolicLink()) {
+      throw new Error(
+        "Refusing to write through a symlink. Replace the symlinked target with a regular file (or remove it) and retry."
+      );
+    }
+  } catch (error) {
+    if (error instanceof Error && error.code === "ENOENT") return;
+    throw error;
+  }
+}
+async function writeFileDurable(targetPath, content) {
+  const dir = dirname(targetPath);
+  const tmpPath = join2(dir, `.${basename(targetPath)}.tmp.${randomUUID()}`);
+  let mode = 420;
+  try {
+    mode = (await stat(targetPath)).mode & 511;
+  } catch (error) {
+    if (!(error instanceof Error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+  let handle;
+  try {
+    handle = await open(tmpPath, "wx", mode);
+    await handle.writeFile(content, "utf8");
+    await handle.chmod(mode);
+    await handle.sync();
+    await handle.close();
+    handle = void 0;
+    await rename(tmpPath, targetPath);
+  } catch (error) {
+    if (handle) await handle.close().catch(() => void 0);
+    await unlink2(tmpPath).catch(() => void 0);
+    throw error;
+  }
+  try {
+    const dirHandle = await open(dir, "r");
+    try {
+      await dirHandle.sync();
+    } finally {
+      await dirHandle.close();
+    }
+  } catch {
+  }
+}
+
+// src/lib/context-channel.ts
+var CODEX_TARGET_PATH = join3(homedir(), ".codex", "AGENTS.md");
+var ORIENTATION_MARKERS = { start: ORIENTATION_START, end: ORIENTATION_END };
+function buildTargetBody(existing, block, markers) {
+  const wrapped = `${markers.start}
+${block}${markers.end}
+`;
+  if (existing === null || existing === "") return wrapped;
+  const section = parseMarkers(existing, markers);
+  switch (section.kind) {
+    case "ok":
+      return `${section.before}${markers.start}
+${block}${markers.end}${section.after}`;
+    case "no_markers": {
+      const sep = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+      return `${existing}${sep}${wrapped}`;
+    }
+    default:
+      throw new Error(
+        "The basou-managed markers in the target are malformed (a marker is missing, duplicated, or out of order). Fix or remove them, then retry."
+      );
+  }
+}
+async function backupOnce(target, existing) {
+  const bak = `${target}.basou-bak`;
+  const already = await readMarkdownFile(bak);
+  if (already !== null) return;
+  await writeFileDurable(bak, existing ?? "");
+}
+async function syncMarkerBlock(opts) {
+  const { target, markers, block } = opts;
+  await assertNotSymlink(target);
+  const existing = await readMarkdownFile(target);
+  const newBody = buildTargetBody(existing, block, markers);
+  if (newBody === existing) return { action: "unchanged" };
+  const hadBlock = existing !== null && parseMarkers(existing, markers).kind === "ok";
+  const action = hadBlock ? "updated" : "installed";
+  if (opts.dryRun === true) return { action };
+  const recheck = await readMarkdownFile(target);
+  if (recheck !== existing) {
+    throw new Error(
+      "The target changed during sync; aborting so a concurrent edit is not overwritten. Re-run the command."
+    );
+  }
+  await backupOnce(target, existing);
+  await writeFileDurable(target, newBody);
+  return { action };
+}
+function assertNoMarkerLine(body, markers) {
+  for (const line of body.split(/\r?\n/)) {
+    if (line === markers.start || line === markers.end) {
+      throw new Error(
+        "The content contains a basou marker line, which would corrupt the managed block. Remove that line from the source."
+      );
+    }
+  }
+}
+async function removeMarkerBlock(opts) {
+  const { target, markers, fileLabel } = opts;
+  await assertNotSymlink(target);
+  const existing = await readMarkdownFile(target);
+  if (existing === null) return { removed: false };
+  const newBody = removeMarkerSection(existing, fileLabel, markers);
+  if (newBody === existing) return { removed: false };
+  if (opts.dryRun === true) return { removed: true };
+  const recheck = await readMarkdownFile(target);
+  if (recheck !== existing) {
+    throw new Error(
+      "The target changed during unsync; aborting so a concurrent edit is not overwritten. Re-run the command."
+    );
+  }
+  if (opts.backup !== false) await backupOnce(target, existing);
+  await writeFileDurable(target, newBody);
+  return { removed: true };
+}
+async function clearOrientationChannel(opts) {
+  return removeMarkerBlock({
+    target: opts.target ?? CODEX_TARGET_PATH,
+    markers: ORIENTATION_MARKERS,
+    // Name the file actually acted on, so an error under the test seam does not
+    // point at the locked path.
+    fileLabel: opts.target ?? "~/.codex/AGENTS.md",
+    // The block is being removed because it should not be on this machine;
+    // preserving it in `.basou-bak` would defeat the command.
+    backup: false,
+    ...opts.dryRun === true ? { dryRun: true } : {}
+  });
+}
+
+// src/commands/channel.ts
+function registerChannelCommand(program2) {
+  const channel = program2.command("channel").description(
+    "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 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);
+  });
+}
+async function runChannelClear(face, options) {
+  if (face !== "codex") {
+    console.error(
+      `Unknown face '${face}'. Faces: codex (~/.codex/AGENTS.md). The basou:protocols block in ~/.claude/CLAUDE.md is removed with \`basou protocol unsync\`.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    await doRunChannelClear(face, options);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunChannelClear(face, options) {
+  const isDry = options.dryRun === true;
+  const { removed } = await clearOrientationChannel({
+    ...options.target !== void 0 ? { target: options.target } : {},
+    ...isDry ? { dryRun: true } : {}
+  });
+  const target = options.target ?? CODEX_TARGET_PATH;
+  const label = options.target ?? "~/.codex/AGENTS.md";
+  const result = { face, target, removed, dry_run: isDry };
+  if (options.json === true) {
+    console.log(JSON.stringify(result));
+    return result;
+  }
+  if (!removed) {
+    console.log(`Nothing to clear: ${label} carries no basou:orientation block.`);
+  } else if (isDry) {
+    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, and nothing renders it again.`
+    );
+  }
+  return result;
+}
+
 // src/commands/decision.ts
 import { readFile } from "fs/promises";
-import { homedir as homedir2 } from "os";
-import { join as join3, resolve as resolve3 } from "path";
+import { homedir as homedir3 } from "os";
+import { join as join5, resolve as resolve3 } from "path";
 import {
   AGENT_INFRA_DIRS,
   acquireLock as acquireLock2,
@@ -657,18 +864,18 @@ import {
 import { InvalidArgumentError } from "commander";
 
 // src/lib/repo-root.ts
-import { realpath, stat } from "fs/promises";
-import { basename, resolve as resolve2 } from "path";
+import { realpath, stat as stat2 } from "fs/promises";
+import { basename as basename2, resolve as resolve2 } from "path";
 import { basouPaths as basouPaths2, readManifest, resolveBasouRepositoryRoot } from "@basou/core";
 
 // src/lib/portfolio-config.ts
-import { homedir } from "os";
-import { isAbsolute, join as join2, resolve } from "path";
+import { homedir as homedir2 } from "os";
+import { isAbsolute, join as join4, resolve } from "path";
 import { readYamlFile as readYamlFile2 } from "@basou/core";
-var DEFAULT_PORTFOLIO_CONFIG_PATH = join2(homedir(), ".basou", "portfolio.yaml");
+var DEFAULT_PORTFOLIO_CONFIG_PATH = join4(homedir2(), ".basou", "portfolio.yaml");
 function expandTilde(p) {
-  if (p === "~") return homedir();
-  if (p.startsWith("~/")) return join2(homedir(), p.slice(2));
+  if (p === "~") return homedir2();
+  if (p.startsWith("~/")) return join4(homedir2(), p.slice(2));
   return p;
 }
 function isRecord(value) {
@@ -750,7 +957,7 @@ async function resolveBasouRootForCommand(cwd, commandName, opts = {}) {
 }
 async function hasBasouStore(root) {
   try {
-    return (await stat(basouPaths2(root).root)).isDirectory();
+    return (await stat2(basouPaths2(root).root)).isDirectory();
   } catch {
     return false;
   }
@@ -782,7 +989,7 @@ async function resolveMemberToMaster(repoRoot, configPath) {
     } catch (error) {
       if (error instanceof Error && error.message !== "YAML file not found") {
         console.error(
-          `Skipping portfolio workspace '${ws.label ?? basename(masterReal)}': could not read its manifest (${error.message}).`
+          `Skipping portfolio workspace '${ws.label ?? basename2(masterReal)}': could not read its manifest (${error.message}).`
         );
       }
       continue;
@@ -791,7 +998,7 @@ async function resolveMemberToMaster(repoRoot, configPath) {
     for (const sr of sourceRoots) {
       const real = await realpathOrNull(resolve2(masterReal, sr));
       if (real !== null && real === memberReal) {
-        claimants.set(masterReal, { root: masterReal, label: ws.label ?? basename(masterReal) });
+        claimants.set(masterReal, { root: masterReal, label: ws.label ?? basename2(masterReal) });
         break;
       }
     }
@@ -1044,7 +1251,7 @@ async function doRunDecisionCapture(options, ctx) {
     "--file",
     sanitizePath(resolve3(cwd, options.file), {
       workingDirectory: repositoryRoot,
-      homedir: homedir2()
+      homedir: homedir3()
     })
   ] : [];
   const adHoc = await createAdHocSessionWithEvent({
@@ -1181,7 +1388,7 @@ function isDecisionId(value) {
 async function decisionExists(paths, decisionId) {
   const entries = await loadSessionEntries(paths, { now: /* @__PURE__ */ new Date() });
   for (const entry of entries) {
-    const sessionDir = join3(paths.sessions, entry.sessionId);
+    const sessionDir = join5(paths.sessions, entry.sessionId);
     try {
       for await (const ev of replayEvents2(sessionDir, {})) {
         if (ev.type === "decision_recorded" && ev.decision_id === decisionId) return true;
@@ -1576,7 +1783,7 @@ import {
   assertBasouRootSafe as assertBasouRootSafe3,
   basouPaths as basouPaths4,
   findErrorCode as findErrorCode3,
-  readMarkdownFile,
+  readMarkdownFile as readMarkdownFile2,
   renderDecisions,
   renderWithMarkers,
   resolveRepositoryRoot as resolveRepositoryRoot3,
@@ -1609,7 +1816,7 @@ async function doRunDecisionsGenerate(options, ctx) {
     onWarning: (w, sid) => printReplayWarning(w, sid),
     onSessionSkip: (sid, reason) => printSessionSkip(sid, reason)
   });
-  const existing = await readMarkdownFile(paths.files.decisions);
+  const existing = await readMarkdownFile2(paths.files.decisions);
   const finalBody = renderWithMarkers(existing, result.body, "decisions.md");
   await writeMarkdownFile(paths.files.decisions, finalBody);
   console.log(`Generated .basou/decisions.md (decisions: ${result.decisionCount})`);
@@ -1640,8 +1847,8 @@ async function assertWorkspaceInitialized3(basouRoot) {
 
 // src/commands/exec.ts
 import { mkdir } from "fs/promises";
-import { homedir as homedir3 } from "os";
-import { join as join4 } from "path";
+import { homedir as homedir4 } from "os";
+import { join as join6 } from "path";
 import {
   acquireLock as acquireLock3,
   assertBasouRootSafe as assertBasouRootSafe4,
@@ -1681,13 +1888,13 @@ async function runExec(command, args, options, ctx = {}) {
   await assertBasouRootSafe4(paths.root);
   const manifest = await readManifest3(paths);
   const sessionId = prefixedUlid3("ses");
-  const sessionDir = join4(paths.sessions, sessionId);
+  const sessionDir = join6(paths.sessions, sessionId);
   await mkdir(sessionDir, { recursive: true });
   const appendEvent = ctx.appendEvent ?? (async (_sessionDir, event) => {
     await coreAppendChainedEvent(paths, sessionId, event);
   });
   const startedAt = now().toISOString();
-  const sessionYamlPath = join4(sessionDir, "session.yaml");
+  const sessionYamlPath = join6(sessionDir, "session.yaml");
   const session = buildInitialSession({
     id: sessionId,
     command,
@@ -1892,7 +2099,7 @@ function buildInitialSession(input) {
       source: { kind: "terminal", version: "0.1.0" },
       started_at: input.startedAt,
       status: "initialized",
-      working_directory: sanitizeWorkingDirectory(input.cwd, { homedir: homedir3() }),
+      working_directory: sanitizeWorkingDirectory(input.cwd, { homedir: homedir4() }),
       invocation: {
         command: input.command,
         args: [...input.args],
@@ -1968,7 +2175,7 @@ import {
   assertBasouRootSafe as assertBasouRootSafe5,
   basouPaths as basouPaths6,
   findErrorCode as findErrorCode4,
-  readMarkdownFile as readMarkdownFile2,
+  readMarkdownFile as readMarkdownFile3,
   renderHandoff,
   renderWithMarkers as renderWithMarkers2,
   resolveRepositoryRoot as resolveRepositoryRoot5,
@@ -2002,7 +2209,7 @@ async function doRunHandoffGenerate(options, ctx) {
     onSessionSkip: (sid, reason) => printSessionSkip(sid, reason),
     onTaskSkip: (taskId, reason) => printTaskSkip(taskId, reason)
   });
-  const existing = await readMarkdownFile2(paths.files.handoff);
+  const existing = await readMarkdownFile3(paths.files.handoff);
   const finalBody = renderWithMarkers2(existing, result.body, "handoff.md");
   await writeMarkdownFile2(paths.files.handoff, finalBody);
   console.log(
@@ -2034,395 +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 homedir4 } from "os";
-import { join as join6 } 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";
 
-// src/lib/durable-write.ts
-import { randomUUID } from "crypto";
-import { lstat, open, rename, stat as stat2, unlink as unlink2 } from "fs/promises";
-import { basename as basename2, dirname, join as join5 } from "path";
-async function assertNotSymlink(targetPath) {
-  try {
-    const st = await lstat(targetPath);
-    if (st.isSymbolicLink()) {
-      throw new Error(
-        "Refusing to write through a symlink. Replace the symlinked target with a regular file (or remove it) and retry."
-      );
-    }
-  } catch (error) {
-    if (error instanceof Error && error.code === "ENOENT") return;
-    throw error;
+// 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;
+}
+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 value;
 }
-async function writeFileDurable(targetPath, content) {
-  const dir = dirname(targetPath);
-  const tmpPath = join5(dir, `.${basename2(targetPath)}.tmp.${randomUUID()}`);
-  let mode = 420;
-  try {
-    mode = (await stat2(targetPath)).mode & 511;
-  } catch (error) {
-    if (!(error instanceof Error && error.code === "ENOENT")) {
-      throw error;
-    }
+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})`;
   }
-  let handle;
+}
+
+// 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 isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function loadHostsConfig(configPath = DEFAULT_HOSTS_CONFIG_PATH) {
+  let raw;
   try {
-    handle = await open(tmpPath, "wx", mode);
-    await handle.writeFile(content, "utf8");
-    await handle.chmod(mode);
-    await handle.sync();
-    await handle.close();
-    handle = void 0;
-    await rename(tmpPath, targetPath);
+    raw = await readYamlFile4(configPath);
   } catch (error) {
-    if (handle) await handle.close().catch(() => void 0);
-    await unlink2(tmpPath).catch(() => 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;
   }
-  try {
-    const dirHandle = await open(dir, "r");
-    try {
-      await dirHandle.sync();
-    } finally {
-      await dirHandle.close();
-    }
-  } catch {
+  if (!isRecord2(raw) || !Array.isArray(raw.hosts)) {
+    throw new Error("~/.basou/hosts.yaml must contain a 'hosts:' list.");
   }
-}
-
-// src/commands/hook.ts
-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
+  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'.");
     }
-  });
-  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 {
+    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'.");
     }
-  }
-  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 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 parseMinEdits(raw) {
-  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
-  return Number(raw);
-}
-var DEFAULT_CLAUDE_SETTINGS_PATH = join6(homedir4(), ".claude", "settings.json");
-function resolveCliEntry() {
-  return fileURLToPath(import.meta.url);
-}
-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.");
+    const expanded = expandTilde2(entry.path.trim());
+    if (!isAbsolute2(expanded)) {
+      throw new Error("Host paths must be absolute (or start with '~').");
     }
-    out.minEdits = parsed;
-  }
-  return out;
-}
-async function readSettings(path) {
-  let raw;
-  try {
-    raw = await readFile2(path, "utf8");
-  } catch (error) {
-    if (error instanceof Error && error.code === "ENOENT") {
-      return { raw: null, parsed: void 0 };
+    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.`);
     }
-    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;
-  }
-  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;
-  }
-}
-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;
+    seenPaths.add(abs);
+    seenLabels.add(label);
+    result.push({ label, path: abs });
   }
-  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 { homedir as homedir5 } from "os";
-import { basename as basename3, dirname as dirname2, join as join7, resolve as resolve4 } from "path";
+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 resolve5 } from "path";
 import { createInterface } from "readline";
 import {
   AGENT_INFRA_DIRS as AGENT_INFRA_DIRS2,
@@ -2492,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)];
 }
@@ -2508,7 +2546,7 @@ async function doRunImportClaudeCode(options, ctx) {
     repoRoot: repositoryRoot,
     cwd: ctx.cwd ?? process.cwd()
   });
-  const projectsRoot = ctx.claudeProjectsDir ?? join7(homedir5(), ".claude", "projects");
+  const projectsRoot = ctx.claudeProjectsDir ?? join8(homedir6(), ".claude", "projects");
   const files = await selectTranscriptFiles(projectsRoot, projectPaths, options);
   const projectSet = new Set(projectPaths);
   const candidates = files.map((file) => {
@@ -2547,7 +2585,7 @@ async function doRunImportCodex(options, ctx) {
     repoRoot: repositoryRoot,
     cwd: ctx.cwd ?? process.cwd()
   });
-  const sessionsRoot = ctx.codexSessionsDir ?? join7(homedir5(), ".codex", "sessions");
+  const sessionsRoot = ctx.codexSessionsDir ?? join8(homedir6(), ".codex", "sessions");
   const rollouts = await discoverCodexRollouts(sessionsRoot, projectPaths, options);
   const candidates = rollouts.map(({ file, externalId }) => ({
     externalId,
@@ -2668,943 +2706,1503 @@ async function importDerivedSessions(paths, manifest, options, sourceKind, candi
       await noteCrossProject(externalId, payload2);
       continue;
     }
-    const payload = validate(await toPayload());
-    if (payload === null) {
-      counts.skippedNoAction++;
-      continue;
+    const payload = validate(await toPayload());
+    if (payload === null) {
+      counts.skippedNoAction++;
+      continue;
+    }
+    if (priors.length > 0 && options.force === true) {
+      if (options.dryRun !== true) {
+        for (const { sessionId } of priors) {
+          await rm(join8(paths.sessions, sessionId), { recursive: true, force: true });
+        }
+      }
+      counts.replaced++;
+    }
+    const result = await importSessionFromJson(paths, manifest, payload, {
+      dryRun: options.dryRun === true
+    });
+    results.push(result);
+    seenThisRun.add(externalId);
+    sanitizedPaths += result.pathSanitizeReport.relatedFiles + (result.pathSanitizeReport.workingDirectoryRewritten ? 1 : 0);
+    await noteCrossProject(externalId, payload);
+  }
+  if (sanitizedPaths > 0) {
+    console.error(`Imported sessions: ${sanitizedPaths} path(s) sanitized`);
+  }
+  if (crossProject.length > 0) {
+    const PATH_SAMPLE = 5;
+    for (const { externalId, outOfRoot } of crossProject) {
+      const sample = outOfRoot.slice(0, PATH_SAMPLE).join(", ");
+      const more = outOfRoot.length > PATH_SAMPLE ? ` (... +${outOfRoot.length - PATH_SAMPLE} more)` : "";
+      console.error(
+        `basou: session ${externalId} edited ${outOfRoot.length} file(s) outside this project's source_roots: ${sample}${more} \u2014 they may belong to another project.`
+      );
+    }
+  }
+  printImportResult(options, results, counts);
+}
+async function classifyReimport(priors, sourcePath, externalId, counts) {
+  if (priors.length > 1) {
+    console.error(
+      `Import: ${externalId} has ${priors.length} prior sessions; re-import skipped (use --force)`
+    );
+    counts.skippedDuplicate++;
+    return null;
+  }
+  const prior = priors[0];
+  if (prior === void 0) {
+    counts.skippedExisting++;
+    return null;
+  }
+  const currentSize = await statSize(sourcePath);
+  if (currentSize === void 0) {
+    counts.skippedExisting++;
+    return null;
+  }
+  if (prior.sourceSizeBytes === void 0) {
+    counts.skippedLegacy++;
+    return null;
+  }
+  if (currentSize === prior.sourceSizeBytes) {
+    counts.skippedExisting++;
+    return null;
+  }
+  if (currentSize < prior.sourceSizeBytes) {
+    console.error(
+      `Import: ${externalId} source shrank (${currentSize} < ${prior.sourceSizeBytes} bytes); re-import skipped (use --force to replace)`
+    );
+    counts.skippedDecreased++;
+    return null;
+  }
+  return prior;
+}
+function encodeProjectDir(projectPath) {
+  return projectPath.replace(/[^a-zA-Z0-9]/g, "-");
+}
+function firstTranscriptCwd(records) {
+  for (const record of records) {
+    const cwd = record.cwd;
+    if (typeof cwd === "string" && cwd.length > 0) return cwd;
+  }
+  return void 0;
+}
+async function loadExistingByExternalId(paths, sourceKind) {
+  const byExternalId = /* @__PURE__ */ new Map();
+  const add = (externalId, prior) => {
+    const list = byExternalId.get(externalId);
+    if (list === void 0) byExternalId.set(externalId, [prior]);
+    else list.push(prior);
+  };
+  let sessionIds;
+  try {
+    sessionIds = await enumerateSessionDirs(paths);
+  } catch {
+    return byExternalId;
+  }
+  for (const sessionId of sessionIds) {
+    let session;
+    try {
+      session = await readSessionYaml2(paths, sessionId);
+    } catch {
+      continue;
+    }
+    if (session.session.source.kind !== sourceKind) continue;
+    const sourceSizeBytes = session.session.source.source_size_bytes;
+    const prior = sourceSizeBytes !== void 0 ? { sessionId, sourceSizeBytes } : { sessionId };
+    const ext = session.session.source.external_id;
+    if (typeof ext === "string" && ext.length > 0) {
+      add(ext, prior);
+      continue;
+    }
+    const label = session.session.label;
+    const match = typeof label === "string" ? label.match(/^claude-code import (\S+)$/) : null;
+    if (match?.[1] !== void 0) add(match[1], prior);
+  }
+  return byExternalId;
+}
+async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
+  if (options.session !== void 0) {
+    const matches = [];
+    for (const projectPath of projectPaths) {
+      const file = join8(projectsRoot, encodeProjectDir(projectPath), `${options.session}.jsonl`);
+      if (await pathExists(file)) matches.push(file);
     }
-    if (priors.length > 0 && options.force === true) {
-      if (options.dryRun !== true) {
-        for (const { sessionId } of priors) {
-          await rm(join7(paths.sessions, sessionId), { recursive: true, force: true });
+    if (matches.length === 0) {
+      throw new Error("Claude transcript not found for session id in project");
+    }
+    return [...new Set(matches)];
+  }
+  const files = [];
+  let anyDirFound = false;
+  for (const projectPath of projectPaths) {
+    const transcriptDir = join8(projectsRoot, encodeProjectDir(projectPath));
+    let entries;
+    try {
+      entries = await readdir(transcriptDir);
+    } catch (error) {
+      if (findErrorCode5(error, "ENOENT")) continue;
+      throw new Error("Failed to read Claude transcript directory", { cause: error });
+    }
+    anyDirFound = true;
+    for (const name of entries) {
+      if (name.endsWith(".jsonl")) files.push(join8(transcriptDir, name));
+    }
+  }
+  if (!anyDirFound) {
+    throw new Error("Claude transcript directory not found for project");
+  }
+  return [...new Set(files)].sort();
+}
+async function pathExists(file) {
+  try {
+    await stat3(file);
+    return true;
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) return false;
+    throw error;
+  }
+}
+async function statSize(file) {
+  try {
+    return (await stat3(file)).size;
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) return void 0;
+    throw error;
+  }
+}
+async function discoverCodexRollouts(sessionsRoot, projectPaths, options) {
+  const projectSet = new Set(projectPaths);
+  const files = await findRolloutFiles(sessionsRoot);
+  const matched = [];
+  for (const file of files) {
+    const meta = await readRolloutMeta(file);
+    if (meta === void 0) continue;
+    if (!projectSet.has(meta.cwd)) continue;
+    if (options.session !== void 0 && meta.id !== options.session) continue;
+    matched.push({ file, externalId: meta.id });
+  }
+  if (options.session !== void 0 && matched.length === 0) {
+    throw new Error("Codex rollout not found for session id in project");
+  }
+  return matched;
+}
+async function findRolloutFiles(sessionsRoot) {
+  const found = [];
+  const walk = async (dir, isRoot) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if (findErrorCode5(error, "ENOENT")) {
+        if (isRoot) {
+          throw new Error("Codex sessions directory not found", { cause: error });
         }
+        return;
       }
-      counts.replaced++;
+      throw new Error("Failed to read Codex sessions directory", { cause: error });
     }
-    const result = await importSessionFromJson(paths, manifest, payload, {
-      dryRun: options.dryRun === true
-    });
-    results.push(result);
-    seenThisRun.add(externalId);
-    sanitizedPaths += result.pathSanitizeReport.relatedFiles + (result.pathSanitizeReport.workingDirectoryRewritten ? 1 : 0);
-    await noteCrossProject(externalId, payload);
-  }
-  if (sanitizedPaths > 0) {
-    console.error(`Imported sessions: ${sanitizedPaths} path(s) sanitized`);
+    for (const entry of entries) {
+      const full = join8(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, false);
+      } else if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(".jsonl")) {
+        found.push(full);
+      }
+    }
+  };
+  await walk(sessionsRoot, true);
+  return found.sort();
+}
+async function readRolloutMeta(file) {
+  const firstLine = await readFirstLine(file);
+  if (firstLine === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(firstLine);
+  } catch {
+    return void 0;
   }
-  if (crossProject.length > 0) {
-    const PATH_SAMPLE = 5;
-    for (const { externalId, outOfRoot } of crossProject) {
-      const sample = outOfRoot.slice(0, PATH_SAMPLE).join(", ");
-      const more = outOfRoot.length > PATH_SAMPLE ? ` (... +${outOfRoot.length - PATH_SAMPLE} more)` : "";
-      console.error(
-        `basou: session ${externalId} edited ${outOfRoot.length} file(s) outside this project's source_roots: ${sample}${more} \u2014 they may belong to another project.`
-      );
+  if (!isObject(parsed) || parsed.type !== "session_meta") return void 0;
+  const payload = isObject(parsed.payload) ? parsed.payload : void 0;
+  if (payload === void 0) return void 0;
+  const id = payload.id;
+  const cwd = payload.cwd;
+  if (typeof id !== "string" || id.length === 0) return void 0;
+  if (typeof cwd !== "string" || cwd.length === 0) return void 0;
+  return { id, cwd };
+}
+async function readFirstLine(file) {
+  const stream = createReadStream(file, { encoding: "utf8" });
+  const rl = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
+  try {
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (trimmed.length > 0) return trimmed;
     }
+    return void 0;
+  } catch {
+    return void 0;
+  } finally {
+    rl.close();
+    stream.destroy();
   }
-  printImportResult(options, results, counts);
 }
-async function classifyReimport(priors, sourcePath, externalId, counts) {
-  if (priors.length > 1) {
-    console.error(
-      `Import: ${externalId} has ${priors.length} prior sessions; re-import skipped (use --force)`
-    );
-    counts.skippedDuplicate++;
-    return null;
+async function readJsonlRecords(file) {
+  let buffer;
+  try {
+    buffer = await readFile2(file);
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) {
+      throw new Error("Source log not found", { cause: error });
+    }
+    if (findErrorCode5(error, "EISDIR")) {
+      throw new Error("Source log path is not a file", { cause: error });
+    }
+    throw new Error("Failed to read source log", { cause: error });
   }
-  const prior = priors[0];
-  if (prior === void 0) {
-    counts.skippedExisting++;
-    return null;
+  const records = [];
+  for (const line of buffer.toString("utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (isObject(parsed)) {
+        records.push(parsed);
+      }
+    } catch {
+    }
   }
-  const currentSize = await statSize(sourcePath);
-  if (currentSize === void 0) {
-    counts.skippedExisting++;
-    return null;
+  return { records, sizeBytes: buffer.length };
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function printImportResult(options, results, counts) {
+  const isDry = options.dryRun === true;
+  const eventTotal = results.reduce((sum, r) => sum + r.eventCount, 0);
+  const {
+    skippedNoAction,
+    skippedExisting,
+    replaced,
+    reimported,
+    skippedLegacy,
+    skippedDecreased,
+    skippedDuplicate,
+    skippedUnverifiable
+  } = counts;
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        imported: results.map((r) => ({
+          session_id: r.sessionId,
+          event_count: r.eventCount,
+          status: r.finalStatus,
+          source: { kind: r.finalSourceKind, version: "0.1.0" }
+        })),
+        imported_count: results.length,
+        replaced_count: replaced,
+        reimported_count: reimported,
+        skipped_no_action: skippedNoAction,
+        skipped_already_imported: skippedExisting,
+        skipped_legacy_untracked: skippedLegacy,
+        skipped_decreased: skippedDecreased,
+        skipped_duplicate: skippedDuplicate,
+        skipped_unverifiable: skippedUnverifiable,
+        event_total: eventTotal,
+        dry_run: isDry
+      })
+    );
+    return;
   }
-  if (prior.sourceSizeBytes === void 0) {
-    counts.skippedLegacy++;
-    return null;
+  const skipParts = [];
+  if (skippedNoAction > 0) skipParts.push(`${skippedNoAction} with no actions`);
+  if (skippedExisting > 0) skipParts.push(`${skippedExisting} already imported`);
+  if (skippedLegacy > 0) skipParts.push(`${skippedLegacy} legacy (untracked size)`);
+  if (skippedDecreased > 0) skipParts.push(`${skippedDecreased} shrank`);
+  if (skippedDuplicate > 0) skipParts.push(`${skippedDuplicate} duplicated`);
+  if (skippedUnverifiable > 0)
+    skipParts.push(`${skippedUnverifiable} unverifiable (run 'basou verify')`);
+  const skipSuffix = skipParts.length > 0 ? `; skipped ${skipParts.join(", ")}` : "";
+  const eventsPart = replaced > 0 ? `${eventTotal} events, ${replaced} replaced` : `${eventTotal} events`;
+  if (isDry) {
+    const parts = [];
+    if (results.length > 0) parts.push(`import ${results.length} session(s) (${eventsPart})`);
+    if (reimported > 0) parts.push(`re-import ${reimported} changed session(s)`);
+    const head = parts.length > 0 ? `Dry run: would ${parts.join(", ")}` : "Dry run: no changes";
+    console.log(`${head}${skipSuffix}`);
+    return;
   }
-  if (currentSize === prior.sourceSizeBytes) {
-    counts.skippedExisting++;
-    return null;
+  if (results.length === 0 && reimported === 0) {
+    console.log(
+      skipParts.length > 0 ? `No new sessions imported (skipped ${skipParts.join(", ")})` : "No transcripts found to import"
+    );
+    return;
   }
-  if (currentSize < prior.sourceSizeBytes) {
-    console.error(
-      `Import: ${externalId} source shrank (${currentSize} < ${prior.sourceSizeBytes} bytes); re-import skipped (use --force to replace)`
+  const segments = [];
+  if (results.length > 0) {
+    const single = results.length === 1 && results[0] !== void 0 ? ` (${shortId2(results[0].sessionId)})` : "";
+    segments.push(`Imported ${results.length} session(s)${single} (${eventsPart})`);
+  }
+  if (reimported > 0) {
+    segments.push(
+      `${results.length > 0 ? "re-imported" : "Re-imported"} ${reimported} changed session(s)`
     );
-    counts.skippedDecreased++;
-    return null;
   }
-  return prior;
-}
-function encodeProjectDir(projectPath) {
-  return projectPath.replace(/[^a-zA-Z0-9]/g, "-");
+  console.log(`${segments.join(", ")}${skipSuffix}`);
 }
-function firstTranscriptCwd(records) {
-  for (const record of records) {
-    const cwd = record.cwd;
-    if (typeof cwd === "string" && cwd.length > 0) return cwd;
+function shortId2(id) {
+  if (id.startsWith(SES_PREFIX2)) {
+    return id.slice(SES_PREFIX2.length, SES_PREFIX2.length + SHORT_ID_LEN2);
   }
-  return void 0;
+  return id.slice(0, SHORT_ID_LEN2);
 }
-async function loadExistingByExternalId(paths, sourceKind) {
-  const byExternalId = /* @__PURE__ */ new Map();
-  const add = (externalId, prior) => {
-    const list = byExternalId.get(externalId);
-    if (list === void 0) byExternalId.set(externalId, [prior]);
-    else list.push(prior);
-  };
-  let sessionIds;
+async function resolveRepositoryRootForImport(cwd) {
   try {
-    sessionIds = await enumerateSessionDirs(paths);
-  } catch {
-    return byExternalId;
-  }
-  for (const sessionId of sessionIds) {
-    let session;
-    try {
-      session = await readSessionYaml2(paths, sessionId);
-    } catch {
-      continue;
-    }
-    if (session.session.source.kind !== sourceKind) continue;
-    const sourceSizeBytes = session.session.source.source_size_bytes;
-    const prior = sourceSizeBytes !== void 0 ? { sessionId, sourceSizeBytes } : { sessionId };
-    const ext = session.session.source.external_id;
-    if (typeof ext === "string" && ext.length > 0) {
-      add(ext, prior);
-      continue;
+    return await resolveRepositoryRoot6(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 import'.", {
+        cause: error
+      });
     }
-    const label = session.session.label;
-    const match = typeof label === "string" ? label.match(/^claude-code import (\S+)$/) : null;
-    if (match?.[1] !== void 0) add(match[1], prior);
+    throw error;
   }
-  return byExternalId;
 }
-async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
-  if (options.session !== void 0) {
-    const matches = [];
-    for (const projectPath of projectPaths) {
-      const file = join7(projectsRoot, encodeProjectDir(projectPath), `${options.session}.jsonl`);
-      if (await pathExists(file)) matches.push(file);
-    }
-    if (matches.length === 0) {
-      throw new Error("Claude transcript not found for session id in project");
+async function assertWorkspaceInitialized5(basouRoot) {
+  try {
+    await assertBasouRootSafe6(basouRoot);
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
-    return [...new Set(matches)];
+    throw error;
   }
-  const files = [];
-  let anyDirFound = false;
-  for (const projectPath of projectPaths) {
-    const transcriptDir = join7(projectsRoot, encodeProjectDir(projectPath));
-    let entries;
+}
+
+// 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(" "));
+  });
+  console.error = (() => {
+  });
+  try {
+    await fn();
+  } finally {
+    console.log = originalLog;
+    console.error = originalError;
+  }
+  for (let i = stdout.length - 1; i >= 0; i--) {
+    const line = stdout[i];
+    if (line === void 0) continue;
     try {
-      entries = await readdir(transcriptDir);
-    } catch (error) {
-      if (findErrorCode5(error, "ENOENT")) continue;
-      throw new Error("Failed to read Claude transcript directory", { cause: error });
-    }
-    anyDirFound = true;
-    for (const name of entries) {
-      if (name.endsWith(".jsonl")) files.push(join7(transcriptDir, name));
+      const parsed = JSON.parse(line);
+      if (parsed !== null && typeof parsed === "object" && "imported_count" in parsed) {
+        return parsed;
+      }
+    } catch {
     }
   }
-  if (!anyDirFound) {
-    throw new Error("Claude transcript directory not found for project");
-  }
-  return [...new Set(files)].sort();
+  throw new Error("Import produced no parseable result");
 }
-async function pathExists(file) {
-  try {
-    await stat4(file);
-    return true;
-  } catch (error) {
-    if (findErrorCode5(error, "ENOENT")) return false;
-    throw error;
-  }
+function readCount(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
-async function statSize(file) {
+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 stat4(file)).size;
+    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 (findErrorCode5(error, "ENOENT")) return void 0;
+    if (isMissingSourceDir(error)) {
+      return { adapter, status: "skipped", reason: "no source logs for this project" };
+    }
     throw error;
   }
 }
-async function discoverCodexRollouts(sessionsRoot, projectPaths, options) {
-  const projectSet = new Set(projectPaths);
-  const files = await findRolloutFiles(sessionsRoot);
-  const matched = [];
-  for (const file of files) {
-    const meta = await readRolloutMeta(file);
-    if (meta === void 0) continue;
-    if (!projectSet.has(meta.cwd)) continue;
-    if (options.session !== void 0 && meta.id !== options.session) continue;
-    matched.push({ file, externalId: meta.id });
-  }
-  if (options.session !== void 0 && matched.length === 0) {
-    throw new Error("Codex rollout not found for session id in project");
-  }
-  return matched;
+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 } : {}
+  };
 }
-async function findRolloutFiles(sessionsRoot) {
-  const found = [];
-  const walk = async (dir, isRoot) => {
-    let entries;
-    try {
-      entries = await readdir(dir, { withFileTypes: true });
-    } catch (error) {
-      if (findErrorCode5(error, "ENOENT")) {
-        if (isRoot) {
-          throw new Error("Codex sessions directory not found", { cause: error });
-        }
-        return;
-      }
-      throw new Error("Failed to read Codex sessions directory", { cause: error });
-    }
-    for (const entry of entries) {
-      const full = join7(dir, entry.name);
-      if (entry.isDirectory()) {
-        await walk(full, false);
-      } else if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(".jsonl")) {
-        found.push(full);
+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
   };
-  await walk(sessionsRoot, true);
-  return found.sort();
 }
-async function readRolloutMeta(file) {
-  const firstLine = await readFirstLine(file);
-  if (firstLine === void 0) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(firstLine);
-  } catch {
-    return void 0;
-  }
-  if (!isObject(parsed) || parsed.type !== "session_meta") return void 0;
-  const payload = isObject(parsed.payload) ? parsed.payload : void 0;
-  if (payload === void 0) return void 0;
-  const id = payload.id;
-  const cwd = payload.cwd;
-  if (typeof id !== "string" || id.length === 0) return void 0;
-  if (typeof cwd !== "string" || cwd.length === 0) return void 0;
-  return { id, cwd };
+function wouldImport(outcome) {
+  return outcome.status === "ran" ? outcome.importedCount : 0;
 }
-async function readFirstLine(file) {
-  const stream = createReadStream(file, { encoding: "utf8" });
-  const rl = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
+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 {
-    for await (const line of rl) {
-      const trimmed = line.trim();
-      if (trimmed.length > 0) return trimmed;
-    }
-    return void 0;
+    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 void 0;
-  } finally {
-    rl.close();
-    stream.destroy();
+    return null;
   }
 }
-async function readJsonlRecords(file) {
-  let buffer;
+
+// 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 runOrient(options, ctx = {}) {
   try {
-    buffer = await readFile3(file);
+    await doRunOrient(options, ctx);
   } catch (error) {
-    if (findErrorCode5(error, "ENOENT")) {
-      throw new Error("Source log not found", { cause: error });
-    }
-    if (findErrorCode5(error, "EISDIR")) {
-      throw new Error("Source log path is not a file", { cause: error });
-    }
-    throw new Error("Failed to read source log", { cause: error });
-  }
-  const records = [];
-  for (const line of buffer.toString("utf8").split("\n")) {
-    const trimmed = line.trim();
-    if (trimmed.length === 0) continue;
-    try {
-      const parsed = JSON.parse(trimmed);
-      if (isObject(parsed)) {
-        records.push(parsed);
-      }
-    } catch {
-    }
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
   }
-  return { records, sizeBytes: buffer.length };
-}
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function printImportResult(options, results, counts) {
-  const isDry = options.dryRun === true;
-  const eventTotal = results.reduce((sum, r) => sum + r.eventCount, 0);
-  const {
-    skippedNoAction,
-    skippedExisting,
-    replaced,
-    reimported,
-    skippedLegacy,
-    skippedDecreased,
-    skippedDuplicate,
-    skippedUnverifiable
-  } = counts;
-  if (options.json === true) {
-    console.log(
-      JSON.stringify({
-        imported: results.map((r) => ({
-          session_id: r.sessionId,
-          event_count: r.eventCount,
-          status: r.finalStatus,
-          source: { kind: r.finalSourceKind, version: "0.1.0" }
-        })),
-        imported_count: results.length,
-        replaced_count: replaced,
-        reimported_count: reimported,
-        skipped_no_action: skippedNoAction,
-        skipped_already_imported: skippedExisting,
-        skipped_legacy_untracked: skippedLegacy,
-        skipped_decreased: skippedDecreased,
-        skipped_duplicate: skippedDuplicate,
-        skipped_unverifiable: skippedUnverifiable,
-        event_total: eventTotal,
-        dry_run: isDry
-      })
-    );
-    return;
-  }
-  const skipParts = [];
-  if (skippedNoAction > 0) skipParts.push(`${skippedNoAction} with no actions`);
-  if (skippedExisting > 0) skipParts.push(`${skippedExisting} already imported`);
-  if (skippedLegacy > 0) skipParts.push(`${skippedLegacy} legacy (untracked size)`);
-  if (skippedDecreased > 0) skipParts.push(`${skippedDecreased} shrank`);
-  if (skippedDuplicate > 0) skipParts.push(`${skippedDuplicate} duplicated`);
-  if (skippedUnverifiable > 0)
-    skipParts.push(`${skippedUnverifiable} unverifiable (run 'basou verify')`);
-  const skipSuffix = skipParts.length > 0 ? `; skipped ${skipParts.join(", ")}` : "";
-  const eventsPart = replaced > 0 ? `${eventTotal} events, ${replaced} replaced` : `${eventTotal} events`;
-  if (isDry) {
-    const parts = [];
-    if (results.length > 0) parts.push(`import ${results.length} session(s) (${eventsPart})`);
-    if (reimported > 0) parts.push(`re-import ${reimported} changed session(s)`);
-    const head = parts.length > 0 ? `Dry run: would ${parts.join(", ")}` : "Dry run: no changes";
-    console.log(`${head}${skipSuffix}`);
-    return;
-  }
-  if (results.length === 0 && reimported === 0) {
+async function doRunOrient(options, ctx) {
+  const result = await renderOrientationForCwd(options, ctx);
+  if (options.quiet === true) {
     console.log(
-      skipParts.length > 0 ? `No new sessions imported (skipped ${skipParts.join(", ")})` : "No transcripts found to import"
-    );
-    return;
-  }
-  const segments = [];
-  if (results.length > 0) {
-    const single = results.length === 1 && results[0] !== void 0 ? ` (${shortId2(results[0].sessionId)})` : "";
-    segments.push(`Imported ${results.length} session(s)${single} (${eventsPart})`);
-  }
-  if (reimported > 0) {
-    segments.push(
-      `${results.length > 0 ? "re-imported" : "Re-imported"} ${reimported} changed session(s)`
+      `Generated .basou/orientation.md (sessions: ${result.sessionCount}, in-flight tasks: ${result.inFlightTaskCount}, pending approvals: ${result.pendingApprovalsCount}, suspect: ${result.suspectCount})`
     );
+  } else {
+    console.log(result.body);
   }
-  console.log(`${segments.join(", ")}${skipSuffix}`);
 }
-function shortId2(id) {
-  if (id.startsWith(SES_PREFIX2)) {
-    return id.slice(SES_PREFIX2.length, SES_PREFIX2.length + SHORT_ID_LEN2);
-  }
-  return id.slice(0, SHORT_ID_LEN2);
+async function renderOrientationForCwd(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveBasouRootForCommand(cwd, "orient");
+  return renderOrientationForRoot(repositoryRoot, options, ctx, { write: true });
 }
-async function resolveRepositoryRootForImport(cwd) {
+async function renderOrientationForRoot(repositoryRoot, options, ctx, behaviour) {
+  const paths = basouPaths8(repositoryRoot);
+  await assertWorkspaceInitialized6(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 {
-    return await resolveRepositoryRoot6(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 import'.", {
-        cause: error
-      });
+    const hosts = await loadHostsConfig(ctx.hostsConfigPath);
+    if (hosts !== null) {
+      federatedRoots = hosts.map((h) => ({ paths: basouPaths8(h.path), host: h.label }));
     }
-    throw error;
+  } 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 assertWorkspaceInitialized5(basouRoot) {
+async function assertWorkspaceInitialized6(basouRoot) {
   try {
-    await assertBasouRootSafe6(basouRoot);
+    await assertBasouRootSafe7(basouRoot);
   } catch (error) {
-    if (findErrorCode5(error, "ENOENT")) {
+    if (findErrorCode6(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw error;
   }
 }
 
-// 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"
+// 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(
-    "--source-root <path>",
-    "Extra import source root, relative to the repo root (repeatable; aggregates sibling repos into this workspace)",
-    collectValue,
-    []
+    "--min-edits <n>",
+    `Minimum file edits before nudging on edits alone (default ${DEFAULT_STOP_HOOK_MIN_EDITS})`
   ).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);
+    "--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 runInit(options, ctx = {}) {
-  try {
-    await doRunInit(options, ctx);
-  } catch (error) {
-    renderCliError(error, { verbose: isVerbose(options) });
+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;
   }
+  await handlers[resolved]();
 }
-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;
-  });
-  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 });
+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 appendBasouGitignore(repositoryRoot, { localOnly: options.localOnly === true });
-  } catch (error) {
-    renderGitignoreWarning(error, isVerbose(options));
+    await doRunHookStop(options, ctx);
+  } catch {
   }
-  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}`);
+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;
   }
-}
-async function resolveRepositoryRootForInit(cwd) {
+  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 {
-    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;
+    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}
+`);
 }
-
-// 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);
+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 };
 }
-async function runNote(body, options, ctx = {}) {
+async function isRegisteredWorkspace(root, portfolioConfigPath) {
+  let entries;
   try {
-    await doRunNote(body, options, ctx);
-  } catch (error) {
-    renderCliError(error, {
-      verbose: isVerbose(options),
-      classifiers: [failedToFinalizeClassifier]
-    });
-    process.exitCode = 1;
+    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;
 }
-async function doRunNote(body, options, ctx) {
-  if (body.trim().length === 0) {
-    throw new Error("Note body must not be empty");
+async function runHookSessionStart(ctx = {}) {
+  try {
+    await doRunHookSessionStart(ctx);
+  } catch {
   }
-  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 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;
   }
-  const cwd = ctx.cwd ?? process.cwd();
-  const repositoryRoot = await resolveBasouRootForCommand(cwd, "note");
-  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();
-    }
-    printNoteResult(options, {
-      mode: "attached",
-      sessionId,
-      eventId: result.eventId,
-      sessionStatus: result.sessionStatus,
-      body
-    });
+  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;
   }
-  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 })
-    ]
-  });
-  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"
-  };
+  if (body.trim().length === 0) return;
+  write(`${body.replace(/\s+$/, "")}
+`);
 }
-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 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;
 }
-function parseBody(raw) {
-  if (raw.trim().length === 0) {
-    throw new InvalidArgumentError2("Note body must not be empty");
+async function defaultReadStdin() {
+  if (process.stdin.isTTY === true) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
   }
-  return raw;
+  return Buffer.concat(chunks).toString("utf8");
 }
-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;
+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 {
+    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();
   }
-  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})`);
+}
+function parseMinEdits(raw) {
+  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
+  return Number(raw);
+}
+var DEFAULT_CLAUDE_SETTINGS_PATH = join9(homedir7(), ".claude", "settings.json");
+function resolveCliEntry() {
+  return fileURLToPath(import.meta.url);
+}
+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 assertWorkspaceInitialized6(basouRoot) {
+async function readSettings(path) {
+  let raw;
   try {
-    await assertBasouRootSafe7(basouRoot);
+    raw = await readFile3(path, "utf8");
   } catch (error) {
-    if (findErrorCode6(error, "ENOENT")) {
-      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    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 Claude settings.json is not valid JSON. Fix it (or remove it) and retry.",
+      {
+        cause: error
+      }
+    );
+  }
 }
-
-// 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 homedir6 } from "os";
-import { isAbsolute as isAbsolute2, join as join8, resolve as resolve6 } from "path";
-import { readYamlFile as readYamlFile4 } from "@basou/core";
-var DEFAULT_HOSTS_CONFIG_PATH = join8(homedir6(), ".basou", "hosts.yaml");
-function expandTilde2(p) {
-  if (p === "~") return homedir6();
-  if (p.startsWith("~/")) return join8(homedir6(), p.slice(2));
-  return p;
+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;
+  }
+  await writeFileDurable(bak, raw);
 }
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+async function runHookInstall(options, ctx = {}) {
+  try {
+    await doRunHookInstall(normalizeInstallOptions(options), ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
 }
-async function loadHostsConfig(configPath = DEFAULT_HOSTS_CONFIG_PATH) {
-  let raw;
+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 {
-    raw = await readYamlFile4(configPath);
+    await doRunHookUninstall(normalizeInstallOptions(options));
   } 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.");
-    }
-    throw error;
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
   }
-  if (!isRecord2(raw) || !Array.isArray(raw.hosts)) {
-    throw new Error("~/.basou/hosts.yaml must contain a 'hosts:' list.");
+}
+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 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 });
+  const { settings, action } = removeStopHook(parsed);
+  if (action === "absent") {
+    console.log("No basou Stop hook found; nothing removed.");
+    return;
   }
-  return result;
+  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.");
 }
-
-// src/lib/provenance-actions.ts
-import {
-  readMarkdownFile as readMarkdownFile3,
-  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(" "));
-  });
-  console.error = (() => {
-  });
+async function runHookStatus(options) {
   try {
-    await fn();
-  } finally {
-    console.log = originalLog;
-    console.error = originalError;
+    await doRunHookStatus(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 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;
   }
-  throw new Error("Import produced no parseable result");
+  const mode = describeHookMode({
+    block: / --block\b/.test(command),
+    review: / --require-review\b/.test(command)
+  });
+  console.log(`basou Stop hook: registered, ${mode}.`);
 }
-function readCount(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+function describeHookMode(tiers) {
+  const enforcement = tiers.block ? "blocking (opt-in enforcement)" : "advisory (non-blocking)";
+  const gates = tiers.review ? "capture + review" : "capture";
+  return `${enforcement}, ${gates}`;
 }
-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";
+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 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;
+  }
 }
-async function runImport(adapter, fn) {
+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 {
-    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
-    };
+    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 } : {}
-  };
-}
-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 readMarkdownFile3(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 readMarkdownFile3(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
-  };
+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;
+  }
 }
-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
-    };
+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;
   }
-  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)
-      }
-    }
+  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}.`
   );
-  return {
-    claudeCode,
-    codex,
-    handoff: { status: "generated", ...handoffCounts },
-    decisions: { status: "generated", ...decisionCounts },
-    orientation: { status: "generated", ...orientationCounts },
-    dryRun
-  };
+  await reportCodexHookState(hooksPath, hooksFile, options);
 }
-function wouldImport(outcome) {
-  return outcome.status === "ran" ? outcome.importedCount : 0;
+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"));
+  }
 }
-function wouldUpdate(outcome) {
-  return outcome.status === "ran" ? outcome.reimportedCount + outcome.replacedCount : 0;
+async function runCodexHookUninstall(options) {
+  try {
+    await doRunCodexHookUninstall(normalizeInstallOptions(options));
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
 }
-function wouldBlock(outcome) {
-  return outcome.status === "ran" ? outcome.skippedUnverifiable : 0;
+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 probeStaleness(args) {
+async function runCodexHookStatus(options) {
   try {
-    const dry = await refreshAll({
-      options: { dryRun: true },
-      ctx: args.ctx,
-      paths: args.paths,
-      nowIso: args.nowIso
-    });
+    await doRunCodexHookStatus(normalizeInstallOptions(options));
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+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 {
-      newSessions: wouldImport(dry.claudeCode) + wouldImport(dry.codex),
-      updatedSessions: wouldUpdate(dry.claudeCode) + wouldUpdate(dry.codex),
-      unverifiableSessions: wouldBlock(dry.claudeCode) + wouldBlock(dry.codex)
+      status: "unknown",
+      detail: `could not read ${configPath ?? DEFAULT_CODEX_CONFIG_PATH}`
     };
-  } catch {
-    return null;
   }
+  const key = codexHookStateKey(
+    hooksPath,
+    "session_start",
+    location.groupIndex,
+    location.handlerIndex
+  );
+  const state = readCodexHookState(configToml, key);
+  const current = computeCodexHookIdentityHash({
+    eventKey: "session_start",
+    matcher: location.matcher,
+    handler: fields
+  });
+  return judgeCodexHookTrust(state, current);
 }
 
-// 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/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 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 runOrient(options, ctx = {}) {
+async function runInit(options, ctx = {}) {
   try {
-    await doRunOrient(options, ctx);
+    await doRunInit(options, ctx);
   } catch (error) {
     renderCliError(error, { verbose: isVerbose(options) });
     process.exitCode = 1;
   }
 }
-async function doRunOrient(options, ctx) {
+async function doRunInit(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
-  const repositoryRoot = await resolveBasouRootForCommand(cwd, "orient");
-  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 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 staleness = await probeStaleness({ ctx: probeCtx, paths, nowIso });
-  let federatedRoots = [];
+  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 {
-    const hosts = await loadHostsConfig(ctx.hostsConfigPath);
-    if (hosts !== null) {
-      federatedRoots = hosts.map((h) => ({ paths: basouPaths9(h.path), host: h.label }));
+    await appendBasouGitignore(repositoryRoot, { localOnly: options.localOnly === true });
+  } catch (error) {
+    renderGitignoreWarning(error, isVerbose(options));
+  }
+  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}`);
+  }
+}
+async function resolveRepositoryRootForInit(cwd) {
+  try {
+    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/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 runNote(body, options, ctx = {}) {
+  try {
+    await doRunNote(body, options, ctx);
   } catch (error) {
-    console.error(
-      `basou: ignoring ~/.basou/hosts.yaml (${error instanceof Error ? error.message : String(error)}); showing local sessions only.`
+    renderCliError(error, {
+      verbose: isVerbose(options),
+      classifiers: [failedToFinalizeClassifier]
+    });
+    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>"\`).`
     );
   }
-  const result = await renderOrientation2({
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveBasouRootForCommand(cwd, "note");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized7(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();
+    }
+    printNoteResult(options, {
+      mode: "attached",
+      sessionId,
+      eventId: result.eventId,
+      sessionStatus: result.sessionStatus,
+      body
+    });
+    return;
+  }
+  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) {
@@ -3620,13 +4218,13 @@ async function assertWorkspaceInitialized7(basouRoot) {
 
 // src/commands/portfolio.ts
 import { existsSync, statSync } from "fs";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 function registerPortfolioCommand(program2) {
   program2.command("portfolio").description(
     "List the workspaces you orient across (read-only): every planning master registered in ~/.basou/portfolio.yaml, with its path and whether it exists / is initialized. The headless text/JSON counterpart to the `basou view --portfolio` GUI \u2014 for discovering where a sibling project lives without opening a browser"
   ).argument("[action]", "optional literal `list` (the only, and default, action)").option("--json", "Output the result as JSON").option(
     "--check",
-    "moved: the redundancy/footprint safety preflight is `basou view --portfolio --check` (this prints that pointer and exits)"
+    "moved: the redundancy/footprint preflight and the capture-coverage report are `basou view --portfolio --check` (this prints that pointer and exits)"
   ).option("-v, --verbose", "Show error causes").action(async (action, opts) => {
     await runPortfolioCommand(action, opts);
   });
@@ -3641,7 +4239,7 @@ function isDirectory(path) {
 async function runPortfolioCommand(action, options, ctx = {}) {
   if (options.check === true) {
     console.error(
-      "`basou portfolio` is a read-only listing; it has no safety preflight.\nRun `basou view --portfolio --check` for the redundancy/footprint check."
+      "`basou portfolio` is a read-only listing; it has no preflight.\nRun `basou view --portfolio --check` for the redundancy/footprint check and the capture-coverage report."
     );
     process.exitCode = 1;
     return;
@@ -3666,7 +4264,7 @@ async function runPortfolioList(options, ctx = {}) {
 async function doRunPortfolioList(options, ctx) {
   const configPath = ctx.configPath ?? DEFAULT_PORTFOLIO_CONFIG_PATH;
   const pathExists2 = ctx.pathExists ?? ((p) => existsSync(p));
-  const isInitialized = ctx.isInitialized ?? ((p) => isDirectory(join9(p, ".basou")));
+  const isInitialized = ctx.isInitialized ?? ((p) => isDirectory(join10(p, ".basou")));
   const workspaces = await loadPortfolioConfig(configPath);
   const result = {
     configPath,
@@ -3706,7 +4304,7 @@ function renderPortfolioList(result) {
   }
   lines.push("");
   lines.push(
-    "Note: read-only listing of ~/.basou/portfolio.yaml. Run `basou view --portfolio` for the cross-workspace GUI, or `basou view --portfolio --check` for the redundancy/footprint safety preflight."
+    "Note: read-only listing of ~/.basou/portfolio.yaml. Run `basou view --portfolio` for the cross-workspace GUI, or `basou view --portfolio --check` for the redundancy/footprint preflight and the capture-coverage report (which session logs no registered workspace imports)."
   );
   return lines.join("\n");
 }
@@ -3731,7 +4329,7 @@ import {
   writeFileSync,
   writeSync
 } from "fs";
-import { basename as basename5, dirname as dirname3, isAbsolute as isAbsolute3, join as join10, relative as relative2, resolve as resolve7 } from "path";
+import { basename as basename5, dirname as dirname3, isAbsolute as isAbsolute3, join as join11, relative as relative2, resolve as resolve7 } from "path";
 import {
   appendBasouGitignore as appendBasouGitignore2,
   basouPaths as basouPaths10,
@@ -3742,7 +4340,7 @@ import {
   GENERATED_START,
   instructionMode,
   isGitNotFound,
-  parseMarkers,
+  parseMarkers as parseMarkers3,
   pathBasename,
   planArchive,
   planGitignore,
@@ -3750,9 +4348,9 @@ import {
   planRosterAdoption,
   planWorkspaceView,
   readManifest as readManifest6,
-  readMarkdownFile as readMarkdownFile4,
+  readMarkdownFile as readMarkdownFile6,
   reconcileSourceRoots,
-  removeMarkerSection,
+  removeMarkerSection as removeMarkerSection2,
   renderAnchorStarter,
   renderViewPresetBlock,
   renderWithMarkers as renderWithMarkers4,
@@ -4113,7 +4711,7 @@ function classifySourceRoot(repositoryRoot, declaredPath) {
   } catch {
     return { path: declaredPath, kind: "unresolved" };
   }
-  return { path: declaredPath, kind: existsSync2(join10(real, ".git")) ? "repo" : "non-repo" };
+  return { path: declaredPath, kind: existsSync2(join11(real, ".git")) ? "repo" : "non-repo" };
 }
 async function doRunProjectAdopt(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
@@ -4217,7 +4815,7 @@ async function gatherRepoWiring(repositoryRoot, entry) {
   } catch {
     return { ...base, reachable: false, instructionFiles: [] };
   }
-  if (!existsSync2(join10(real, ".git"))) {
+  if (!existsSync2(join11(real, ".git"))) {
     return { ...base, reachable: false, instructionFiles: [] };
   }
   try {
@@ -4225,7 +4823,7 @@ async function gatherRepoWiring(repositoryRoot, entry) {
     for (const name of INSTRUCTION_FILES) {
       let present = true;
       try {
-        lstatSync(join10(real, name));
+        lstatSync(join11(real, name));
       } catch {
         present = false;
       }
@@ -4336,10 +4934,10 @@ function gatherRepoGitignore(repositoryRoot, entry) {
   } catch {
     return { ...base, reachable: false, currentLines: [] };
   }
-  if (!existsSync2(join10(real, ".git"))) {
+  if (!existsSync2(join11(real, ".git"))) {
     return { ...base, reachable: false, currentLines: [] };
   }
-  return { ...base, reachable: true, currentLines: readGitignoreLines(join10(real, ".gitignore")) };
+  return { ...base, reachable: true, currentLines: readGitignoreLines(join11(real, ".gitignore")) };
 }
 function hasErrorCode(error) {
   return error instanceof Error && typeof error.code === "string";
@@ -4353,7 +4951,7 @@ function readGitignoreLines(file) {
   }
 }
 function applyGitignorePlan(repositoryRoot, plan) {
-  const file = join10(realpathSync(resolve7(repositoryRoot, plan.path)), ".gitignore");
+  const file = join11(realpathSync(resolve7(repositoryRoot, plan.path)), ".gitignore");
   let existing = "";
   try {
     existing = readFileSync(file, "utf8");
@@ -4493,7 +5091,7 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
     return { ...base, isAnchor: false, reachable: false, canonicalPresent: false, files: [] };
   }
   if (real === anchorReal) {
-    const anchorCanonical = join10(real, CANONICAL_FILE);
+    const anchorCanonical = join11(real, CANONICAL_FILE);
     const anchorState = anchorCanonicalState(anchorCanonical);
     if (anchorState === "absent") {
       return { ...base, isAnchor: true, reachable: true, canonicalPresent: false, files: [] };
@@ -4513,7 +5111,7 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
       anchorCanonical,
       "self"
     ).map((spec) => {
-      const { state, actualTarget } = inspectSymlink(join10(real, spec.name), spec.target);
+      const { state, actualTarget } = inspectSymlink(join11(real, spec.name), spec.target);
       return {
         name: spec.name,
         expectedTarget: spec.target,
@@ -4530,16 +5128,16 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
       files: anchorFiles
     };
   }
-  if (!existsSync2(join10(real, ".git"))) {
+  if (!existsSync2(join11(real, ".git"))) {
     return { ...base, isAnchor: false, reachable: false, canonicalPresent: false, files: [] };
   }
-  const canonicalFile = isSelf ? join10(real, CANONICAL_FILE) : join10(anchorReal, "agents", basename5(real), CANONICAL_FILE);
+  const canonicalFile = isSelf ? join11(real, CANONICAL_FILE) : join11(anchorReal, "agents", basename5(real), CANONICAL_FILE);
   if (!existsSync2(canonicalFile)) {
     return { ...base, isAnchor: false, reachable: true, canonicalPresent: false, files: [] };
   }
   const files = expectedSymlinkTargets(real, canonicalFile, mode).map(
     (spec) => {
-      const { state, actualTarget } = inspectSymlink(join10(real, spec.name), spec.target);
+      const { state, actualTarget } = inspectSymlink(join11(real, spec.name), spec.target);
       return {
         name: spec.name,
         expectedTarget: spec.target,
@@ -4568,7 +5166,7 @@ function applySymlinkPlan(repositoryRoot, plan) {
   const created = [];
   const failed = [];
   for (const { name, target } of plan.toCreate) {
-    const filePath = join10(real, name);
+    const filePath = join11(real, name);
     try {
       mkdirSync(dirname3(filePath), { recursive: true });
       symlinkSync(target, filePath);
@@ -4602,7 +5200,7 @@ function gatherViewSymlinks(repositoryRoot, anchorReal, roster, viewDir) {
   if (!existsSync2(canonicalFile)) return { kind: "missing-canonical", viewName };
   const files = expectedSymlinkTargets(viewDir, canonicalFile, "hub").map(
     (spec) => {
-      const { state, actualTarget } = inspectSymlink(join10(viewDir, spec.name), spec.target);
+      const { state, actualTarget } = inspectSymlink(join11(viewDir, spec.name), spec.target);
       return {
         name: spec.name,
         expectedTarget: spec.target,
@@ -4618,7 +5216,7 @@ function applyViewSymlinks(viewDir, files) {
   const failed = [];
   for (const f of files) {
     if (f.state !== "missing") continue;
-    const filePath = join10(viewDir, f.name);
+    const filePath = join11(viewDir, f.name);
     try {
       mkdirSync(dirname3(filePath), { recursive: true });
       symlinkSync(f.expectedTarget, filePath);
@@ -4840,7 +5438,7 @@ function resolveViewDir(repositoryRoot, viewPath) {
     return realpathSync(abs);
   } catch {
     try {
-      return join10(realpathSync(dirname3(abs)), basename5(abs));
+      return join11(realpathSync(dirname3(abs)), basename5(abs));
     } catch {
       return abs;
     }
@@ -4858,7 +5456,7 @@ function gatherViewRepo(repositoryRoot, viewDir, entry) {
     return { path: entry.path, reachable: false };
   }
   const linkName = basename5(repoReal);
-  const { state, actualTarget } = inspectSymlink(join10(viewDir, linkName), expectedTarget);
+  const { state, actualTarget } = inspectSymlink(join11(viewDir, linkName), expectedTarget);
   return {
     path: entry.path,
     reachable: true,
@@ -4872,7 +5470,7 @@ function applyViewPlan(viewDir, toCreate) {
   const created = [];
   const failed = [];
   for (const { name, target } of toCreate) {
-    const filePath = join10(viewDir, name);
+    const filePath = join11(viewDir, name);
     try {
       mkdirSync(dirname3(filePath), { recursive: true });
       symlinkSync(target, filePath);
@@ -4887,7 +5485,7 @@ var TOP_LEVEL_INSTRUCTION_FILES_LOWER = new Set(
   INSTRUCTION_FILES.filter((f) => !f.includes("/")).map((f) => f.toLowerCase())
 );
 function classifyViewLink(viewDir, name, rosterRealpaths) {
-  const filePath = join10(viewDir, name);
+  const filePath = join11(viewDir, name);
   let isLink;
   try {
     isLink = lstatSync(filePath).isSymbolicLink();
@@ -4916,7 +5514,7 @@ function classifyViewLink(viewDir, name, rosterRealpaths) {
   if (!isDir) {
     return { target, kind: existsSync2(resolved) ? "non-repo" : "broken" };
   }
-  return { target, kind: existsSync2(join10(resolved, ".git")) ? "repo" : "non-repo" };
+  return { target, kind: existsSync2(join11(resolved, ".git")) ? "repo" : "non-repo" };
 }
 function gatherExistingViewLinks(viewDir, rosterRealpaths) {
   let names;
@@ -4941,7 +5539,7 @@ function pruneViewLinks(viewDir, toPrune, rosterRealpaths) {
   const pruned = [];
   const failed = [];
   for (const { name } of toPrune) {
-    const filePath = join10(viewDir, name);
+    const filePath = join11(viewDir, name);
     const c = classifyViewLink(viewDir, name, rosterRealpaths);
     if (c === null || c.kind !== "repo") {
       failed.push({
@@ -5154,10 +5752,10 @@ async function runProjectPreset(options, ctx = {}) {
   }
 }
 function canonicalFileFor(anchorReal, canonicalName) {
-  return join10(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+  return join11(anchorReal, "agents", canonicalName, CANONICAL_FILE);
 }
 function canonicalLabelFor(canonicalName) {
-  return join10("agents", canonicalName, CANONICAL_FILE);
+  return join11("agents", canonicalName, CANONICAL_FILE);
 }
 async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
   const declared = {
@@ -5178,13 +5776,13 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
   if (real === anchorReal) {
     return { ...declared, isAnchor: true, reachable: true, canonicalPresent: false };
   }
-  if (!existsSync2(join10(real, ".git"))) {
+  if (!existsSync2(join11(real, ".git"))) {
     return { ...declared, isAnchor: false, reachable: false, canonicalPresent: false };
   }
   const canonicalName = basename5(real);
   let content;
   try {
-    content = await readMarkdownFile4(canonicalFileFor(anchorReal, canonicalName));
+    content = await readMarkdownFile6(canonicalFileFor(anchorReal, canonicalName));
   } catch {
     return {
       ...declared,
@@ -5204,7 +5802,7 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
       canonicalPresent: false
     };
   }
-  const section = parseMarkers(content);
+  const section = parseMarkers3(content);
   return {
     ...declared,
     isAnchor: false,
@@ -5267,7 +5865,7 @@ function gatherViewPreset(repositoryRoot, anchorReal, viewName, roster) {
     }
     return { kind: "unreadable", canonicalName: viewName, viewName };
   }
-  const section = parseMarkers(content);
+  const section = parseMarkers3(content);
   if (section.kind === "ok") {
     if (normalizeViewBlock(section.generated) === normalizeViewBlock(desiredBlock)) {
       return { kind: "in-sync", canonicalName: viewName, viewName };
@@ -5293,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 readMarkdownFile4(file);
+  const existing = await readMarkdownFile6(file);
   await writeMarkdownFile5(file, renderWithMarkers4(existing, outcome.block, label));
 }
 async function applyPresetPlan(anchorReal, plan) {
@@ -5307,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 readMarkdownFile4(file);
+  const existing = await readMarkdownFile6(file);
   await writeMarkdownFile5(file, renderWithMarkers4(existing, plan.desiredBlock, label));
 }
 function presetFailureReason(error) {
@@ -5560,24 +6158,24 @@ function gatherArchiveTeardown(repositoryRoot, manifest, target) {
   const instructionFiles = [];
   for (const name of INSTRUCTION_FILES) {
     try {
-      lstatSync(join10(real, name));
+      lstatSync(join11(real, name));
       instructionFiles.push(name);
     } catch {
     }
   }
   let ignored;
   try {
-    ignored = new Set(readGitignoreLines(join10(real, ".gitignore")).map((l) => l.trim()));
+    ignored = new Set(readGitignoreLines(join11(real, ".gitignore")).map((l) => l.trim()));
   } catch {
     ignored = /* @__PURE__ */ new Set();
   }
   const gitignorePatterns = INSTRUCTION_FILES.filter((p) => ignored.has(p) || ignored.has(`/${p}`));
-  const canonical2 = existsSync2(join10(anchorReal, "agents", canonicalName, CANONICAL_FILE));
+  const canonical2 = existsSync2(join11(anchorReal, "agents", canonicalName, CANONICAL_FILE));
   let viewLink = false;
   const viewPath = manifest.workspace.view;
   if (viewPath !== void 0) {
     try {
-      lstatSync(join10(resolveViewDir(repositoryRoot, viewPath), canonicalName));
+      lstatSync(join11(resolveViewDir(repositoryRoot, viewPath), canonicalName));
       viewLink = true;
     } catch {
     }
@@ -5591,11 +6189,11 @@ function gatherArchiveTeardown(repositoryRoot, manifest, target) {
   };
 }
 function teardownExpectedTargets(repoReal, anchorReal, canonicalName) {
-  const canonicalFile = join10(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+  const canonicalFile = join11(anchorReal, "agents", canonicalName, CANONICAL_FILE);
   return expectedSymlinkTargets(repoReal, canonicalFile);
 }
 function viewLinkPointsAt(viewDir, name, repoReal) {
-  const filePath = join10(viewDir, name);
+  const filePath = join11(viewDir, name);
   try {
     if (!lstatSync(filePath).isSymbolicLink()) return false;
     const target = readlinkSync(filePath);
@@ -5606,7 +6204,7 @@ function viewLinkPointsAt(viewDir, name, repoReal) {
   }
 }
 function viewLinkPointsAtPath(viewDir, name, expectedRepoPath) {
-  const filePath = join10(viewDir, name);
+  const filePath = join11(viewDir, name);
   try {
     if (!lstatSync(filePath).isSymbolicLink()) return false;
     const target = readlinkSync(filePath);
@@ -5657,7 +6255,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
   if (!isAnchor) {
     if (repoReal !== void 0) {
       for (const spec of teardownExpectedTargets(repoReal, anchorReal, canonicalName)) {
-        const { state, actualTarget } = inspectSymlink(join10(repoReal, spec.name), spec.target);
+        const { state, actualTarget } = inspectSymlink(join11(repoReal, spec.name), spec.target);
         if (isSelf) {
           if (state !== "missing")
             items.push({
@@ -5694,7 +6292,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
       }
       let ignored;
       try {
-        ignored = new Set(readGitignoreLines(join10(repoReal, ".gitignore")).map((l) => l.trim()));
+        ignored = new Set(readGitignoreLines(join11(repoReal, ".gitignore")).map((l) => l.trim()));
         for (const p of INSTRUCTION_FILES) {
           if (ignored.has(p) || ignored.has(`/${p}`)) {
             items.push({
@@ -5717,7 +6315,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
     const viewPath = manifest.workspace.view;
     if (viewPath !== void 0) {
       const viewDir = resolveViewDir(repositoryRoot, viewPath);
-      const linkPath = join10(viewDir, canonicalName);
+      const linkPath = join11(viewDir, canonicalName);
       let isLink = false;
       try {
         isLink = lstatSync(linkPath).isSymbolicLink();
@@ -5743,8 +6341,8 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
         else items.push({ kind: "view-symlink", label: canonicalName, state: "removable" });
       }
     }
-    const canonicalFile = join10(anchorReal, "agents", canonicalName, CANONICAL_FILE);
-    const canonicalLabel = join10("agents", canonicalName, CANONICAL_FILE);
+    const canonicalFile = join11(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+    const canonicalLabel = join11("agents", canonicalName, CANONICAL_FILE);
     let canonicalIsLink = false;
     try {
       canonicalIsLink = lstatSync(canonicalFile).isSymbolicLink();
@@ -5771,7 +6369,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
         });
       }
       if (content !== void 0 && content !== "") {
-        const section = parseMarkers(content);
+        const section = parseMarkers3(content);
         if (section.kind === "ok" && canonicalShared) {
           items.push({
             kind: "canonical-block",
@@ -5787,7 +6385,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
             note: "repo could not be resolved, so ownership cannot be verified (check manually)"
           });
         } else if (section.kind === "ok") {
-          const emptyAfter = removeMarkerSection(content, canonicalLabel).trim().length === 0;
+          const emptyAfter = removeMarkerSection2(content, canonicalLabel).trim().length === 0;
           items.push({
             kind: "canonical-block",
             label: canonicalLabel,
@@ -5848,12 +6446,12 @@ function applyRepoTeardown(repositoryRoot, manifest, plan) {
   );
   for (const item of removable.filter((i) => i.kind === "instruction-symlink")) {
     const expected = expectedByName.get(item.label);
-    if (repoReal === null || expected === void 0 || inspectSymlink(join10(repoReal, item.label), expected).state !== "correct") {
+    if (repoReal === null || expected === void 0 || inspectSymlink(join11(repoReal, item.label), expected).state !== "correct") {
       changed(item.label);
       continue;
     }
     try {
-      unlinkSync(join10(repoReal, item.label));
+      unlinkSync(join11(repoReal, item.label));
       removed.push(item.label);
     } catch (error) {
       failed.push({ label: item.label, message: failureReason(error) });
@@ -5872,7 +6470,7 @@ function applyRepoTeardown(repositoryRoot, manifest, plan) {
       continue;
     }
     try {
-      unlinkSync(join10(viewDir, item.label));
+      unlinkSync(join11(viewDir, item.label));
       removed.push(`view/${item.label}`);
     } catch (error) {
       failed.push({ label: `view/${item.label}`, message: failureReason(error) });
@@ -5880,7 +6478,7 @@ function applyRepoTeardown(repositoryRoot, manifest, plan) {
   }
   const NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0;
   for (const item of removable.filter((i) => i.kind === "canonical-block")) {
-    const canonicalFile = join10(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+    const canonicalFile = join11(anchorReal, "agents", canonicalName, CANONICAL_FILE);
     try {
       if (lstatSync(canonicalFile).isSymbolicLink()) {
         changed(item.label);
@@ -5900,11 +6498,11 @@ function applyRepoTeardown(repositoryRoot, manifest, plan) {
     }
     try {
       const content = readFileSync(fd, "utf8");
-      if (parseMarkers(content).kind !== "ok") {
+      if (parseMarkers3(content).kind !== "ok") {
         changed(item.label);
         continue;
       }
-      const next = Buffer.from(removeMarkerSection(content, item.label), "utf8");
+      const next = Buffer.from(removeMarkerSection2(content, item.label), "utf8");
       ftruncateSync(fd, 0);
       writeSync(fd, next, 0, next.length, 0);
       removed.push(item.label);
@@ -6154,12 +6752,12 @@ function gatherRenameWiring(repositoryRoot, manifest, oldBasename) {
   } catch {
     return { canonicalDirOld: false, viewLinkOld: false };
   }
-  const canonicalDirOld = existsSync2(join10(anchorReal, "agents", oldBasename));
+  const canonicalDirOld = existsSync2(join11(anchorReal, "agents", oldBasename));
   let viewLinkOld = false;
   const viewPath = manifest.workspace.view;
   if (viewPath !== void 0) {
     try {
-      lstatSync(join10(resolveViewDir(repositoryRoot, viewPath), oldBasename));
+      lstatSync(join11(resolveViewDir(repositoryRoot, viewPath), oldBasename));
       viewLinkOld = true;
     } catch {
     }
@@ -6517,7 +7115,7 @@ async function doRunProjectSeedAnchor(options, ctx) {
     console.log("\u2139\uFE0F No repo roster declared \u2014 nothing to seed.");
     return;
   }
-  const anchorDoc = join10(repositoryRoot, CANONICAL_FILE);
+  const anchorDoc = join11(repositoryRoot, CANONICAL_FILE);
   if (pathPresent(anchorDoc)) {
     console.log(
       `\u2705 The anchor's own \`${CANONICAL_FILE}\` already exists \u2014 hand-maintained, left untouched.`
@@ -6579,7 +7177,7 @@ function regularFileSpokes(repoReal) {
   const out = [];
   for (const spoke of ["CLAUDE.md", ".github/copilot-instructions.md"]) {
     try {
-      const st = lstatSync(join10(repoReal, spoke));
+      const st = lstatSync(join11(repoReal, spoke));
       if (!st.isSymbolicLink() && st.isFile()) out.push(spoke);
     } catch {
     }
@@ -6625,8 +7223,8 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
     };
   }
   const isAnchor = argReal === anchorReal;
-  const reachable = existsSync2(join10(argReal, ".git"));
-  const canonicalFile = join10(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+  const reachable = existsSync2(join11(argReal, ".git"));
+  const canonicalFile = join11(anchorReal, "agents", canonicalName, CANONICAL_FILE);
   return {
     path,
     declared,
@@ -6635,13 +7233,13 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
     reachable,
     canonicalName,
     ...viewCanonicalName !== void 0 ? { viewCanonicalName } : {},
-    agentsState: inspectAgentsState(join10(argReal, CANONICAL_FILE)),
+    agentsState: inspectAgentsState(join11(argReal, CANONICAL_FILE)),
     canonicalExists: pathPresent(canonicalFile),
     regularSpokes: regularFileSpokes(argReal)
   };
 }
 function relocateAgentsFile(repoReal, canonicalFile) {
-  const agentsFile = join10(repoReal, CANONICAL_FILE);
+  const agentsFile = join11(repoReal, CANONICAL_FILE);
   try {
     mkdirSync(dirname3(canonicalFile), { recursive: true });
   } catch (error) {
@@ -6675,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 = parseMarkers(content);
+  const section = parseMarkers3(content);
   if (section.kind === "ok") return { kind: "already-marked", viewName };
   if (section.kind === "no_markers") {
     const block = renderViewPresetBlock({
@@ -6696,7 +7294,7 @@ async function applyViewRetrofit(anchorReal, outcome) {
     isLink = false;
   }
   if (isLink) throw new Error(`Canonical is a symlink in ${label}`);
-  const existing = await readMarkdownFile4(file);
+  const existing = await readMarkdownFile6(file);
   await writeMarkdownFile5(file, seedMarkers(existing, outcome.block, label));
 }
 async function doRunProjectRetrofit(repo, options, ctx) {
@@ -6758,7 +7356,7 @@ async function doRunProjectRetrofit(repo, options, ctx) {
   let failure;
   let partial = false;
   if (options.apply === true && plan.action === "relocate" && argReal !== void 0) {
-    const canonicalFile = join10(anchorReal, "agents", plan.canonicalName, CANONICAL_FILE);
+    const canonicalFile = join11(anchorReal, "agents", plan.canonicalName, CANONICAL_FILE);
     const res = relocateAgentsFile(argReal, canonicalFile);
     if (res.ok) {
       applied = true;
@@ -6959,119 +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";
-
-// src/lib/context-channel.ts
-import { homedir as homedir7 } from "os";
-import { join as join11 } from "path";
-import {
-  ORIENTATION_END,
-  ORIENTATION_START,
-  parseMarkers as parseMarkers2,
-  readMarkdownFile as readMarkdownFile5,
-  removeMarkerSection as removeMarkerSection2
-} from "@basou/core";
-var CODEX_TARGET_PATH = join11(homedir7(), ".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}
-`;
-  if (existing === null || existing === "") return wrapped;
-  const section = parseMarkers2(existing, markers);
-  switch (section.kind) {
-    case "ok":
-      return `${section.before}${markers.start}
-${block}${markers.end}${section.after}`;
-    case "no_markers": {
-      const sep = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-      return `${existing}${sep}${wrapped}`;
-    }
-    default:
-      throw new Error(
-        "The basou-managed markers in the target are malformed (a marker is missing, duplicated, or out of order). Fix or remove them, then retry."
-      );
-  }
-}
-async function backupOnce(target, existing) {
-  if (existing === null) return;
-  const bak = `${target}.basou-bak`;
-  const already = await readMarkdownFile5(bak);
-  if (already !== null) return;
-  await writeFileDurable(bak, existing);
-}
-async function syncMarkerBlock(opts) {
-  const { target, markers, block } = opts;
-  await assertNotSymlink(target);
-  const existing = await readMarkdownFile5(target);
-  const newBody = buildTargetBody(existing, block, markers);
-  if (newBody === existing) return { action: "unchanged" };
-  const hadBlock = existing !== null && parseMarkers2(existing, markers).kind === "ok";
-  const action = hadBlock ? "updated" : "installed";
-  if (opts.dryRun === true) return { action };
-  const recheck = await readMarkdownFile5(target);
-  if (recheck !== existing) {
-    throw new Error(
-      "The target changed during sync; aborting so a concurrent edit is not overwritten. Re-run the command."
-    );
-  }
-  await backupOnce(target, existing);
-  await writeFileDurable(target, newBody);
-  return { action };
-}
-function assertNoMarkerLine(body, markers) {
-  for (const line of body.split(/\r?\n/)) {
-    if (line === markers.start || line === markers.end) {
-      throw new Error(
-        "The content contains a basou marker line, which would corrupt the managed block. Remove that line from the source."
-      );
-    }
-  }
-}
-async function removeMarkerBlock(opts) {
-  const { target, markers, fileLabel } = opts;
-  await assertNotSymlink(target);
-  const existing = await readMarkdownFile5(target);
-  if (existing === null) return { removed: false };
-  const newBody = removeMarkerSection2(existing, fileLabel, markers);
-  if (newBody === existing) return { removed: false };
-  if (opts.dryRun === true) return { removed: true };
-  const recheck = await readMarkdownFile5(target);
-  if (recheck !== existing) {
-    throw new Error(
-      "The target changed during unsync; aborting so a concurrent edit is not overwritten. Re-run the command."
-    );
-  }
-  await backupOnce(target, existing);
-  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 renderOrientationToCodexChannel(opts) {
-  const body = await readMarkdownFile5(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"}`
-  };
-}
+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";
@@ -7155,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) => {
@@ -7254,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}`);
@@ -7282,7 +7770,12 @@ async function doRunProtocolUnsync(options) {
 }
 
 // src/commands/refresh.ts
-import { assertBasouRootSafe as assertBasouRootSafe9, basouPaths as basouPaths11, findErrorCode as findErrorCode9 } from "@basou/core";
+import {
+  assertBasouRootSafe as assertBasouRootSafe9,
+  basouPaths as basouPaths11,
+  findErrorCode as findErrorCode9,
+  readManifest as readManifest7
+} from "@basou/core";
 import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
 
 // src/commands/refresh-watch.ts
@@ -7436,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)",
@@ -7567,24 +8060,23 @@ async function computeRefresh(options, ctx) {
 }
 async function doRunRefresh(options, ctx) {
   const { result, paths } = await computeRefresh(options, ctx);
-  const channelLine = options.dryRun === true ? null : await syncCodexOrientationChannel(paths, ctx.codexChannelPath);
+  const reported = { ...result, codexChannel: { status: "retired" } };
   if (options.json === true) {
-    console.log(JSON.stringify(result));
+    console.log(JSON.stringify(reported));
   } else {
     printRefreshSummary(result);
-    if (channelLine !== null) console.log(channelLine);
+    const line = await retiredChannelNotice(paths);
+    if (line !== null) console.log(line);
   }
-  return result;
+  return reported;
 }
-async function syncCodexOrientationChannel(paths, channelPath) {
+async function retiredChannelNotice(paths) {
   try {
-    const rendered = await renderOrientationToCodexChannel({
-      orientationPath: paths.files.orientation,
-      ...channelPath !== void 0 ? { channelPath } : {}
-    });
-    return rendered === null ? null : rendered.line;
-  } catch (error) {
-    return `codex channel skipped: ${error instanceof Error ? error.message : String(error)}`;
+    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) {
@@ -7737,7 +8229,7 @@ import {
   findErrorCode as findErrorCode11,
   findUnbindableRepos,
   parseReviewRecordInput,
-  readManifest as readManifest7,
+  readManifest as readManifest8,
   resolveRepoRoot,
   sanitizePath as sanitizePath2
 } from "@basou/core";
@@ -7824,7 +8316,7 @@ async function doRunReviewRecord(options, ctx) {
   }
   const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
   const occurredAt = now.toISOString();
-  const manifest = await readManifest7(paths);
+  const manifest = await readManifest8(paths);
   const invocationArgs = options.file !== void 0 ? [
     "--file",
     sanitizePath2(resolve10(cwd, options.file), {
@@ -8162,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 {
@@ -8174,11 +8666,12 @@ import {
   codexAdapterMetadata,
   appendChainedEvent as coreAppendChainedEvent2,
   finalizeSessionYaml as finalizeSessionYaml2,
+  findBasouSessionStartHook as findBasouSessionStartHook2,
   getDiff,
   getSnapshot as getSnapshot2,
   overwriteYamlFile as overwriteYamlFile2,
   prefixedUlid as prefixedUlid4,
-  readManifest as readManifest8,
+  readManifest as readManifest9,
   readYamlFile as readYamlFile6,
   resolveClaudeCodeCommand,
   resolveCodexCommand,
@@ -8225,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) {
@@ -8238,7 +8731,7 @@ async function runTrackedTool(args, options, ctx, adapter) {
   const repoRoot = await resolveRepositoryRootForRun(cwd);
   const paths = basouPaths15(repoRoot);
   await assertBasouRootSafe12(paths.root);
-  const manifest = await readManifest8(paths);
+  const manifest = await readManifest9(paths);
   const sessionId = prefixedUlid4("ses");
   const sessionDir = join14(paths.sessions, sessionId);
   await mkdir2(sessionDir, { recursive: true });
@@ -8592,22 +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 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,
@@ -8619,7 +9115,7 @@ import {
   importSessionFromJson as importSessionFromJson2,
   loadSessionEntries as loadSessionEntries2,
   readAllEvents,
-  readManifest as readManifest9,
+  readManifest as readManifest10,
   readYamlFile as readYamlFile7,
   rechainSessionInPlace,
   resolveSessionId as resolveSessionId3,
@@ -9031,7 +9527,7 @@ async function doRunSessionImport(options, ctx) {
   const repositoryRoot = await resolveRepositoryRootForSession(cwd, "import");
   const paths = basouPaths16(repositoryRoot);
   await assertWorkspaceInitialized11(paths.root);
-  const manifest = await readManifest9(paths);
+  const manifest = await readManifest10(paths);
   const rawBody = await readInputFile(options.from);
   const json = parseJsonStrict(rawBody);
   const parsed = SessionImportPayloadSchema2.safeParse(json);
@@ -9058,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 });
@@ -9175,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 });
@@ -9413,7 +9909,7 @@ import {
   basouPaths as basouPaths18,
   buildStatusSnapshot,
   findErrorCode as findErrorCode14,
-  readManifest as readManifest10,
+  readManifest as readManifest11,
   resolveRepositoryRoot as resolveRepositoryRoot12,
   writeStatus
 } from "@basou/core";
@@ -9444,7 +9940,7 @@ async function doRunStatus(options, ctx) {
   }
   let manifest;
   try {
-    manifest = await readManifest10(paths);
+    manifest = await readManifest11(paths);
   } catch (error) {
     if (findErrorCode14(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
@@ -9496,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,
@@ -9510,7 +10006,7 @@ import {
   loadSessionEntries as loadSessionEntries3,
   loadTaskEntries,
   prefixedUlid as prefixedUlid5,
-  readManifest as readManifest11,
+  readManifest as readManifest12,
   readTaskFile,
   readTaskFileWithArchiveFallback,
   reconcileAllTasks,
@@ -9637,7 +10133,7 @@ async function doRunTaskNew(options, ctx) {
     });
     return;
   }
-  const manifest = await readManifest11(paths);
+  const manifest = await readManifest12(paths);
   const result = await createTaskWithEvent({
     mode: "ad-hoc",
     paths,
@@ -9985,7 +10481,7 @@ async function doRunTaskStatus(taskIdInput, newStatusInput, options, ctx) {
     });
     return;
   }
-  const manifest = await readManifest11(paths);
+  const manifest = await readManifest12(paths);
   const result = await updateTaskStatusWithEvent({
     mode: "ad-hoc",
     paths,
@@ -10038,7 +10534,7 @@ async function doRunTaskReconcile(options, ctx) {
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "reconcile");
   const paths = basouPaths19(repositoryRoot);
   await assertWorkspaceInitialized13(paths.root);
-  const manifest = await readManifest11(paths);
+  const manifest = await readManifest12(paths);
   const nowProvider = ctx.nowProvider ?? (() => /* @__PURE__ */ new Date());
   const write = options.write === true;
   const verbose = isVerbose(options);
@@ -10218,7 +10714,7 @@ async function doRunTaskRefreshLinkage(taskIdInput, options, ctx) {
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "refresh-linkage");
   const paths = basouPaths19(repositoryRoot);
   await assertWorkspaceInitialized13(paths.root);
-  const manifest = await readManifest11(paths);
+  const manifest = await readManifest12(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   const nowProvider = ctx.nowProvider ?? (() => /* @__PURE__ */ new Date());
   const write = options.write === true;
@@ -10298,7 +10794,7 @@ async function doRunTaskEdit(taskIdInput, options, ctx) {
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "edit");
   const paths = basouPaths19(repositoryRoot);
   await assertWorkspaceInitialized13(paths.root);
-  const manifest = await readManifest11(paths);
+  const manifest = await readManifest12(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
   const occurredAt = now.toISOString();
@@ -10354,7 +10850,7 @@ async function doRunTaskDelete(taskIdInput, options, ctx) {
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "delete");
   const paths = basouPaths19(repositoryRoot);
   await assertWorkspaceInitialized13(paths.root);
-  const manifest = await readManifest11(paths);
+  const manifest = await readManifest12(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   if (options.yes !== true) {
     await confirmDestructiveAction("delete", taskId);
@@ -10399,7 +10895,7 @@ async function doRunTaskArchive(taskIdInput, options, ctx) {
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "archive");
   const paths = basouPaths19(repositoryRoot);
   await assertWorkspaceInitialized13(paths.root);
-  const manifest = await readManifest11(paths);
+  const manifest = await readManifest12(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   if (options.yes !== true) {
     await confirmDestructiveAction("archive", taskId);
@@ -10441,8 +10937,8 @@ async function confirmDestructiveAction(action, taskId) {
   }
 }
 async function readSingleLineFromStdin() {
-  const { createInterface: createInterface2 } = await import("readline/promises");
-  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  const { createInterface: createInterface3 } = await import("readline/promises");
+  const rl = createInterface3({ input: process.stdin, output: process.stdout });
   try {
     const line = await rl.question("");
     return line;
@@ -10511,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 });
@@ -10715,30 +11211,342 @@ async function assertWorkspaceInitialized14(basouRoot) {
 
 // src/commands/view.ts
 import { spawn } from "child_process";
-import { createHash } from "crypto";
-import { basename as basename8, resolve as resolve13 } from "path";
+import { createHash as createHash2 } from "crypto";
+import { basename as basename9, resolve as resolve13 } from "path";
 import {
   assertBasouRootSafe as assertBasouRootSafe18,
-  basouPaths as basouPaths21,
+  basouPaths as basouPaths22,
   findErrorCode as findErrorCode18,
-  readManifest as readManifest14,
-  resolveRepositoryRoot as resolveRepositoryRoot14
+  readManifest as readManifest16,
+  resolveRepositoryRoot as resolveRepositoryRoot15
 } from "@basou/core";
 import { InvalidArgumentError as InvalidArgumentError7 } from "commander";
 
+// src/lib/portfolio-coverage.ts
+import { createReadStream as createReadStream2 } from "fs";
+import { readdir as readdir3, stat as stat6 } from "fs/promises";
+import { homedir as homedir12 } from "os";
+import { basename as basename7, dirname as dirname4, join as join17 } from "path";
+import { createInterface as createInterface2 } from "readline";
+import { basouPaths as basouPaths21, readManifest as readManifest13, resolveRepositoryRoot as resolveRepositoryRoot14 } from "@basou/core";
+function uncapturedTotal(result) {
+  return result.groups.reduce((sum, g) => sum + g.logs, 0) + result.unplaceable;
+}
+async function checkPortfolioCoverage(workspaces, ctx = {}) {
+  const { roots, inertWorkspaces } = await collectDeclaredRoots(workspaces);
+  const listedDirs = new Set([...roots].map((root) => encodeProjectDir(root)));
+  const claudeProjectsDir = ctx.claudeProjectsDir ?? join17(homedir12(), ".claude", "projects");
+  const codexSessionsDir = ctx.codexSessionsDir ?? join17(homedir12(), ".codex", "sessions");
+  const tally = new Tally(roots);
+  const absentTrees = [];
+  const claudeFiles = await listClaudeTranscripts(claudeProjectsDir);
+  if (claudeFiles === void 0) absentTrees.push(claudeProjectsDir);
+  else {
+    for (const file of claudeFiles) {
+      await tally.add(
+        file,
+        "claude-code",
+        claudeTranscriptCwd,
+        listedDirs.has(basename7(dirname4(file)))
+      );
+    }
+  }
+  const codexFiles = await listCodexRollouts(codexSessionsDir);
+  if (codexFiles === void 0) absentTrees.push(codexSessionsDir);
+  else {
+    for (const file of codexFiles) await tally.add(file, "codex", codexRolloutCwd, true);
+  }
+  return tally.finish(absentTrees, inertWorkspaces);
+}
+async function collectDeclaredRoots(workspaces) {
+  const roots = /* @__PURE__ */ new Set();
+  const inertWorkspaces = [];
+  for (const ws of workspaces) {
+    let importRoot;
+    try {
+      importRoot = await resolveRepositoryRoot14(ws.repoRoot);
+    } catch {
+      inertWorkspaces.push({ path: ws.repoRoot, reason: "not_a_git_repo" });
+      continue;
+    }
+    let resolved;
+    try {
+      const manifest = await readManifest13(basouPaths21(importRoot));
+      resolved = resolveSourceRoots({
+        projectFlags: [],
+        manifest,
+        repoRoot: importRoot,
+        cwd: importRoot
+      });
+    } catch (error) {
+      const absent = error instanceof Error && error.message === "YAML file not found";
+      inertWorkspaces.push({
+        path: ws.repoRoot,
+        reason: absent ? "no_store" : "unreadable_store"
+      });
+      continue;
+    }
+    for (const root of resolved) roots.add(root);
+  }
+  return { roots, inertWorkspaces };
+}
+var Tally = class {
+  constructor(declaredRoots) {
+    this.declaredRoots = declaredRoots;
+  }
+  declaredRoots;
+  groups = /* @__PURE__ */ new Map();
+  kinds = /* @__PURE__ */ new Map();
+  attributed = 0;
+  scanned = 0;
+  unplaceable = 0;
+  unreadable = 0;
+  /**
+   * Record one source log. `listedByImport` is whether the importer would even
+   * read this file (the Claude directory guard); a cwd match on a file import
+   * never lists is not capture.
+   */
+  async add(file, source, readCwd, listedByImport) {
+    this.scanned++;
+    const cwd = await readCwd(file);
+    if (cwd === null) {
+      this.unreadable++;
+      return;
+    }
+    if (cwd === void 0) {
+      this.unplaceable++;
+      return;
+    }
+    const declared = this.declaredRoots.has(cwd);
+    if (declared && listedByImport) {
+      this.attributed++;
+      return;
+    }
+    const kind = declared ? "dir_not_listed" : enclosingRoot(cwd, this.declaredRoots) !== void 0 ? "below_declared_root" : "no_declared_root";
+    this.kinds.set(cwd, kind);
+    const group = this.groups.get(cwd);
+    if (group === void 0) this.groups.set(cwd, { logs: 1, sources: /* @__PURE__ */ new Set([source]) });
+    else {
+      group.logs++;
+      group.sources.add(source);
+    }
+  }
+  finish(absentTrees, inertWorkspaces) {
+    const groups = [];
+    for (const [cwd, { logs, sources }] of this.groups) {
+      const kind = this.kinds.get(cwd) ?? "no_declared_root";
+      const declaredRoot = kind === "below_declared_root" ? enclosingRoot(cwd, this.declaredRoots) : void 0;
+      groups.push({
+        cwd,
+        logs,
+        sources: [...sources].sort(),
+        kind,
+        ...declaredRoot !== void 0 ? { declaredRoot } : {}
+      });
+    }
+    const rank = (k) => k === "dir_not_listed" ? 0 : k === "below_declared_root" ? 1 : 2;
+    groups.sort((a, b) => {
+      if (a.kind !== b.kind) return rank(a.kind) - rank(b.kind);
+      if (a.logs !== b.logs) return b.logs - a.logs;
+      return a.cwd < b.cwd ? -1 : a.cwd > b.cwd ? 1 : 0;
+    });
+    return {
+      logsScanned: this.scanned,
+      attributed: this.attributed,
+      groups,
+      unplaceable: this.unplaceable,
+      unreadable: this.unreadable,
+      absentTrees,
+      inertWorkspaces
+    };
+  }
+};
+function enclosingRoot(cwd, roots) {
+  for (const root of roots) {
+    if (cwd.startsWith(root.endsWith("/") ? root : `${root}/`)) return root;
+  }
+  return void 0;
+}
+async function isDirEntry(parent, entry) {
+  if (entry.isDirectory()) return true;
+  if (!entry.isSymbolicLink()) return false;
+  try {
+    return (await stat6(join17(parent, entry.name))).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function listClaudeTranscripts(projectsRoot) {
+  let entries;
+  try {
+    entries = await readdir3(projectsRoot, { withFileTypes: true });
+  } catch {
+    return void 0;
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (!await isDirEntry(projectsRoot, entry)) continue;
+    const full = join17(projectsRoot, entry.name);
+    let names;
+    try {
+      names = await readdir3(full);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (name.endsWith(".jsonl")) files.push(join17(full, name));
+    }
+  }
+  return files.sort();
+}
+async function listCodexRollouts(sessionsRoot) {
+  const found = [];
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await readdir3(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join17(dir, entry.name);
+      if (entry.isDirectory()) await walk(full);
+      else if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(".jsonl")) {
+        found.push(full);
+      }
+    }
+  };
+  try {
+    await readdir3(sessionsRoot);
+  } catch {
+    return void 0;
+  }
+  await walk(sessionsRoot);
+  return found.sort();
+}
+async function claudeTranscriptCwd(file) {
+  const stream = createReadStream2(file, { encoding: "utf8" });
+  const lines = createInterface2({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
+  try {
+    for await (const line of lines) {
+      if (line.length === 0) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (typeof record !== "object" || record === null || Array.isArray(record)) continue;
+      const cwd = record.cwd;
+      if (typeof cwd === "string" && cwd.length > 0) return cwd;
+    }
+    return void 0;
+  } catch {
+    return null;
+  } finally {
+    lines.close();
+    stream.destroy();
+  }
+}
+async function codexRolloutCwd(file) {
+  const meta = await readRolloutMeta(file);
+  return meta === void 0 ? void 0 : meta.cwd;
+}
+var GROUP_LIST_CAP = 10;
+function groupNote(group) {
+  if (group.kind === "below_declared_root") {
+    return ` \u2014 inside declared root ${group.declaredRoot}, and the recorded cwd must EQUAL a source root`;
+  }
+  if (group.kind === "dir_not_listed") {
+    return " \u2014 this cwd IS a declared root, but the transcript's per-project directory is not one import lists";
+  }
+  return "";
+}
+function formatCoverageReport(result) {
+  const lines = [];
+  if (result.logsScanned === 0) {
+    const where = result.absentTrees.length > 0 ? ` (no source logs found: ${result.absentTrees.join(", ")})` : "";
+    lines.push(
+      `Capture coverage: nothing to check \u2014 no native session logs on this machine${where}.`
+    );
+    return [...lines, ...inertLines(result)];
+  }
+  const total = uncapturedTotal(result);
+  const caveats = [];
+  if (result.unreadable > 0) caveats.push(`${result.unreadable} unreadable, verdict unknown`);
+  if (result.absentTrees.length > 0) caveats.push(`not scanned: ${result.absentTrees.join(", ")}`);
+  const caveat = caveats.length > 0 ? ` (${caveats.join("; ")})` : "";
+  if (total === 0 && result.unreadable === 0) {
+    lines.push(
+      `Capture coverage: OK. ${result.logsScanned} source log(s) scanned, all imported by a registered workspace${caveat}.`
+    );
+    return [...lines, ...inertLines(result)];
+  }
+  const pct = Math.round(total / result.logsScanned * 100);
+  lines.push(
+    `Capture coverage: ${total} of ${result.logsScanned} source log(s) (${pct}%) are imported by no registered workspace${caveat}:`
+  );
+  for (const g of result.groups.slice(0, GROUP_LIST_CAP)) {
+    const via = g.sources.join("+");
+    lines.push(`  ${String(g.logs).padStart(4)}  ${g.cwd} (${via})${groupNote(g)}`);
+  }
+  const rest = result.groups.length - GROUP_LIST_CAP;
+  if (rest > 0) {
+    const restLogs = result.groups.slice(GROUP_LIST_CAP).reduce((sum, g) => sum + g.logs, 0);
+    lines.push(
+      `  \u2026 +${rest} more working director${rest === 1 ? "y" : "ies"} (${restLogs} log(s))`
+    );
+  }
+  if (result.unplaceable > 0) {
+    lines.push(
+      `  ${String(result.unplaceable).padStart(4)}  (no directory to name: the log records no cwd import can use, so import drops it)`
+    );
+  }
+  if (result.groups.some((g) => g.kind === "below_declared_root")) {
+    lines.push(
+      "A cwd inside a declared root is dropped by the exact-match rule: the enclosing declaration does not cover it. Declaring that subdirectory itself as a further import.source_roots entry captures it."
+    );
+  }
+  if (result.groups.some((g) => g.kind === "dir_not_listed")) {
+    lines.push(
+      "A transcript whose cwd IS declared but whose per-project directory no declared root encodes to is never listed by the importer. Check that the workspace is registered by the same path spelling the sessions ran in."
+    );
+  }
+  lines.push(
+    "Register the project in a workspace's import.source_roots to start capturing it (registering a path in ~/.basou/portfolio.yaml alone imports nothing \u2014 it only adds the workspace to this view). A scratch directory, a temp path, or a GUI tool's own working directory has no repo to declare and is expected to stay here."
+  );
+  return [...lines, ...inertLines(result)];
+}
+function inertLines(result) {
+  if (result.inertWorkspaces.length === 0) return [];
+  const detail = {
+    not_a_git_repo: "not a git repository",
+    no_store: "no .basou store (never initialized)",
+    unreadable_store: "the .basou manifest is unreadable"
+  };
+  const n = result.inertWorkspaces.length;
+  const lines = [
+    `Capture coverage: ${n} registered entr${n === 1 ? "y" : "ies"} import cannot run in, so ${n === 1 ? "it declares" : "they declare"} no source roots:`
+  ];
+  for (const ws of result.inertWorkspaces) {
+    lines.push(`  ${ws.path} \u2014 ${detail[ws.reason]}`);
+  }
+  return lines;
+}
+
 // src/lib/portfolio-safety.ts
 import { execFile } from "child_process";
-import { lstat as lstat2, realpath as realpath2 } from "fs/promises";
-import { isAbsolute as isAbsolute7, join as join17, relative as relative4, resolve as resolve11 } from "path";
+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 readManifest12 } from "@basou/core";
+import { readManifest as readManifest14 } from "@basou/core";
 var execFileAsync = promisify(execFile);
 function errorCode(error) {
   return error instanceof Error ? error.code : void 0;
 }
 async function canonical(p) {
   try {
-    return await realpath2(p);
+    return await realpath3(p);
   } catch {
     return resolve11(p);
   }
@@ -10753,7 +11561,7 @@ function isBasouPath(p) {
 async function inspectRepo(repoPath) {
   let hasEntry = false;
   try {
-    await lstat2(join17(repoPath, ".basou"));
+    await lstat2(join18(repoPath, ".basou"));
     hasEntry = true;
   } catch (error) {
     if (errorCode(error) !== "ENOENT") {
@@ -10787,7 +11595,7 @@ async function checkPortfolioSafety(workspaces) {
     let viewPath;
     let isMaster = false;
     try {
-      const manifest = await readManifest12(ws.paths);
+      const manifest = await readManifest14(ws.paths);
       sourceRoots = manifest.import?.source_roots ?? [];
       viewPath = manifest.workspace.view;
       isMaster = true;
@@ -10907,7 +11715,7 @@ function formatSafetyReport(result) {
 
 // src/lib/view-server.ts
 import { createServer } from "http";
-import { basename as basename7, join as join18, resolve as resolve12 } from "path";
+import { basename as basename8, join as join19, resolve as resolve12 } from "path";
 import {
   computeWorkStats as computeWorkStats2,
   enumerateApprovals as enumerateApprovals2,
@@ -10917,8 +11725,8 @@ import {
   loadSessionEntries as loadSessionEntries4,
   loadTaskEntries as loadTaskEntries2,
   readAllEvents as readAllEvents2,
-  readManifest as readManifest13,
-  readMarkdownFile as readMarkdownFile7,
+  readManifest as readManifest15,
+  readMarkdownFile as readMarkdownFile8,
   readSessionYaml as readSessionYaml3,
   readTaskFile as readTaskFile2,
   renderDecisions as renderDecisions3,
@@ -11873,7 +12681,7 @@ async function captureStaleness(ws, nowIso) {
 async function overview(ws, nowProvider, resolveRemoteUrl) {
   let manifest;
   try {
-    manifest = await readManifest13(ws.paths);
+    manifest = await readManifest15(ws.paths);
   } catch (error) {
     if (findErrorCode17(error, "ENOENT")) {
       return { initialized: false, repoRoot: ws.repoRoot };
@@ -11913,7 +12721,7 @@ async function rosterRepos(repoRoot, manifest, resolveRemoteUrl) {
       const remote = await resolveRemoteUrl(abs);
       const url = remote !== void 0 ? toBrowserUrl(remote) : null;
       return {
-        name: basename7(abs),
+        name: basename8(abs),
         path: repo.path,
         ...url !== null ? { url } : {},
         ...repo.visibility !== void 0 ? { visibility: repo.visibility } : {}
@@ -11948,7 +12756,7 @@ async function sessionDetail(ws, sessionId) {
     throw error;
   }
   try {
-    const events = await readAllEvents2(join18(ws.paths.sessions, sessionId));
+    const events = await readAllEvents2(join19(ws.paths.sessions, sessionId));
     return { session, events };
   } catch {
     return { session, events: [], degraded: true };
@@ -11970,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 };
   }
@@ -11993,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 };
   }
@@ -12103,7 +12911,10 @@ function registerViewCommand(program2) {
     "--workspace <path>",
     "Workspace repo path to include (repeatable; implies portfolio mode; resolved against the cwd)",
     collectPath3
-  ).option("--check", "Run the portfolio safety preflight and exit (no server)").option("--skip-safety-check", "Skip the portfolio safety preflight on start (not recommended)").option("-v, --verbose", "Show error causes").action(async (options) => {
+  ).option(
+    "--check",
+    "Run the read-only preflight and exit (no server): the portfolio safety check, plus \u2014 in portfolio mode \u2014 a capture-coverage report of session logs no registered workspace imports"
+  ).option("--skip-safety-check", "Skip the portfolio safety preflight on start (not recommended)").option("-v, --verbose", "Show error causes").action(async (options) => {
     await runView(options);
   });
 }
@@ -12119,10 +12930,19 @@ async function doRunView(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const workspaceFlags = options.workspace ?? [];
   const isPortfolio = workspaceFlags.length > 0 || options.portfolio === true;
+  const isWholeRegistry = options.portfolio === true && workspaceFlags.length === 0;
   const deps = isPortfolio ? await buildPortfolioDeps(workspaceFlags, ctx, cwd) : await buildSingleDeps(ctx, cwd);
   if (options.check === true) {
     const result = await checkPortfolioSafety(deps.workspaces);
     for (const line of formatSafetyReport(result)) console.log(line);
+    if (isWholeRegistry) {
+      const coverage = await checkPortfolioCoverage(deps.workspaces, {
+        ...ctx.claudeProjectsDir !== void 0 ? { claudeProjectsDir: ctx.claudeProjectsDir } : {},
+        ...ctx.codexSessionsDir !== void 0 ? { codexSessionsDir: ctx.codexSessionsDir } : {}
+      });
+      console.log("");
+      for (const line of formatCoverageReport(coverage)) console.log(line);
+    }
     if (result.findings.length > 0) process.exitCode = 1;
     return;
   }
@@ -12162,7 +12982,7 @@ async function doRunView(options, ctx) {
 }
 async function buildSingleDeps(ctx, cwd) {
   const repositoryRoot = await resolveRepositoryRootForView(cwd);
-  const paths = basouPaths21(repositoryRoot);
+  const paths = basouPaths22(repositoryRoot);
   await assertWorkspaceInitialized15(paths.root);
   const entry = await buildWorkspaceEntry(repositoryRoot, ctx);
   return {
@@ -12196,14 +13016,14 @@ async function buildPortfolioDeps(workspaceFlags, ctx, cwd) {
   };
 }
 async function buildWorkspaceEntry(repoRoot, ctx, labelOverride) {
-  const paths = basouPaths21(repoRoot);
+  const paths = basouPaths22(repoRoot);
   const importCtx = {
     cwd: repoRoot,
     ...ctx.claudeProjectsDir !== void 0 ? { claudeProjectsDir: ctx.claudeProjectsDir } : {},
     ...ctx.codexSessionsDir !== void 0 ? { codexSessionsDir: ctx.codexSessionsDir } : {}
   };
   try {
-    const manifest = await readManifest14(paths);
+    const manifest = await readManifest16(paths);
     return {
       key: manifest.workspace.id,
       label: labelOverride ?? manifest.workspace.name,
@@ -12215,8 +13035,8 @@ 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)}`,
-      label: labelOverride ?? basename8(repoRoot),
+      key: `ws-${createHash2("sha1").update(repoRoot).digest("hex").slice(0, 12)}`,
+      label: labelOverride ?? basename9(repoRoot),
       paths,
       repoRoot,
       importCtx,
@@ -12283,7 +13103,7 @@ function waitForShutdown(signal) {
 }
 async function resolveRepositoryRootForView(cwd) {
   try {
-    return await resolveRepositoryRoot14(cwd);
+    return await resolveRepositoryRoot15(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 view'.", {
@@ -12334,6 +13154,7 @@ function buildProgram() {
   registerReviewGapsCommand(program2);
   registerProjectCommand(program2);
   registerProtocolCommand(program2);
+  registerChannelCommand(program2);
   registerHookCommand(program2);
   return program2;
 }