@basou/cli 0.28.0 → 0.30.0

package/dist/program.js

@@ -2034,11 +2034,73 @@ async function assertWorkspaceInitialized4(basouRoot) {
 }
 
 // src/commands/hook.ts
-import { open, readFile as readFile2, stat as stat2 } from "fs/promises";
+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 { fileURLToPath } from "url";
 import {
+  buildStopHookCommand,
   DEFAULT_STOP_HOOK_MIN_EDITS,
-  evaluateStopHook
+  evaluateStopHook,
+  findBasouStopHookCommand,
+  removeStopHook,
+  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;
+  }
+}
+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;
+    }
+  }
+  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/commands/hook.ts
 var MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
 function registerHookCommand(program) {
   const hook = program.command("hook").description(
@@ -2049,29 +2111,58 @@ function registerHookCommand(program) {
   ).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 } : {});
+    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 = `
-Install as a Claude Code Stop hook in ~/.claude/settings.json:
-  {
-    "hooks": {
-      "Stop": [
-        { "hooks": [ { "type": "command", "command": "basou hook stop" } ] }
-      ]
-    }
-  }
+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 emits a non-blocking reminder so the agent can
-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. The reminder is
-non-blocking: Claude sees it and may act on it or stop; it never forces the turn
-to continue. The 'stop_hook_active' flag is honored so the nudge cannot loop.
+'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 {
@@ -2109,16 +2200,21 @@ async function doRunHookStop(options, ctx) {
     stopHookActive: false,
     ...options.minEdits !== void 0 ? { minEdits: options.minEdits } : {}
   });
-  if (evaluation.kind !== "nudge") return;
-  write(
-    `${JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "Stop",
-        additionalContext: evaluation.additionalContext
-      }
-    })}
-`
-  );
+  const parts = [];
+  if (evaluation.kind === "nudge") parts.push(evaluation.additionalContext);
+  if (options.requireReview === true && evaluation.review.fires) {
+    parts.push(evaluation.review.additionalContext);
+  }
+  if (parts.length === 0) return;
+  const reason = parts.join("\n\n");
+  const payloadJson = options.block === true ? JSON.stringify({ decision: "block", reason }) : JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "Stop",
+      additionalContext: reason
+    }
+  });
+  write(`${payloadJson}
+`);
 }
 function parseTranscript(transcript) {
   const records = [];
@@ -2143,9 +2239,9 @@ async function defaultReadStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 async function readTranscriptBounded(path, maxBytes = MAX_TRANSCRIPT_BYTES) {
-  const { size } = await stat2(path);
+  const { size } = await stat3(path);
   if (size <= maxBytes) return readFile2(path, "utf8");
-  const handle = await open(path, "r");
+  const handle = await open2(path, "r");
   try {
     const buffer = Buffer.alloc(maxBytes);
     const { bytesRead } = await handle.read(buffer, 0, maxBytes, size - maxBytes);
@@ -2160,12 +2256,173 @@ 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.");
+    }
+    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 };
+    }
+    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;
+  }
+  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}`;
+}
 
 // src/commands/import.ts
 import { createReadStream } from "fs";
-import { readdir, readFile as readFile3, rm, stat as stat3 } from "fs/promises";
-import { homedir as homedir4 } from "os";
-import { basename as basename2, dirname, join as join5, resolve as resolve4 } from "path";
+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 { createInterface } from "readline";
 import {
   AGENT_INFRA_DIRS as AGENT_INFRA_DIRS2,
@@ -2251,11 +2508,11 @@ async function doRunImportClaudeCode(options, ctx) {
     repoRoot: repositoryRoot,
     cwd: ctx.cwd ?? process.cwd()
   });
-  const projectsRoot = ctx.claudeProjectsDir ?? join5(homedir4(), ".claude", "projects");
+  const projectsRoot = ctx.claudeProjectsDir ?? join7(homedir5(), ".claude", "projects");
   const files = await selectTranscriptFiles(projectsRoot, projectPaths, options);
   const projectSet = new Set(projectPaths);
   const candidates = files.map((file) => {
-    const externalId = basename2(file, ".jsonl");
+    const externalId = basename3(file, ".jsonl");
     return {
       externalId,
       sourcePath: file,
@@ -2290,7 +2547,7 @@ async function doRunImportCodex(options, ctx) {
     repoRoot: repositoryRoot,
     cwd: ctx.cwd ?? process.cwd()
   });
-  const sessionsRoot = ctx.codexSessionsDir ?? join5(homedir4(), ".codex", "sessions");
+  const sessionsRoot = ctx.codexSessionsDir ?? join7(homedir5(), ".codex", "sessions");
   const rollouts = await discoverCodexRollouts(sessionsRoot, projectPaths, options);
   const candidates = rollouts.map(({ file, externalId }) => ({
     externalId,
@@ -2345,7 +2602,7 @@ async function importDerivedSessions(paths, manifest, options, sourceKind, candi
         files: payload.session.related_files ?? [],
         workingDirectory: payload.session.working_directory,
         sourceRoots: projectPaths,
-        masterRoot: dirname(paths.root),
+        masterRoot: dirname2(paths.root),
         extraInRoot: AGENT_INFRA_DIRS2
       });
       if (scope.outOfRoot.length > 0) crossProject.push({ externalId, outOfRoot: scope.outOfRoot });
@@ -2419,7 +2676,7 @@ async function importDerivedSessions(paths, manifest, options, sourceKind, candi
     if (priors.length > 0 && options.force === true) {
       if (options.dryRun !== true) {
         for (const { sessionId } of priors) {
-          await rm(join5(paths.sessions, sessionId), { recursive: true, force: true });
+          await rm(join7(paths.sessions, sessionId), { recursive: true, force: true });
         }
       }
       counts.replaced++;
@@ -2530,7 +2787,7 @@ async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
   if (options.session !== void 0) {
     const matches = [];
     for (const projectPath of projectPaths) {
-      const file = join5(projectsRoot, encodeProjectDir(projectPath), `${options.session}.jsonl`);
+      const file = join7(projectsRoot, encodeProjectDir(projectPath), `${options.session}.jsonl`);
       if (await pathExists(file)) matches.push(file);
     }
     if (matches.length === 0) {
@@ -2541,7 +2798,7 @@ async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
   const files = [];
   let anyDirFound = false;
   for (const projectPath of projectPaths) {
-    const transcriptDir = join5(projectsRoot, encodeProjectDir(projectPath));
+    const transcriptDir = join7(projectsRoot, encodeProjectDir(projectPath));
     let entries;
     try {
       entries = await readdir(transcriptDir);
@@ -2551,7 +2808,7 @@ async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
     }
     anyDirFound = true;
     for (const name of entries) {
-      if (name.endsWith(".jsonl")) files.push(join5(transcriptDir, name));
+      if (name.endsWith(".jsonl")) files.push(join7(transcriptDir, name));
     }
   }
   if (!anyDirFound) {
@@ -2561,7 +2818,7 @@ async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
 }
 async function pathExists(file) {
   try {
-    await stat3(file);
+    await stat4(file);
     return true;
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) return false;
@@ -2570,7 +2827,7 @@ async function pathExists(file) {
 }
 async function statSize(file) {
   try {
-    return (await stat3(file)).size;
+    return (await stat4(file)).size;
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) return void 0;
     throw error;
@@ -2608,7 +2865,7 @@ async function findRolloutFiles(sessionsRoot) {
       throw new Error("Failed to read Codex sessions directory", { cause: error });
     }
     for (const entry of entries) {
-      const full = join5(dir, entry.name);
+      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")) {
@@ -2786,7 +3043,7 @@ async function assertWorkspaceInitialized5(basouRoot) {
 }
 
 // src/commands/init.ts
-import { basename as basename3, relative, resolve as resolve5 } from "path";
+import { basename as basename4, relative, resolve as resolve5 } from "path";
 import {
   appendBasouGitignore,
   createManifest,
@@ -2825,7 +3082,7 @@ async function runInit(options, ctx = {}) {
 async function doRunInit(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForInit(cwd);
-  const workspaceName = options.name ?? basename3(repositoryRoot);
+  const workspaceName = options.name ?? basename4(repositoryRoot);
   let repositoryUrl;
   if (options.repoUrl !== void 0) {
     repositoryUrl = options.repoUrl === "" ? null : options.repoUrl;
@@ -3050,13 +3307,13 @@ import {
 } from "@basou/core";
 
 // src/lib/hosts-config.ts
-import { homedir as homedir5 } from "os";
-import { isAbsolute as isAbsolute2, join as join6, resolve as resolve6 } from "path";
+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 = join6(homedir5(), ".basou", "hosts.yaml");
+var DEFAULT_HOSTS_CONFIG_PATH = join8(homedir6(), ".basou", "hosts.yaml");
 function expandTilde2(p) {
-  if (p === "~") return homedir5();
-  if (p.startsWith("~/")) return join6(homedir5(), p.slice(2));
+  if (p === "~") return homedir6();
+  if (p.startsWith("~/")) return join8(homedir6(), p.slice(2));
   return p;
 }
 function isRecord2(value) {
@@ -3382,7 +3639,7 @@ import {
   writeFileSync,
   writeSync
 } from "fs";
-import { basename as basename4, dirname as dirname2, isAbsolute as isAbsolute3, join as join7, relative as relative2, resolve as resolve7 } from "path";
+import { basename as basename5, dirname as dirname3, isAbsolute as isAbsolute3, join as join9, relative as relative2, resolve as resolve7 } from "path";
 import {
   appendBasouGitignore as appendBasouGitignore2,
   basouPaths as basouPaths10,
@@ -3686,7 +3943,7 @@ function classifySourceRoot(repositoryRoot, declaredPath) {
   } catch {
     return { path: declaredPath, kind: "unresolved" };
   }
-  return { path: declaredPath, kind: existsSync(join7(real, ".git")) ? "repo" : "non-repo" };
+  return { path: declaredPath, kind: existsSync(join9(real, ".git")) ? "repo" : "non-repo" };
 }
 async function doRunProjectAdopt(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
@@ -3790,7 +4047,7 @@ async function gatherRepoWiring(repositoryRoot, entry) {
   } catch {
     return { ...base, reachable: false, instructionFiles: [] };
   }
-  if (!existsSync(join7(real, ".git"))) {
+  if (!existsSync(join9(real, ".git"))) {
     return { ...base, reachable: false, instructionFiles: [] };
   }
   try {
@@ -3798,7 +4055,7 @@ async function gatherRepoWiring(repositoryRoot, entry) {
     for (const name of INSTRUCTION_FILES) {
       let present = true;
       try {
-        lstatSync(join7(real, name));
+        lstatSync(join9(real, name));
       } catch {
         present = false;
       }
@@ -3909,10 +4166,10 @@ function gatherRepoGitignore(repositoryRoot, entry) {
   } catch {
     return { ...base, reachable: false, currentLines: [] };
   }
-  if (!existsSync(join7(real, ".git"))) {
+  if (!existsSync(join9(real, ".git"))) {
     return { ...base, reachable: false, currentLines: [] };
   }
-  return { ...base, reachable: true, currentLines: readGitignoreLines(join7(real, ".gitignore")) };
+  return { ...base, reachable: true, currentLines: readGitignoreLines(join9(real, ".gitignore")) };
 }
 function hasErrorCode(error) {
   return error instanceof Error && typeof error.code === "string";
@@ -3926,7 +4183,7 @@ function readGitignoreLines(file) {
   }
 }
 function applyGitignorePlan(repositoryRoot, plan) {
-  const file = join7(realpathSync(resolve7(repositoryRoot, plan.path)), ".gitignore");
+  const file = join9(realpathSync(resolve7(repositoryRoot, plan.path)), ".gitignore");
   let existing = "";
   try {
     existing = readFileSync(file, "utf8");
@@ -4057,16 +4314,16 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
   if (real === anchorReal) {
     return { ...base, isAnchor: true, reachable: true, canonicalPresent: false, files: [] };
   }
-  if (!existsSync(join7(real, ".git"))) {
+  if (!existsSync(join9(real, ".git"))) {
     return { ...base, isAnchor: false, reachable: false, canonicalPresent: false, files: [] };
   }
-  const canonicalFile = isSelf ? join7(real, CANONICAL_FILE) : join7(anchorReal, "agents", basename4(real), CANONICAL_FILE);
+  const canonicalFile = isSelf ? join9(real, CANONICAL_FILE) : join9(anchorReal, "agents", basename5(real), CANONICAL_FILE);
   if (!existsSync(canonicalFile)) {
     return { ...base, isAnchor: false, reachable: true, canonicalPresent: false, files: [] };
   }
   const files = expectedSymlinkTargets(real, canonicalFile, mode).map(
     (spec) => {
-      const { state, actualTarget } = inspectSymlink(join7(real, spec.name), spec.target);
+      const { state, actualTarget } = inspectSymlink(join9(real, spec.name), spec.target);
       return {
         name: spec.name,
         expectedTarget: spec.target,
@@ -4080,7 +4337,7 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
     isAnchor: false,
     reachable: true,
     canonicalPresent: true,
-    canonicalName: basename4(real),
+    canonicalName: basename5(real),
     files
   };
 }
@@ -4095,9 +4352,9 @@ function applySymlinkPlan(repositoryRoot, plan) {
   const created = [];
   const failed = [];
   for (const { name, target } of plan.toCreate) {
-    const filePath = join7(real, name);
+    const filePath = join9(real, name);
     try {
-      mkdirSync(dirname2(filePath), { recursive: true });
+      mkdirSync(dirname3(filePath), { recursive: true });
       symlinkSync(target, filePath);
       created.push(name);
     } catch (error) {
@@ -4248,7 +4505,7 @@ function resolveViewDir(repositoryRoot, viewPath) {
     return realpathSync(abs);
   } catch {
     try {
-      return join7(realpathSync(dirname2(abs)), basename4(abs));
+      return join9(realpathSync(dirname3(abs)), basename5(abs));
     } catch {
       return abs;
     }
@@ -4265,8 +4522,8 @@ function gatherViewRepo(repositoryRoot, viewDir, entry) {
   if (expectedTarget === "" || expectedTarget === ".") {
     return { path: entry.path, reachable: false };
   }
-  const linkName = basename4(repoReal);
-  const { state, actualTarget } = inspectSymlink(join7(viewDir, linkName), expectedTarget);
+  const linkName = basename5(repoReal);
+  const { state, actualTarget } = inspectSymlink(join9(viewDir, linkName), expectedTarget);
   return {
     path: entry.path,
     reachable: true,
@@ -4280,9 +4537,9 @@ function applyViewPlan(viewDir, toCreate) {
   const created = [];
   const failed = [];
   for (const { name, target } of toCreate) {
-    const filePath = join7(viewDir, name);
+    const filePath = join9(viewDir, name);
     try {
-      mkdirSync(dirname2(filePath), { recursive: true });
+      mkdirSync(dirname3(filePath), { recursive: true });
       symlinkSync(target, filePath);
       created.push(name);
     } catch (error) {
@@ -4295,7 +4552,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 = join7(viewDir, name);
+  const filePath = join9(viewDir, name);
   let isLink;
   try {
     isLink = lstatSync(filePath).isSymbolicLink();
@@ -4324,7 +4581,7 @@ function classifyViewLink(viewDir, name, rosterRealpaths) {
   if (!isDir) {
     return { target, kind: existsSync(resolved) ? "non-repo" : "broken" };
   }
-  return { target, kind: existsSync(join7(resolved, ".git")) ? "repo" : "non-repo" };
+  return { target, kind: existsSync(join9(resolved, ".git")) ? "repo" : "non-repo" };
 }
 function gatherExistingViewLinks(viewDir, rosterRealpaths) {
   let names;
@@ -4349,7 +4606,7 @@ function pruneViewLinks(viewDir, toPrune, rosterRealpaths) {
   const pruned = [];
   const failed = [];
   for (const { name } of toPrune) {
-    const filePath = join7(viewDir, name);
+    const filePath = join9(viewDir, name);
     const c = classifyViewLink(viewDir, name, rosterRealpaths);
     if (c === null || c.kind !== "repo") {
       failed.push({
@@ -4395,7 +4652,7 @@ async function doRunProjectWorkspace(options, ctx) {
   } else {
     const viewDir = resolveViewDir(repositoryRoot, viewPath);
     const facts = roster.map((entry) => gatherViewRepo(repositoryRoot, viewDir, entry));
-    const rosterNames = roster.map((entry) => basename4(resolve7(repositoryRoot, entry.path)));
+    const rosterNames = roster.map((entry) => basename5(resolve7(repositoryRoot, entry.path)));
     const rosterRealpaths = /* @__PURE__ */ new Set();
     for (const entry of roster) {
       try {
@@ -4562,10 +4819,10 @@ async function runProjectPreset(options, ctx = {}) {
   }
 }
 function canonicalFileFor(anchorReal, canonicalName) {
-  return join7(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+  return join9(anchorReal, "agents", canonicalName, CANONICAL_FILE);
 }
 function canonicalLabelFor(canonicalName) {
-  return join7("agents", canonicalName, CANONICAL_FILE);
+  return join9("agents", canonicalName, CANONICAL_FILE);
 }
 async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
   const declared = {
@@ -4586,10 +4843,10 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
   if (real === anchorReal) {
     return { ...declared, isAnchor: true, reachable: true, canonicalPresent: false };
   }
-  if (!existsSync(join7(real, ".git"))) {
+  if (!existsSync(join9(real, ".git"))) {
     return { ...declared, isAnchor: false, reachable: false, canonicalPresent: false };
   }
-  const canonicalName = basename4(real);
+  const canonicalName = basename5(real);
   let content;
   try {
     content = await readMarkdownFile4(canonicalFileFor(anchorReal, canonicalName));
@@ -4634,7 +4891,7 @@ async function applyPresetPlan(anchorReal, plan) {
     isLink = false;
   }
   if (isLink) throw new Error(`Canonical is a symlink in ${label}`);
-  if (plan.action === "create") mkdirSync(dirname2(file), { recursive: true });
+  if (plan.action === "create") mkdirSync(dirname3(file), { recursive: true });
   const existing = await readMarkdownFile4(file);
   await writeMarkdownFile5(file, renderWithMarkers4(existing, plan.desiredBlock, label));
 }
@@ -4824,28 +5081,28 @@ function gatherArchiveTeardown(repositoryRoot, manifest, target) {
     return empty;
   }
   const anchorReal = realpathSync(repositoryRoot);
-  const canonicalName = basename4(real);
+  const canonicalName = basename5(real);
   const instructionFiles = [];
   for (const name of INSTRUCTION_FILES) {
     try {
-      lstatSync(join7(real, name));
+      lstatSync(join9(real, name));
       instructionFiles.push(name);
     } catch {
     }
   }
   let ignored;
   try {
-    ignored = new Set(readGitignoreLines(join7(real, ".gitignore")).map((l) => l.trim()));
+    ignored = new Set(readGitignoreLines(join9(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 = existsSync(join7(anchorReal, "agents", canonicalName, CANONICAL_FILE));
+  const canonical2 = existsSync(join9(anchorReal, "agents", canonicalName, CANONICAL_FILE));
   let viewLink = false;
   const viewPath = manifest.workspace.view;
   if (viewPath !== void 0) {
     try {
-      lstatSync(join7(resolveViewDir(repositoryRoot, viewPath), canonicalName));
+      lstatSync(join9(resolveViewDir(repositoryRoot, viewPath), canonicalName));
       viewLink = true;
     } catch {
     }
@@ -4859,11 +5116,11 @@ function gatherArchiveTeardown(repositoryRoot, manifest, target) {
   };
 }
 function teardownExpectedTargets(repoReal, anchorReal, canonicalName) {
-  const canonicalFile = join7(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+  const canonicalFile = join9(anchorReal, "agents", canonicalName, CANONICAL_FILE);
   return expectedSymlinkTargets(repoReal, canonicalFile);
 }
 function viewLinkPointsAt(viewDir, name, repoReal) {
-  const filePath = join7(viewDir, name);
+  const filePath = join9(viewDir, name);
   try {
     if (!lstatSync(filePath).isSymbolicLink()) return false;
     const target = readlinkSync(filePath);
@@ -4874,7 +5131,7 @@ function viewLinkPointsAt(viewDir, name, repoReal) {
   }
 }
 function viewLinkPointsAtPath(viewDir, name, expectedRepoPath) {
-  const filePath = join7(viewDir, name);
+  const filePath = join9(viewDir, name);
   try {
     if (!lstatSync(filePath).isSymbolicLink()) return false;
     const target = readlinkSync(filePath);
@@ -4894,7 +5151,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
   }
   const isAnchor = repoReal !== void 0 && repoReal === anchorReal;
   const targetAbs = resolve7(repositoryRoot, target);
-  const canonicalName = basename4(repoReal ?? targetAbs);
+  const canonicalName = basename5(repoReal ?? targetAbs);
   const roster = manifest.repos ?? [];
   const declaredEntry = roster.find((r) => {
     try {
@@ -4915,17 +5172,17 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
     }
     if (rReal !== null) {
       if (repoReal !== void 0 && rReal === repoReal) return false;
-      return basename4(rReal).toLowerCase() === cnFold;
+      return basename5(rReal).toLowerCase() === cnFold;
     }
     if (resolve7(repositoryRoot, r.path) === targetAbs) return false;
-    return basename4(resolve7(repositoryRoot, r.path)).toLowerCase() === cnFold;
+    return basename5(resolve7(repositoryRoot, r.path)).toLowerCase() === cnFold;
   });
   const collisionNote = "shared with another repo of the same basename, so it cannot be removed (check manually)";
   const items = [];
   if (!isAnchor) {
     if (repoReal !== void 0) {
       for (const spec of teardownExpectedTargets(repoReal, anchorReal, canonicalName)) {
-        const { state, actualTarget } = inspectSymlink(join7(repoReal, spec.name), spec.target);
+        const { state, actualTarget } = inspectSymlink(join9(repoReal, spec.name), spec.target);
         if (isSelf) {
           if (state !== "missing")
             items.push({
@@ -4962,7 +5219,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
       }
       let ignored;
       try {
-        ignored = new Set(readGitignoreLines(join7(repoReal, ".gitignore")).map((l) => l.trim()));
+        ignored = new Set(readGitignoreLines(join9(repoReal, ".gitignore")).map((l) => l.trim()));
         for (const p of INSTRUCTION_FILES) {
           if (ignored.has(p) || ignored.has(`/${p}`)) {
             items.push({
@@ -4985,7 +5242,7 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
     const viewPath = manifest.workspace.view;
     if (viewPath !== void 0) {
       const viewDir = resolveViewDir(repositoryRoot, viewPath);
-      const linkPath = join7(viewDir, canonicalName);
+      const linkPath = join9(viewDir, canonicalName);
       let isLink = false;
       try {
         isLink = lstatSync(linkPath).isSymbolicLink();
@@ -5011,8 +5268,8 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
         else items.push({ kind: "view-symlink", label: canonicalName, state: "removable" });
       }
     }
-    const canonicalFile = join7(anchorReal, "agents", canonicalName, CANONICAL_FILE);
-    const canonicalLabel = join7("agents", canonicalName, CANONICAL_FILE);
+    const canonicalFile = join9(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+    const canonicalLabel = join9("agents", canonicalName, CANONICAL_FILE);
     let canonicalIsLink = false;
     try {
       canonicalIsLink = lstatSync(canonicalFile).isSymbolicLink();
@@ -5116,12 +5373,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(join7(repoReal, item.label), expected).state !== "correct") {
+    if (repoReal === null || expected === void 0 || inspectSymlink(join9(repoReal, item.label), expected).state !== "correct") {
       changed(item.label);
       continue;
     }
     try {
-      unlinkSync(join7(repoReal, item.label));
+      unlinkSync(join9(repoReal, item.label));
       removed.push(item.label);
     } catch (error) {
       failed.push({ label: item.label, message: failureReason(error) });
@@ -5140,7 +5397,7 @@ function applyRepoTeardown(repositoryRoot, manifest, plan) {
       continue;
     }
     try {
-      unlinkSync(join7(viewDir, item.label));
+      unlinkSync(join9(viewDir, item.label));
       removed.push(`view/${item.label}`);
     } catch (error) {
       failed.push({ label: `view/${item.label}`, message: failureReason(error) });
@@ -5148,7 +5405,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 = join7(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+    const canonicalFile = join9(anchorReal, "agents", canonicalName, CANONICAL_FILE);
     try {
       if (lstatSync(canonicalFile).isSymbolicLink()) {
         changed(item.label);
@@ -5383,7 +5640,7 @@ function renderProjectArchive(result) {
   if (t.gitignorePatterns.length > 0)
     items.push(`.gitignore instruction patterns (${t.gitignorePatterns.join(", ")})`);
   if (t.canonical)
-    items.push(`the anchor's canonical (agents/${basename4(result.target)}/AGENTS.md)`);
+    items.push(`the anchor's canonical (agents/${basename5(result.target)}/AGENTS.md)`);
   if (!t.inspected) {
     lines.push(
       "## Manual teardown (the repo could not be resolved on disk, so it was not inspected)"
@@ -5422,12 +5679,12 @@ function gatherRenameWiring(repositoryRoot, manifest, oldBasename) {
   } catch {
     return { canonicalDirOld: false, viewLinkOld: false };
   }
-  const canonicalDirOld = existsSync(join7(anchorReal, "agents", oldBasename));
+  const canonicalDirOld = existsSync(join9(anchorReal, "agents", oldBasename));
   let viewLinkOld = false;
   const viewPath = manifest.workspace.view;
   if (viewPath !== void 0) {
     try {
-      lstatSync(join7(resolveViewDir(repositoryRoot, viewPath), oldBasename));
+      lstatSync(join9(resolveViewDir(repositoryRoot, viewPath), oldBasename));
       viewLinkOld = true;
     } catch {
     }
@@ -5586,7 +5843,7 @@ async function resolveRepositoryRootForNew(cwd) {
 async function doRunProjectNew(repos, options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForNew(cwd);
-  const workspaceName = basename4(repositoryRoot);
+  const workspaceName = basename5(repositoryRoot);
   const declared = repos.map((p) => {
     const abs = resolve7(cwd, p);
     let real;
@@ -5768,7 +6025,7 @@ function regularFileSpokes(repoReal) {
   const out = [];
   for (const spoke of ["CLAUDE.md", ".github/copilot-instructions.md"]) {
     try {
-      const st = lstatSync(join7(repoReal, spoke));
+      const st = lstatSync(join9(repoReal, spoke));
       if (!st.isSymbolicLink() && st.isFile()) out.push(spoke);
     } catch {
     }
@@ -5798,7 +6055,7 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
   const self = declaredEntry !== void 0 && instructionMode(declaredEntry) === "self";
   const displayRel = argReal !== void 0 ? relative2(anchorReal, argReal) : relative2(repositoryRoot, argAbs);
   const path = displayRel === "" ? "." : displayRel;
-  const canonicalName = basename4(argReal ?? argAbs);
+  const canonicalName = basename5(argReal ?? argAbs);
   if (argReal === void 0) {
     return {
       path,
@@ -5813,8 +6070,8 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
     };
   }
   const isAnchor = argReal === anchorReal;
-  const reachable = existsSync(join7(argReal, ".git"));
-  const canonicalFile = join7(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+  const reachable = existsSync(join9(argReal, ".git"));
+  const canonicalFile = join9(anchorReal, "agents", canonicalName, CANONICAL_FILE);
   return {
     path,
     declared,
@@ -5822,15 +6079,15 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
     isAnchor,
     reachable,
     canonicalName,
-    agentsState: inspectAgentsState(join7(argReal, CANONICAL_FILE)),
+    agentsState: inspectAgentsState(join9(argReal, CANONICAL_FILE)),
     canonicalExists: pathPresent(canonicalFile),
     regularSpokes: regularFileSpokes(argReal)
   };
 }
 function relocateAgentsFile(repoReal, canonicalFile) {
-  const agentsFile = join7(repoReal, CANONICAL_FILE);
+  const agentsFile = join9(repoReal, CANONICAL_FILE);
   try {
-    mkdirSync(dirname2(canonicalFile), { recursive: true });
+    mkdirSync(dirname3(canonicalFile), { recursive: true });
   } catch (error) {
     return { ok: false, message: failureReason(error), partial: false };
   }
@@ -5868,7 +6125,7 @@ async function doRunProjectRetrofit(repo, options, ctx) {
   let failure;
   let partial = false;
   if (options.apply === true && plan.action === "relocate" && argReal !== void 0) {
-    const canonicalFile = join7(anchorReal, "agents", plan.canonicalName, CANONICAL_FILE);
+    const canonicalFile = join9(anchorReal, "agents", plan.canonicalName, CANONICAL_FILE);
     const res = relocateAgentsFile(argReal, canonicalFile);
     if (res.ok) {
       applied = true;
@@ -5992,78 +6249,131 @@ 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 join10 } from "path";
 import {
-  PROTOCOL_END,
-  PROTOCOL_START,
+  ORIENTATION_END,
+  ORIENTATION_START,
   parseMarkers as parseMarkers2,
   readMarkdownFile as readMarkdownFile5,
   removeMarkerSection as removeMarkerSection2
 } from "@basou/core";
-
-// src/lib/durable-write.ts
-import { randomUUID } from "crypto";
-import { lstat, open as open2, rename, stat as stat4, unlink as unlink2 } from "fs/promises";
-import { basename as basename5, dirname as dirname3, join as join8 } from "path";
-async function assertNotSymlink(targetPath) {
-  try {
-    const st = await lstat(targetPath);
-    if (st.isSymbolicLink()) {
+var CODEX_TARGET_PATH = join10(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(
-        "Refusing to write through a symlink. Replace the symlinked target with a regular file (or remove it) and retry."
+        "The basou-managed markers in the target are malformed (a marker is missing, duplicated, or out of order). Fix or remove them, then retry."
       );
-    }
-  } catch (error) {
-    if (error instanceof Error && error.code === "ENOENT") return;
-    throw error;
   }
 }
-async function writeFileDurable(targetPath, content) {
-  const dir = dirname3(targetPath);
-  const tmpPath = join8(dir, `.${basename5(targetPath)}.tmp.${randomUUID()}`);
-  let mode = 420;
-  try {
-    mode = (await stat4(targetPath)).mode & 511;
-  } catch (error) {
-    if (!(error instanceof Error && error.code === "ENOENT")) {
-      throw error;
-    }
-  }
-  let handle;
-  try {
-    handle = await open2(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;
+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."
+    );
   }
-  try {
-    const dirHandle = await open2(dir, "r");
-    try {
-      await dirHandle.sync();
-    } finally {
-      await dirHandle.close();
+  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."
+      );
     }
-  } catch {
   }
 }
+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"}`
+  };
+}
 
 // src/lib/protocols-config.ts
-import { homedir as homedir6 } from "os";
-import { isAbsolute as isAbsolute4, join as join9, resolve as resolve8 } from "path";
+import { homedir as homedir8 } from "os";
+import { isAbsolute as isAbsolute4, join as join11, resolve as resolve8 } from "path";
 import { readYamlFile as readYamlFile5 } from "@basou/core";
-var DEFAULT_PROTOCOLS_CONFIG_PATH = join9(homedir6(), ".basou", "protocols.yaml");
-var DEFAULT_TARGET_PATH = join9(homedir6(), ".claude", "CLAUDE.md");
+var DEFAULT_PROTOCOLS_CONFIG_PATH = join11(homedir8(), ".basou", "protocols.yaml");
+var DEFAULT_TARGET_PATH = join11(homedir8(), ".claude", "CLAUDE.md");
 var ALLOWED_TOP_KEYS = /* @__PURE__ */ new Set(["version", "protocols"]);
 var ALLOWED_ENTRY_KEYS = /* @__PURE__ */ new Set(["source", "title"]);
 function expandTilde3(p) {
-  if (p === "~") return homedir6();
-  if (p.startsWith("~/")) return join9(homedir6(), p.slice(2));
+  if (p === "~") return homedir8();
+  if (p.startsWith("~/")) return join11(homedir8(), p.slice(2));
   return p;
 }
 function isRecord3(value) {
@@ -6184,13 +6494,7 @@ async function readProtocolSources(entries) {
       }
       throw new Error("Failed to read a protocol source file.", { cause: error });
     }
-    for (const line of content.split(/\r?\n/)) {
-      if (line === PROTOCOL_START || line === PROTOCOL_END) {
-        throw new Error(
-          "A protocol source contains a BASOU:PROTOCOLS marker line, which would corrupt the managed block. Remove that line from the source."
-        );
-      }
-    }
+    assertNoMarkerLine(content, PROTOCOL_MARKERS);
     out.push({ entry, content });
   }
   return out;
@@ -6207,74 +6511,41 @@ ${body}` : body;
 ${sections.join("\n\n")}
 `;
 }
-function buildTargetBody(existing, block) {
-  const wrapped = `${PROTOCOL_START}
-${block}${PROTOCOL_END}
-`;
-  if (existing === null || existing === "") return wrapped;
-  const section = parseMarkers2(existing, PROTOCOL_MARKERS);
-  switch (section.kind) {
-    case "ok":
-      return `${section.before}${PROTOCOL_START}
-${block}${PROTOCOL_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:PROTOCOLS 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 doRunProtocolSync(options) {
   const configPath = options.config ?? DEFAULT_PROTOCOLS_CONFIG_PATH;
   const target = options.target ?? DEFAULT_TARGET_PATH;
   const entries = await loadProtocolsConfig(configPath);
   const sources = await readProtocolSources(entries);
   const block = buildBlock(sources);
-  await assertNotSymlink(target);
-  const existing = await readMarkdownFile5(target);
-  const newBody = buildTargetBody(existing, block);
-  if (newBody === existing) {
+  const result = await syncMarkerBlock({
+    target,
+    markers: PROTOCOL_MARKERS,
+    block,
+    ...options.dryRun === true ? { dryRun: true } : {}
+  });
+  if (result.action === "unchanged") {
     console.log(`The basou:protocols block is already up to date (${entries.length} protocol(s)).`);
     return;
   }
-  const hadBlock = existing !== null && parseMarkers2(existing, PROTOCOL_MARKERS).kind === "ok";
   if (options.dryRun === true) {
     console.log(
-      `[dry-run] Would ${hadBlock ? "update" : "install"} the basou:protocols block (${entries.length} protocol(s)).`
+      `[dry-run] Would ${result.action === "updated" ? "update" : "install"} the basou:protocols block (${entries.length} protocol(s)).`
     );
     for (const { entry } of sources) {
       console.log(`  - ${entry.title ?? entry.source}`);
     }
     return;
   }
-  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 'basou protocol sync'."
-    );
-  }
-  await backupOnce(target, existing);
-  await writeFileDurable(target, newBody);
   console.log(
-    `${hadBlock ? "Updated" : "Installed"} the basou:protocols block in the global CLAUDE.md (${entries.length} protocol(s)).`
+    `${result.action === "updated" ? "Updated" : "Installed"} the basou:protocols block in the global CLAUDE.md (${entries.length} protocol(s)).`
   );
 }
 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 readMarkdownFile5(target);
-  const installed = existing !== null && parseMarkers2(existing, PROTOCOL_MARKERS).kind === "ok";
+  const existing = await readMarkdownFile6(target);
+  const installed = existing !== null && parseMarkers3(existing, PROTOCOL_MARKERS).kind === "ok";
   console.log(`Declared protocols (${entries.length}):`);
   for (const entry of entries) {
     console.log(`  - ${entry.title ?? entry.source}`);
@@ -6283,14 +6554,13 @@ async function doRunProtocolList(options) {
 }
 async function doRunProtocolUnsync(options) {
   const target = options.target ?? DEFAULT_TARGET_PATH;
-  await assertNotSymlink(target);
-  const existing = await readMarkdownFile5(target);
-  if (existing === null) {
-    console.log("No target file; nothing to remove.");
-    return;
-  }
-  const newBody = removeMarkerSection2(existing, "CLAUDE.md", PROTOCOL_MARKERS);
-  if (newBody === existing) {
+  const result = await removeMarkerBlock({
+    target,
+    markers: PROTOCOL_MARKERS,
+    fileLabel: "CLAUDE.md",
+    ...options.dryRun === true ? { dryRun: true } : {}
+  });
+  if (!result.removed) {
     console.log("No basou:protocols block found; nothing removed.");
     return;
   }
@@ -6298,14 +6568,6 @@ async function doRunProtocolUnsync(options) {
     console.log("[dry-run] Would remove the basou:protocols block from the global CLAUDE.md.");
     return;
   }
-  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 'basou protocol unsync'."
-    );
-  }
-  await backupOnce(target, existing);
-  await writeFileDurable(target, newBody);
   console.log("Removed the basou:protocols block from the global CLAUDE.md.");
 }
 
@@ -6315,16 +6577,16 @@ import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
 
 // src/commands/refresh-watch.ts
 import { readdir as readdir2, stat as stat5 } from "fs/promises";
-import { homedir as homedir7 } from "os";
-import { join as join10 } from "path";
+import { homedir as homedir9 } from "os";
+import { join as join12 } from "path";
 import { findErrorCode as findErrorCode8 } from "@basou/core";
 var DEFAULT_WATCH_INTERVAL_SEC = 30;
 var MIN_WATCH_INTERVAL_SEC = 5;
 var MAX_WATCH_INTERVAL_SEC = 86400;
 function watchedRoots(ctx) {
   return [
-    ctx.codexSessionsDir ?? join10(homedir7(), ".codex", "sessions"),
-    ctx.claudeProjectsDir ?? join10(homedir7(), ".claude", "projects")
+    ctx.codexSessionsDir ?? join12(homedir9(), ".codex", "sessions"),
+    ctx.claudeProjectsDir ?? join12(homedir9(), ".claude", "projects")
   ];
 }
 async function scanSourceLogs(roots) {
@@ -6338,7 +6600,7 @@ async function scanSourceLogs(roots) {
       throw new Error("Failed to read a source log directory", { cause: error });
     }
     for (const entry of entries) {
-      const full = join10(dir, entry.name);
+      const full = join12(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(full);
       } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
@@ -6445,19 +6707,19 @@ function parseInterval(value) {
   return seconds;
 }
 function abortableSleep(ms, signal) {
-  return new Promise((resolve12) => {
+  return new Promise((resolve13) => {
     if (signal.aborted) {
-      resolve12();
+      resolve13();
       return;
     }
     let timer;
     const onAbort = () => {
       clearTimeout(timer);
-      resolve12();
+      resolve13();
     };
     timer = setTimeout(() => {
       signal.removeEventListener("abort", onAbort);
-      resolve12();
+      resolve13();
     }, ms);
     signal.addEventListener("abort", onAbort, { once: true });
   });
@@ -6510,7 +6772,7 @@ async function doRunRefreshPortfolio(options, ctx) {
   for (const ws of workspaces) {
     const label = ws.label ?? ws.path;
     try {
-      const result = await computeRefresh(
+      const { result } = await computeRefresh(
         { ...options, portfolio: false },
         { ...ctx, cwd: ws.path }
       );
@@ -6579,7 +6841,7 @@ async function computeRefresh(options, ctx) {
   const paths = basouPaths11(repositoryRoot);
   await assertWorkspaceInitialized8(paths.root);
   const nowIso = (ctx.nowProvider?.() ?? /* @__PURE__ */ new Date()).toISOString();
-  return refreshAll({
+  const result = await refreshAll({
     options: {
       ...options.project !== void 0 && options.project.length > 0 ? { project: options.project } : {},
       ...options.force === true ? { force: true } : {},
@@ -6591,16 +6853,30 @@ async function computeRefresh(options, ctx) {
     paths,
     nowIso
   });
+  return { result, paths };
 }
 async function doRunRefresh(options, ctx) {
-  const result = await computeRefresh(options, ctx);
+  const { result, paths } = await computeRefresh(options, ctx);
+  const channelLine = options.dryRun === true ? null : await syncCodexOrientationChannel(paths, ctx.codexChannelPath);
   if (options.json === true) {
     console.log(JSON.stringify(result));
   } else {
     printRefreshSummary(result);
+    if (channelLine !== null) console.log(channelLine);
   }
   return result;
 }
+async function syncCodexOrientationChannel(paths, channelPath) {
+  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)}`;
+  }
+}
 function describeImport(outcome) {
   if (outcome.status === "skipped") {
     return `${outcome.adapter}: skipped (${outcome.reason})`;
@@ -6733,9 +7009,195 @@ async function assertWorkspaceInitialized9(basouRoot) {
   }
 }
 
-// src/commands/review-gaps.ts
+// src/commands/review.ts
+import { readFile as readFile5 } from "fs/promises";
+import { homedir as homedir10 } from "os";
+import { resolve as resolve10 } from "path";
 import {
+  assertBasouRootSafe as assertBasouRootSafe11,
   basouPaths as basouPaths13,
+  buildReviewRecordedEvent,
+  buildReviewRecordLabel,
+  createAdHocSessionWithEvent as createAdHocSessionWithEvent3,
+  findErrorCode as findErrorCode11,
+  parseReviewRecordInput,
+  readManifest as readManifest7,
+  sanitizePath as sanitizePath2
+} from "@basou/core";
+function registerReviewCommand(program) {
+  const review = program.command("review").description("Record reviews that ran (the durable signal a review happened)");
+  review.command("record").description(
+    "Record that a review ran, from a JSON object (stdin or --file). The in-loop agent runs an adversarial / second-opinion review and pipes a description -- reviewer, target, optional verdict/findings/blocked -- and basou writes one review_recorded event deterministically."
+  ).option("--file <path>", "Read the JSON object from a file instead of stdin").option("--dry-run", "Validate and preview the review without writing it").option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").addHelpText("after", REVIEW_RECORD_HELP).action(async (options) => {
+    await runReviewRecord(options);
+  });
+}
+var REVIEW_RECORD_HELP = `
+Input format (a single JSON object describing one review):
+  {
+    "reviewer": "codex",
+    "target":   "working-tree",
+    "verdict":  "needs-attention",
+    "findings": [
+      { "title": "Off-by-one in pager", "severity": "medium", "location": "src/page.ts:42", "summary": "..." }
+    ],
+    "blocked": [
+      { "title": "Reviewer wanted to drop the singleton", "reason": "design-reversal", "why": "Settled in decision_X" }
+    ]
+  }
+
+Only "reviewer" and "target" are required; verdict / findings / blocked are
+optional. Record blocked findings (spec-deviation / design-reversal) here so the
+adversarial-review protocol's "always report what you blocked" becomes a durable
+trail artifact -- an explicit empty "blocked": [] is encouraged to record that
+you blocked nothing. The review is written into one ad-hoc session timestamped
+now. Run from a workspace-view directory and it resolves to the planning repo,
+like 'basou decision capture' / 'basou note'.
+
+Example (heredoc on stdin):
+  basou review record <<'JSON'
+  { "reviewer": "codex", "target": "working-tree", "verdict": "pass", "blocked": [] }
+  JSON
+`;
+async function runReviewRecord(options, ctx = {}) {
+  try {
+    await doRunReviewRecord(options, ctx);
+  } catch (error) {
+    renderCliError(error, {
+      verbose: isVerbose(options),
+      classifiers: [failedToFinalizeClassifier]
+    });
+    process.exitCode = 1;
+  }
+}
+async function doRunReviewRecord(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveBasouRootForCommand(cwd, "review record");
+  const paths = basouPaths13(repositoryRoot);
+  await assertWorkspaceInitialized10(paths.root);
+  const raw = await readReviewInput(options, ctx);
+  const review = parseReviewRecordInput(raw);
+  if (options.dryRun === true) {
+    printReviewPreview(options, review);
+    return;
+  }
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  const manifest = await readManifest7(paths);
+  const invocationArgs = options.file !== void 0 ? [
+    "--file",
+    sanitizePath2(resolve10(cwd, options.file), {
+      workingDirectory: repositoryRoot,
+      homedir: homedir10()
+    })
+  ] : [];
+  const adHoc = await createAdHocSessionWithEvent3({
+    paths,
+    manifest,
+    label: buildReviewRecordLabel(review),
+    occurredAt,
+    sessionSource: "human",
+    workingDirectory: repositoryRoot,
+    invocation: { command: "basou review record", args: invocationArgs },
+    targetEventBuilders: [
+      (sessionId, eventId) => buildReviewRecordedEvent({ eventId, sessionId, occurredAt, review })
+    ]
+  });
+  printReviewResult(options, {
+    sessionId: adHoc.sessionId,
+    eventId: adHoc.targetEventIds[0],
+    review
+  });
+}
+async function readReviewInput(options, ctx) {
+  if (options.file !== void 0) {
+    try {
+      return await readFile5(options.file, "utf8");
+    } catch (error) {
+      if (findErrorCode11(error, "ENOENT")) {
+        throw new Error(`Input file not found: ${options.file}`);
+      }
+      throw error;
+    }
+  }
+  if (ctx.readInput !== void 0) {
+    return await ctx.readInput();
+  }
+  if (process.stdin.isTTY === true) {
+    throw new Error(NO_INPUT_HINT2);
+  }
+  return await readStdinToEnd2();
+}
+async function readStdinToEnd2() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+var NO_INPUT_HINT2 = "No input: pipe a JSON object describing the review to stdin or pass --file <path>.";
+function reviewToPayload(review) {
+  const payload = {
+    reviewer: review.reviewer,
+    target: review.target
+  };
+  if (review.verdict !== void 0) payload.verdict = review.verdict;
+  if (review.findings !== void 0) payload.findings = review.findings;
+  if (review.blocked !== void 0) payload.blocked = review.blocked;
+  return payload;
+}
+function reviewSummaryLine(review) {
+  const parts = [];
+  if (review.verdict !== void 0) parts.push(`verdict: ${review.verdict}`);
+  if (review.findings !== void 0) {
+    parts.push(`${review.findings.length} finding${review.findings.length === 1 ? "" : "s"}`);
+  }
+  if (review.blocked !== void 0) {
+    parts.push(`${review.blocked.length} blocked`);
+  }
+  return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+function printReviewPreview(options, review) {
+  if (options.json === true) {
+    console.log(JSON.stringify({ dry_run: true, review: reviewToPayload(review) }));
+    return;
+  }
+  console.log(
+    `Would record review by ${review.reviewer} of ${review.target}${reviewSummaryLine(review)} (dry run; nothing written).`
+  );
+}
+function printReviewResult(options, result) {
+  const sid = shortSessionId(result.sessionId);
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        mode: "ad-hoc",
+        session_id: result.sessionId,
+        session_status: "completed",
+        event_id: result.eventId,
+        review: reviewToPayload(result.review)
+      })
+    );
+    return;
+  }
+  console.log(
+    `Recorded review by ${result.review.reviewer} of ${result.review.target}${reviewSummaryLine(result.review)} in ad-hoc session ${sid}.`
+  );
+}
+async function assertWorkspaceInitialized10(basouRoot) {
+  try {
+    await assertBasouRootSafe11(basouRoot);
+  } catch (error) {
+    if (findErrorCode11(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+
+// src/commands/review-gaps.ts
+import {
+  basouPaths as basouPaths14,
   findReviewGaps
 } from "@basou/core";
 import { InvalidArgumentError as InvalidArgumentError4 } from "commander";
@@ -6776,7 +7238,7 @@ async function runReviewGaps(options, ctx = {}) {
 async function doRunReviewGaps(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveBasouRootForCommand(cwd, "review-gaps");
-  const paths = basouPaths13(repositoryRoot);
+  const paths = basouPaths14(repositoryRoot);
   const nowIso = (ctx.nowProvider?.() ?? /* @__PURE__ */ new Date()).toISOString();
   const summary = await findReviewGaps({
     paths,
@@ -6859,23 +7321,25 @@ function renderReviewGaps(summary) {
 
 // src/commands/run.ts
 import { mkdir as mkdir2 } from "fs/promises";
-import { homedir as homedir8 } from "os";
-import { join as join11 } from "path";
+import { homedir as homedir11 } from "os";
+import { join as join13 } from "path";
 import {
   acquireLock as acquireLock5,
-  assertBasouRootSafe as assertBasouRootSafe11,
-  basouPaths as basouPaths14,
+  assertBasouRootSafe as assertBasouRootSafe12,
+  basouPaths as basouPaths15,
   ChildProcessRunner as ChildProcessRunner2,
   claudeCodeAdapterMetadata,
+  codexAdapterMetadata,
   appendChainedEvent as coreAppendChainedEvent2,
   finalizeSessionYaml as finalizeSessionYaml2,
   getDiff,
   getSnapshot as getSnapshot2,
   overwriteYamlFile as overwriteYamlFile2,
   prefixedUlid as prefixedUlid4,
-  readManifest as readManifest7,
+  readManifest as readManifest8,
   readYamlFile as readYamlFile6,
   resolveClaudeCodeCommand,
+  resolveCodexCommand,
   resolveRepositoryRoot as resolveRepositoryRoot10,
   SessionSchema as SessionSchema2,
   sanitizeRelatedFiles,
@@ -6883,50 +7347,72 @@ import {
   writeYamlFile as writeYamlFile2
 } from "@basou/core";
 function registerRunCommand(program, ctx = {}) {
-  const runCommand = program.command("run").description("Run an AI coding tool through Basou as a tracked session").enablePositionalOptions().option("--no-snapshot", "Skip git_snapshot before/after the session").option("--cwd <path>", "Run from a Basou root other than process.cwd()").option("-v, --verbose", "Show error causes");
-  runCommand.command("claude-code [args...]").description("Run Claude Code CLI as a Basou-tracked session").option("--no-snapshot", "Skip git_snapshot before/after the session").option("--cwd <path>", "Run from a Basou root other than process.cwd()").option("-v, --verbose", "Show error causes").passThroughOptions().action(async (args, options, command) => {
+  const runCommand = addRunOptions(
+    program.command("run").description("Run an AI coding tool through Basou as a tracked session").enablePositionalOptions()
+  );
+  const dispatch = async (args, options, command, run) => {
     const parentOptions = command.parent?.opts() ?? {};
     const snapshotOn = parentOptions.snapshot !== false && options.snapshot !== false;
-    const merged = {
-      ...parentOptions,
-      ...options,
-      snapshot: snapshotOn
-    };
+    const merged = { ...parentOptions, ...options, snapshot: snapshotOn };
     try {
-      const exitCode = await runClaudeCode(args, merged, ctx);
+      const exitCode = await run(args, merged, ctx);
       process.exit(exitCode);
     } catch (error) {
       renderCliError(error, { verbose: isVerbose(merged) });
       process.exit(1);
     }
+  };
+  addRunOptions(runCommand.command("claude-code [args...]")).description("Run Claude Code CLI as a Basou-tracked session").passThroughOptions().action(
+    (args, options, command) => dispatch(args, options, command, runClaudeCode)
+  );
+  addRunOptions(runCommand.command("codex [args...]")).description("Run the Codex CLI as a Basou-tracked session").passThroughOptions().action(
+    (args, options, command) => dispatch(args, options, command, runCodex)
+  );
+}
+function addRunOptions(command) {
+  return command.option("--no-snapshot", "Skip git_snapshot before/after the session").option("--cwd <path>", "Run from a Basou root other than process.cwd()").option("-v, --verbose", "Show error causes");
+}
+function runClaudeCode(args, options, ctx = {}) {
+  return runTrackedTool(args, options, ctx, {
+    resolveCommand: ctx.resolveCommand ?? resolveClaudeCodeCommand,
+    metadata: claudeCodeAdapterMetadata
   });
 }
-async function runClaudeCode(args, options, ctx = {}) {
+function runCodex(args, options, ctx = {}) {
+  return runTrackedTool(args, options, ctx, {
+    resolveCommand: ctx.resolveCodexCommand ?? resolveCodexCommand,
+    metadata: codexAdapterMetadata,
+    transformArgs: (a) => ["-c", "shell_environment_policy.inherit=all", ...a],
+    preSpawn: syncCodexOrientationChannelPreSpawn
+  });
+}
+async function runTrackedTool(args, options, ctx, adapter) {
   const runner = ctx.runner ?? new ChildProcessRunner2();
   const now = ctx.now ?? (() => /* @__PURE__ */ new Date());
-  const resolveCommand = ctx.resolveCommand ?? resolveClaudeCodeCommand;
   const getDiffFn = ctx.getDiff ?? getDiff;
-  const { command } = await resolveCommand();
+  const { command } = await adapter.resolveCommand();
+  const childArgs = adapter.transformArgs ? adapter.transformArgs(args) : args;
   const cwd = options.cwd ?? process.cwd();
   const repoRoot = await resolveRepositoryRootForRun(cwd);
-  const paths = basouPaths14(repoRoot);
-  await assertBasouRootSafe11(paths.root);
-  const manifest = await readManifest7(paths);
+  const paths = basouPaths15(repoRoot);
+  await assertBasouRootSafe12(paths.root);
+  const manifest = await readManifest8(paths);
   const sessionId = prefixedUlid4("ses");
-  const sessionDir = join11(paths.sessions, sessionId);
+  const sessionDir = join13(paths.sessions, sessionId);
   await mkdir2(sessionDir, { recursive: true });
   const appendEvent = ctx.appendEvent ?? (async (_sessionDir, event) => {
     await coreAppendChainedEvent2(paths, sessionId, event);
   });
   const startedAt = now().toISOString();
-  const sessionYamlPath = join11(sessionDir, "session.yaml");
+  const sessionYamlPath = join13(sessionDir, "session.yaml");
   const session = buildInitialSession2({
     id: sessionId,
     command,
-    args,
+    args: childArgs,
     cwd: repoRoot,
     workspaceId: manifest.workspace.id,
-    startedAt
+    startedAt,
+    source: adapter.metadata
   });
   await writeYamlFile2(sessionYamlPath, session);
   await appendEvent(sessionDir, {
@@ -6935,7 +7421,7 @@ async function runClaudeCode(args, options, ctx = {}) {
     id: prefixedUlid4("evt"),
     session_id: sessionId,
     occurred_at: startedAt,
-    source: claudeCodeAdapterMetadata.kind
+    source: adapter.metadata.kind
   });
   let preSnapshot = null;
   if (options.snapshot !== false) {
@@ -6948,7 +7434,7 @@ async function runClaudeCode(args, options, ctx = {}) {
     id: prefixedUlid4("evt"),
     session_id: sessionId,
     occurred_at: runningAt,
-    source: claudeCodeAdapterMetadata.kind,
+    source: adapter.metadata.kind,
     from: "initialized",
     to: "running"
   });
@@ -6982,10 +7468,14 @@ async function runClaudeCode(args, options, ctx = {}) {
   process.on("SIGTERM", onSigTerm);
   process.on("exit", exitHandler);
   ctx.onExitHookInstalled?.(exitHandler);
+  if (adapter.preSpawn !== void 0) {
+    const line = await adapter.preSpawn(cwd, ctx);
+    if (line !== null) console.log(line);
+  }
   let result;
   try {
     try {
-      result = await runner.run(command, args, {
+      result = await runner.run(command, childArgs, {
         cwd: repoRoot,
         capture: "none",
         signal: controller.signal,
@@ -6996,10 +7486,11 @@ async function runClaudeCode(args, options, ctx = {}) {
     } catch (spawnError) {
       await finalizeSessionAsFailed2(paths, sessionDir, sessionId, appendEvent, {
         command,
-        args,
+        args: childArgs,
         cwd: repoRoot,
         occurredAt: now().toISOString(),
-        signalReceived
+        signalReceived,
+        sourceKind: adapter.metadata.kind
       });
       throw spawnError;
     }
@@ -7018,7 +7509,7 @@ async function runClaudeCode(args, options, ctx = {}) {
     occurred_at: endedAt,
     source: "terminal-recording",
     command,
-    args,
+    args: childArgs,
     cwd: repoRoot,
     exit_code: result.exit_code,
     ...result.signal !== null ? { signal: result.signal } : {},
@@ -7045,7 +7536,7 @@ async function runClaudeCode(args, options, ctx = {}) {
   const rawRelated = computeRelatedFiles(preSnapshot, postSnapshot, diff);
   const relatedFiles = sanitizeRelatedFiles(rawRelated, {
     workingDirectory: repoRoot,
-    homedir: homedir8()
+    homedir: homedir11()
   }).sanitized;
   const finalStatus = decideFinalStatus2(result, signalReceived);
   await appendEvent(sessionDir, {
@@ -7054,7 +7545,7 @@ async function runClaudeCode(args, options, ctx = {}) {
     id: prefixedUlid4("evt"),
     session_id: sessionId,
     occurred_at: endedAt,
-    source: claudeCodeAdapterMetadata.kind,
+    source: adapter.metadata.kind,
     from: "running",
     to: finalStatus
   });
@@ -7064,7 +7555,7 @@ async function runClaudeCode(args, options, ctx = {}) {
     id: prefixedUlid4("evt"),
     session_id: sessionId,
     occurred_at: endedAt,
-    source: claudeCodeAdapterMetadata.kind,
+    source: adapter.metadata.kind,
     ...result.exit_code !== null ? { exit_code: result.exit_code } : {}
   });
   await finalizeSessionYaml2(paths, sessionId, (s) => {
@@ -7186,10 +7677,10 @@ function buildInitialSession2(input) {
       label: `basou run ${cmdline} (${input.startedAt})`,
       task_id: null,
       workspace_id: input.workspaceId,
-      source: { ...claudeCodeAdapterMetadata },
+      source: { ...input.source },
       started_at: input.startedAt,
       status: "initialized",
-      working_directory: sanitizeWorkingDirectory2(input.cwd, { homedir: homedir8() }),
+      working_directory: sanitizeWorkingDirectory2(input.cwd, { homedir: homedir11() }),
       invocation: {
         command: input.command,
         args: [...input.args],
@@ -7229,7 +7720,7 @@ async function finalizeSessionAsFailed2(paths, sessionDir, sessionId, appendEven
     id: prefixedUlid4("evt"),
     session_id: sessionId,
     occurred_at: ctx.occurredAt,
-    source: claudeCodeAdapterMetadata.kind,
+    source: ctx.sourceKind,
     from: "running",
     to: "failed"
   });
@@ -7239,7 +7730,7 @@ async function finalizeSessionAsFailed2(paths, sessionDir, sessionId, appendEven
     id: prefixedUlid4("evt"),
     session_id: sessionId,
     occurred_at: ctx.occurredAt,
-    source: claudeCodeAdapterMetadata.kind
+    source: ctx.sourceKind
   });
   await finalizeSessionYaml2(paths, sessionId, (s) => {
     s.session.status = "failed";
@@ -7259,21 +7750,34 @@ async function resolveRepositoryRootForRun(cwd) {
     throw error;
   }
 }
+async function syncCodexOrientationChannelPreSpawn(cwd, ctx) {
+  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;
+  }
+}
 
 // src/commands/session.ts
-import { readFile as readFile5 } from "fs/promises";
-import { basename as basename6, isAbsolute as isAbsolute6, join as join12, relative as relative3 } from "path";
+import { readFile as readFile6 } from "fs/promises";
+import { basename as basename6, isAbsolute as isAbsolute6, join as join14, relative as relative3 } from "path";
 import {
   acquireLock as acquireLock6,
   appendEventToExistingSession as appendEventToExistingSession3,
-  assertBasouRootSafe as assertBasouRootSafe12,
-  basouPaths as basouPaths15,
+  assertBasouRootSafe as assertBasouRootSafe13,
+  basouPaths as basouPaths16,
   enumerateSessionDirs as enumerateSessionDirs2,
-  findErrorCode as findErrorCode11,
+  findErrorCode as findErrorCode12,
   importSessionFromJson as importSessionFromJson2,
   loadSessionEntries as loadSessionEntries2,
   readAllEvents,
-  readManifest as readManifest8,
+  readManifest as readManifest9,
   readYamlFile as readYamlFile7,
   rechainSessionInPlace,
   resolveSessionId as resolveSessionId3,
@@ -7332,8 +7836,8 @@ async function runSessionList(options, ctx = {}) {
 async function doRunSessionList(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForSession(cwd, "list");
-  const paths = basouPaths15(repositoryRoot);
-  await assertWorkspaceInitialized10(paths.root);
+  const paths = basouPaths16(repositoryRoot);
+  await assertWorkspaceInitialized11(paths.root);
   const now = /* @__PURE__ */ new Date();
   const records = (await loadSessionEntries2(paths, {
     now,
@@ -7384,17 +7888,17 @@ async function runSessionShow(idInput, options, ctx = {}) {
 async function doRunSessionShow(idInput, options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForSession(cwd, "show");
-  const paths = basouPaths15(repositoryRoot);
-  await assertWorkspaceInitialized10(paths.root);
+  const paths = basouPaths16(repositoryRoot);
+  await assertWorkspaceInitialized11(paths.root);
   const sessionId = await resolveSessionId3(paths, idInput);
-  const sessionDir = join12(paths.sessions, sessionId);
-  const sessionYamlPath = join12(sessionDir, "session.yaml");
+  const sessionDir = join14(paths.sessions, sessionId);
+  const sessionYamlPath = join14(sessionDir, "session.yaml");
   let session;
   try {
     const raw = await readYamlFile7(sessionYamlPath);
     session = SessionSchema3.parse(raw);
   } catch (error) {
-    if (findErrorCode11(error, "ENOENT")) {
+    if (findErrorCode12(error, "ENOENT")) {
       throw new Error(`Session not found: ${idInput}`);
     }
     throw new Error("Failed to read session", { cause: error });
@@ -7588,6 +8092,11 @@ function eventVariantSummary(ev) {
       return `task ${shortTaskId2(ev.task_id)}: ${ev.title} (archived)`;
     case "note_added":
       return ev.body.length > 80 ? `${ev.body.slice(0, 77)}...` : ev.body;
+    case "review_recorded": {
+      const verdict = ev.verdict !== void 0 ? ` (${ev.verdict})` : "";
+      const blocked = ev.blocked !== void 0 && ev.blocked.length > 0 ? ` ${ev.blocked.length} blocked` : "";
+      return `${ev.reviewer} -> ${ev.target}${verdict}${blocked}`;
+    }
     case "adapter_output":
       return `${ev.stream} "${ev.summary}" raw_ref=${ev.raw_ref}`;
   }
@@ -7635,11 +8144,11 @@ function maxLen2(values, floor) {
 async function resolveRepositoryRootForSession(cwd, subcmd) {
   return resolveBasouRootForCommand(cwd, `session ${subcmd}`);
 }
-async function assertWorkspaceInitialized10(basouRoot) {
+async function assertWorkspaceInitialized11(basouRoot) {
   try {
-    await assertBasouRootSafe12(basouRoot);
+    await assertBasouRootSafe13(basouRoot);
   } catch (error) {
-    if (findErrorCode11(error, "ENOENT")) {
+    if (findErrorCode12(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw error;
@@ -7677,9 +8186,9 @@ async function runSessionImport(options, ctx = {}) {
 async function doRunSessionImport(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForSession(cwd, "import");
-  const paths = basouPaths15(repositoryRoot);
-  await assertWorkspaceInitialized10(paths.root);
-  const manifest = await readManifest8(paths);
+  const paths = basouPaths16(repositoryRoot);
+  await assertWorkspaceInitialized11(paths.root);
+  const manifest = await readManifest9(paths);
   const rawBody = await readInputFile(options.from);
   const json = parseJsonStrict(rawBody);
   const parsed = SessionImportPayloadSchema2.safeParse(json);
@@ -7706,12 +8215,12 @@ async function doRunSessionImport(options, ctx) {
 }
 async function readInputFile(path) {
   try {
-    return await readFile5(path, "utf8");
+    return await readFile6(path, "utf8");
   } catch (error) {
-    if (findErrorCode11(error, "ENOENT")) {
+    if (findErrorCode12(error, "ENOENT")) {
       throw new Error("Import source not found", { cause: error });
     }
-    if (findErrorCode11(error, "EISDIR")) {
+    if (findErrorCode12(error, "EISDIR")) {
       throw new Error("Import source is not a file", { cause: error });
     }
     throw new Error("Failed to read import source", { cause: error });
@@ -7791,8 +8300,8 @@ async function doRunSessionNote(sessionIdInput, options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForSession(cwd, "note");
-  const paths = basouPaths15(repositoryRoot);
-  await assertWorkspaceInitialized10(paths.root);
+  const paths = basouPaths16(repositoryRoot);
+  await assertWorkspaceInitialized11(paths.root);
   const sessionId = await resolveSessionId3(paths, sessionIdInput);
   const body = hasBody ? options.body : await readNoteFile(options.fromFile);
   if (body.length === 0) {
@@ -7823,12 +8332,12 @@ async function doRunSessionNote(sessionIdInput, options, ctx) {
 }
 async function readNoteFile(path) {
   try {
-    return await readFile5(path, "utf8");
+    return await readFile6(path, "utf8");
   } catch (error) {
-    if (findErrorCode11(error, "ENOENT")) {
+    if (findErrorCode12(error, "ENOENT")) {
       throw new Error("Note source not found", { cause: error });
     }
-    if (findErrorCode11(error, "EISDIR")) {
+    if (findErrorCode12(error, "EISDIR")) {
       throw new Error("Note source is not a file", { cause: error });
     }
     throw new Error("Failed to read note source", { cause: error });
@@ -7873,8 +8382,8 @@ async function doRunSessionRechain(options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForSession(cwd, "rechain");
-  const paths = basouPaths15(repositoryRoot);
-  await assertWorkspaceInitialized10(paths.root);
+  const paths = basouPaths16(repositoryRoot);
+  await assertWorkspaceInitialized11(paths.root);
   const sessionIds = options.session !== void 0 ? [await resolveSessionId3(paths, options.session)] : await enumerateSessionDirs2(paths);
   const dryRun = options.dryRun === true;
   const rows = [];
@@ -7927,10 +8436,10 @@ function renderRechainRow(row, dryRun) {
 
 // src/commands/stats.ts
 import {
-  assertBasouRootSafe as assertBasouRootSafe13,
-  basouPaths as basouPaths16,
+  assertBasouRootSafe as assertBasouRootSafe14,
+  basouPaths as basouPaths17,
   computeWorkStats,
-  findErrorCode as findErrorCode12,
+  findErrorCode as findErrorCode13,
   resolveRepositoryRoot as resolveRepositoryRoot11
 } from "@basou/core";
 function registerStatsCommand(program) {
@@ -7949,8 +8458,8 @@ async function runStats(options, ctx = {}) {
 async function doRunStats(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForStats(cwd);
-  const paths = basouPaths16(repositoryRoot);
-  await assertWorkspaceInitialized11(paths.root);
+  const paths = basouPaths17(repositoryRoot);
+  await assertWorkspaceInitialized12(paths.root);
   const now = ctx.nowProvider?.() ?? /* @__PURE__ */ new Date();
   const result = await computeWorkStats({
     paths,
@@ -8044,11 +8553,11 @@ async function resolveRepositoryRootForStats(cwd) {
     throw error;
   }
 }
-async function assertWorkspaceInitialized11(basouRoot) {
+async function assertWorkspaceInitialized12(basouRoot) {
   try {
-    await assertBasouRootSafe13(basouRoot);
+    await assertBasouRootSafe14(basouRoot);
   } catch (error) {
-    if (findErrorCode12(error, "ENOENT")) {
+    if (findErrorCode13(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw error;
@@ -8057,11 +8566,11 @@ async function assertWorkspaceInitialized11(basouRoot) {
 
 // src/commands/status.ts
 import {
-  assertBasouRootSafe as assertBasouRootSafe14,
-  basouPaths as basouPaths17,
+  assertBasouRootSafe as assertBasouRootSafe15,
+  basouPaths as basouPaths18,
   buildStatusSnapshot,
-  findErrorCode as findErrorCode13,
-  readManifest as readManifest9,
+  findErrorCode as findErrorCode14,
+  readManifest as readManifest10,
   resolveRepositoryRoot as resolveRepositoryRoot12,
   writeStatus
 } from "@basou/core";
@@ -8081,20 +8590,20 @@ async function runStatus(options, ctx = {}) {
 async function doRunStatus(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForStatus(cwd);
-  const paths = basouPaths17(repositoryRoot);
+  const paths = basouPaths18(repositoryRoot);
   try {
-    await assertBasouRootSafe14(paths.root);
+    await assertBasouRootSafe15(paths.root);
   } catch (error) {
-    if (findErrorCode13(error, "ENOENT")) {
+    if (findErrorCode14(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw error;
   }
   let manifest;
   try {
-    manifest = await readManifest9(paths);
+    manifest = await readManifest10(paths);
   } catch (error) {
-    if (findErrorCode13(error, "ENOENT")) {
+    if (findErrorCode14(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw new Error("Failed to read workspace manifest", { cause: error });
@@ -8130,21 +8639,21 @@ async function resolveRepositoryRootForStatus(cwd) {
 }
 
 // src/commands/task.ts
-import { readFile as readFile6 } from "fs/promises";
-import { join as join13 } from "path";
+import { readFile as readFile7 } from "fs/promises";
+import { join as join15 } from "path";
 import {
   archiveTask,
-  assertBasouRootSafe as assertBasouRootSafe15,
-  basouPaths as basouPaths18,
+  assertBasouRootSafe as assertBasouRootSafe16,
+  basouPaths as basouPaths19,
   createTaskWithEvent,
   deleteTask,
   editTask,
   enumerateArchivedTaskIds,
-  findErrorCode as findErrorCode14,
+  findErrorCode as findErrorCode15,
   loadSessionEntries as loadSessionEntries3,
   loadTaskEntries,
   prefixedUlid as prefixedUlid5,
-  readManifest as readManifest10,
+  readManifest as readManifest11,
   readTaskFile,
   readTaskFileWithArchiveFallback,
   reconcileAllTasks,
@@ -8236,8 +8745,8 @@ async function doRunTaskNew(options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "new");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
   const description = options.description !== void 0 ? options.description : options.fromFile !== void 0 ? await readDescriptionFile(options.fromFile) : "";
   const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
   const occurredAt = now.toISOString();
@@ -8271,7 +8780,7 @@ async function doRunTaskNew(options, ctx) {
     });
     return;
   }
-  const manifest = await readManifest10(paths);
+  const manifest = await readManifest11(paths);
   const result = await createTaskWithEvent({
     mode: "ad-hoc",
     paths,
@@ -8345,8 +8854,8 @@ async function runTaskList(options, ctx = {}) {
 async function doRunTaskList(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "list");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
   const entries = await loadTaskEntries(paths, {
     onSkip: (id, reason) => printTaskSkip(id, reason)
   });
@@ -8449,15 +8958,15 @@ async function runTaskShow(idInput, options, ctx = {}) {
 async function doRunTaskShow(idInput, options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "show");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
   const taskId = await resolveTaskId2(paths, idInput, { includeArchived: true });
   const { doc, archived } = await readTaskFileWithArchiveFallback(paths, taskId);
   const sessions = await loadSessionEntries3(paths, { now: /* @__PURE__ */ new Date() });
   const events = [];
   const linkedSessionIds = new Set(doc.task.task.linked_sessions);
   for (const s of sessions) {
-    const sessionDir = join13(paths.sessions, s.sessionId);
+    const sessionDir = join15(paths.sessions, s.sessionId);
     try {
       for await (const ev of replayEvents3(sessionDir, {
         onWarning: (w) => printReplayWarning(w, s.sessionId)
@@ -8593,8 +9102,8 @@ async function doRunTaskStatus(taskIdInput, newStatusInput, options, ctx) {
   const newStatus = parseTaskStatusPositional(newStatusInput);
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "status");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
   const occurredAt = now.toISOString();
@@ -8619,7 +9128,7 @@ async function doRunTaskStatus(taskIdInput, newStatusInput, options, ctx) {
     });
     return;
   }
-  const manifest = await readManifest10(paths);
+  const manifest = await readManifest11(paths);
   const result = await updateTaskStatusWithEvent({
     mode: "ad-hoc",
     paths,
@@ -8670,9 +9179,9 @@ async function runTaskReconcile(options, ctx = {}) {
 async function doRunTaskReconcile(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "reconcile");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
-  const manifest = await readManifest10(paths);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
+  const manifest = await readManifest11(paths);
   const nowProvider = ctx.nowProvider ?? (() => /* @__PURE__ */ new Date());
   const write = options.write === true;
   const verbose = isVerbose(options);
@@ -8850,9 +9359,9 @@ async function doRunTaskRefreshLinkage(taskIdInput, options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "refresh-linkage");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
-  const manifest = await readManifest10(paths);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
+  const manifest = await readManifest11(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   const nowProvider = ctx.nowProvider ?? (() => /* @__PURE__ */ new Date());
   const write = options.write === true;
@@ -8930,9 +9439,9 @@ async function doRunTaskEdit(taskIdInput, options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "edit");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
-  const manifest = await readManifest10(paths);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
+  const manifest = await readManifest11(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
   const occurredAt = now.toISOString();
@@ -8986,9 +9495,9 @@ async function doRunTaskDelete(taskIdInput, options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "delete");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
-  const manifest = await readManifest10(paths);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
+  const manifest = await readManifest11(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   if (options.yes !== true) {
     await confirmDestructiveAction("delete", taskId);
@@ -9031,9 +9540,9 @@ async function doRunTaskArchive(taskIdInput, options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForTask(cwd, "archive");
-  const paths = basouPaths18(repositoryRoot);
-  await assertWorkspaceInitialized12(paths.root);
-  const manifest = await readManifest10(paths);
+  const paths = basouPaths19(repositoryRoot);
+  await assertWorkspaceInitialized13(paths.root);
+  const manifest = await readManifest11(paths);
   const taskId = await resolveTaskId2(paths, taskIdInput);
   if (options.yes !== true) {
     await confirmDestructiveAction("archive", taskId);
@@ -9145,12 +9654,12 @@ function parsePositiveInt2(raw) {
 }
 async function readDescriptionFile(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile7(path, "utf8");
   } catch (error) {
-    if (findErrorCode14(error, "ENOENT")) {
+    if (findErrorCode15(error, "ENOENT")) {
       throw new Error("Description source not found", { cause: error });
     }
-    if (findErrorCode14(error, "EISDIR")) {
+    if (findErrorCode15(error, "EISDIR")) {
       throw new Error("Description source is not a file", { cause: error });
     }
     throw new Error("Failed to read description source", { cause: error });
@@ -9159,11 +9668,11 @@ async function readDescriptionFile(path) {
 async function resolveRepositoryRootForTask(cwd, subcmd) {
   return resolveBasouRootForCommand(cwd, `task ${subcmd}`);
 }
-async function assertWorkspaceInitialized12(basouRoot) {
+async function assertWorkspaceInitialized13(basouRoot) {
   try {
-    await assertBasouRootSafe15(basouRoot);
+    await assertBasouRootSafe16(basouRoot);
   } catch (error) {
-    if (findErrorCode14(error, "ENOENT")) {
+    if (findErrorCode15(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw error;
@@ -9251,10 +9760,10 @@ function maxLen3(values, floor) {
 
 // src/commands/verify.ts
 import {
-  assertBasouRootSafe as assertBasouRootSafe16,
-  basouPaths as basouPaths19,
+  assertBasouRootSafe as assertBasouRootSafe17,
+  basouPaths as basouPaths20,
   enumerateSessionDirs as enumerateSessionDirs3,
-  findErrorCode as findErrorCode15,
+  findErrorCode as findErrorCode16,
   resolveRepositoryRoot as resolveRepositoryRoot13,
   resolveSessionId as resolveSessionId5,
   verifyEventsChain
@@ -9278,8 +9787,8 @@ async function doRunVerify(options, ctx) {
   }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForVerify(cwd);
-  const paths = basouPaths19(repositoryRoot);
-  await assertWorkspaceInitialized13(paths.root);
+  const paths = basouPaths20(repositoryRoot);
+  await assertWorkspaceInitialized14(paths.root);
   const sessionIds = options.session !== void 0 ? [await resolveSessionId5(paths, options.session)] : await enumerateSessionDirs3(paths);
   const rows = [];
   for (const sessionId of sessionIds) {
@@ -9336,11 +9845,11 @@ async function resolveRepositoryRootForVerify(cwd) {
     throw error;
   }
 }
-async function assertWorkspaceInitialized13(basouRoot) {
+async function assertWorkspaceInitialized14(basouRoot) {
   try {
-    await assertBasouRootSafe16(basouRoot);
+    await assertBasouRootSafe17(basouRoot);
   } catch (error) {
-    if (findErrorCode15(error, "ENOENT")) {
+    if (findErrorCode16(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw error;
@@ -9350,12 +9859,12 @@ async function assertWorkspaceInitialized13(basouRoot) {
 // src/commands/view.ts
 import { spawn } from "child_process";
 import { createHash } from "crypto";
-import { basename as basename7, resolve as resolve11 } from "path";
+import { basename as basename7, resolve as resolve12 } from "path";
 import {
-  assertBasouRootSafe as assertBasouRootSafe17,
-  basouPaths as basouPaths20,
-  findErrorCode as findErrorCode17,
-  readManifest as readManifest13,
+  assertBasouRootSafe as assertBasouRootSafe18,
+  basouPaths as basouPaths21,
+  findErrorCode as findErrorCode18,
+  readManifest as readManifest14,
   resolveRepositoryRoot as resolveRepositoryRoot14
 } from "@basou/core";
 import { InvalidArgumentError as InvalidArgumentError7 } from "commander";
@@ -9363,9 +9872,9 @@ import { InvalidArgumentError as InvalidArgumentError7 } from "commander";
 // 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 join14, relative as relative4, resolve as resolve10 } from "path";
+import { isAbsolute as isAbsolute7, join as join16, relative as relative4, resolve as resolve11 } from "path";
 import { promisify } from "util";
-import { readManifest as readManifest11 } from "@basou/core";
+import { readManifest as readManifest12 } from "@basou/core";
 var execFileAsync = promisify(execFile);
 function errorCode(error) {
   return error instanceof Error ? error.code : void 0;
@@ -9374,7 +9883,7 @@ async function canonical(p) {
   try {
     return await realpath2(p);
   } catch {
-    return resolve10(p);
+    return resolve11(p);
   }
 }
 function isInside(child, parent) {
@@ -9387,7 +9896,7 @@ function isBasouPath(p) {
 async function inspectRepo(repoPath) {
   let hasEntry = false;
   try {
-    await lstat2(join14(repoPath, ".basou"));
+    await lstat2(join16(repoPath, ".basou"));
     hasEntry = true;
   } catch (error) {
     if (errorCode(error) !== "ENOENT") {
@@ -9418,7 +9927,7 @@ async function checkPortfolioSafety(workspaces) {
     const wsReal = await canonical(ws.repoRoot);
     let sourceRoots = [];
     try {
-      const manifest = await readManifest11(ws.paths);
+      const manifest = await readManifest12(ws.paths);
       sourceRoots = manifest.import?.source_roots ?? [];
     } catch (error) {
       if (error instanceof Error && error.message === "YAML file not found") {
@@ -9436,7 +9945,7 @@ async function checkPortfolioSafety(workspaces) {
     }
     const monitored = /* @__PURE__ */ new Map();
     for (const root of sourceRoots) {
-      const display = resolve10(ws.repoRoot, root);
+      const display = resolve11(ws.repoRoot, root);
       const real = await canonical(display);
       if (real !== wsReal) monitored.set(real, display);
     }
@@ -9488,18 +9997,18 @@ function formatSafetyReport(result) {
 
 // src/lib/view-server.ts
 import { createServer } from "http";
-import { join as join15 } from "path";
+import { join as join17 } from "path";
 import {
   computeWorkStats as computeWorkStats2,
   enumerateApprovals as enumerateApprovals2,
-  findErrorCode as findErrorCode16,
+  findErrorCode as findErrorCode17,
   isLazyExpired as isLazyExpired2,
   loadApproval as loadApproval2,
   loadSessionEntries as loadSessionEntries4,
   loadTaskEntries as loadTaskEntries2,
   readAllEvents as readAllEvents2,
-  readManifest as readManifest12,
-  readMarkdownFile as readMarkdownFile6,
+  readManifest as readManifest13,
+  readMarkdownFile as readMarkdownFile7,
   readSessionYaml as readSessionYaml3,
   readTaskFile as readTaskFile2,
   renderDecisions as renderDecisions3,
@@ -10149,7 +10658,7 @@ function startViewServer(opts) {
   };
   let boundPort = port;
   const getPort = () => boundPort;
-  return new Promise((resolve12, reject) => {
+  return new Promise((resolve13, reject) => {
     const server = createServer((req, res) => {
       handleRequest(req, res, deps, getPort, runExclusive).catch((error) => {
         sendError(res, error instanceof HttpError ? error.status : 500, pathlessMessage(error));
@@ -10160,7 +10669,7 @@ function startViewServer(opts) {
       const address = server.address();
       boundPort = isAddressInfo(address) ? address.port : port;
       server.off("error", reject);
-      resolve12({
+      resolve13({
         url: `http://${host}:${boundPort}`,
         port: boundPort,
         close: () => closeServer(server)
@@ -10172,8 +10681,8 @@ function isAddressInfo(value) {
   return value !== null && typeof value === "object";
 }
 function closeServer(server) {
-  return new Promise((resolve12) => {
-    server.close(() => resolve12());
+  return new Promise((resolve13) => {
+    server.close(() => resolve13());
     server.closeAllConnections();
   });
 }
@@ -10390,9 +10899,9 @@ async function captureStaleness(ws, nowIso) {
 async function overview(ws, nowProvider) {
   let manifest;
   try {
-    manifest = await readManifest12(ws.paths);
+    manifest = await readManifest13(ws.paths);
   } catch (error) {
-    if (findErrorCode16(error, "ENOENT")) {
+    if (findErrorCode17(error, "ENOENT")) {
       return { initialized: false, repoRoot: ws.repoRoot };
     }
     throw error;
@@ -10447,7 +10956,7 @@ async function sessionDetail(ws, sessionId) {
     throw error;
   }
   try {
-    const events = await readAllEvents2(join15(ws.paths.sessions, sessionId));
+    const events = await readAllEvents2(join17(ws.paths.sessions, sessionId));
     return { session, events };
   } catch {
     return { session, events: [], degraded: true };
@@ -10469,7 +10978,7 @@ async function taskDetail(ws, taskId) {
   }
 }
 async function decisionsView(ws, nowProvider) {
-  const fromDisk = await readMarkdownFile6(ws.paths.files.decisions);
+  const fromDisk = await readMarkdownFile7(ws.paths.files.decisions);
   if (fromDisk !== null) {
     return { body: fromDisk, fromDisk: true };
   }
@@ -10492,7 +11001,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 readMarkdownFile6(ws.paths.files.handoff);
+  const fromDisk = await readMarkdownFile7(ws.paths.files.handoff);
   if (fromDisk !== null) {
     return { body: fromDisk, fromDisk: true };
   }
@@ -10661,18 +11170,18 @@ async function doRunView(options, ctx) {
 }
 async function buildSingleDeps(ctx, cwd) {
   const repositoryRoot = await resolveRepositoryRootForView(cwd);
-  const paths = basouPaths20(repositoryRoot);
-  await assertWorkspaceInitialized14(paths.root);
+  const paths = basouPaths21(repositoryRoot);
+  await assertWorkspaceInitialized15(paths.root);
   const entry = await buildWorkspaceEntry(repositoryRoot, ctx);
   return { workspaces: [entry], mode: "single", nowProvider: nowProviderOf(ctx) };
 }
 async function buildPortfolioDeps(workspaceFlags, ctx, cwd) {
-  const specs = workspaceFlags.length > 0 ? workspaceFlags.map((p) => ({ path: resolve11(cwd, p) })) : await loadPortfolioConfig(ctx.portfolioConfigPath);
+  const specs = workspaceFlags.length > 0 ? workspaceFlags.map((p) => ({ path: resolve12(cwd, p) })) : await loadPortfolioConfig(ctx.portfolioConfigPath);
   const entries = [];
   const seenPath = /* @__PURE__ */ new Set();
   const seenKey = /* @__PURE__ */ new Set();
   for (const spec of specs) {
-    const repoRoot = resolve11(spec.path);
+    const repoRoot = resolve12(spec.path);
     if (seenPath.has(repoRoot)) continue;
     seenPath.add(repoRoot);
     const entry = await buildWorkspaceEntry(repoRoot, ctx, spec.label);
@@ -10685,14 +11194,14 @@ async function buildPortfolioDeps(workspaceFlags, ctx, cwd) {
   return { workspaces: entries, mode: "portfolio", nowProvider: nowProviderOf(ctx) };
 }
 async function buildWorkspaceEntry(repoRoot, ctx, labelOverride) {
-  const paths = basouPaths20(repoRoot);
+  const paths = basouPaths21(repoRoot);
   const importCtx = {
     cwd: repoRoot,
     ...ctx.claudeProjectsDir !== void 0 ? { claudeProjectsDir: ctx.claudeProjectsDir } : {},
     ...ctx.codexSessionsDir !== void 0 ? { codexSessionsDir: ctx.codexSessionsDir } : {}
   };
   try {
-    const manifest = await readManifest13(paths);
+    const manifest = await readManifest14(paths);
     return {
       key: manifest.workspace.id,
       label: labelOverride ?? manifest.workspace.name,
@@ -10721,7 +11230,7 @@ async function startListening(port, deps) {
   try {
     return await startViewServer({ port, deps });
   } catch (error) {
-    if (findErrorCode17(error, "EADDRINUSE")) {
+    if (findErrorCode18(error, "EADDRINUSE")) {
       throw new Error(`Port ${port} is already in use. Pass --port <n> to choose another.`, {
         cause: error
       });
@@ -10744,7 +11253,7 @@ function openInBrowser(url, override) {
   }
 }
 function waitForShutdown(signal) {
-  return new Promise((resolve12) => {
+  return new Promise((resolve13) => {
     const cleanup = () => {
       process.off("SIGINT", onSignal);
       process.off("SIGTERM", onSignal);
@@ -10752,18 +11261,18 @@ function waitForShutdown(signal) {
     };
     const onSignal = () => {
       cleanup();
-      resolve12();
+      resolve13();
     };
     const onAbort = () => {
       cleanup();
-      resolve12();
+      resolve13();
     };
     process.on("SIGINT", onSignal);
     process.on("SIGTERM", onSignal);
     if (signal !== void 0) {
       if (signal.aborted) {
         cleanup();
-        resolve12();
+        resolve13();
         return;
       }
       signal.addEventListener("abort", onAbort);
@@ -10782,11 +11291,11 @@ async function resolveRepositoryRootForView(cwd) {
     throw error;
   }
 }
-async function assertWorkspaceInitialized14(basouRoot) {
+async function assertWorkspaceInitialized15(basouRoot) {
   try {
-    await assertBasouRootSafe17(basouRoot);
+    await assertBasouRootSafe18(basouRoot);
   } catch (error) {
-    if (findErrorCode17(error, "ENOENT")) {
+    if (findErrorCode18(error, "ENOENT")) {
       throw new Error("Workspace not initialized. Run 'basou init' first.");
     }
     throw error;
@@ -10818,6 +11327,7 @@ function buildProgram() {
   registerDecisionsCommand(program);
   registerReportCommand(program);
   registerOrientCommand(program);
+  registerReviewCommand(program);
   registerReviewGapsCommand(program);
   registerProjectCommand(program);
   registerProtocolCommand(program);