@basou/cli 0.27.0 → 0.29.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,48 @@ 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"
   ).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 } : {}
+    });
+  });
+  hook.command("install").description(
+    "Register the Stop hook in ~/.claude/settings.json (reproducible, idempotent). Default is advisory; --block opts into in-turn enforcement."
+  ).option("--block", "Register the blocking (opt-in enforcement) form instead of advisory").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.
+
+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 {
@@ -2110,15 +2191,14 @@ async function doRunHookStop(options, ctx) {
     ...options.minEdits !== void 0 ? { minEdits: options.minEdits } : {}
   });
   if (evaluation.kind !== "nudge") return;
-  write(
-    `${JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "Stop",
-        additionalContext: evaluation.additionalContext
-      }
-    })}
-`
-  );
+  const payloadJson = options.block === true ? JSON.stringify({ decision: "block", reason: evaluation.additionalContext }) : JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "Stop",
+      additionalContext: evaluation.additionalContext
+    }
+  });
+  write(`${payloadJson}
+`);
 }
 function parseTranscript(transcript) {
   const records = [];
@@ -2143,9 +2223,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 +2240,160 @@ 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.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.minEdits !== void 0 ? { minEdits: options.minEdits } : {}
+  });
+  const mode = options.block === true ? "blocking" : "advisory";
+  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 = / --block\b/.test(command) ? "blocking (opt-in enforcement)" : "advisory (non-blocking)";
+  console.log(`basou Stop hook: registered, ${mode}.`);
+}
 
 // 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 +2479,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 +2518,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 +2573,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 +2647,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 +2758,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 +2769,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 +2779,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 +2789,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 +2798,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 +2836,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 +3014,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 +3053,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 +3278,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 +3610,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,
@@ -3391,6 +3619,7 @@ import {
   ensureBasouDirectory as ensureBasouDirectory2,
   GENERATED_END,
   GENERATED_START,
+  instructionMode,
   isGitNotFound,
   parseMarkers,
   pathBasename,
@@ -3685,7 +3914,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();
@@ -3780,7 +4009,8 @@ async function isTrackedByGit(repoRoot, relPath) {
 async function gatherRepoWiring(repositoryRoot, entry) {
   const base = {
     path: entry.path,
-    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {}
+    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {},
+    ...instructionMode(entry) === "self" ? { self: true } : {}
   };
   let real;
   try {
@@ -3788,7 +4018,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 {
@@ -3796,7 +4026,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;
       }
@@ -3863,6 +4093,13 @@ function renderProjectWiring(result) {
     for (const p of result.unknown) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.self.length > 0) {
+    lines.push(
+      `## instructions: self (${result.self.length}) \u2014 committed instruction files are intentional (no leak risk)`
+    );
+    for (const p of result.self) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.incomplete.length > 0) {
     lines.push(
       `## Missing instruction files (${result.incomplete.length}) \u2014 to be filled by a later generation slice`
@@ -3891,7 +4128,8 @@ async function runProjectGitignore(options, ctx = {}) {
 function gatherRepoGitignore(repositoryRoot, entry) {
   const base = {
     path: entry.path,
-    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {}
+    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {},
+    ...instructionMode(entry) === "self" ? { self: true } : {}
   };
   let real;
   try {
@@ -3899,10 +4137,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";
@@ -3916,7 +4154,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");
@@ -3986,6 +4224,13 @@ function renderProjectGitignore(result) {
     for (const p of result.unknown) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.self.length > 0) {
+    lines.push(
+      `## instructions: self (${result.self.length}) \u2014 skipped by design; their committed instruction files are shared, never gitignored`
+    );
+    for (const p of result.self) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.unreachable.length > 0) {
     lines.push(`## Unreachable (${result.unreachable.length}) \u2014 path unresolved / not a git repo`);
     for (const p of result.unreachable) lines.push(`- ${p}`);
@@ -4007,12 +4252,13 @@ async function runProjectSymlinks(options, ctx = {}) {
     process.exitCode = 1;
   }
 }
-function expectedSymlinkTargets(repoDirReal, canonicalFile) {
-  return [
-    { name: "AGENTS.md", target: relative2(repoDirReal, canonicalFile) },
+function expectedSymlinkTargets(repoDirReal, canonicalFile, mode = "hub") {
+  const spokes = [
     { name: "CLAUDE.md", target: CANONICAL_FILE },
     { name: ".github/copilot-instructions.md", target: `../${CANONICAL_FILE}` }
   ];
+  if (mode === "self") return spokes;
+  return [{ name: "AGENTS.md", target: relative2(repoDirReal, canonicalFile) }, ...spokes];
 }
 function inspectSymlink(filePath, expectedTarget) {
   let isLink;
@@ -4027,7 +4273,9 @@ function inspectSymlink(filePath, expectedTarget) {
   return actual === expectedTarget ? { state: "correct" } : { state: "mismatch", actualTarget: actual };
 }
 function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
-  const base = { path: entry.path };
+  const mode = instructionMode(entry);
+  const isSelf = mode === "self";
+  const base = { path: entry.path, ...isSelf ? { self: true } : {} };
   let real;
   try {
     real = realpathSync(resolve7(repositoryRoot, entry.path));
@@ -4037,16 +4285,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 = 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).map(
+  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,
@@ -4060,7 +4308,7 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
     isAnchor: false,
     reachable: true,
     canonicalPresent: true,
-    canonicalName: basename4(real),
+    canonicalName: basename5(real),
     files
   };
 }
@@ -4075,9 +4323,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) {
@@ -4197,6 +4445,13 @@ function renderProjectSymlinks(result) {
     for (const p of result.missingCanonical) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.selfAgentsMissing.length > 0) {
+    lines.push(
+      `## AGENTS.md missing (${result.selfAgentsMissing.length}) \u2014 these \`instructions: self\` repos have no committed AGENTS.md yet; author it, then re-run to wire the spokes`
+    );
+    for (const p of result.selfAgentsMissing) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.unreachable.length > 0) {
     lines.push(`## Unreachable (${result.unreachable.length}) \u2014 path unresolved / not a git repo`);
     for (const p of result.unreachable) lines.push(`- ${p}`);
@@ -4221,7 +4476,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;
     }
@@ -4238,8 +4493,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,
@@ -4253,9 +4508,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) {
@@ -4268,7 +4523,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();
@@ -4297,7 +4552,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;
@@ -4322,7 +4577,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({
@@ -4368,7 +4623,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 {
@@ -4535,10 +4790,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 = {
@@ -4547,6 +4802,9 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
     ...entry.language !== void 0 ? { language: entry.language } : {},
     ...entry.publishes !== void 0 ? { publishes: entry.publishes } : {}
   };
+  if (instructionMode(entry) === "self") {
+    return { ...declared, self: true, isAnchor: false, reachable: true, canonicalPresent: false };
+  }
   let real;
   try {
     real = realpathSync(resolve7(repositoryRoot, entry.path));
@@ -4556,10 +4814,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));
@@ -4604,7 +4862,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));
 }
@@ -4754,6 +5012,13 @@ function renderProjectPreset(result) {
     for (const p of result.anchors) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.self.length > 0) {
+    lines.push(
+      `## instructions: self (${result.self.length}) \u2014 hands-off; their hand-authored AGENTS.md is never written by basou`
+    );
+    for (const p of result.self) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.unreachable.length > 0) {
     lines.push(`## Unreachable (${result.unreachable.length}) \u2014 path unresolved / not a git repo`);
     for (const p of result.unreachable) lines.push(`- ${p}`);
@@ -4787,28 +5052,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 {
     }
@@ -4822,11 +5087,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);
@@ -4837,7 +5102,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);
@@ -4857,15 +5122,17 @@ 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 inRoster = roster.some((r) => {
+  const declaredEntry = roster.find((r) => {
     try {
       return realpathSync(resolve7(repositoryRoot, r.path)) === (repoReal ?? "\0");
     } catch {
       return resolve7(repositoryRoot, r.path) === targetAbs;
     }
   });
+  const inRoster = declaredEntry !== void 0;
+  const isSelf = declaredEntry !== void 0 && instructionMode(declaredEntry) === "self";
   const cnFold = canonicalName.toLowerCase();
   const canonicalShared = roster.some((r) => {
     let rReal = null;
@@ -4876,17 +5143,27 @@ 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({
+              kind: "instruction-symlink",
+              label: spec.name,
+              state: "foreign",
+              note: "instructions: self \u2014 committed, left untouched"
+            });
+          continue;
+        }
         if (state === "correct")
           items.push({ kind: "instruction-symlink", label: spec.name, state: "removable" });
         else if (state === "mismatch")
@@ -4913,7 +5190,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({
@@ -4936,7 +5213,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();
@@ -4962,8 +5239,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();
@@ -5067,12 +5344,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) });
@@ -5091,7 +5368,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) });
@@ -5099,7 +5376,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);
@@ -5334,7 +5611,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)"
@@ -5373,12 +5650,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 {
     }
@@ -5537,7 +5814,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;
@@ -5719,7 +5996,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 {
     }
@@ -5735,7 +6012,7 @@ function pathPresent(p) {
   }
 }
 function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, argReal) {
-  const declared = roster.some((entry) => {
+  const declaredEntry = roster.find((entry) => {
     const entryAbs = resolve7(repositoryRoot, entry.path);
     if (argReal !== void 0) {
       try {
@@ -5745,13 +6022,16 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
     }
     return entryAbs === argAbs;
   });
+  const declared = declaredEntry !== void 0;
+  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,
       declared,
+      ...self ? { self: true } : {},
       isAnchor: false,
       reachable: false,
       canonicalName,
@@ -5761,23 +6041,24 @@ 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,
+    ...self ? { self: true } : {},
     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 };
   }
@@ -5815,7 +6096,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;
@@ -5868,6 +6149,10 @@ function renderProjectRetrofit(result) {
       lines.push(
         `\u2139\uFE0F \`${result.path}\` is not declared in the roster (manifest \`repos\`). Add it first with \`basou project new\` / \`basou project adopt\`, then re-run.`
       );
+    } else if (result.reason === "self") {
+      lines.push(
+        `\u2139\uFE0F \`${result.path}\` declares \`instructions: self\` \u2014 its \`${CANONICAL_FILE}\` is a hand-authored committed file that stays in the repo, so there is no anchor canonical to relocate it to. Retrofit does not apply (its CLAUDE.md / Copilot spokes are wired by \`basou project symlinks\`).`
+      );
     } else if (result.reason === "anchor") {
       lines.push(
         `\u26A0\uFE0F \`${result.path}\` is the anchor (the project root). It owns its canonical directly \u2014 there is nothing to relocate.`
@@ -5943,70 +6228,17 @@ import {
   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()) {
-      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 = 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;
-  }
-  try {
-    const dirHandle = await open2(dir, "r");
-    try {
-      await dirHandle.sync();
-    } finally {
-      await dirHandle.close();
-    }
-  } catch {
-  }
-}
-
 // 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 homedir7 } from "os";
+import { isAbsolute as isAbsolute4, join as join10, 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 = join10(homedir7(), ".basou", "protocols.yaml");
+var DEFAULT_TARGET_PATH = join10(homedir7(), ".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 homedir7();
+  if (p.startsWith("~/")) return join10(homedir7(), p.slice(2));
   return p;
 }
 function isRecord3(value) {
@@ -6258,16 +6490,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 homedir8 } from "os";
+import { join as join11 } 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 ?? join11(homedir8(), ".codex", "sessions"),
+    ctx.claudeProjectsDir ?? join11(homedir8(), ".claude", "projects")
   ];
 }
 async function scanSourceLogs(roots) {
@@ -6281,7 +6513,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 = join11(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(full);
       } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
@@ -6802,8 +7034,8 @@ 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 homedir9 } from "os";
+import { join as join12 } from "path";
 import {
   acquireLock as acquireLock5,
   assertBasouRootSafe as assertBasouRootSafe11,
@@ -6856,13 +7088,13 @@ async function runClaudeCode(args, options, ctx = {}) {
   await assertBasouRootSafe11(paths.root);
   const manifest = await readManifest7(paths);
   const sessionId = prefixedUlid4("ses");
-  const sessionDir = join11(paths.sessions, sessionId);
+  const sessionDir = join12(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 = join12(sessionDir, "session.yaml");
   const session = buildInitialSession2({
     id: sessionId,
     command,
@@ -6988,7 +7220,7 @@ async function runClaudeCode(args, options, ctx = {}) {
   const rawRelated = computeRelatedFiles(preSnapshot, postSnapshot, diff);
   const relatedFiles = sanitizeRelatedFiles(rawRelated, {
     workingDirectory: repoRoot,
-    homedir: homedir8()
+    homedir: homedir9()
   }).sanitized;
   const finalStatus = decideFinalStatus2(result, signalReceived);
   await appendEvent(sessionDir, {
@@ -7132,7 +7364,7 @@ function buildInitialSession2(input) {
       source: { ...claudeCodeAdapterMetadata },
       started_at: input.startedAt,
       status: "initialized",
-      working_directory: sanitizeWorkingDirectory2(input.cwd, { homedir: homedir8() }),
+      working_directory: sanitizeWorkingDirectory2(input.cwd, { homedir: homedir9() }),
       invocation: {
         command: input.command,
         args: [...input.args],
@@ -7205,7 +7437,7 @@ async function resolveRepositoryRootForRun(cwd) {
 
 // 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 { basename as basename6, isAbsolute as isAbsolute6, join as join13, relative as relative3 } from "path";
 import {
   acquireLock as acquireLock6,
   appendEventToExistingSession as appendEventToExistingSession3,
@@ -7330,8 +7562,8 @@ async function doRunSessionShow(idInput, options, ctx) {
   const paths = basouPaths15(repositoryRoot);
   await assertWorkspaceInitialized10(paths.root);
   const sessionId = await resolveSessionId3(paths, idInput);
-  const sessionDir = join12(paths.sessions, sessionId);
-  const sessionYamlPath = join12(sessionDir, "session.yaml");
+  const sessionDir = join13(paths.sessions, sessionId);
+  const sessionYamlPath = join13(sessionDir, "session.yaml");
   let session;
   try {
     const raw = await readYamlFile7(sessionYamlPath);
@@ -8074,7 +8306,7 @@ async function resolveRepositoryRootForStatus(cwd) {
 
 // src/commands/task.ts
 import { readFile as readFile6 } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 import {
   archiveTask,
   assertBasouRootSafe as assertBasouRootSafe15,
@@ -8400,7 +8632,7 @@ async function doRunTaskShow(idInput, options, ctx) {
   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 = join14(paths.sessions, s.sessionId);
     try {
       for await (const ev of replayEvents3(sessionDir, {
         onWarning: (w) => printReplayWarning(w, s.sessionId)
@@ -9306,7 +9538,7 @@ 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 join15, relative as relative4, resolve as resolve10 } from "path";
 import { promisify } from "util";
 import { readManifest as readManifest11 } from "@basou/core";
 var execFileAsync = promisify(execFile);
@@ -9330,7 +9562,7 @@ function isBasouPath(p) {
 async function inspectRepo(repoPath) {
   let hasEntry = false;
   try {
-    await lstat2(join14(repoPath, ".basou"));
+    await lstat2(join15(repoPath, ".basou"));
     hasEntry = true;
   } catch (error) {
     if (errorCode(error) !== "ENOENT") {
@@ -9431,7 +9663,7 @@ function formatSafetyReport(result) {
 
 // src/lib/view-server.ts
 import { createServer } from "http";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 import {
   computeWorkStats as computeWorkStats2,
   enumerateApprovals as enumerateApprovals2,
@@ -10390,7 +10622,7 @@ async function sessionDetail(ws, sessionId) {
     throw error;
   }
   try {
-    const events = await readAllEvents2(join15(ws.paths.sessions, sessionId));
+    const events = await readAllEvents2(join16(ws.paths.sessions, sessionId));
     return { session, events };
   } catch {
     return { session, events: [], degraded: true };