@marcomigozzi/trailhead 0.4.0 → 0.5.1

package/bin/lib/codex-projection.test.js

@@ -81,8 +81,22 @@ ok('codexSkillAdapterHeader §D pins the exact agent_type dispatch call shape',
   header.includes('spawn_agent(agent_type="trailhead-<technique>"'));
 ok('codexSkillAdapterHeader §D keeps the base spawn_agent v1 fallback path',
   header.includes('base multi_agent v1') && header.includes('inherit the one session model'));
+ok('codexSkillAdapterHeader §D warns against a single blocking wait_agent with a poll loop',
+  header.includes('bounded wait') && header.includes('poll'));
+ok('codexSkillAdapterHeader §D offers a background-job fallback for a stalling review',
+  header.includes('background job'));
+ok('codexSkillAdapterHeader §D makes background+poll the hard cross-host default for reviews',
+  header.includes('always run this way') && header.includes('hard cross-host default'));
 ok('codexSkillAdapterHeader §F mentions real Codex hooks', header.includes('real Codex hooks'));
 ok('codexSkillAdapterHeader §F no longer says Codex has no hook bus', !header.includes('Codex has no hook bus'));
+ok('codexSkillAdapterHeader §H maps plan-review external-CLI Bash timeout/background onto Codex shell',
+  header.includes('## H.') && header.includes('Cross-AI plan review') && header.includes('run_in_background') && header.includes('shell/exec'));
+ok('codexSkillAdapterHeader §H distinguishes the external-CLI shell path from the §D subagent path',
+  header.includes('external-CLI') && header.includes('not a spawned Codex subagent'));
+ok('codexSkillAdapterHeader §H makes backgrounding reviewers the default',
+  header.includes('the default is to background the reviewers'));
+ok('codexSkillAdapterHeader §H closes reviewer stdin to avoid the EOF hang',
+  header.includes('/dev/null') && header.toLowerCase().includes('stdin'));
 
 // --- codexVerbSkillContent (#46) ---
 ok('codexVerbSkillContent: SKILL.md frontmatter is at byte 0 with name+description', (() => {
@@ -129,11 +143,13 @@ ok('codexVerbSkillPlan: null verbs yields nothing', codexVerbSkillPlan('/c', nul
 
 // --- codexHookEntries ---
 const entries = codexHookEntries('/h');
-ok('codexHookEntries returns 4 entries', Array.isArray(entries) && entries.length === 4);
+ok('codexHookEntries returns 5 entries', Array.isArray(entries) && entries.length === 5);
 ok('codexHookEntries: commit-guard is PreToolUse/Bash', entries.some((e) =>
   e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-commit-guard.js') && e.command.includes('/h')));
 ok('codexHookEntries: secret-guard is PreToolUse/Bash', entries.some((e) =>
   e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-secret-guard.js')));
+ok('codexHookEntries: install-guard is PreToolUse/Bash', entries.some((e) =>
+  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-install-guard.js')));
 ok('codexHookEntries: injection-scanner is PostToolUse/Bash', entries.some((e) =>
   e.event === 'PostToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-issue-injection-scanner.js')));
 ok('codexHookEntries: check-update is SessionStart', entries.some((e) =>
@@ -184,24 +200,110 @@ ok('codexAgentToml without effort omits model_reasoning_effort', (() => {
   });
   return out.includes('model = "gpt-5.6-terra"') && !out.includes('model_reasoning_effort');
 })());
+ok('codexAgentToml with no model emits a pin-less TOML (no model line, no effort line, keeps the rest)', (() => {
+  const out = codexAgentToml({
+    name: 'trailhead-fix',
+    description: 'desc',
+    developerInstructions: 'fix the thing',
+    model: null,
+    effort: null,
+  });
+  return out.includes('name = "trailhead-fix"') &&
+    out.includes('description = "desc"') &&
+    !/^model = /m.test(out) &&
+    !out.includes('model_reasoning_effort') &&
+    out.includes("developer_instructions = '''") &&
+    out.includes('fix the thing');
+})());
+
+ok('codexAgentToml escapes a " and \\ in name/description so the TOML stays valid', (() => {
+  const out = codexAgentToml({
+    name: 'trailhead-plan',
+    description: 'has a "quote" and a back\\slash',
+    developerInstructions: 'body',
+    model: null,
+    effort: null,
+  });
+  // The emitted basic string must carry escaped forms, never a raw " that
+  // would prematurely close the TOML string.
+  return out.includes('description = "has a \\"quote\\" and a back\\\\slash"');
+})());
 
 // --- codexAgentTomlPlan ---
-ok('codexAgentTomlPlan: string value produces one write with the right path/name/model', (() => {
-  const plan = codexAgentTomlPlan('/c', { execute: 'gpt-5.6-terra' });
-  return plan.writes.length === 1 &&
-    plan.writes[0].path === '/c/agents/trailhead-execute.toml' &&
-    plan.writes[0].name === 'trailhead-execute' &&
-    plan.writes[0].content.includes('model = "gpt-5.6-terra"');
-})());
-ok('codexAgentTomlPlan: object value includes model + effort', (() => {
-  const plan = codexAgentTomlPlan('/c', { execute: { model: 'gpt-5.6-sol', effort: 'high' } });
-  const c = plan.writes[0].content;
-  return c.includes('model = "gpt-5.6-sol"') && c.includes('model_reasoning_effort = "high"');
-})());
-ok('codexAgentTomlPlan: empty object -> no writes', codexAgentTomlPlan('/c', {}).writes.length === 0);
-ok('codexAgentTomlPlan: null -> no writes', codexAgentTomlPlan('/c', null).writes.length === 0);
-ok('codexAgentTomlPlan: unknown key skipped', codexAgentTomlPlan('/c', { bogus: 'x' }).writes.length === 0);
-ok('codexAgentTomlPlan: object value with no model is skipped', codexAgentTomlPlan('/c', { execute: { effort: 'high' } }).writes.length === 0);
+// 7-entry stub agentDefs mirroring the real plugins/trailhead/agents/*.md
+// sources: 5 keyed techniques (plan/execute/research/review/debug, whose
+// filenames derive from trailhead-executor -> execute and
+// trailhead-code-review -> review) + 2 always-keyless agents.
+const STUB_AGENT_DEFS = [
+  { name: 'trailhead-plan', description: 'plan desc', tools: 'Read', body: 'Plan body.' },
+  { name: 'trailhead-executor', description: 'execute desc', tools: 'Read, Write', body: 'Execute body.' },
+  { name: 'trailhead-research', description: 'research desc', tools: 'Read', body: 'Research body.' },
+  { name: 'trailhead-code-review', description: 'review desc', tools: 'Read', body: 'Review body.' },
+  { name: 'trailhead-debug', description: 'debug desc', tools: 'Read', body: 'Debug body.' },
+  { name: 'trailhead-fix', description: 'fix desc', tools: 'Read, Write', body: 'Fix body.' },
+  { name: 'trailhead-codebase-map', description: 'map desc', tools: 'Read', body: 'Map body.' },
+];
+
+ok('codexAgentTomlPlan: 7 agentDefs -> 7 writes with only the pinned key carrying a model', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
+  if (plan.writes.length !== 7) return false;
+  const byName = Object.fromEntries(plan.writes.map((w) => [w.name, w]));
+  const execute = byName['trailhead-execute'];
+  if (!execute || execute.path !== '/c/agents/trailhead-execute.toml') return false;
+  if (!execute.content.includes('model = "gpt-5.6-terra"')) return false;
+  const others = plan.writes.filter((w) => w.name !== 'trailhead-execute');
+  return others.length === 6 && others.every((w) => !/^model = /m.test(w.content));
+})());
+
+ok('codexAgentTomlPlan: keyless trailhead-fix / trailhead-codebase-map are always pin-less', (() => {
+  const plan = codexAgentTomlPlan('/c', { fix: 'gpt-5.6-terra', 'codebase-map': 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
+  const byName = Object.fromEntries(plan.writes.map((w) => [w.name, w]));
+  const fix = byName['trailhead-fix'];
+  const map = byName['trailhead-codebase-map'];
+  return fix && map &&
+    fix.path === '/c/agents/trailhead-fix.toml' && !/^model = /m.test(fix.content) &&
+    map.path === '/c/agents/trailhead-codebase-map.toml' && !/^model = /m.test(map.content);
+})());
+
+ok('codexAgentTomlPlan: empty models object -> 7 pin-less writes (not zero)', (() => {
+  const plan = codexAgentTomlPlan('/c', {}, STUB_AGENT_DEFS);
+  return plan.writes.length === 7 && plan.writes.every((w) => !/^model = /m.test(w.content));
+})());
+
+ok('codexAgentTomlPlan: null models -> 7 pin-less writes (not zero)', (() => {
+  const plan = codexAgentTomlPlan('/c', null, STUB_AGENT_DEFS);
+  return plan.writes.length === 7 && plan.writes.every((w) => !/^model = /m.test(w.content));
+})());
+
+ok('codexAgentTomlPlan: object model value on the execute key carries model + model_reasoning_effort', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: { model: 'gpt-5.6-sol', effort: 'high' } }, STUB_AGENT_DEFS);
+  const execute = plan.writes.find((w) => w.name === 'trailhead-execute');
+  return execute.content.includes('model = "gpt-5.6-sol"') && execute.content.includes('model_reasoning_effort = "high"');
+})());
+
+ok('codexAgentTomlPlan: a keyed key whose object value has no model stays pin-less', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: { effort: 'high' } }, STUB_AGENT_DEFS);
+  const execute = plan.writes.find((w) => w.name === 'trailhead-execute');
+  return plan.writes.length === 7 && !/^model = /m.test(execute.content) && !execute.content.includes('model_reasoning_effort');
+})());
+
+ok('codexAgentTomlPlan: description is routed through convertToCodex (host paths rewritten)', (() => {
+  const defs = [{ name: 'trailhead-plan', description: 'see ~/.claude/skills', tools: 'Read', body: 'b' }];
+  const plan = codexAgentTomlPlan('/c', {}, defs);
+  return plan.writes[0].content.includes('description = "see ~/.codex/skills"');
+})());
+
+ok('codexAgentTomlPlan: a missing description renders as an empty string, not "undefined"', (() => {
+  const defs = [{ name: 'trailhead-plan', tools: 'Read', body: 'b' }];
+  const plan = codexAgentTomlPlan('/c', {}, defs);
+  return plan.writes[0].content.includes('description = ""') && !plan.writes[0].content.includes('description = "undefined"');
+})());
+
+ok('codexAgentTomlPlan: empty/undefined agentDefs -> no writes (installer then leaves multi_agent_v2 off)', (() => {
+  return codexAgentTomlPlan('/c', {}, []).writes.length === 0 &&
+    codexAgentTomlPlan('/c', {}).writes.length === 0 &&
+    codexAgentTomlPlan('/c', {}, null).writes.length === 0;
+})());
 
 // --- enableCodexMultiAgentV2Feature ---
 ok('enableCodexMultiAgentV2Feature: dotted form already true -> null',

package/bin/trailhead.js

@@ -23,10 +23,41 @@ const readline = require('readline');
 const { spawnSync } = require('child_process');
 
 const { getHost, configDirFor, codexVersionGate } = require('./lib/host-descriptor.js');
-const { codexLayout, convertToCodex, injectCodexAdapterHeader, codexAgentsYaml, codexHookEntries, enableCodexHooksFeature, codexAgentTomlPlan, codexVerbSkillPlan, enableCodexMultiAgentV2Feature } = require('./lib/codex-projection.js');
+const { codexLayout, convertToCodex, injectCodexAdapterHeader, codexAgentsYaml, codexClusterAgentsYaml, codexHookEntries, enableCodexHooksFeature, codexAgentTomlPlan, codexVerbSkillPlan, enableCodexMultiAgentV2Feature } = require('./lib/codex-projection.js');
 
 const PKG = path.resolve(__dirname, '..');
 const SRC = path.join(PKG, 'plugins', 'trailhead');
+
+// Enumerate the engine skill dirs shipped under plugins/trailhead/skills: the
+// dispatcher, the cluster skills, and the shared core. A subdir qualifies when
+// it is `_shared` (the shared core, no SKILL.md) or contains a SKILL.md, so a
+// stray empty dir is skipped and a new cluster is picked up automatically.
+function engineSkillDirs() {
+  const skillsRoot = path.join(SRC, 'skills');
+  if (!fs.existsSync(skillsRoot)) return [];
+  return fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => name === '_shared' || fs.existsSync(path.join(skillsRoot, name, 'SKILL.md')))
+    .sort();
+}
+
+// Sweep every trailhead-owned skill dir under a skills root, by name: the
+// dispatcher (`trailhead`), the shared core (`_shared`), and every
+// `trailhead-<cluster|verb>` sibling. Clears a prior layout's stale dirs (an
+// old monolith fallback, a removed cluster, a renamed verb skill) the current
+// install no longer ships, so a re-install or /trailhead:update never leaves a
+// dangling skill. The skills root is shared with other plugins, so only
+// trailhead's own names are touched, never the whole dir.
+function sweepTrailheadSkills(skillsRoot) {
+  rmrf(path.join(skillsRoot, 'trailhead'));
+  rmrf(path.join(skillsRoot, '_shared'));
+  if (!fs.existsSync(skillsRoot)) return;
+  for (const f of fs.readdirSync(skillsRoot)) {
+    if (f.startsWith('trailhead-')) rmrf(path.join(skillsRoot, f));
+  }
+}
+
 const args = process.argv.slice(2);
 const has = (f) => args.includes(f);
 const useSymlink = has('--symlink');
@@ -138,14 +169,14 @@ async function resolveHostName() {
 // --- Claude adapter (unchanged behaviour) -----------------------------------
 function claudePaths(configDir) {
   return {
-    skill: path.join(configDir, 'skills', 'trailhead'),
     commands: path.join(configDir, 'commands', 'trailhead'),
     hooksDir: path.join(configDir, 'hooks'),
     templates: path.join(configDir, 'trailhead', 'templates'),
+    agents: path.join(configDir, 'agents'),
     settings: path.join(configDir, 'settings.json'),
   };
 }
-const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-check-update.js'];
+const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-check-update.js'];
 // Runtime libs the hook scripts require (trailhead-commit-guard.js does
 // require('./lib/commit-message-check.js')). Copied by name, never a recursive
 // sweep: the Claude hooks/lib dir is shared with other plugins, so we must not
@@ -155,18 +186,28 @@ const HOOK_LIB_FILES = ['commit-message-check.js'];
 // Copy the hook scripts and their runtime libs into a destination hooks dir
 // (Claude's ~/.claude/hooks or Codex's skills/trailhead/hooks). Shared by both
 // install paths so the lib copy can never drift from the script copy again.
-function copyHookScripts(destHooksDir) {
+// Place the allow-listed hook scripts into destHooksDir. Normal install copies
+// (+chmod so the exec bit is set regardless of the source mode); a --symlink dev
+// install links each file per-file into the package source so hook edits are
+// live too, matching skills/commands. Never symlink the whole hooks/ dir: it is
+// shared with other plugins, so only the curated allowlist is touched. rmrf the
+// dest first so a reinstall over an existing file or symlink never hits EEXIST.
+function copyHookScripts(destHooksDir, { useSymlink = false } = {}) {
   ensure(destHooksDir);
-  for (const f of HOOK_FILES) {
-    fs.copyFileSync(path.join(SRC, 'hooks', f), path.join(destHooksDir, f));
-    fs.chmodSync(path.join(destHooksDir, f), 0o755);
-  }
+  const put = (src, dest) => {
+    rmrf(dest);
+    if (useSymlink) {
+      fs.symlinkSync(src, dest, 'file');
+    } else {
+      fs.copyFileSync(src, dest);
+      fs.chmodSync(dest, 0o755);
+    }
+  };
+  for (const f of HOOK_FILES) put(path.join(SRC, 'hooks', f), path.join(destHooksDir, f));
   if (HOOK_LIB_FILES.length) {
     const libDest = path.join(destHooksDir, 'lib');
     ensure(libDest);
-    for (const f of HOOK_LIB_FILES) {
-      fs.copyFileSync(path.join(SRC, 'hooks', 'lib', f), path.join(libDest, f));
-    }
+    for (const f of HOOK_LIB_FILES) put(path.join(SRC, 'hooks', 'lib', f), path.join(libDest, f));
   }
 }
 
@@ -177,6 +218,43 @@ function place(src, dest, symlink) {
   else fs.cpSync(src, dest, { recursive: true });
 }
 
+// The committed engine agents (plugins/trailhead/agents/trailhead-*.md). On a
+// Claude install they must register as user subagent types under
+// <configDir>/agents/, so the engine can dispatch each technique to its
+// trailhead-<technique> agent and honour config.models.<key>; without them
+// every technique falls back to running inline on the session model (the
+// per-technique model split silently never applies). The agents dir is shared
+// with the user's own agents and other plugins, so touch trailhead's own files
+// by name only, never the whole dir (mirrors the skills/hooks discipline).
+function agentFileNames() {
+  const dir = path.join(SRC, 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.startsWith('trailhead-') && f.endsWith('.md'));
+}
+function sweepTrailheadAgents(agentsDir) {
+  if (!fs.existsSync(agentsDir)) return;
+  for (const f of fs.readdirSync(agentsDir)) {
+    if (f.startsWith('trailhead-') && f.endsWith('.md')) rmrf(path.join(agentsDir, f));
+  }
+}
+// Place the engine agents into destAgentsDir by name (copy, or per-file symlink
+// under a --symlink dev install so agent edits are live). Returns the names
+// placed. rmrf each dest first so a reinstall over a file or symlink never
+// hits EEXIST.
+function copyAgentFiles(destAgentsDir, { useSymlink = false } = {}) {
+  const names = agentFileNames();
+  if (!names.length) return names;
+  ensure(destAgentsDir);
+  for (const f of names) {
+    const src = path.join(SRC, 'agents', f);
+    const dest = path.join(destAgentsDir, f);
+    rmrf(dest);
+    if (useSymlink) fs.symlinkSync(src, dest, 'file');
+    else fs.copyFileSync(src, dest);
+  }
+  return names;
+}
+
 function addHook(s, event, matcher, command) {
   s.hooks = s.hooks || {};
   s.hooks[event] = s.hooks[event] || [];
@@ -195,7 +273,13 @@ function stripHook(s, event, substr) {
 
 function uninstallClaude(configDir) {
   const P = claudePaths(configDir);
-  [P.skill, P.commands, path.join(configDir, 'trailhead')].forEach(rmrf);
+  // Sweep every trailhead-owned skill dir (current set + any stale dir a prior
+  // layout left that this package no longer ships), never the shared dir itself.
+  sweepTrailheadSkills(path.join(configDir, 'skills'));
+  [P.commands, path.join(configDir, 'trailhead')].forEach(rmrf);
+  // Remove trailhead's own agents by name; the agents dir is shared, so never
+  // rmrf the whole dir (same discipline as skills/hooks).
+  sweepTrailheadAgents(P.agents);
   HOOK_FILES.forEach((f) => rmrf(path.join(P.hooksDir, f)));
   // Remove only trailhead's own lib files by name: the hooks/lib dir is shared
   // with other plugins, so never rmrf the whole dir.
@@ -203,6 +287,7 @@ function uninstallClaude(configDir) {
   const s = readJSON(P.settings);
   stripHook(s, 'PreToolUse', 'trailhead-commit-guard.js');
   stripHook(s, 'PreToolUse', 'trailhead-secret-guard.js');
+  stripHook(s, 'PreToolUse', 'trailhead-install-guard.js');
   stripHook(s, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
   stripHook(s, 'SessionStart', 'trailhead-check-update.js');
   writeJSON(P.settings, s);
@@ -213,10 +298,29 @@ function installClaude(configDir, { useSymlink }) {
   const P = claudePaths(configDir);
   const hookCmd = (name) => `node "${path.join(P.hooksDir, name)}"`;
 
-  place(path.join(SRC, 'skills', 'trailhead'), P.skill, useSymlink);
+  // Place each engine skill dir as a sibling under configDir/skills so the
+  // ../_shared/ and ../trailhead-<cluster>/ relative refs resolve. The skills
+  // dir is shared with other plugins: place by name, never touch the whole dir.
+  // Migration: sweep any stale trailhead-owned skill dirs from a prior layout
+  // (an old monolith, a removed cluster) before laying the current set down, so
+  // an update over an old install leaves no dangling skill. The skills dir is
+  // shared with other plugins: place by name, never touch the whole dir.
+  const skillDirs = engineSkillDirs();
+  sweepTrailheadSkills(path.join(configDir, 'skills'));
+  for (const name of skillDirs) {
+    place(path.join(SRC, 'skills', name), path.join(configDir, 'skills', name), useSymlink);
+  }
   place(path.join(SRC, 'commands'), P.commands, useSymlink);
   place(path.join(SRC, 'templates'), P.templates, useSymlink);
-  copyHookScripts(P.hooksDir);
+  copyHookScripts(P.hooksDir, { useSymlink });
+  // Register the engine agents as Claude subagents: sweep any stale
+  // trailhead-*.md first (a removed/renamed agent), then place the current set
+  // by name. This is what makes config.models.<key> take effect on the
+  // skills/npm channel; without it every technique runs inline (see
+  // agentFileNames above). The agents dir is shared, so only our names are
+  // touched.
+  sweepTrailheadAgents(P.agents);
+  const agentFiles = copyAgentFiles(P.agents, { useSymlink });
   // version marker: serve al check-update hook per la versione installata (canale npm)
   const pkgVersion = (readJSON(path.join(SRC, '.claude-plugin', 'plugin.json')).version || '').trim();
   if (pkgVersion) {
@@ -228,14 +332,16 @@ function installClaude(configDir, { useSymlink }) {
   const added = [
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-commit-guard.js')),
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-secret-guard.js')),
+    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-install-guard.js')),
     addHook(s, 'PostToolUse', 'Bash', hookCmd('trailhead-issue-injection-scanner.js')),
     addHook(s, 'SessionStart', '', hookCmd('trailhead-check-update.js')),
   ].some(Boolean);
   writeJSON(P.settings, s);
 
   console.log(`✓ trailhead installed for Claude Code → ${configDir}`);
-  console.log(`  skill     → ${P.skill}${useSymlink ? '  (symlink)' : ''}`);
+  console.log(`  skills    → ${path.join(configDir, 'skills')}/  (${skillDirs.join(', ')})${useSymlink ? '  (symlink)' : ''}`);
   console.log(`  commands  → ${P.commands}  (/trailhead:*)`);
+  console.log(`  agents    → ${P.agents}/  (${agentFiles.length} agent(s): trailhead-*)${useSymlink ? '  (symlink)' : ''}`);
   console.log(`  hooks     → ${P.hooksDir}/  (${added ? 'registered' : 'already present'} in settings.json)`);
   console.log(`  templates → ${P.templates}`);
   console.log('\nRestart or reload your agent to pick up the commands, then run /trailhead to start.');
@@ -295,6 +401,39 @@ function readCommandVerbs() {
     .sort((a, b) => a.verb.localeCompare(b.verb));
 }
 
+// Unquote a YAML double-quoted scalar (unlike commands/*.md, the agent .md
+// frontmatter wraps `description:` in double quotes). Leaves a plain/
+// unquoted scalar untouched, so this is safe to apply unconditionally.
+function unquoteYamlScalar(v) {
+  if (typeof v !== 'string' || v.length < 2 || v[0] !== '"' || v[v.length - 1] !== '"') return v;
+  return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+
+// Read the 7 committed agent sources from plugins/trailhead/agents/*.md: each
+// file's basename is the agent's name; frontmatter description/tools ride
+// along, and `body` is the markdown after the closing frontmatter `---`.
+// Single-sources the Codex agent-TOML projection so it never drifts from the
+// committed agent prose. Mirrors readCommandVerbs's shape. Pure fs; kept out
+// of codex-projection.js, which must stay fs-free.
+function readAgentDefs() {
+  const dir = path.join(SRC, 'agents');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.startsWith('trailhead-') && f.endsWith('.md'))
+    .map((f) => {
+      const raw = fs.readFileSync(path.join(dir, f), 'utf8');
+      const fm = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/.exec(raw);
+      const body = fm ? raw.slice(fm[0].length) : raw;
+      return {
+        name: f.slice(0, -3),
+        description: unquoteYamlScalar(fmValue(raw, 'description')),
+        tools: fmValue(raw, 'tools'),
+        body,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
 // Extract one frontmatter scalar's raw value verbatim (an already-valid YAML
 // scalar re-serialises unchanged). Looks only inside the leading ---...--- block.
 // Returns undefined when the key is absent or its value is empty.
@@ -333,7 +472,7 @@ function installCodex(configDir, { useSymlink }) {
   const L = codexLayout(configDir);
 
   if (useSymlink) {
-    console.log('Note: symlink install is unavailable for Codex (artifacts are generated, not copied verbatim); installing copies instead.');
+    console.log('Note: on Codex, --symlink links the verbatim artifacts (hooks, templates) into the package source for live edits; the skill files are text-converted at install, so they are written (projected), not linked.');
   }
 
   // Migration: sweep the pre-#25 layout AND the #42 prompt shims that never
@@ -346,31 +485,44 @@ function installCodex(configDir, { useSymlink }) {
   }
   rmrf(L.legacyEngineDir);
 
-  // Engine: clean skill dir, then project with conversion.
-  rmrf(L.skillDir);
-  ensure(L.skillDir);
-  copySkillConverted(path.join(SRC, 'skills', 'trailhead'), L.skillDir, true);
+  // Sweep the whole engine + any prior per-verb skills, then project fresh.
+  sweepTrailheadSkills(L.skillsRoot);
+
+  // Project each engine skill dir (dispatcher + 5 clusters + _shared) as a
+  // sibling under skills/, converting text and injecting the adapter header into
+  // each top-level SKILL.md. The ../_shared/ relative refs survive conversion and
+  // resolve as siblings (decision #54). _shared has no SKILL.md, so no header.
+  const engineDirs = engineSkillDirs();
+  for (const name of engineDirs) {
+    copySkillConverted(path.join(SRC, 'skills', name), path.join(L.skillsRoot, name), true);
+  }
 
   // Templates (verbatim, never converted), bundled inside the skill dir so
   // ${CLAUDE_PLUGIN_ROOT}/templates resolves to ~/.codex/skills/trailhead/templates.
-  ensure(L.templatesDir);
-  fs.cpSync(path.join(SRC, 'templates'), L.templatesDir, { recursive: true });
+  place(path.join(SRC, 'templates'), L.templatesDir, useSymlink);
 
   // agents/openai.yaml: UI metadata + explicit-only invocation (no auto-trigger).
   ensure(L.agentsDir);
   fs.writeFileSync(L.agentsYaml, codexAgentsYaml());
+  // Each cluster skill also gets explicit-only UI metadata (never auto-invoked).
+  for (const name of engineDirs) {
+    if (name === 'trailhead' || name === '_shared') continue;
+    const dir = path.join(L.skillsRoot, name, 'agents');
+    ensure(dir);
+    fs.writeFileSync(path.join(dir, 'openai.yaml'), codexClusterAgentsYaml(name));
+  }
 
   // Per-verb discoverability (#46): one thin Codex skill per verb
   // (skills/trailhead-<verb>/, invocable as $trailhead-<verb>), each delegating
   // to $trailhead <verb>. Codex custom prompts (~/.codex/prompts/) never surface
   // as slash commands, so per-verb skills carry the surface, exactly as GSD does.
-  // Sweep stale trailhead-* verb skills first (a removed verb, or an upgrade from
-  // the old prompt-shim layout), never the main skills/trailhead. Verbs come from
-  // the canonical commands/*.md so the surfaces never drift.
-  for (const f of (fs.existsSync(L.skillsRoot) ? fs.readdirSync(L.skillsRoot) : [])) {
-    if (f.startsWith('trailhead-')) rmrf(path.join(L.skillsRoot, f));
-  }
-  const verbSkillPlan = codexVerbSkillPlan(configDir, readCommandVerbs());
+  // Verbs come from the canonical commands/*.md so the surfaces never drift.
+  // Skip any verb whose skill dir would collide with a projected cluster skill
+  // (e.g. verb `work` vs the trailhead-work cluster): the cluster skill is its
+  // own $trailhead-<name> entry. Compute the skip-set from the projected dirs.
+  const clusterDirNames = new Set(engineDirs);
+  const verbList = readCommandVerbs().filter((c) => !clusterDirNames.has(`trailhead-${c.verb}`));
+  const verbSkillPlan = codexVerbSkillPlan(configDir, verbList);
   for (const d of verbSkillPlan.dirs) ensure(path.join(d, 'agents'));
   for (const w of verbSkillPlan.writes) fs.writeFileSync(w.path, w.content);
 
@@ -379,7 +531,7 @@ function installCodex(configDir, { useSymlink }) {
 
   // Hooks: copy the 4 guard scripts into the skill dir and register them in
   // ~/.codex/hooks.json (same shape as Claude's settings.json hooks block).
-  copyHookScripts(L.hooksScriptsDir);
+  copyHookScripts(L.hooksScriptsDir, { useSymlink });
   const h = readJSON(L.hooksJson);
   for (const e of codexHookEntries(L.hooksScriptsDir)) addHook(h, e.event, e.matcher, e.command);
   writeJSON(L.hooksJson, h);
@@ -397,9 +549,13 @@ function installCodex(configDir, { useSymlink }) {
     featureManual = true;
   }
 
-  // Per-technique model pins: project models.codex.* (merged project + global
-  // config) into trailhead-<technique>.toml under the real ~/.codex/agents/
-  // dir. Sweep only trailhead's own files first, so a stale pin from a prior
+  // Per-technique agent registry: project ALL 7 committed agents
+  // (readAgentDefs, sourced from plugins/trailhead/agents/*.md) as
+  // trailhead-<technique>.toml under the real ~/.codex/agents/ dir, uniformly.
+  // A keyed technique (plan/execute/research/review/debug) carries its
+  // models.codex.<key> pin (merged project + global config) when set, else is
+  // pin-less; the 2 keyless agents (fix, codebase-map) are always pin-less.
+  // Sweep only trailhead's own files first, so a stale pin from a prior
   // install (or a removed technique) never lingers, without touching the
   // user's other custom-agent TOMLs.
   const codexModels = readCodexModels(configDir);
@@ -407,16 +563,15 @@ function installCodex(configDir, { useSymlink }) {
   for (const f of fs.readdirSync(L.codexAgentsDir)) {
     if (/^trailhead-.*\.toml$/.test(f)) rmrf(path.join(L.codexAgentsDir, f));
   }
-  const plan = codexAgentTomlPlan(configDir, codexModels);
+  const plan = codexAgentTomlPlan(configDir, codexModels, readAgentDefs());
   for (const w of plan.writes) fs.writeFileSync(w.path, w.content);
 
   // Feature flag: Codex gates per-subagent model pinning behind
-  // features.multi_agent_v2 = true. Enable it ONLY when we actually projected
-  // pins: with no models.codex.* set, base multi_agent already fans out and the
-  // adapter's §D runtime detection expects no trailhead agent_type registry, so
-  // leaving v2 off keeps that contract sound. (A reinstall that drops all pins
-  // sweeps the TOMLs above but leaves any prior v2 flag in place; harmless, as
-  // no trailhead-* agents remain for the runtime to dispatch to.)
+  // features.multi_agent_v2 = true. All 7 agent TOMLs are normally projected
+  // (pinned or pin-less), so v2 is enabled on every healthy Codex install: the
+  // adapter's §D runtime detection expects a trailhead agent_type registry,
+  // pins or not. Still guarded on writes so a degenerate case (no agent .md
+  // found, zero writes) never flips the flag on with an empty registry.
   let featureManualV2 = false;
   if (plan.writes.length > 0) {
     const updatedTomlV2 = enableCodexMultiAgentV2Feature(current);
@@ -433,17 +588,19 @@ function installCodex(configDir, { useSymlink }) {
   console.log(`  templates → ${L.templatesDir}/`);
   console.log(`  verb skills → ${L.skillsRoot}/trailhead-<verb>/  (${verbSkillPlan.dirs.length} discoverability skills: invoke $trailhead-<verb>)`);
   console.log(`  hooks     → ${L.hooksScriptsDir}/  (registered in hooks.json)`);
-  if (plan.writes.length > 0) {
-    console.log(`  agents    → ${L.codexAgentsDir}/  (${plan.writes.length} model pin(s): ${plan.writes.map((w) => w.name + '.toml').join(', ')})`);
-  } else {
-    console.log('  agents    → no models.codex.* set, subagents inherit the session model');
+  {
+    const pinned = plan.writes.filter((w) => w.content.includes('\nmodel = '));
+    const pinsNote = pinned.length > 0
+      ? `${pinned.length} pinned: ${pinned.map((w) => w.name + '.toml').join(', ')}`
+      : 'no models.codex.* set, all pin-less (session model)';
+    console.log(`  agents    → ${L.codexAgentsDir}/  (${plan.writes.length} agent(s) projected; ${pinsNote})`);
   }
   console.log('\nRestart or reload Codex to pick up the skill, then run $trailhead to start.');
   // The trust prompt only fires once the feature flag is on. When we could not
   // edit config.toml, the hooks stay inert until the user sets it by hand, so
   // don't reassure them about a trust review that won't happen yet.
   if (featureManual) {
-    console.log(`  ⚠ could not edit ${L.configToml} automatically — add \`features.hooks = true\` under [features] by hand, then Codex will ask you to trust trailhead's hooks on next start.`);
+    console.log(`  ⚠ could not edit ${L.configToml} automatically; add \`features.hooks = true\` under [features] by hand, then Codex will ask you to trust trailhead's hooks on next start.`);
   } else {
     console.log('Note: Codex will ask you to trust trailhead\'s hooks on next start (feature `features.hooks`).');
   }
@@ -454,12 +611,8 @@ function installCodex(configDir, { useSymlink }) {
 
 function uninstallCodex(configDir) {
   const L = codexLayout(configDir);
-  rmrf(L.skillDir);
-  // sweep the per-verb discoverability skills (skills/trailhead-<verb>/, #46),
-  // never the main skills/trailhead (already removed above; does not match).
-  for (const f of (fs.existsSync(L.skillsRoot) ? fs.readdirSync(L.skillsRoot) : [])) {
-    if (f.startsWith('trailhead-')) rmrf(path.join(L.skillsRoot, f));
-  }
+  // Sweep the dispatcher, _shared, the clusters, and the per-verb skills.
+  sweepTrailheadSkills(L.skillsRoot);
   // sweep any pre-#25 layout AND the #42 prompt shims from prompts/
   rmrf(path.join(L.promptsDir, 'trailhead.md'));
   for (const f of (fs.existsSync(L.promptsDir) ? fs.readdirSync(L.promptsDir) : [])) {
@@ -482,6 +635,7 @@ function uninstallCodex(configDir) {
     const h = readJSON(L.hooksJson);
     stripHook(h, 'PreToolUse', 'trailhead-commit-guard.js');
     stripHook(h, 'PreToolUse', 'trailhead-secret-guard.js');
+    stripHook(h, 'PreToolUse', 'trailhead-install-guard.js');
     stripHook(h, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
     stripHook(h, 'SessionStart', 'trailhead-check-update.js');
     writeJSON(L.hooksJson, h);