cairn-ai 0.2.8 → 0.3.0

package/scripts/cairn-lifecycle-claude.mjs

@@ -0,0 +1,142 @@
+import { spawnSync } from "node:child_process";
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { quoteShellArg, renderMirrorFile, writeLocator } from "./cairn-lifecycle-mirror.mjs";
+
+// Claude Code loads a plugin's default hooks/hooks.json and merges any manifest hooks, and it only expands
+// ${CLAUDE_PLUGIN_ROOT}. The shared package hooks use Codex's ${PLUGIN_ROOT}, so Claude gets a separate thin
+// plugin whose hooks call the installed versioned runtime by absolute path. Commands and agents stay in the
+// existing ~/.claude mirrors so they are not listed twice.
+export async function stageClaudePlugin({
+  stageRoot, runtimeStage, destinationRoot, versionedPluginRoot, marketplaceName, pluginName,
+  releaseVersion, skillNames, platform = process.platform,
+}) {
+  const staged = join(stageRoot, "claude-plugin");
+  const pluginDir = join(staged, pluginName);
+  const packageJson = JSON.parse(await readFile(join(runtimeStage, "package.json"), "utf8"));
+  const description = packageJson.description ?? "Cairn agent harness";
+
+  await writeJson(join(staged, ".claude-plugin", "marketplace.json"), {
+    name: marketplaceName,
+    description: "Local Cairn marketplace managed by `cairn install`",
+    owner: { name: packageJson.author?.name ?? "Cairn" },
+    plugins: [{ name: pluginName, source: `./${pluginName}`, description, version: releaseVersion }],
+  });
+  await writeJson(join(pluginDir, ".claude-plugin", "plugin.json"), {
+    name: pluginName,
+    version: releaseVersion,
+    description,
+    author: { name: packageJson.author?.name ?? "Cairn" },
+    ...(packageJson.homepage ? { homepage: packageJson.homepage } : {}),
+    ...(packageJson.license ? { license: packageJson.license } : {}),
+  });
+  await writeJson(join(pluginDir, "hooks", "hooks.json"), await claudeHooks(runtimeStage, versionedPluginRoot, platform));
+
+  for (const name of skillNames) {
+    const skillStage = join(pluginDir, "skills", name);
+    await cp(join(runtimeStage, "skills", name), skillStage, { recursive: true });
+    const locatorPath = join(destinationRoot, pluginName, "skills", name, "references", "cairn-runtime.json");
+    await renderMirrorFile(join(runtimeStage, "skills", name, "SKILL.md"), join(skillStage, "SKILL.md"), {
+      locatorPath, runtimeRoot: versionedPluginRoot, includeLocatorNotice: true,
+    });
+    await writeLocator(join(skillStage, "references", "cairn-runtime.json"), versionedPluginRoot);
+  }
+  return staged;
+}
+
+async function claudeHooks(runtimeStage, versionedPluginRoot, platform) {
+  const source = JSON.parse(await readFile(join(runtimeStage, "hooks", "hooks.json"), "utf8"));
+  const stateScript = quoteShellArg(join(versionedPluginRoot, "scripts", "cairn-state.mjs"), platform);
+  const hooks = {};
+  for (const [eventName, groups] of Object.entries(source.hooks ?? {})) {
+    hooks[eventName] = groups.map((group) => ({
+      ...group,
+      hooks: (group.hooks ?? []).map((handler) => {
+        const event = String(handler.command ?? "").match(/cairn-state\.mjs"?\s+([a-z-]+)\s*$/)?.[1];
+        if (!event) throw new Error(`Unsupported Cairn hook command for Claude Code: ${handler.command}`);
+        return { ...handler, command: `node ${stateScript} ${event}` };
+      }),
+    }));
+  }
+  return { hooks };
+}
+
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+// Registration goes through the documented `claude plugin` CLI. CLAUDE_CONFIG_DIR is only set when the caller
+// overrode the Claude home, because setting it for the default home would move Claude's global config file.
+export function createClaudeRegistration({ claudeHome, claudeHomeOverridden, marketplaceRoot, marketplaceName, pluginName }) {
+  const cli = process.env.CAIRN_CLAUDE_CLI ?? "claude";
+  const pluginId = `${pluginName}@${marketplaceName}`;
+  const env = claudeHomeOverridden ? { ...process.env, CLAUDE_CONFIG_DIR: claudeHome } : process.env;
+
+  // A .mjs/.js override runs through the current Node binary so tests can supply a portable stand-in CLI.
+  function run(args) {
+    if (/\.m?js$/.test(cli)) return spawnSync(process.execPath, [cli, ...args], { encoding: "utf8", env, timeout: 120_000 });
+    return spawnSync(cli, args, { encoding: "utf8", env, timeout: 120_000, shell: process.platform === "win32" });
+  }
+
+  function available() {
+    if (cli === "none") return false;
+    const result = run(["--version"]);
+    return !result.error && result.status === 0;
+  }
+
+  function json(args) {
+    const result = run([...args, "--json"]);
+    if (result.error || result.status !== 0) {
+      throw new Error(`claude ${args.join(" ")} failed: ${(result.stderr || result.stdout || result.error?.message || "").trim().split("\n").at(-1)}`);
+    }
+    const text = result.stdout.trim();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return JSON.parse(text.split("\n").filter(Boolean).at(-1));
+    }
+  }
+
+  const ownsMarketplace = (entry) => entry?.name === marketplaceName
+    && typeof entry.path === "string" && resolve(entry.path) === resolve(marketplaceRoot);
+  const ownedPlugins = (list) => (Array.isArray(list) ? list : [])
+    .filter((entry) => entry?.id === pluginId && entry.scope === "user");
+
+  function status({ checked = false } = {}) {
+    if (!checked && !available()) return { available: false, marketplace: false, installed: false, enabled: false };
+    const marketplace = json(["plugin", "marketplace", "list"]).find((entry) => entry?.name === marketplaceName) ?? null;
+    const plugin = ownedPlugins(json(["plugin", "list"]))[0] ?? null;
+    return {
+      available: true,
+      marketplace: ownsMarketplace(marketplace),
+      foreignMarketplace: Boolean(marketplace) && !ownsMarketplace(marketplace),
+      installed: Boolean(plugin),
+      enabled: Boolean(plugin?.enabled),
+    };
+  }
+
+  function register() {
+    if (!available()) return { registered: false, reason: "claude CLI not found" };
+    const current = status({ checked: true });
+    if (current.foreignMarketplace) {
+      return { registered: false, reason: `a different Claude Code marketplace named "${marketplaceName}" already exists` };
+    }
+    if (!current.marketplace) json(["plugin", "marketplace", "add", marketplaceRoot, "--scope", "user"]);
+    if (!current.installed) json(["plugin", "install", pluginId, "--scope", "user"]);
+    else if (!current.enabled) json(["plugin", "enable", pluginId, "--scope", "user"]);
+    return { registered: true };
+  }
+
+  function unregister() {
+    if (!available()) return { unregistered: false, reason: "claude CLI not found" };
+    const current = status({ checked: true });
+    // Only remove a registration that points at Cairn's own marketplace directory.
+    if (!current.marketplace) return { unregistered: false, reason: "no Cairn-owned Claude Code marketplace is registered" };
+    if (current.installed) json(["plugin", "uninstall", pluginId, "--scope", "user"]);
+    json(["plugin", "marketplace", "remove", marketplaceName]);
+    return { unregistered: true };
+  }
+
+  return { available, register, status, unregister, pluginId };
+}

package/scripts/cairn-lifecycle-commands.mjs

@@ -5,11 +5,12 @@ import { hasSetting, readSharedConfigSnapshot, removeCairnConfig, splitSections
 import {
   installedSkillLocatorPath, validRuntimeLocator, validateAntigravitySkills,
 } from "./cairn-lifecycle-mirror.mjs";
+import { createClaudeRegistration } from "./cairn-lifecycle-claude.mjs";
 
 export function createCommands(context) {
   const {
-    antigravityCliHome, antigravityHome, claudeRuntimeLocatorPath,
-    codexHome, configPath, installedPluginRoot, installedRuntimeLocatorPath,
+    antigravityCliHome, antigravityHome, claudeHome, claudeHomeOverridden, claudePluginMarketplaceRoot,
+    claudeRuntimeLocatorPath, codexHome, marketplaceName, configPath, installedPluginRoot, installedRuntimeLocatorPath,
     marketplaceJsonPath, ownershipPath, phases, pluginName, pluginRoot,
     pruneUninstallScaffolds, releaseVersion, samePath, skillNames, t, transaction,
     versionedPluginRoot, staging, integrity,
@@ -19,6 +20,9 @@ export function createCommands(context) {
     removeManagedTarget, replaceTarget, rollback,
   } = transaction;
   const { legacyMigrationTargets, stageInstall } = staging;
+  const claudeRegistration = createClaudeRegistration({
+    claudeHome, claudeHomeOverridden, marketplaceRoot: claudePluginMarketplaceRoot, marketplaceName, pluginName,
+  });
   const {
     adoptLegacy, anyManagedArtifactExists, assertOwnershipDigests,
     assertTargetsReplaceable, ownershipDigestsValid, readOwnership, targetDigest,
@@ -80,6 +84,24 @@ async function install(mode) {
     if (transaction.state !== "committed") await rollback(transaction);
     throw error;
   }
+  reportClaudeRegistration();
+}
+
+// Files are committed first; registering with Claude Code is idempotent, and a failure leaves the files
+// installed with a manual command to finish, instead of rolling back a working Codex/Antigravity install.
+function reportClaudeRegistration() {
+  const manual = `claude plugin marketplace add ${JSON.stringify(claudePluginMarketplaceRoot)} && claude plugin install ${claudeRegistration.pluginId} --scope user`;
+  try {
+    const result = claudeRegistration.register();
+    if (result.registered) {
+      console.log(`Claude Code plugin: ${claudeRegistration.pluginId} (${claudePluginMarketplaceRoot})`);
+      return;
+    }
+    console.log(`Claude Code plugin not registered: ${result.reason}. To register: ${manual}`);
+  } catch (error) {
+    console.log(`Claude Code plugin registration failed: ${error.message}. To register: ${manual}`);
+    process.exitCode = 1;
+  }
 }
 
 async function uninstall() {
@@ -92,6 +114,8 @@ async function uninstall() {
     if (record.type !== "config" && current !== record.installedDigest) conflicts.push(record.path);
   }
   if (conflicts.length > 0) throw new Error(`Refusing to uninstall modified managed artifacts: ${conflicts.join(", ")}`);
+  // Unregister before removing files so Claude Code never points at a deleted plugin; a failure aborts with nothing changed.
+  const unregistered = claudeRegistration.unregister().unregistered;
   const transaction = await createTransaction();
   try {
     const configRecord = ownership.targets.find((record) => record.type === "config");
@@ -114,7 +138,13 @@ async function uninstall() {
     await finishTransaction(transaction);
     injectFailure("uninstall-after-commit");
   } catch (error) {
-    if (transaction.state !== "committed") await rollback(transaction);
+    if (transaction.state !== "committed") {
+      await rollback(transaction);
+      // The rollback restored the plugin files, so restore the Claude Code registration that preceded them.
+      if (unregistered) {
+        try { claudeRegistration.register(); } catch (registrationError) { console.error(`Claude Code plugin re-registration failed: ${registrationError.message}`); }
+      }
+    }
     throw error;
   }
   await pruneUninstallScaffolds();
@@ -141,6 +171,14 @@ async function doctor() {
   checks.push(["config marketplace", splitSections(config).some((section) => section.header === "marketplaces.cairn")]);
   checks.push(["config plugin enabled", hasSetting(config, 'plugins."cairn@cairn"', "enabled", "true")]);
   checks.push(["Claude runtime locator", await validRuntimeLocator(claudeRuntimeLocatorPath, versionedPluginRoot)]);
+  const claudePluginManifest = await readJson(join(claudePluginMarketplaceRoot, pluginName, ".claude-plugin", "plugin.json"));
+  checks.push(["Claude plugin files", claudePluginManifest?.version === releaseVersion
+    && await exists(join(claudePluginMarketplaceRoot, ".claude-plugin", "marketplace.json"))
+    && await exists(join(claudePluginMarketplaceRoot, pluginName, "hooks", "hooks.json"))]);
+  let claudeStatus = null;
+  try { claudeStatus = claudeRegistration.status(); } catch { claudeStatus = null; }
+  checks.push(["Claude plugin registered", Boolean(claudeStatus?.marketplace && claudeStatus.installed)]);
+  checks.push(["Claude plugin enabled", Boolean(claudeStatus?.enabled)]);
   checks.push(["Antigravity IDE skills", await exists(join(antigravityHome, "skills", "cairn-plan", "SKILL.md"))]);
   checks.push(["Antigravity CLI flat skills", await exists(join(antigravityCliHome, "skills", "cairn-plan.md"))]);
 

package/scripts/cairn-lifecycle-integrity.mjs

@@ -7,7 +7,7 @@ import { antigravityRuntimeLocatorPath } from "./cairn-lifecycle-mirror.mjs";
 
 export function createIntegrity(context) {
   const {
-    antigravityCliHome, antigravityHome, claudeHome, claudeRuntimeLocatorPath,
+    antigravityCliHome, antigravityHome, claudeHome, claudePluginMarketplaceRoot, claudeRuntimeLocatorPath,
     commandNames, configPath, installedPluginRoot, legacyAntigravityHome,
     marketplaceJsonPath, marketplaceRoot, ownershipPath, phases, pluginName,
     releaseVersion, skillNames,
@@ -97,13 +97,25 @@ function validateOwnershipShape(ownership, { required = false } = {}) {
     paths.add(record.path);
   }
   const requiredTargets = requiredOwnershipTargets(ownership.version);
-  if (ids.size !== requiredTargets.size || [...requiredTargets.keys()].some((id) => !ids.has(id))) {
+  const optionalIds = new Set(requiredTargets.has("claude-plugin") ? [] : ["claude-plugin"]);
+  if ([...ids].some((id) => !requiredTargets.has(id) && !optionalIds.has(id)) || [...requiredTargets.keys()].some((id) => !ids.has(id))) {
     throw new Error("Ownership manifest does not contain the complete managed target set.");
   }
 }
 
+const CLAUDE_PLUGIN_SINCE = "0.2.9";
+
+function compareVersions(left, right) {
+  const parse = (value) => String(value).split("-")[0].split(".").map(Number);
+  const [a, b] = [parse(left), parse(right)];
+  for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] - b[index];
+  return 0;
+}
+
 function requiredOwnershipTargets(version = releaseVersion) {
   const ids = ["codex-source", "codex-runtime", "marketplace", "claude-runtime", "ide-runtime", "cli-runtime", "codex-config"];
+  // Manifests written before the Claude Code plugin existed must stay valid so those installs can upgrade.
+  if (compareVersions(version, CLAUDE_PLUGIN_SINCE) >= 0) ids.push("claude-plugin");
   for (const name of commandNames()) ids.push(`claude-command-${name}`, `ide-workflow-${name}`, `cli-workflow-${name}`);
   for (const name of ["explorer", "worker"]) ids.push(`claude-agent-${name}`);
   for (const name of skillNames()) ids.push(`ide-skill-${name}`, `cli-skill-${name}`);
@@ -116,6 +128,7 @@ function expectedManagedTarget(id, version = releaseVersion) {
     "codex-runtime": { phase: "codex", path: versionedRuntimeRoot(version), type: "tree" },
     marketplace: { phase: "codex", path: marketplaceJsonPath, type: "file" },
     "claude-runtime": { phase: "claude", path: claudeRuntimeLocatorPath, type: "file" },
+    "claude-plugin": { phase: "claude", path: claudePluginMarketplaceRoot, type: "tree" },
     "ide-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(antigravityHome), type: "file" },
     "cli-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(antigravityCliHome), type: "file" },
     "legacy-ide-runtime": { phase: "antigravity", path: antigravityRuntimeLocatorPath(legacyAntigravityHome), type: "file" },

package/scripts/cairn-lifecycle-staging.mjs

@@ -4,11 +4,12 @@ import { readSharedConfigSnapshot, trustedHookStates } from "./cairn-lifecycle-c
 import {
   antigravityRuntimeLocatorPath, antigravitySkillLocatorPath, renderMirrorFile, writeLocator,
 } from "./cairn-lifecycle-mirror.mjs";
+import { stageClaudePlugin } from "./cairn-lifecycle-claude.mjs";
 
 export function createStaging(context) {
   const {
-    agentNames, antigravityCliHome, antigravityHome, claudeHome,
-    claudeRuntimeLocatorPath, commandNames, configPath, installedPluginRoot,
+    agentNames, antigravityCliHome, antigravityHome, claudeHome, claudePluginMarketplaceRoot,
+    claudeRuntimeLocatorPath, commandNames, releaseVersion, configPath, installedPluginRoot,
     legacyAntigravityHome, marketplaceJsonPath, marketplaceName, pluginName,
     pluginRoot, skillNames, updateConfig, versionedPluginRoot, assertRegularTree,
   } = context;
@@ -44,6 +45,12 @@ async function stageInstall(stageRoot) {
     add(`claude-agent-${name}`, "claude", join(claudeHome, "agents", `cairn-${name}.md`), staged, "file");
   }
 
+  const claudePluginStage = await stageClaudePlugin({
+    stageRoot, runtimeStage, destinationRoot: claudePluginMarketplaceRoot, versionedPluginRoot,
+    marketplaceName, pluginName, releaseVersion, skillNames: skillNames(),
+  });
+  add("claude-plugin", "claude", claudePluginMarketplaceRoot, claudePluginStage);
+
   await stageAntigravity(targets, stageRoot, runtimeStage, antigravityHome, "ide", false);
   await stageAntigravity(targets, stageRoot, runtimeStage, antigravityCliHome, "cli", true);
 

package/scripts/cairn-lifecycle.mjs

@@ -30,6 +30,7 @@ export {
 const pluginRoot = resolvePluginRoot(import.meta.url);
 const homeRoot = process.env.HOME ?? process.env.USERPROFILE ?? homedir() ?? ".";
 const codexHome = resolve(process.env.CODEX_HOME ?? join(homeRoot, ".codex"));
+const claudeHomeOverridden = typeof process.env.CLAUDE_HOME === "string" && process.env.CLAUDE_HOME.length > 0;
 const claudeHome = resolve(process.env.CLAUDE_HOME ?? join(homeRoot, ".claude"));
 const antigravityHome = resolve(process.env.ANTIGRAVITY_HOME ?? join(homeRoot, ".gemini", "config"));
 const legacyAntigravityHome = resolve(process.env.CAIRN_LEGACY_ANTIGRAVITY_HOME ?? join(homeRoot, ".agents"));
@@ -45,6 +46,7 @@ const transactionPath = join(marketplaceRoot, ".cairn", "transaction.json");
 const transactionRoot = join(marketplaceRoot, ".cairn", "transactions");
 const lifecycleLockPath = join(marketplaceRoot, ".cairn", "lifecycle.lock");
 const claudeRuntimeLocatorPath = join(claudeHome, "cairn", "runtime.json");
+const claudePluginMarketplaceRoot = join(marketplaceRoot, "claude");
 const sourceManifest = JSON.parse(await readFile(join(pluginRoot, ".codex-plugin", "plugin.json"), "utf8"));
 const releaseVersion = sourceManifest.version;
 const versionedPluginRoot = join(marketplaceRoot, pluginName, releaseVersion);
@@ -53,7 +55,8 @@ const phases = ["codex", "claude", "antigravity", "config", "cleanup"];
 const MAX_LIFECYCLE_LOCK_TIMEOUT_MS = 2_147_483_647;
 
 const lifecycleContext = {
-  agentNames, antigravityCliHome, antigravityHome, claudeHome, claudeRuntimeLocatorPath,
+  agentNames, antigravityCliHome, antigravityHome, claudeHome, claudeHomeOverridden,
+  claudePluginMarketplaceRoot, claudeRuntimeLocatorPath,
   codexHome, commandNames, configPath, installedPluginRoot, installedRuntimeLocatorPath,
   legacyAntigravityHome, lifecycleLockPath, marketplaceJsonPath, marketplaceName,
   marketplaceRoot, ownershipPath, phases, pluginName, pluginRoot, releaseVersion,
@@ -105,7 +108,7 @@ function lifecycleLockTimeout() {
 async function assertLifecycleMutationPaths() {
   const roots = [
     [codexHome, lifecycleLockPath], [codexHome, installedPluginRoot], [codexHome, versionedPluginRoot],
-    [codexHome, marketplaceJsonPath], [isInside(codexHome, configPath) ? codexHome : dirname(configPath), configPath],
+    [codexHome, marketplaceJsonPath], [codexHome, claudePluginMarketplaceRoot], [isInside(codexHome, configPath) ? codexHome : dirname(configPath), configPath],
     [claudeHome, join(claudeHome, "commands")], [claudeHome, join(claudeHome, "agents")],
     [claudeHome, claudeRuntimeLocatorPath], [antigravityHome, join(antigravityHome, "skills")],
     ...skillNames().map((name) => [antigravityHome, join(antigravityHome, "skills", name)]),

package/scripts/cairn-state-context.mjs

@@ -3,6 +3,7 @@ const contextLimits = {
   roadmapTaskId: 24,
   taskTitle: 40,
   roadmapWindow: 3,
+  parallelTitle: 16,
 };
 
 export function prependContext(result, notice) {
@@ -21,6 +22,8 @@ export function prependContext(result, notice) {
   };
 }
 
+import { currentTask } from "./cairn-goal-policy.mjs";
+
 export function contextResult({ ko, state, event }) {
   const base = kernelBase(ko);
   const idlePolicy = event === "user-prompt-submit"
@@ -37,9 +40,7 @@ export function contextResult({ ko, state, event }) {
     return interruptedContextResult(event, ko, state);
   }
   if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}${failClosed}` });
-  const task = state.tasks.find((item) => item.status === "active")
-    ?? state.tasks.find((item) => item.status === "pending")
-    ?? state.tasks.find((item) => item.status === "blocked");
+  const task = currentTask(state);
   const planId = state.goal.planId;
   const phase = task ? "cairn-work" : "cairn-review";
   const activeHeader = ko
@@ -69,7 +70,15 @@ export function contextResult({ ko, state, event }) {
         ? `곁가지 질문·조향 뒤 ${taskId}를 재개하고 남은 task를 최종 검토까지 진행하세요(일시정지·중단·전환 요청 제외).`
         : `After a side question or steer, resume ${taskId}, then advance remaining tasks to final review unless asked to pause, stop, or switch.`))
     : "";
-  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
+  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, parallelLine(ko, state), resume].filter(Boolean).join("\n") });
+}
+
+// Only when several tasks run at once: their ids and clipped titles, never the dependency graph.
+function parallelLine(ko, state) {
+  const active = state.tasks.filter((task) => task.status === "active");
+  if (active.length < 2) return "";
+  const list = active.map((task) => `${clipText(task.id, contextLimits.roadmapTaskId)} (${clipText(task.title, contextLimits.parallelTitle)})`).join(", ");
+  return `${ko ? "병렬 active" : "Parallel active"}: ${list}`;
 }
 
 function kernelBase(ko) {

package/scripts/cairn-state.mjs

@@ -5,7 +5,7 @@ import { contextResult, foreignSessionContextResult, prependContext } from "./ca
 import { continuationReason, stopAllowedMessage, stopHookOutput } from "./cairn-state-hook.mjs";
 import { initializeProject } from "./cairn-state-init.mjs";
 import { evaluateStop, isGoalOwnedBySession, reconcileWorktreeState } from "./cairn-goal.mjs";
-import { readStopGuard, writeStopGuard } from "./cairn-goal-state.mjs";
+import { readHookGuard, readStopGuard, writeHookGuard, writeStopGuard } from "./cairn-goal-state.mjs";
 import { resolveRepoRoot } from "./cairn-paths.mjs";
 
 const recoverableGoalStatuses = new Set(["active", "paused", "blocked"]);
@@ -52,7 +52,10 @@ export async function runStateResult(event = "manual", {
     if (recoverableGoalStatuses.has(state?.goal?.status) && !isGoalOwnedBySession(state, payload?.session_id)) {
       return foreignSessionContextResult({ ko, event, sessionId: payload?.session_id, root: resolvedRoot });
     }
-    const result = contextResult({ ko, state, event });
+    const context = contextResult({ ko, state, event });
+    // SessionStart (also after compaction) carries a literal CLI prefix so agents do not rebuild or store it in a
+    // shell variable, which does not survive between tool calls.
+    const result = event === "session-start" ? appendContext(context, cliPrefixLine()) : context;
     if (!reconciled.removed) return result;
     const notice = ko
       ? "Cairn worktree 점검: 현재 worktree에 속하지 않는 stale Cairn 상태를 제거했습니다."
@@ -67,6 +70,19 @@ export async function runStateResult(event = "manual", {
     if (state?.goal?.status !== "active" || !isGoalOwnedBySession(state, payload?.session_id)) {
       return { status: 0, message: "", hookOutput: {} };
     }
+    // Remind once per goal, task, and session; repeating it after every edit only grows the cached prefix.
+    const reminderKey = {
+      goalId: state.goal.id,
+      taskId: state.tasks.find((task) => task.status === "active")?.id ?? null,
+      sessionId: payload?.session_id ?? null,
+    };
+    const previousReminder = await readHookGuard(resolvedRoot, "reminder");
+    if (previousReminder?.goalId === reminderKey.goalId
+      && previousReminder?.taskId === reminderKey.taskId
+      && previousReminder?.sessionId === reminderKey.sessionId) {
+      return { status: 0, message: "", hookOutput: {} };
+    }
+    await writeHookGuard(resolvedRoot, "reminder", reminderKey);
     const message = ko
       ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거 기록이 필요합니다. 활성 목표가 있다면 현재 task에 성공 증거를 기록하세요."
       : "Cairn check: external-state changes need dry-run/check evidence. When a goal is active, record successful evidence for its current task.";
@@ -106,14 +122,40 @@ export async function runStateResult(event = "manual", {
 
 async function recordStopProgress(root, state, event, payload) {
   const scope = event === "subagent-stop" ? `subagent:${payload?.agent_id ?? ""}` : "turn";
+  // Parallel workers share this guard: keep one entry per scope, and measure a worker's progress by its own task
+  // so sibling writes (which bump the goal revision) do not look like progress.
+  const assigned = event === "subagent-stop"
+    ? state.tasks.find((task) => task.status === "active" && task.assignedAgentId === payload?.agent_id)
+    : null;
+  const marker = assigned ? `${assigned.id}:${assigned.status}:${assigned.updatedAt}` : state.revision;
   const previous = await readStopGuard(root);
-  const progressed = previous?.goalId !== state.goal.id
-    || previous?.scope !== scope
-    || previous?.revision !== state.revision;
-  if (progressed) await writeStopGuard(root, { goalId: state.goal.id, scope, revision: state.revision });
+  const scopes = previous?.goalId === state.goal.id && previous?.scopes && typeof previous.scopes === "object" ? previous.scopes : {};
+  const progressed = scopes[scope] !== marker;
+  if (progressed) {
+    const entries = Object.entries({ ...scopes, [scope]: marker }).slice(-16);
+    await writeStopGuard(root, { goalId: state.goal.id, scopes: Object.fromEntries(entries) });
+  }
   return progressed;
 }
 
+// Only the CLI path: goal commands resolve the repository root themselves, and a second absolute path would let
+// long install or checkout paths push the SessionStart capsule past its budget.
+function cliPrefixLine() {
+  const cli = fileURLToPath(new URL("./cairn.mjs", import.meta.url));
+  return `Cairn CLI: node ${JSON.stringify(cli)} goal <command>`;
+}
+
+function appendContext(result, line) {
+  const specific = result.hookOutput?.hookSpecificOutput;
+  return {
+    ...result,
+    message: `${result.message}\n${line}`,
+    hookOutput: specific
+      ? { ...result.hookOutput, hookSpecificOutput: { ...specific, additionalContext: `${specific.additionalContext}\n${line}` } }
+      : result.hookOutput,
+  };
+}
+
 function hookFailureResult(event, error) {
   const detail = String(error?.message ?? error).split("\n")[0].slice(0, 300);
   const message = `Cairn ${event} hook could not read goal state: ${detail}. Run cairn goal status to inspect it; do not treat an active goal as finished.`;