create-byan-agent 2.39.0 → 2.42.0

package/CHANGELOG.md

@@ -9,7 +9,159 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.39.0] - 2026-07-02
+## [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
+  `UserPromptSubmit` hook estimates the rolling-5h Claude consumption from the
+  local transcripts (live) + session-meta (fallback), and nudges delegation on
+  three triggers: pressure (>= 80% estimated, configurable), task nature
+  (delegable coding work), and an opt-in perf forces table. The red line holds:
+  only delegable natures are proposed; judgment / soul / verification stay on
+  Claude. Disarmed by default — the yanstaller arms it on opt-in (device-flow
+  `codex login --device-auth`, entitled model gpt-5.4) by writing
+  `_byan/_config/autodelegate.json`. The 5h gauge is an honest ESTIMATE (no
+  provider exposes a machine-readable quota; `pct` is null without a configured
+  budget), and perf routing ships neutral (below the L2 perf floor, tagged
+  heuristic). New: `.claude/hooks/codex-autodelegate.js` +
+  `.claude/hooks/lib/{usage-estimator,autodelegate-decision,perf-routing}.js`,
+  `install/lib/codex-autodelegate-setup.js`. 47 unit tests. See
+  `docs/codex-auto-delegation.md`.
+
+### Fixed
+- **lb: Codex pool targeted a non-entitled model on ChatGPT subscription.** The
+  provider defaulted to `gpt-5-codex`; the OpenAI backend rejects every
+  `-codex`-suffixed model on a subscription account (API-key only). Default is
+  now the entitled `gpt-5.4`, and a new pure `resolveCodexModel({ requested,
+  authPool })` remaps a `-codex` request to `gpt-5.4` under subscription auth
+  only (passthrough on api-key or an already-plain id). `loadbalancer.default.yaml`
+  codex models set to `gpt-5.4`. Covered by 7 new unit tests (mock runner, no
+  real CLI/network). See `docs/loadbalancer-multipool.md`.
+
+## [2.41.0] - 2026-07-03
+
+### Added - multi-pool subscription arbitrage: Codex as a second pool + the 5h-window ladder
+
+The load-balancer had claude + copilot + byan_api but no OpenAI pool, and its
+pressure-score modelled API-burst (429) pressure, not the rolling 5h subscription
+window that users actually hit. This release adds the second pool and the window
+tracking that switches before the wall, without denaturing BYAN.
+
+- **CodexProvider** (`src/loadbalancer/providers/codex-provider.js`) - wraps the
+  `codex exec --json` SYSTEM CLI (not an npm SDK); degrades to disabled if the
+  binary is absent; two auth pools (CODEX_API_KEY per-token, else the
+  ChatGPT-subscription session). Rate-limit exhaustion read from stderr (no
+  machine-readable quota, OpenAI issue #10233). Registered in the yaml +
+  capability-matrix; provider factory (`providers/factory.js`).
+- **subscription-window tracker** (`subscription-window.js`) - per-pool rolling-5h
+  + weekly token burn, a `window-proximity` signal (distinct from 429-pressure) +
+  ETA. Honest estimate: `null` proximity without a configured budget, no
+  fabricated percentage.
+- **Execution stubs unblocked** (`mcp-server.js`) - `lb_send` / `lb_switch` /
+  `lb_get_context` now really route / transfer context / read state; the
+  SessionBridge and GracefulDegradation (previously orphaned) are wired; all
+  seams injectable so tests avoid spawning codex or hitting the OpenAI quota.
+- **switch-tolerance** (`switch-tolerance.js`) - the red line: only delegable
+  natures (exploration / mechanical / implementation) may cross to Codex;
+  verification / analysis / soul / identity / review / gate stay on Claude and
+  queue rather than denature.
+- **4-rung degradation ladder** (`degradation-ladder.js`) - HEALTHY ->
+  PRIMARY_HOT -> PRIMARY_EXHAUSTED -> ALL_EXHAUSTED, driven by the window
+  proximity, obeying the red line at every rung. `planRoute(nature)` on the live
+  shell.
+- **lb_budget** MCP tool + `getBudget()` - the anti-"5h limit reached" dashboard:
+  per-pool 5h/weekly burn, proximity, ETA, rung, with the honest estimate/
+  doubles-the-ceiling note.
+- **Docs** - `docs/loadbalancer-multipool.md` (architecture, the red line, the two
+  hard truths, honest shipping status).
+
+### Added - native workflow model tiering: the sonnet tier lives, ad-hoc scripts are gated
+
+Claude Code's Workflow tool runs every `agent()` leaf on the session model
+unless the script pins `opts.model`, and the tiering contract only reached
+committed `.claude/workflows/*.js` through the repo linter. Two consequences,
+both observed live: ad-hoc scripts (written inline for one run) executed
+all-deep (14 agents on Opus for one review), and the `balanced` tier was
+unreachable (0/131 committed leaves on sonnet). This release closes both.
+
+- **`mech-` opt-in class (native-tiers)** - a `mech-` label prefix
+  (`mech-validate-json`) declares a MECHANICAL verification: a binary,
+  judgment-free check (JSON parses, schema matches, lint passes) that tiers to
+  `balanced` (sonnet). Explicit opt-in only, no keyword fuzziness:
+  `validate-json` without the prefix stays protected (deep). The linter holds
+  the script to the declaration: `mechanical-without-model` and
+  `mechanical-below-tier` are hard contract violations.
+- **tier-script engine + CLI** - `lib/tier-script.js` analyzes any workflow
+  script TEXT (committed, ad-hoc or draft): one verdict per labelled leaf
+  against native-tiers, plus the deny-once gate decision. Parsing stays in
+  `workflows-lint.js` (`extractLabelledLeaves`). `bin/byan-tier-script.js`
+  prints the report (exit 0 clean/acknowledged, 1 gaps, 2 violations).
+- **tier gate hook** - `.claude/hooks/tier-script-guard.js` (PreToolUse,
+  matcher `Workflow`) gates EVERY Workflow invocation at the one chokepoint an
+  ad-hoc script crosses. Undecided exploration/`mech-` leaves deny ONCE with
+  the exact leaf list; `// BYAN-TIER: reviewed` acknowledges deliberate deep
+  choices; an identical resubmission passes (deny-once by design); registry
+  invocations pass. It rewrites nothing (STRICT-2 No Downgrade). Every
+  decision lands in `_byan-output/tier-ledger.jsonl` with a per-model
+  histogram - the measurement basis for token gains. Escape hatch:
+  `.byan-tier/off`.
+- **`byan_dispatch` batch mode** - `{ leaves: [{ label, nature? }] }` returns
+  the `opts.model` per planned leaf BEFORE the script is written; the nature
+  enum gains `mechanical` on both axes.
+- **Docs** - `native-workflows.md` rule + `docs/native-workflows-contract.md`
+  describe the three live tiers, the two nets (repo linter floor + tier gate
+  hook) and the authoring flow; byan-byan and hermes-dispatch skills carry the
+  same doctrine.
 
 ### Added - shippable soul stays in sync with the active soul (byan-sync-soul)
 

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

@@ -20,6 +20,7 @@ const { setupRtkIntegration, shouldOfferRtk } = require('../lib/rtk-integration'
 const { setupGdocPublish, shouldOfferGdoc } = require('../lib/gdoc-setup');
 const { setupClaudeNative } = require('../lib/claude-native-setup');
 const { setupCodexNative } = require('../lib/codex-native-setup');
+const { setupCodexAutodelegate, DEVICE_FLOW_INSTRUCTION } = require('../lib/codex-autodelegate-setup');
 const { setupMcpExtensions } = require('../lib/mcp-extensions');
 const { setupStagingConsent } = require('../lib/staging-consent');
 const { getLatestVersion, compareVersions } = require('../lib/utils/version-compare');
@@ -1323,17 +1324,56 @@ 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.`
         )
       );
     }
+
+    // Optional: opt into a Codex BACKUP pool. When enabled, BYAN auto-proposes
+    // handing delegable work to Codex on the ChatGPT subscription (no API credit)
+    // to spare the Claude 5h budget. Arms the F5 hook by writing
+    // _byan/_config/autodelegate.json. TTY -> prompt; non-TTY -> env opt-in.
+    console.log();
+    console.log(chalk.cyan('Codex backup pool (auto-delegation)'));
+    let wantAutodelegate = false;
+    if (process.stdin.isTTY) {
+      try {
+        const ans = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'enable',
+            message:
+              'Add Codex as a backup pool? BYAN will propose offloading delegable work to Codex (your ChatGPT subscription, no API credit) when Claude is under 5h pressure.',
+            default: true,
+          },
+        ]);
+        wantAutodelegate = ans.enable;
+      } catch {
+        wantAutodelegate = false;
+      }
+    } else {
+      wantAutodelegate = process.env.BYAN_CODEX_AUTODELEGATE === '1';
+      if (!wantAutodelegate) {
+        console.log(
+          chalk.gray('  · non-TTY — skipped (set BYAN_CODEX_AUTODELEGATE=1 to arm)')
+        );
+      }
+    }
+    if (wantAutodelegate) {
+      try {
+        await setupCodexAutodelegate(projectRoot);
+      } catch (error) {
+        console.log(chalk.yellow(`  ! Codex auto-delegation setup skipped: ${error.message}`));
+        console.log(chalk.gray(`    ${DEVICE_FLOW_INSTRUCTION.replace(/\n/g, '\n    ')}`));
+      }
+    }
   }
 
   if (needsClaude) {
@@ -1386,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-autodelegate-setup.js

@@ -0,0 +1,100 @@
+/**
+ * Codex auto-delegation setup (installer F4) — opts the user into a Codex backup
+ * pool and ARMS the F5 auto-delegation hook by writing
+ * `_byan/_config/autodelegate.json`.
+ *
+ * Linking uses the LOCAL Codex auth — the ChatGPT subscription established by
+ * `codex login` — NOT an API key: delegated turns cost subscription quota, not
+ * per-token API credit. The entitled model is `gpt-5.4` (the `-codex` ids are
+ * API-only on a subscription; see src/loadbalancer/providers/codex-provider.js).
+ *
+ * On a headless server the browser localhost redirect of the default login
+ * fails, so we surface the DEVICE-FLOW instruction (`codex login --device-auth`)
+ * rather than pretend the link worked.
+ *
+ * Companion to codex-native-setup.js (which wires the BYAN MCP into
+ * ~/.codex/config.toml). This module owns only the auto-delegation opt-in. All
+ * fs is injectable so the unit tests write nothing real; the hook it arms is a
+ * no-op until this config exists (disarmed-by-default, see the F5 hook).
+ */
+
+const realFs = require('fs');
+const realPath = require('path');
+const os = require('os');
+let chalk;
+try { chalk = require('chalk'); } catch { chalk = null; }
+
+const paint = (fn, s) => (chalk && chalk[fn] ? chalk[fn](s) : s);
+
+const DEVICE_FLOW_INSTRUCTION = [
+  'Codex is not linked yet. On THIS machine run:',
+  '    codex login --device-auth',
+  'then open the printed URL, enter the code, and re-run the installer.',
+  '(device-auth avoids the localhost browser redirect that fails on a headless server).',
+].join('\n');
+
+// Which local Codex auth backs the CLI: 'api-key' (CODEX_API_KEY, per-token),
+// 'subscription' (~/.codex/auth.json, the 5h window), or null (not linked).
+function codexAuthState({ home = os.homedir(), fs = realFs, path = realPath } = {}) {
+  if (process.env.CODEX_API_KEY) return 'api-key';
+  try {
+    if (fs.existsSync(path.join(home, '.codex', 'auth.json'))) return 'subscription';
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+// The config that ARMS the F5 hook. enabled:true is the whole point — the hook
+// no-ops without this file.
+function autodelegateConfig({ threshold = 80, budget = null, invocation = 'codex:codex-rescue --model gpt-5.4' } = {}) {
+  return {
+    enabled: true,
+    threshold,
+    budget,
+    invocation,
+    model: 'gpt-5.4',
+    note: 'Written by the BYAN installer (F4). Delete or set enabled:false to disarm auto-delegation.',
+  };
+}
+
+function writeAutodelegateConfig({ projectRoot, config, fs = realFs, path = realPath }) {
+  const dir = path.join(projectRoot, '_byan', '_config');
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, 'autodelegate.json');
+  fs.writeFileSync(p, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return p;
+}
+
+// Orchestrate the opt-in step. Called only when the user chose "add a Codex
+// backup" at install. Arms the hook when Codex is linked; otherwise leaves it
+// disarmed and surfaces the device-flow so the link can be completed and the
+// installer re-run. Never throws on a link check — an unlinked Codex is a normal
+// outcome, not an installer failure.
+async function setupCodexAutodelegate(projectRoot, options = {}) {
+  const log = options.quiet ? () => {} : (...a) => console.log(...a);
+  const fs = options.fs || realFs;
+  const path = options.path || realPath;
+
+  const auth = codexAuthState({ fs, path, home: options.home });
+  if (!auth) {
+    log(paint('yellow', '  ! Codex not linked - auto-delegation left DISARMED'));
+    log(paint('gray', `    ${DEVICE_FLOW_INSTRUCTION.replace(/\n/g, '\n    ')}`));
+    return { armed: false, reason: 'codex-not-linked' };
+  }
+
+  const config = autodelegateConfig(options);
+  config.linkedVia = auth;
+  const p = writeAutodelegateConfig({ projectRoot, config, fs, path });
+  log(paint('green', `  + Codex auto-delegation ARMED (${auth}) -> ${p}`));
+  log(paint('gray', '    BYAN will now propose handing delegable work to Codex (no API credit).'));
+  return { armed: true, path: p, authPool: auth, config };
+}
+
+module.exports = {
+  DEVICE_FLOW_INSTRUCTION,
+  codexAuthState,
+  autodelegateConfig,
+  writeAutodelegateConfig,
+  setupCodexAutodelegate,
+};

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,
 };