create-byan-agent 2.41.0 → 2.42.0

package/CHANGELOG.md

@@ -9,6 +9,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.42.0] - 2026-07-06
+
+### Fixed - Shipped Claude Code hooks no longer spam MODULE_NOT_FOUND
+- **Every hook command in the shipped `.claude/settings.json` is now
+  self-guarded.** The hooks run on every tool (empty matcher); a bare
+  `node "$CLAUDE_PROJECT_DIR"/.claude/hooks/X.js` threw `MODULE_NOT_FOUND` on
+  every tool call whenever the script was not resolvable — a non-BYAN project, an
+  empty `$CLAUDE_PROJECT_DIR`, a partial install, or version drift. Each command
+  is now `p="$CLAUDE_PROJECT_DIR/.claude/hooks/X.js"; [ -f "$p" ] || exit 0; exec
+  node "$p"`: a missing script no-ops with exit 0 (the tool proceeds), a present
+  script runs via `exec` so its exit code is preserved (a blocking PreToolUse /
+  Stop guard still blocks). Covered by
+  `install/__tests__/hook-invocation-guard.test.js` (guarded-shape on all 24
+  commands + runtime sh simulation: absent/empty -> 0, blocker -> 2, stdin
+  passthrough).
+
+### Changed - Handoff auto-import instructions
+- **Claude and Codex activation surfaces now know how to handle
+  `importe depuis claude` / `importe depuis codex` automatically.** `CLAUDE.md`
+  and BYAN skills instruct the assistant to run
+  `byan-handoff latest --from <source> --prompt` and resume from the generated
+  context without relying on native assistant memory.
+
+### Added - Portable Claude/Codex Markdown handoff
+- **BYAN can now export/import project state as a portable Markdown handoff for
+  switching between Claude Code and Codex.** The new `byan-handoff` CLI writes
+  handoffs under `_byan-output/handoffs/`, embeds a parseable
+  `json byan-handoff` block, and can print a compact resume prompt via
+  `byan-handoff latest --from <source> --prompt` or
+  `byan-handoff import <file> --prompt`.
+  A new `project-handoff` BYAN workflow documents the limit-switch protocol.
+  Covered by `install/__tests__/project-handoff.test.js`.
+
+### Changed - RTK offered on Codex-selected installs
+- **Yanstaller now offers RTK when the selected target includes Codex, not only
+  Claude Code.** Claude Code keeps the transparent `rtk init -g --auto-patch`
+  hook path. Codex installs get the verified native `rtk` binary and an explicit
+  no-transparent-hook status, matching BYAN's current Codex adapter model.
+  Covered by `install/__tests__/rtk-integration.test.js`.
+
+### Added - Codex native skills in yanstaller
+- **Codex installs now get real native skills, not just project prompt stubs.**
+  When the yanstaller target includes Codex (Codex-only or Claude+Codex), it
+  writes the BYAN MCP entry to `~/.codex/config.toml` and copies BYAN skill
+  folders into `~/.codex/skills`, creating `~/.codex` when Codex was explicitly
+  selected. The project template also ships `.codex/skills/byan/SKILL.md`, so a
+  fresh Codex install has a native skill named `byan` in addition to the
+  Claude-derived BYAN specialty skills. This closes the gap where a fresh
+  machine had `.codex/prompts/` and MCP wiring but no native `$byan` / BYAN skill
+  surface for delegation. Covered by `install/__tests__/codex-native-setup.test.js`.
+
 ### Added - Codex auto-delegation (opt-in, native)
 - **BYAN now proposes handing delegable work to Codex on your ChatGPT
   subscription (no API credit) when Claude nears its 5h limit.** A

package/install/bin/byan-handoff.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  buildHandoff,
+  latestHandoff,
+  parseMarkdown,
+  renderMarkdown,
+  renderResumePrompt,
+  writeHandoff,
+} = require('../lib/project-handoff');
+
+function usage() {
+  return [
+    'byan-handoff export [--from claude|codex] [--to codex|claude] [--task <text>] [--summary <text>] [--next <text>] [--out <file>] [--root <dir>] [--stdout]',
+    'byan-handoff import <file> [--prompt] [--json] [--root <dir>]',
+    'byan-handoff latest [--from claude|codex] [--prompt] [--json] [--root <dir>]',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const args = {
+    cmd: argv[2] || 'export',
+    root: process.cwd(),
+    from: null,
+    to: null,
+    task: null,
+    summary: null,
+    out: null,
+    stdout: false,
+    prompt: false,
+    json: false,
+    next: [],
+    decisions: [],
+    blockers: [],
+    commands: [],
+    notes: [],
+    file: null,
+  };
+
+  for (let i = 3; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--root') args.root = argv[++i];
+    else if (a === '--from') args.from = argv[++i];
+    else if (a === '--to') args.to = argv[++i];
+    else if (a === '--task') args.task = argv[++i];
+    else if (a === '--summary') args.summary = argv[++i];
+    else if (a === '--out') args.out = argv[++i];
+    else if (a === '--stdout') args.stdout = true;
+    else if (a === '--prompt') args.prompt = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--next') args.next.push(argv[++i]);
+    else if (a === '--decision') args.decisions.push(argv[++i]);
+    else if (a === '--blocker') args.blockers.push(argv[++i]);
+    else if (a === '--command') args.commands.push(argv[++i]);
+    else if (a === '--note') args.notes.push(argv[++i]);
+    else if (a === '-h' || a === '--help') args.help = true;
+    else if (!args.file) args.file = a;
+    else throw new Error(`Unexpected argument: ${a}`);
+  }
+  return args;
+}
+
+function readHandoffFile(file) {
+  return parseMarkdown(fs.readFileSync(file, 'utf8'));
+}
+
+function printImported(handoff, args) {
+  if (args.json) {
+    process.stdout.write(JSON.stringify(handoff, null, 2) + '\n');
+  } else if (args.prompt) {
+    process.stdout.write(renderResumePrompt(handoff) + '\n');
+  } else {
+    process.stdout.write(renderMarkdown(handoff) + '\n');
+  }
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv);
+    if (args.help) {
+      console.log(usage());
+      return;
+    }
+
+    const root = path.resolve(args.root);
+    if (args.cmd === 'export') {
+      const handoff = buildHandoff({
+        root,
+        from: args.from,
+        to: args.to,
+        task: args.task,
+        summary: args.summary,
+        nextActions: args.next,
+        decisions: args.decisions,
+        blockers: args.blockers,
+        commands: args.commands,
+        notes: args.notes,
+      });
+      if (args.stdout) {
+        process.stdout.write(renderMarkdown(handoff) + '\n');
+        return;
+      }
+      const result = writeHandoff(root, handoff, { outPath: args.out });
+      process.stdout.write(`${result.path}\n`);
+      return;
+    }
+
+    if (args.cmd === 'import') {
+      if (!args.file) throw new Error('Missing handoff file');
+      printImported(readHandoffFile(path.resolve(root, args.file)), args);
+      return;
+    }
+
+    if (args.cmd === 'latest') {
+      const file = latestHandoff(root, { from: args.from });
+      if (!file) {
+        const suffix = args.from ? ` from ${args.from}` : '';
+        throw new Error(`No handoff${suffix} found under _byan-output/handoffs`);
+      }
+      if (!args.prompt && !args.json) {
+        process.stdout.write(`${file}\n`);
+        return;
+      }
+      printImported(readHandoffFile(file), args);
+      return;
+    }
+
+    throw new Error(`Unknown command: ${args.cmd}`);
+  } catch (err) {
+    process.stderr.write(`byan-handoff: ${err.message}\n`);
+    process.stderr.write(usage() + '\n');
+    process.exit(1);
+  }
+}
+
+main();

package/install/bin/create-byan-agent-v2.js

@@ -1324,14 +1324,14 @@ async function install(options = {}) {
 
   if (needsCodex) {
     console.log();
-    console.log(chalk.cyan('Codex CLI MCP setup (~/.codex/config.toml)'));
+    console.log(chalk.cyan('Codex CLI native setup (~/.codex/config.toml + ~/.codex/skills)'));
     try {
-      await setupCodexNative(projectRoot);
+      await setupCodexNative(projectRoot, { templateDir, force: true });
     } catch (error) {
-      console.log(chalk.red(`  ✘ Codex MCP setup failed: ${error.message}`));
+      console.log(chalk.red(`  ✘ Codex native setup failed: ${error.message}`));
       console.log(
         chalk.yellow(
-          `    → Edit ~/.codex/config.toml manually to add the byan MCP entry.`
+          `    → Edit ~/.codex/config.toml manually to add the byan MCP entry, then copy BYAN skills into ~/.codex/skills.`
         )
       );
     }
@@ -1426,26 +1426,47 @@ async function install(options = {}) {
     }
   }
 
-  if (needsClaude && shouldOfferRtk()) {
+  if ((needsClaude || needsCodex) && shouldOfferRtk()) {
     console.log();
     console.log(chalk.cyan('RTK token optimizer (optional — Rust binary, cuts dev-command tokens 60-90%)'));
     try {
+      const rtkTargets = [
+        ...(needsClaude ? ['claude'] : []),
+        ...(needsCodex ? ['codex'] : []),
+      ];
+      const rtkMessage = needsClaude && needsCodex
+        ? 'Install rtk now? Runs its official installer, adds the GLOBAL Claude Code hook via `rtk init -g --auto-patch`, and makes the native rtk binary available for Codex (no transparent Codex hook).'
+        : needsClaude
+          ? 'Install rtk now? Runs its official installer (brew/cargo, or a pinned curl|sh) and adds a GLOBAL Claude Code hook via `rtk init -g --auto-patch`.'
+          : 'Install rtk now? Runs its official installer (brew/cargo, or a pinned curl|sh) and makes the native rtk binary available for Codex workflows. Codex has no transparent RTK hook here.';
       const { proceed } = await inquirer.prompt([
         {
           type: 'confirm',
           name: 'proceed',
-          message: 'Install rtk now? Runs its official installer (brew/cargo, or a pinned curl|sh) and adds a GLOBAL Claude Code hook via `rtk init -g --auto-patch`.',
+          message: rtkMessage,
           default: false,
         },
       ]);
       if (proceed) {
         console.log(chalk.gray('  Installing... progress streams below. The cargo fallback compiles from source (can take minutes); Ctrl+C is safe — BYAN is already installed.'));
-        const r = setupRtkIntegration({ log: (m) => console.log(chalk.gray('  ' + m)) });
+        const r = setupRtkIntegration({ targetPlatforms: rtkTargets, log: (m) => console.log(chalk.gray('  ' + m)) });
         if (r.synced) {
-          console.log(chalk.green(`  ✓ rtk ready (${r.installedVia}, v${r.version || '?'}) — restart Claude Code to activate`));
+          if (r.claudeHook && r.codexReady) {
+            console.log(chalk.green(`  ✓ rtk ready (${r.installedVia}, v${r.version || '?'}) — restart Claude Code to activate; Codex can use the native rtk binary`));
+          } else if (r.claudeHook) {
+            console.log(chalk.green(`  ✓ rtk ready (${r.installedVia}, v${r.version || '?'}) — restart Claude Code to activate`));
+          } else if (r.codexReady) {
+            console.log(chalk.green(`  ✓ rtk ready for Codex (${r.installedVia}, v${r.version || '?'}) — native binary installed; no transparent Codex hook`));
+          } else {
+            console.log(chalk.green(`  ✓ rtk ready (${r.installedVia}, v${r.version || '?'})`));
+          }
           if (r.pathHint) console.log(chalk.yellow(`  ⚠ rtk is not on your PATH — add it: ${r.pathHint}`));
         } else {
-          console.log(chalk.yellow(`  ⚠ rtk not wired (${r.reason}) — BYAN unaffected; re-run \`npm run setup-rtk\` anytime`));
+          if (r.codexReady) {
+            console.log(chalk.yellow(`  ⚠ rtk Claude hook not wired (${r.reason}) — Codex can still use the native rtk binary; re-run \`npm run setup-rtk\` anytime`));
+          } else {
+            console.log(chalk.yellow(`  ⚠ rtk not ready (${r.reason}) — BYAN unaffected; re-run \`npm run setup-rtk\` anytime`));
+          }
           if (r.pathHint) console.log(chalk.yellow(`  ⚠ rtk found off-PATH — add it then re-run: ${r.pathHint}`));
         }
       } else {

package/install/lib/codex-native-setup.js

@@ -25,6 +25,10 @@ function getCodexConfigPath() {
   return path.join(os.homedir(), '.codex', 'config.toml');
 }
 
+function getCodexSkillsDir() {
+  return path.join(os.homedir(), '.codex', 'skills');
+}
+
 async function detectCodex() {
   return fs.pathExists(path.join(os.homedir(), '.codex'));
 }
@@ -123,6 +127,81 @@ async function patchCodexConfig(projectRoot, options = {}) {
   return { path: configPath, hadExisting: existing.length > 0, tokenSet: apiToken.length > 0 };
 }
 
+function uniqueExistingDirs(dirs) {
+  const seen = new Set();
+  const out = [];
+  for (const dir of dirs.filter(Boolean)) {
+    const resolved = path.resolve(dir);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+async function findSkillDirs(sourceDirs = []) {
+  const skills = [];
+  const seenNames = new Set();
+
+  for (const sourceDir of uniqueExistingDirs(sourceDirs)) {
+    if (!(await fs.pathExists(sourceDir))) continue;
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillName = entry.name;
+      if (seenNames.has(skillName)) continue;
+      const skillDir = path.join(sourceDir, skillName);
+      const skillFile = path.join(skillDir, 'SKILL.md');
+      if (!(await fs.pathExists(skillFile))) continue;
+      seenNames.add(skillName);
+      skills.push({ name: skillName, path: skillDir, sourceDir });
+    }
+  }
+
+  return skills;
+}
+
+function defaultSkillSourceDirs(projectRoot, options = {}) {
+  const templateDir = options.templateDir;
+  return [
+    path.join(projectRoot, '.codex', 'skills'),
+    path.join(projectRoot, '.claude', 'skills'),
+    templateDir ? path.join(templateDir, '.codex', 'skills') : null,
+    templateDir ? path.join(templateDir, '.claude', 'skills') : null,
+  ];
+}
+
+async function installCodexNativeSkills(projectRoot, options = {}) {
+  const destDir = options.destDir || getCodexSkillsDir();
+  const sourceDirs = options.sourceDirs || defaultSkillSourceDirs(projectRoot, options);
+  const overwrite = options.overwrite !== false;
+
+  await fs.ensureDir(destDir);
+
+  const skills = await findSkillDirs(sourceDirs);
+  const result = {
+    destDir,
+    installed: 0,
+    skipped: 0,
+    skills: [],
+  };
+
+  for (const skill of skills) {
+    const dest = path.join(destDir, skill.name);
+    const exists = await fs.pathExists(dest);
+    if (exists && !overwrite) {
+      result.skipped++;
+      result.skills.push({ name: skill.name, status: 'skipped-existing', path: dest });
+      continue;
+    }
+    await fs.copy(skill.path, dest, { overwrite: true, errorOnExist: false });
+    result.installed++;
+    result.skills.push({ name: skill.name, status: exists ? 'updated' : 'installed', path: dest });
+  }
+
+  return result;
+}
+
 async function setupCodexNative(projectRoot, options = {}) {
   const log = options.quiet ? () => {} : (...a) => console.log(...a);
 
@@ -142,15 +221,28 @@ async function setupCodexNative(projectRoot, options = {}) {
     );
     log(chalk.gray('      (or rerun with BYAN_API_TOKEN=byan_xxx in the env)'));
   }
-  log(chalk.gray('    Restart Codex CLI for the new MCP server to load'));
-  return result;
+  const skills = await installCodexNativeSkills(projectRoot, options);
+  if (skills.installed > 0) {
+    log(chalk.green(`  ✓ Codex native skills installed to ${skills.destDir} (${skills.installed})`));
+  } else {
+    log(chalk.yellow(`  ! No Codex native skills found to install into ${skills.destDir}`));
+  }
+  if (skills.skipped > 0) {
+    log(chalk.gray(`    ${skills.skipped} existing skill(s) skipped`));
+  }
+  log(chalk.gray('    Restart Codex CLI for the new MCP server and skills to load'));
+  return { ...result, skills };
 }
 
 module.exports = {
   setupCodexNative,
   patchCodexConfig,
+  installCodexNativeSkills,
+  findSkillDirs,
+  defaultSkillSourceDirs,
   stripServerSections,
   buildByanBlock,
   getCodexConfigPath,
+  getCodexSkillsDir,
   detectCodex,
 };

package/install/lib/project-handoff.js

@@ -0,0 +1,300 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const FORMAT = 'byan-project-handoff';
+const VERSION = '1.0';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function slugify(s) {
+  return String(s || 'handoff')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'handoff';
+}
+
+function timestampForFile(d = new Date()) {
+  return d.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function handoffDir(root) {
+  return path.join(root, '_byan-output', 'handoffs');
+}
+
+function defaultHandoffPath(root, handoff, date = new Date()) {
+  const from = slugify(handoff.from || 'unknown');
+  const to = slugify(handoff.to || 'next');
+  const task = slugify(handoff.currentTask || handoff.project || 'project');
+  return path.join(handoffDir(root), `${timestampForFile(date)}-${from}-to-${to}-${task}.md`);
+}
+
+function arrayify(value) {
+  if (Array.isArray(value)) return value.filter((v) => String(v || '').trim()).map(String);
+  if (value == null || value === '') return [];
+  return [String(value)];
+}
+
+function readJsonFile(file) {
+  try {
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function safeRun(cmd, { cwd, maxBuffer = 1024 * 1024 } = {}) {
+  try {
+    return String(execSync(cmd, { cwd, stdio: 'pipe', encoding: 'utf8', maxBuffer })).trim();
+  } catch {
+    return '';
+  }
+}
+
+function collectGitSnapshot(root, { run = safeRun } = {}) {
+  const status = run('git status --short', { cwd: root });
+  const branch = run('git branch --show-current', { cwd: root }) || run('git rev-parse --abbrev-ref HEAD', { cwd: root });
+  const head = run('git rev-parse --short HEAD', { cwd: root });
+  const changedFiles = status
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.replace(/^.. /, '').replace(/^..\s+/, ''));
+  return { branch: branch || null, head: head || null, status, changedFiles };
+}
+
+function collectFdState(root) {
+  const state = readJsonFile(path.join(root, '_byan-output', 'fd-state.json'));
+  if (!state) return null;
+  return {
+    fd_id: state.fd_id || null,
+    feature_name: state.feature_name || null,
+    phase: state.phase || null,
+    strict_mode: Boolean(state.strict_mode),
+    backlog: Array.isArray(state.backlog) ? state.backlog : [],
+    validate_verdict: state.validate_verdict || null,
+  };
+}
+
+function buildHandoff(input = {}) {
+  const root = path.resolve(input.root || process.cwd());
+  const git = input.git || collectGitSnapshot(root, input);
+  const fd = input.fd === undefined ? collectFdState(root) : input.fd;
+  const project = input.project || path.basename(root);
+  const from = input.from || process.env.BYAN_HANDOFF_FROM || 'unknown';
+  const to = input.to || process.env.BYAN_HANDOFF_TO || 'next-assistant';
+  const currentTask = input.currentTask || input.task || (fd && fd.feature_name) || 'Resume project work';
+  const filesTouched = arrayify(input.filesTouched || input.files || git.changedFiles);
+  const decisions = arrayify(input.decisions);
+  const blockers = arrayify(input.blockers);
+  const nextActions = arrayify(input.nextActions || input.next);
+  const commands = arrayify(input.commands);
+  const notes = arrayify(input.notes || input.note);
+
+  return {
+    format: FORMAT,
+    version: VERSION,
+    project,
+    root,
+    from,
+    to,
+    createdAt: input.createdAt || nowIso(),
+    currentTask,
+    summary: input.summary || '',
+    decisions,
+    filesTouched,
+    commands,
+    blockers,
+    nextActions,
+    notes,
+    git,
+    fd,
+  };
+}
+
+function renderList(items, empty = '- (none recorded)') {
+  const arr = arrayify(items);
+  if (!arr.length) return empty;
+  return arr.map((item) => `- ${item}`).join('\n');
+}
+
+function renderJsonBlock(handoff) {
+  return [
+    '```json byan-handoff',
+    JSON.stringify(handoff, null, 2),
+    '```',
+  ].join('\n');
+}
+
+function renderMarkdown(handoff) {
+  const h = buildHandoff(handoff);
+  const lines = [];
+  lines.push(`# BYAN Project Handoff: ${h.from} -> ${h.to}`);
+  lines.push('');
+  lines.push('> Portable Markdown handoff for switching between Claude Code and Codex. This file is the source of truth for the next assistant; native assistant memory is optional context only.');
+  lines.push('');
+  lines.push('## Machine Data');
+  lines.push('');
+  lines.push(renderJsonBlock(h));
+  lines.push('');
+  lines.push('## Resume Prompt');
+  lines.push('');
+  lines.push(renderResumePrompt(h));
+  lines.push('');
+  lines.push('## Human Summary');
+  lines.push('');
+  lines.push(h.summary || '_A completer avant le passage si le resume automatique est insuffisant._');
+  lines.push('');
+  lines.push('## Current Task');
+  lines.push('');
+  lines.push(h.currentTask);
+  lines.push('');
+  lines.push('## Decisions');
+  lines.push('');
+  lines.push(renderList(h.decisions));
+  lines.push('');
+  lines.push('## Files Touched');
+  lines.push('');
+  lines.push(renderList(h.filesTouched));
+  lines.push('');
+  lines.push('## Commands And Tests');
+  lines.push('');
+  lines.push(renderList(h.commands));
+  lines.push('');
+  lines.push('## Blockers And Risks');
+  lines.push('');
+  lines.push(renderList(h.blockers));
+  lines.push('');
+  lines.push('## Next Actions');
+  lines.push('');
+  lines.push(renderList(h.nextActions, '- Re-read this handoff, inspect the listed files, then continue the current task.'));
+  lines.push('');
+  lines.push('## Notes');
+  lines.push('');
+  lines.push(renderList(h.notes));
+  lines.push('');
+  lines.push('## Git Snapshot');
+  lines.push('');
+  lines.push(`- Branch: ${h.git && h.git.branch ? h.git.branch : 'unknown'}`);
+  lines.push(`- Head: ${h.git && h.git.head ? h.git.head : 'unknown'}`);
+  lines.push('');
+  lines.push('```text');
+  lines.push((h.git && h.git.status) || '(clean or unavailable)');
+  lines.push('```');
+  lines.push('');
+  if (h.fd) {
+    lines.push('## FD Snapshot');
+    lines.push('');
+    lines.push(`- FD: ${h.fd.fd_id || 'unknown'}`);
+    lines.push(`- Feature: ${h.fd.feature_name || 'unknown'}`);
+    lines.push(`- Phase: ${h.fd.phase || 'unknown'}`);
+    lines.push(`- Strict: ${h.fd.strict_mode ? 'yes' : 'no'}`);
+    lines.push('');
+    lines.push('### Backlog');
+    lines.push('');
+    lines.push(renderList((h.fd.backlog || []).map((b) => `${b.id || '-'} [${b.status || '?'}] ${b.title || ''}`)));
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function extractJsonBlock(markdown) {
+  const text = String(markdown || '');
+  const re = /```json\s+byan-handoff\s*\n([\s\S]*?)\n```/m;
+  const m = text.match(re);
+  if (!m) throw new Error('Missing ```json byan-handoff block');
+  try {
+    return JSON.parse(m[1]);
+  } catch (err) {
+    throw new Error(`Invalid byan-handoff JSON: ${err.message}`);
+  }
+}
+
+function parseMarkdown(markdown) {
+  const h = extractJsonBlock(markdown);
+  if (h.format !== FORMAT) throw new Error(`Invalid handoff format: ${h.format || 'missing'}`);
+  if (!h.version) throw new Error('Missing handoff version');
+  return h;
+}
+
+function normalizeProvider(value) {
+  return slugify(value || '');
+}
+
+function providerMatches(actual, expected) {
+  const a = normalizeProvider(actual);
+  const e = normalizeProvider(expected);
+  if (!e) return true;
+  return a === e || a.startsWith(`${e}-`);
+}
+
+function renderResumePrompt(handoff) {
+  const h = buildHandoff(handoff);
+  const lines = [];
+  lines.push(`Continue this BYAN project from a portable handoff created by ${h.from} for ${h.to}.`);
+  lines.push(`Project: ${h.project}`);
+  lines.push(`Task: ${h.currentTask}`);
+  if (h.summary) lines.push(`Summary: ${h.summary}`);
+  if (h.decisions.length) lines.push(`Decisions: ${h.decisions.join(' | ')}`);
+  if (h.filesTouched.length) lines.push(`Files to inspect first: ${h.filesTouched.join(', ')}`);
+  if (h.commands.length) lines.push(`Known commands/tests: ${h.commands.join(' | ')}`);
+  if (h.blockers.length) lines.push(`Blockers/risks: ${h.blockers.join(' | ')}`);
+  if (h.nextActions.length) lines.push(`Next actions: ${h.nextActions.join(' | ')}`);
+  if (h.fd && h.fd.phase) lines.push(`FD state: ${h.fd.feature_name || h.fd.fd_id || 'unknown'} is in phase ${h.fd.phase}.`);
+  lines.push('Use repo files and BYAN portable state as source of truth; do not rely on native assistant memory.');
+  return lines.join('\n');
+}
+
+function writeHandoff(root, handoff, { outPath, mkdirp = fs.mkdirSync, writeFile = fs.writeFileSync } = {}) {
+  const h = buildHandoff({ ...handoff, root });
+  const target = path.resolve(outPath || defaultHandoffPath(path.resolve(root), h));
+  mkdirp(path.dirname(target), { recursive: true });
+  writeFile(target, renderMarkdown(h), 'utf8');
+  return { path: target, handoff: h };
+}
+
+function latestHandoff(root, { from = null, exists = fs.existsSync, readdir = fs.readdirSync, readFile = fs.readFileSync } = {}) {
+  const dir = handoffDir(path.resolve(root));
+  if (!exists(dir)) return null;
+  const files = readdir(dir)
+    .filter((f) => /\.md$/i.test(f))
+    .sort()
+    .reverse();
+  if (!files.length) return null;
+  if (!from) return path.join(dir, files[0]);
+
+  for (const file of files) {
+    const full = path.join(dir, file);
+    try {
+      const handoff = parseMarkdown(readFile(full, 'utf8'));
+      if (providerMatches(handoff.from, from)) return full;
+    } catch {
+      // Ignore non-handoff markdown files in the handoff directory.
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  FORMAT,
+  VERSION,
+  buildHandoff,
+  collectFdState,
+  collectGitSnapshot,
+  defaultHandoffPath,
+  extractJsonBlock,
+  handoffDir,
+  latestHandoff,
+  parseMarkdown,
+  providerMatches,
+  renderMarkdown,
+  renderResumePrompt,
+  writeHandoff,
+};