fix(skill): stale user-level skill copy shadowed injections; seed the preamble

Two live failures from one root cause: Claude Code loads a same-named
user-level skill (~/.claude/skills/codeman, written once by `codeman skill
install`) over the fresh per-case copy, and nothing ever refreshed it. A
stale Aug-9 copy (pre fast-path, pre lineage header) made every agent-driven
spawn run the old recipes: workers spawned serially with pid polls and
without X-Codeman-Parent-Session, so the web UI drew no lineage arcs.

- refreshUserAgentSkill(): session create now refreshes a marker-owned
  user-level copy (refresh-only: absent copies are not installed,
  foreign/symlink copies stay untouched).
- seedAgentSessionPreamble(): local claude session create pre-seeds the
  skill's preamble into ${XDG_CACHE_HOME:-~/.cache}/codeman-agent-<id>.sh,
  single-sourced from the new skills/codeman/preamble.sh, so the skill's §0
  bootstrap collapses to a two-line loader instead of a ~150-line paste the
  model has to type out (measured ~47s of generation per run).
- SKILL.md: §0 now leads with the loader and keeps the full block as the
  stale/missing fallback; explicit verbatim-paste warning (a hand-assembled
  preamble is how the header and the fast-path functions got lost);
  spawn_worker also sends parentSessionId in the body as defense in depth;
  preamble stamp bumped to 1.18.3 so pre-fix cached preambles self-heal.
- test/agent-skill.test.ts pins preamble.sh byte-identical to the SKILL.md
  heredoc and covers seeding (XDG + HOME fallback, 0600) and the user-level
  refresh (absent/stale/foreign).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/hooks-config.ts

@@ -31,6 +31,7 @@
 import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readFile, writeFile, mkdir, lstat, readdir, realpath, rename, unlink, rmdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -948,6 +949,49 @@ export async function installAgentSkillInto(skillDir: string): Promise<AgentSkil
   });
 }
 
+/**
+ * Seed a claude session's agent preamble file (`$XDG_CACHE_HOME/codeman-agent-<id>.sh`,
+ * default `~/.cache/`) from the packaged `skills/codeman/preamble.sh`, so the agent
+ * skill's §0 bootstrap collapses to a two-line loader instead of a ~150-line block the
+ * model has to type out (measured live: that paste alone cost a spawn run ~47 s of
+ * generation time). The path formula must match the skill's
+ * `${XDG_CACHE_HOME:-$HOME/.cache}` exactly; sessions inherit the server's env, so
+ * reading the server's own XDG_CACHE_HOME keeps the two in agreement (`||` mirrors the
+ * shell's `:-`, treating empty as unset). Callers gate to LOCAL claude sessions (a
+ * remote or in-container HOME is not this filesystem) and treat it as best-effort: the
+ * skill's §0 fallback block self-heals a missing or stale file.
+ */
+export async function seedAgentSessionPreamble(sessionId: string): Promise<void> {
+  const content = await readFile(join(agentSkillSourceDir(), 'preamble.sh'), 'utf-8');
+  const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  await mkdir(cacheDir, { recursive: true });
+  await writeFile(join(cacheDir, `codeman-agent-${sessionId}.sh`), content, { mode: 0o600 });
+}
+
+/**
+ * Refresh the USER-LEVEL skill copy (`~/.claude/skills/codeman`) IF one exists and is
+ * Codeman-managed. `codeman skill install` (no `--case`) writes that copy once, and
+ * unlike per-case copies (re-installed on every session create) nothing ever refreshed
+ * it, so it stayed at whatever version installed it. That matters because Claude Code
+ * loads the USER-LEVEL copy over a case's fresh one when both carry the name `codeman`:
+ * observed live 2026-08-14, an Aug 9 user copy (pre fast-path, pre lineage header)
+ * shadowed the current per-case injections, so every agent-driven spawn ran the old
+ * recipes, spawned workers serially, and lost their lineage arcs.
+ *
+ * Refresh-ONLY: an absent copy is not installed (the user never asked for a global
+ * copy), and foreign/symlink copies are refused by installAgentSkillInto itself.
+ */
+export async function refreshUserAgentSkill(): Promise<AgentSkillApplyResult | 'absent'> {
+  const skillDir = join(homedir(), '.claude', 'skills', 'codeman');
+  try {
+    const existing = await readFile(join(skillDir, 'SKILL.md'), 'utf-8');
+    if (!existing.includes(AGENT_SKILL_MARKER_PREFIX)) return 'foreign';
+  } catch {
+    return 'absent';
+  }
+  return installAgentSkillInto(skillDir);
+}
+
 /**
  * Remove a Codeman-managed skill copy from `skillDir`. Same ownership and symlink
  * refusals as the install path. Deletes only files the packaged source would have

src/web/routes/session-routes.ts

@@ -82,6 +82,8 @@ import {
   stripCaseEnvKeys,
   applyStatusLineConfig,
   applyAgentSkill,
+  refreshUserAgentSkill,
+  seedAgentSessionPreamble,
   refreshStaleCodemanHooks,
 } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
@@ -601,6 +603,13 @@ function abortOnClientHangUp(reply: FastifyReply): AbortController {
 async function injectAgentSkill(casePath: string): Promise<void> {
   const skillDir = join(casePath, '.claude', 'skills', 'codeman');
   try {
+    // Claude Code loads a same-named USER-LEVEL skill (`~/.claude/skills/codeman`,
+    // written once by `codeman skill install`) over the case copy injected below, so a
+    // stale user copy silently replaces every fresh injection (observed 2026-08-14: an
+    // old copy cost every spawned worker its lineage arc and the fast path). Keep it
+    // current on the same trigger. Refresh-only + marker-guarded; quiet on refusal,
+    // since a foreign user copy is the user's own authored skill, not a config error.
+    await refreshUserAgentSkill();
     const result = await applyAgentSkill(casePath, true);
     if (result === 'foreign') {
       console.warn(
@@ -913,6 +922,13 @@ export function registerSessionRoutes(
     ctx.store.incrementSessionsCreated();
     ctx.persistSessionState(session);
     await ctx.setupSessionListeners(session);
+    // Pre-seed the agent skill's preamble cache so its §0 bootstrap is a two-line
+    // loader (see seedAgentSessionPreamble). Local claude sessions only; best-effort.
+    if (mode === 'claude' && !remote && (await ctx.getAgentSkillEnabled())) {
+      await seedAgentSessionPreamble(session.id).catch((err: unknown) =>
+        console.warn(`[agent-skill] preamble seed failed for ${session.id}: ${getErrorMessage(err)}`)
+      );
+    }
     getLifecycleLog().log({ event: 'created', sessionId: session.id, name: session.name });
 
     // Use light state for broadcast + response — buffers are fetched on-demand via /terminal.
@@ -3016,6 +3032,13 @@ export function registerSessionRoutes(
     ctx.store.incrementSessionsCreated();
     ctx.persistSessionState(session);
     await ctx.setupSessionListeners(session);
+    // Pre-seed the agent skill's preamble cache so its §0 bootstrap is a two-line
+    // loader (see seedAgentSessionPreamble). Local claude sessions only; best-effort.
+    if (mode === 'claude' && !remote && !docker && (await ctx.getAgentSkillEnabled())) {
+      await seedAgentSessionPreamble(session.id).catch((err: unknown) =>
+        console.warn(`[agent-skill] preamble seed failed for ${session.id}: ${getErrorMessage(err)}`)
+      );
+    }
     getLifecycleLog().log({
       event: 'created',
       sessionId: session.id,