geneseed 2.0.0

package/js/migrate.mjs

@@ -0,0 +1,251 @@
+/**
+ * `geneseed migrate` — move a machine from the git-checkout install shape to the npm one.
+ *
+ * P10d, AND IT IS NOT A PORT. Every other module here reproduces a Python original byte for
+ * byte; this verb is new behaviour on both sides, written twice in the same change so that
+ * `tests/harness_golden.py` — a CROSS-IMPLEMENTATION gate — has a reference side at all. A
+ * Node-only verb would have nothing to compare against, and `test_every_entry_verb_is_a_real_
+ * harness_subcommand` plus `test_the_matrix_covers_every_verb_it_claims` would both fail it.
+ *
+ * WHAT IT IS NOT: `rebuild-all`. That was the first answer and it was checked before being
+ * discarded, because the re-emit really is the same engine and is reused rather than rewritten
+ * here. Four behaviours differ, and each is a cell:
+ *
+ *   | an unknown emit marker | rebuild-all COERCES it to a default | migrate REFUSES         |
+ *   | a failing root         | continues, exit 1                   | ROLLS BACK all, exit 1  |
+ *   | an already-done machine| re-emits everything                 | no-op, writes NOTHING   |
+ *   | stale autostart        | not its subject                     | surveyed and REPORTED   |
+ *
+ * Coercing an unrecognised marker is right for a rebuild and is *guessing what the user
+ * installed* for a migration. Continuing past a failure is right for a rebuild — one broken
+ * install must not block the rest — and for a migration it is the half-migrated machine the
+ * whole verb exists to prevent.
+ *
+ * THE TWO TRIGGERS, AND WHY IT TAKES BOTH. Work is needed when the machine's wiring is
+ * `legacy` (see `migrateShape` — and note that shapes 2 and 3 differ only inside the shim
+ * body, never in the settings file) OR when the stamp does not name this ROOT. Neither alone
+ * is enough: an OpenCode-only machine wires no hooks at all, so its shape is permanently
+ * `none` and a shape-only trigger would re-emit it on every run forever; and a user who
+ * reinstalls the old Python build flips the shape back to `legacy` while the stamp still
+ * matches, which must migrate again. Both inputs, and the stamp is written only on success.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+
+import { main as driverMain } from '../bin/geneseed.mjs';
+import { ROOT } from './checkout.mjs';
+import {
+  EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, footprintOfDir, installState,
+  installTargets, modeOfDir, postureOfDir, readMaybe, themeOfDir,
+} from './installs.mjs';
+import { DEFAULT_EMIT, setupBuildArgs } from './generate.mjs';
+import {
+  autostartPaths, autostartStale, hookShimPath, migrateShape, readJsonc, shimHome,
+} from './settings.mjs';
+import { writeText, pyPrint, pyPrintErr } from './lib/fs.mjs';
+
+/** Every emit name the generator answers to — the set an unrecognised marker is NOT in. */
+const KNOWN_EMITS = new Set(EMIT_HOST_SCOPE.keys());
+
+/**
+ * The settings file a host wires hooks into, or null for a host that has none.
+ *
+ * Only Claude and Bob carry hook commands. OpenCode's hooks are a PLUGIN (`js/opencode.mjs`
+ * emits JS that runs in the host's own process and names neither the shim nor `harness.py`),
+ * and Copilot has no hook mechanism at all. So those two classify as `none` and their whole
+ * migration is the re-emit — which is the same re-emit, in the same change, on all three
+ * hosts, which is what the project's host-parity rule asks for.
+ */
+function hookSettingsFile(root, host, scope) {
+  if (host !== 'claude' && host !== 'bob') return null;
+  const name = scope === 'project' && host !== 'bob' ? 'settings.local.json' : 'settings.json';
+  return path.join(root, name);
+}
+
+/** Every hook command string in a settings file, or [] when it cannot be read or parsed. */
+export function hookCommandsOf(file) {
+  // `readJsonc`, NOT `JSON.parse`. A hand-edited settings.json with comments and a trailing
+  // comma is the one shape no machine in this project writes, and strict JSON rejects it —
+  // which would classify a wired install as `none` and make `migrate` skip the machine
+  // silently. `mergeClaudeSettings` already reads through comments for exactly this reason.
+  // Found by the JSONC corpus fixture; a generated fixture would have hidden it.
+  let loaded;
+  try { [loaded] = readJsonc(readFileSync(file, 'utf8')); } catch { return []; }
+  if (!loaded || typeof loaded !== 'object') return [];
+  const hooks = loaded.hooks;
+  if (!hooks || typeof hooks !== 'object') return [];
+  const out = [];
+  for (const groups of Object.values(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const g of groups) {
+      for (const h of (g && Array.isArray(g.hooks) ? g.hooks : [])) {
+        if (h && typeof h.command === 'string') out.push(h.command);
+      }
+    }
+  }
+  return out;
+}
+
+/** `<GENESEED_HOME>/.migrated` — the ROOT the last successful migration installed from. */
+export function stampPath() { return path.join(shimHome(), '.migrated'); }
+
+/** Where the pre-migration copies live while the re-emit runs. */
+function stashDir() { return path.join(shimHome(), '.migrate-backup'); }
+
+/**
+ * Step 1 — classify, WITHOUT touching anything.
+ *
+ * A refusal that happens here is free: nothing has been written, so "refuse and report" needs
+ * no rollback. That ordering is the cheapest atomicity there is and it is why the survey is a
+ * separate pass rather than a check inside the loop.
+ */
+export function migrateSurvey() {
+  const rows = [];
+  const commands = [];
+  const unrecognised = [];
+  for (const [host, scope, root] of installTargets()) {
+    if (installState(root, host, scope) !== 'active') continue;
+    const raw = readMaybe(path.join(root, '.geneseed-emit'));
+    const marker = raw === null ? '' : raw.trim();
+    // An unrecognised marker is a REFUSAL, not a default. `rebuild-all` coerces here.
+    if (marker && !KNOWN_EMITS.has(marker)) {
+      unrecognised.push({ host, scope, root, marker });
+      continue;
+    }
+    const file = hookSettingsFile(root, host, scope);
+    if (file) commands.push(...hookCommandsOf(file));
+    rows.push({ host, scope, root, marker, file });
+  }
+  let shimBody = '';
+  try { shimBody = readFileSync(hookShimPath(), 'utf8'); } catch { /* no shim yet */ }
+  const shape = migrateShape(commands, shimBody);
+  const stamped = (readMaybe(stampPath()) || '').trim();
+  // THE TRIGGER IS THE STAMP, AND THE SHAPE IS REPORTED — the first draft had it the other
+  // way round and the ref-vs-ref self-check killed it in one run. `shape === 'legacy'` cannot
+  // be a trigger, because what "current" MEANS is "the shim body names the .mjs entry", and
+  // the Python implementation bakes python + harness.py by design (`_hook_runner_entry`). So
+  // a migration run from the reference can never reach `current`, its second run would
+  // re-emit forever, and the two implementations would diverge on idempotence by
+  // construction. The stamp is a value both sides write and read identically.
+  return { rows, unrecognised, shape, stamped, needed: stamped !== ROOT };
+}
+
+/** Hand-written login entries that still name some other checkout. Reported, never rewritten. */
+function autostartFindings() {
+  const out = [];
+  for (const p of autostartPaths()) {
+    const text = readMaybe(p);
+    if (text !== null && autostartStale(text, ROOT)) out.push(p);
+  }
+  return out;
+}
+
+/** A stash key that cannot collide across drives, and is a legal file name on both platforms. */
+const stashKey = (p) => p.replace(/[\\/:]/g, '_');
+
+export function cmdMigrate(args = {}) {
+  const dryRun = Boolean(args.dryRun);
+  const { rows, unrecognised, shape, needed } = migrateSurvey();
+
+  if (unrecognised.length) {
+    // Refuse the WHOLE run. A migration that skipped the row it did not understand and
+    // migrated the rest is the half-migrated machine this verb exists to prevent.
+    pyPrintErr('[migrate] REFUSED — unrecognised install marker(s):\n');
+    for (const u of unrecognised) {
+      pyPrintErr(`[migrate]   ${u.host}:${u.scope} (${u.root}) has .geneseed-emit `
+        + `'${u.marker}', which is not an emit this generator answers to.\n`);
+    }
+    pyPrintErr('[migrate] Nothing was changed. Fix or delete the marker, then re-run.\n');
+    return 3;
+  }
+
+  if (!rows.length) {
+    pyPrint('[migrate] no active installs detected.\n');
+    return 0;
+  }
+
+  if (!needed) {
+    pyPrint(`[migrate] already on the npm shape (${rows.length} install(s)); nothing to do.\n`);
+    return 0;
+  }
+
+  pyPrint(`[migrate] ${rows.length} install(s), wiring shape: ${shape}\n`);
+  if (dryRun) {
+    for (const r of rows) {
+      pyPrint(`[migrate] would re-emit ${r.host}:${r.scope} (${r.root})\n`);
+    }
+    for (const p of autostartFindings()) {
+      pyPrint(`[migrate] would report the autostart entry at ${p}\n`);
+    }
+    pyPrint('[migrate] --dry-run: nothing was written.\n');
+    return 0;
+  }
+
+  // Step 2 — stash every file the re-emit can touch, so step 4 can put it all back.
+  const stash = stashDir();
+  const saved = [];
+  try {
+    rmSync(stash, { recursive: true, force: true });
+    mkdirSync(stash, { recursive: true });
+    const shim = hookShimPath();
+    for (const p of [...rows.map((r) => r.file).filter(Boolean), shim]) {
+      if (!existsSync(p)) continue;
+      const dest = path.join(stash, stashKey(p));
+      copyFileSync(p, dest);
+      saved.push([p, dest]);
+    }
+  } catch (e) {
+    pyPrintErr(`[migrate] could not stage a backup (${e.message}); nothing was changed.\n`);
+    return 1;
+  }
+
+  const restore = () => {
+    for (const [orig, dest] of saved) {
+      try { copyFileSync(dest, orig); } catch { /* best effort — report below regardless */ }
+    }
+    try { rmSync(stash, { recursive: true, force: true }); } catch { /* nothing to undo */ }
+  };
+
+  // Step 3 — re-emit, in each install's OWN five values. Same reads as `cmdRebuildAll`.
+  for (const r of rows) {
+    const marker = r.marker && (EMIT_HOST_SCOPE.get(r.marker) ?? ['', ''])[0] === r.host
+      ? r.marker : '';
+    const emit = marker || DEFAULT_EMIT.get(`${r.host} ${r.scope}`) || 'opencode-global';
+    const theme = themeOfDir(r.root) || defaultTheme();
+    const out = r.scope === 'global' ? null : r.root;
+    const argv = setupBuildArgs(theme, emit, out, out, footprintOfDir(r.root),
+      postureOfDir(r.root) || defaultPosture(), modeOfDir(r.root) || defaultMode());
+    const label = `${r.host}:${r.scope} (${r.root})`;
+    pyPrint(`[migrate] re-emitting ${label}: theme=${theme} emit=${emit}\n`);
+    let rc = 1;
+    try { rc = driverMain(argv); } catch { rc = 1; }
+    if (rc !== 0) {
+      // Step 4 — ALL OR NOTHING. `rebuild-all` continues here on purpose; a migration
+      // must not, or the machine is left half on each shape.
+      pyPrintErr(`[migrate] FAILED ${label} (exit ${rc}) — rolling back.\n`);
+      restore();
+      pyPrintErr(`[migrate] rolled back ${saved.length} file(s); the install is unchanged.\n`);
+      return 1;
+    }
+  }
+
+  try { rmSync(stash, { recursive: true, force: true }); } catch { /* nothing to undo */ }
+  try {
+    mkdirSync(path.dirname(stampPath()), { recursive: true });
+    writeText(stampPath(), `${ROOT}\n`);
+  } catch { /* an unwritable stamp costs a redundant re-emit next run, never correctness */ }
+
+  pyPrint(`[migrate] migrated ${rows.length} install(s).\n`);
+
+  // Step 5 — what could NOT be fixed automatically. Reported, never rewritten: nothing in
+  // this repository has ever written an autostart entry, so migrate does not own the file.
+  // The `start` ACTION is load-bearing, not decoration: bare `web` runs `serve()` in the
+  // FOREGROUND with `daemon=false`, which never writes the daemon record, so `web stop`,
+  // `web restart` and `web status` stay blind to the server this note just told someone to
+  // launch at every login. Derived, not trusted: `TheMigrateNoteAdvisesARealWebAction`.
+  for (const p of autostartFindings()) {
+    pyPrint(`[migrate] NOTE: the autostart entry at ${p} still names another checkout — `
+      + 'update it by hand to run: geneseed web start --no-browser\n');
+  }
+  return 0;
+}

package/js/native.mjs

@@ -0,0 +1,426 @@
+/**
+ * The host-native layer, in Node — where RENDER stops being pure.
+ *
+ * A faithful translation of `_build_emit._write_native_layer` and the frontmatter
+ * builders it dispatches to. Capability specs become host-native subagents and skills:
+ * one dialect per host (OpenCode / Claude Code / Copilot), vendored skill folders copied
+ * through verbatim, authoring templates shipped flat.
+ *
+ * WHY THIS IS THE HARD HALF. `js/render.mjs` is a pure function of `src/` and `themes/`;
+ * this file is not, in three separate ways, and each one is a place a port can be subtly
+ * wrong while looking right:
+ *
+ *   1. The frontmatter depends on the USER's `agent-overrides.json`, read out of the emit
+ *      target. So the output is a function of the machine it runs on.
+ *   2. Claim-on-create decides which files get written AT ALL: a target that already
+ *      exists and was not in the previous manifest belongs to the user, and is skipped
+ *      with a warning. So the output is a function of what is already on disk.
+ *   3. Three host dialects diverge inside one loop — including a FILENAME change
+ *      (`<name>.agent.md`) that drags a link rewrite along with it.
+ *
+ * None of the three is reachable from the golden harness's happy path: golden emits into
+ * a fresh tree with an empty overrides stub. `tests/test_native_layer_parity.py` drives
+ * both implementations over the cells golden cannot construct, and byte-compares the
+ * written trees, the returned values AND the warning stream.
+ *
+ * NOTHING HERE MAY WRITE TO STDOUT. Python's warnings all go to stderr, and the emitted
+ * hook gates signal by printing JSON on stdout — a stray byte from a library on that path
+ * turns a blocking gate into a silently permissive one (see the P0 notes in the spec).
+ * Warnings go through `warn()` below, which is stderr, always.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { writeText, copyFile, jsonDumps, parseJson, pyStr, pyRepr, pyTruthy, readText }
+  from './lib/fs.mjs';
+
+/** Mirrors `_build_core.VENDORED_SKILL_DIRS`. */
+export const VENDORED_SKILL_DIRS = new Set(['react-view-transitions', 'daydream', 'token-report']);
+
+/**
+ * `PurePath(rel).parts` — split on EITHER separator, empties dropped.
+ *
+ * `'skills/x/'.split('/')` carries a trailing `''` that `Path` does not have, and the two
+ * vendored predicates below are `len(parts) >= 2` tests where that would matter.
+ */
+const pathParts = (rel) => rel.split(/[\\/]+/).filter((p) => p !== '');
+
+/**
+ * `_build_render.is_vendored_path` — a BUNDLE-relative `skills/<vendored>/…`.
+ *
+ * `DIR_SKILLS` is always the neutral `skills`, so the second segment is the skill name.
+ */
+export function isVendoredPath(rel) {
+  const parts = pathParts(rel);
+  return parts.length >= 2 && parts[0] === 'skills' && VENDORED_SKILL_DIRS.has(parts[1]);
+}
+
+/**
+ * `build._validate_is_vendored` — the same question, tolerant of `skills` at ANY depth.
+ *
+ * The per-repo native layers nest one level deeper than a `files`/opencode-global bundle
+ * (`.claude/skills/<name>/…`, `.bob/skills/<name>/…`, `.github/skills/<name>/…`), so
+ * `doctor`'s scan of those trees needs the loose form or every vendored folder's own
+ * upstream cross-links read as dead links. Never the last segment — `parts[:-1]`, because a
+ * FILE named `skills` is not a directory of them.
+ */
+export function validateIsVendored(rel) {
+  const parts = pathParts(rel);
+  return parts.slice(0, -1).some((p, i) => p === 'skills' && VENDORED_SKILL_DIRS.has(parts[i + 1]));
+}
+
+/** Mirrors `_build_emit.AGENT_COLORS` — the fallback when a theme carries no map. */
+const AGENT_COLORS = {
+  architect: 'primary', reviewer: 'warning', tester: 'success',
+  docs: 'info', security: 'error', explorer: 'accent',
+  _default: 'secondary',
+};
+
+/** Mirrors `_build_emit._VALID_AGENT_COLOR_SLOTS` — OpenCode's named theme slots. */
+const VALID_AGENT_COLOR_SLOTS = new Set(
+  ['primary', 'secondary', 'accent', 'success', 'warning', 'error', 'info']);
+
+/** `_build_emit._SIBLING_AGENT_LINK_RE` — a bare same-dir agent filename in a link. */
+const SIBLING_AGENT_LINK_RE = /\]\(([A-Za-z0-9_-]+)\.md\)/g;
+
+/**
+ * `_build_emit._strip_skill_body_links`'s pattern: every RELATIVE markdown link to a
+ * `.md` spec, keeping the link text. Python's `\s` and JS's differ on U+FEFF, which is
+ * not whitespace to Python and is to JS — unreachable inside a link target.
+ */
+const SKILL_BODY_LINK_RE = /\[([^\]]+)\]\((?!https?:\/\/|\/|#)[^)\s]*\.md(?:#[^)\s]*)?\)/g;
+
+/** Every warning in this module. stderr, never stdout — see the module header. */
+function warn(line) {
+  process.stderr.write(`${line}\n`);
+}
+
+/** `_build_render._first_blockquote` — the one-line purpose of a spec. */
+export function firstBlockquote(text) {
+  // `splitlines()` also breaks on VT, FF, FS-GS-RS, NEL and the two Unicode separators;
+  // `split('\n')` does not. Measured: no `src/**.md` contains any of them, and readText
+  // has already folded CRLF and CR. Likewise `str.strip()` covers a few code points JS's
+  // `trim()` does not (and vice versa) — none of them occur either.
+  for (const line of text.split('\n')) {
+    const s = line.trim();
+    if (s.startsWith('>')) return s.replace(/^>+/, '').trim();   // `lstrip(">")`
+  }
+  return '';
+}
+
+/** `_build_emit.desc_of`. */
+export function descOf(text) {
+  return firstBlockquote(text);
+}
+
+/** `_build_render._HTML_COMMENT_RE`. */
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+
+/**
+ * `_build_render._desc_block_problem` — "" when the spec's shape holds, else the reason.
+ *
+ * The guard `firstBlockquote` needs and cannot be: it returns the first `>` line ANYWHERE,
+ * so a spec that opens with prose and quotes something later gets that unrelated line as its
+ * OpenCode/Claude/Bob `description:`, with nothing anywhere reporting it. This asserts the
+ * shape every real spec has — title, then the purpose blockquote — after the authoring
+ * comment is stripped.
+ *
+ * `.replace` with a `g` regex, matching `re.sub`'s replace-all; the Python's pattern is
+ * non-global-looking but `re.sub` always is. `split('\n')` rather than `pySplitLines`: the
+ * text has been through `readText`, and the reason `firstBlockquote` gives for the same
+ * choice applies verbatim to the same files.
+ */
+export function descBlockProblem(text) {
+  const nonblank = text.replace(HTML_COMMENT_RE, '').split('\n').filter((ln) => ln.trim());
+  if (!nonblank.length) return 'file is empty (after stripping authoring comments)';
+  if (!nonblank[0].replace(/^\s+/, '').startsWith('#')) {
+    return `first content line is not a title ('# ...'): ${pyRepr(nonblank[0].trim())}`;
+  }
+  if (nonblank.length < 2) return 'has a title but no purpose blockquote after it';
+  const second = nonblank[1].trim();
+  if (!second.startsWith('>')) {
+    return `first block after the title is not a '>' blockquote: ${pyRepr(second)}`;
+  }
+  if (!second.replace(/^>+/, '').trim()) return 'purpose blockquote is empty';
+  return '';
+}
+
+/** `_build_render._is_readonly`. */
+function isReadonly(text) {
+  return text.includes('Read-only');
+}
+
+/** `_build_emit._strip_skill_body_links`. */
+export function stripSkillBodyLinks(body) {
+  return body.replace(SKILL_BODY_LINK_RE, '$1');
+}
+
+/** `_build_emit._agent_color_map` — validated, always a valid OpenCode slot. */
+function agentColorMap(theme) {
+  let raw = null;
+  if (isPlainObject(theme)) raw = theme.AGENT_COLORS;
+  if (!isPlainObject(raw)) raw = AGENT_COLORS;
+  const cleaned = {};
+  // Insertion order matters: it is the order the warnings below are printed in, and the
+  // parity gate compares the warning stream. Python dicts and JS objects agree on it for
+  // string keys that are not array indices — agent names never are.
+  for (const [k, v] of Object.entries(raw)) {
+    if (VALID_AGENT_COLOR_SLOTS.has(v)) {
+      cleaned[k] = v;
+    } else {
+      warn(`[geneseed] WARN: AGENT_COLORS[${pyRepr(k)}] = ${pyRepr(v)} is not a valid `
+        + `OpenCode theme slot (${[...VALID_AGENT_COLOR_SLOTS].sort().join(', ')}) — `
+        + `falling back to 'secondary'`);
+      cleaned[k] = 'secondary';
+    }
+  }
+  if (!Object.prototype.hasOwnProperty.call(cleaned, '_default')) cleaned._default = 'secondary';
+  return cleaned;
+}
+
+/** `_build_emit._agent_color`. */
+function agentColor(stem, theme) {
+  const colors = agentColorMap(theme);
+  return Object.prototype.hasOwnProperty.call(colors, stem) ? colors[stem] : colors._default;
+}
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** `is not None` — the test that lets a configured `temperature: 0` survive. */
+function given(v) {
+  return v !== undefined && v !== null;
+}
+
+/**
+ * `overrides.get(stem) or {}`.
+ *
+ * The `hasOwnProperty` guard is not ceremony: a bare `overrides[stem]` reaches
+ * `Object.prototype` for an agent named `constructor`, `toString` or `valueOf`, and would
+ * hand back a function where Python hands back `None`.
+ *
+ * Known divergence, recorded rather than papered over: where the value is present but is
+ * NOT an object (a user writing `"reviewer": "haiku"` instead of
+ * `"reviewer": {"model": "haiku"}`), Python raises AttributeError and aborts the emit
+ * while this returns undefined for every key and emits no override lines. Not a byte
+ * difference on any path the gate covers — a difference in which malformed input crashes.
+ */
+function agentOverride(overrides, stem) {
+  return (Object.prototype.hasOwnProperty.call(overrides, stem) && overrides[stem]) || {};
+}
+
+/**
+ * The four optional per-agent override lines.
+ *
+ * Emitted ONLY when configured, so an empty `agent-overrides.json` is zero change. The
+ * `model`/`variant` tests are truthiness and the `temperature`/`steps` tests are
+ * `is not None` — a configured `temperature: 0` must survive, an empty model must not.
+ *
+ * Python spells these four ifs out twice, in `_opencode_agent_frontmatter` and in
+ * `_write_primary_agent`. One owner here rather than a second copy: the two Python
+ * bodies are identical today, and the parity gate drives BOTH call sites, so if they
+ * ever diverge the gate says so instead of the copies silently rotting apart.
+ */
+export function pushOverrideLines(fm, ov) {
+  if (pyTruthy(ov.model)) fm.push(`model: ${pyStr(ov.model)}`);
+  if (given(ov.temperature)) fm.push(`temperature: ${pyStr(ov.temperature)}`);
+  if (pyTruthy(ov.variant)) fm.push(`variant: ${pyStr(ov.variant)}`);
+  if (given(ov.steps)) fm.push(`steps: ${pyStr(ov.steps)}`);
+}
+
+/** `_build_emit._claude_agent_frontmatter`. */
+function claudeAgentFrontmatter(stem, text, overrides) {
+  const fm = [`name: ${stem}`, `description: ${jsonDumps(descOf(text))}`];
+  const ov = agentOverride(overrides, stem);
+  if (pyTruthy(ov.model)) fm.push(`model: ${pyStr(ov.model)}`);
+  if (isReadonly(text)) {
+    const denied = ['Write', 'Edit', 'NotebookEdit', 'WebFetch'];
+    if (!text.includes('<!-- bash: allow -->')) denied.push('Bash');
+    fm.push(`disallowedTools: ${denied.join(', ')}`);
+  }
+  return fm;
+}
+
+/** `_build_emit._copilot_agent_frontmatter` — `tools:` is an ALLOWLIST, not a denylist. */
+function copilotAgentFrontmatter(stem, text, overrides) {
+  const fm = [`name: ${stem}`, `description: ${jsonDumps(descOf(text))}`];
+  const ov = agentOverride(overrides, stem);
+  if (pyTruthy(ov.model)) fm.push(`model: ${pyStr(ov.model)}`);
+  if (isReadonly(text)) {
+    const allowed = ['read', 'search', 'todo', 'agent'];
+    if (text.includes('<!-- bash: allow -->')) allowed.push('execute');
+    fm.push(`tools: [${allowed.join(', ')}]`);
+  }
+  return fm;
+}
+
+/** `_build_emit._opencode_agent_frontmatter`. */
+function opencodeAgentFrontmatter(stem, text, overrides, theme = null) {
+  const fm = [`description: ${jsonDumps(descOf(text))}`, 'mode: subagent'];
+  fm.push(`color: ${agentColor(stem, theme)}`);
+  pushOverrideLines(fm, agentOverride(overrides, stem));
+  if (isReadonly(text)) {
+    fm.push('permission:', '  edit: deny', '  webfetch: deny');
+    if (text.includes('<!-- bash: allow -->')) fm.push('  bash:', '    "*": ask');
+    else fm.push('  bash: deny');
+  }
+  return fm;
+}
+
+/** `_build_emit._load_agent_overrides`. */
+export function loadAgentOverrides(base) {
+  let data;
+  try {
+    // parseJson, not JSON.parse: the override values are rendered with `pyStr`, which
+    // needs the int/float distinction the raw literal carries and `JSON.parse` discards.
+    data = parseJson(readText(path.join(base, 'agent-overrides.json')));
+  } catch {
+    // Missing or malformed => no overrides, so agents inherit the host model.
+    // Wider than Python's `except (OSError, json.JSONDecodeError)` by one case: a file
+    // that is not valid UTF-8 raises UnicodeDecodeError there and aborts the emit, where
+    // Node's 'utf8' decode substitutes U+FFFD and this degrades to `{}`. Recorded rather
+    // than reproduced — matching it means detecting a decode error Node does not report.
+    return {};
+  }
+  const agents = isPlainObject(data) ? data.agents : null;
+  return isPlainObject(agents) ? agents : {};
+}
+
+/** `Path.relative_to(base).as_posix()`. */
+function relPosix(base, target) {
+  return path.relative(base, target).split(path.sep).join('/');
+}
+
+/**
+ * `_build_emit._write_native_layer`.
+ *
+ * `items` are `render_all`'s, as `{ rel, text, src }` — `text` null for a binary that is
+ * copied rather than rendered. `src` is the absolute source path; `opts.src` is the
+ * source root it is relativised against (Python reads `_build_core.SRC` directly, which
+ * is the module-level single owner; here it travels explicitly, as in `js/render.mjs`).
+ *
+ * Returns `{ nAgents, nSkills, written }` — Python's 3-tuple, with `written` as absolute
+ * paths in write order.
+ *
+ * That order is NOT observable, and this comment used to claim it was ("it lands in
+ * `owned`, which the prune diffs against"). Measured when a mutation reversing it stayed
+ * green: all three manifest writers spell `"owned": sorted(owned)` and every prune is
+ * `set(old_owned) - set(owned)`, so the sequence is erased on both sides. Write order is
+ * kept because it mirrors the Python and costs nothing, not because anything reads it —
+ * the same distinction `themed_rel` earned, and the reason the mutation is recorded here
+ * rather than papered over with a cell that cannot exist.
+ */
+export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null, {
+  host = 'opencode', oldOwned = null, cfg = null, manifestExisted = true,
+  theme = null, src,
+} = {}) {
+  const ov = overrides || {};
+  const oldSet = oldOwned !== null && oldOwned !== undefined ? new Set(oldOwned) : null;
+  let nAgents = 0;
+  let nSkills = 0;
+  const written = [];
+  let headerPrinted = false;
+
+  // True -> ok to (over)write; false -> a pre-existing file we never owned, so it is the
+  // user's: leave it, warn, and keep it out of the manifest.
+  const claim = (dest) => {
+    if (oldSet === null || cfg === null || !existsSync(dest)) return true;
+    const rel = relPosix(cfg, dest);
+    if (oldSet.has(rel)) return true;
+    if (!manifestExisted && !headerPrinted) {
+      warn('[geneseed] first emit over a pre-manifest install — existing files '
+        + 'are treated as yours');
+      headerPrinted = true;
+    }
+    warn(`[geneseed] kept your existing ${rel} — skipped Geneseed's copy to avoid `
+      + 'clobbering it');
+    return false;
+  };
+
+  const write = (dest, text) => {
+    mkdirSync(path.dirname(dest), { recursive: true });
+    writeText(dest, text);
+    written.push(dest);
+  };
+
+  for (const { text, src: source } of items) {
+    const sparts = relPosix(src, source).split('/');
+
+    // Vendored third-party skill folders ride along verbatim, preserving their own
+    // multi-file layout — copied through, NOT wrapped as a native SKILL.md, and never
+    // counted as harness skills.
+    // `isVendoredPath`, not a fourth copy of the same three clauses: P5g gave the predicate a
+    // second caller (`doctor`'s bundle scan) and the byte gate is what licenses the merge.
+    if (isVendoredPath(relPosix(src, source))) {
+      const dest = path.join(skillsDir, ...sparts.slice(1));
+      if (!claim(dest)) continue;
+      mkdirSync(path.dirname(dest), { recursive: true });
+      // The same vendored folder mixes both writers: a rendered `.md` goes through
+      // writeText (and picks up CRLF on Windows), a binary through copy2 (and keeps LF).
+      if (text !== null) writeText(dest, text);
+      else copyFile(source, dest);
+      written.push(dest);
+      continue;
+    }
+    if (text === null) continue;
+    if (sparts.length !== 2 || !sparts[1].endsWith('.md')) continue;
+    const [folder, fname] = sparts;
+    const targetDir = { agents: agentsDir, skills: skillsDir }[folder];
+    if (targetDir === undefined) continue;
+
+    if (fname.startsWith('_')) {
+      // Authoring templates are shipped verbatim and FLAT — not wrapped as a native
+      // skill — so an author following the `_template.md` note has the scaffold on disk.
+      const dest = path.join(targetDir, fname);
+      if (!claim(dest)) continue;
+      write(dest, lstripNewlines(text));
+      continue;
+    }
+
+    const stem = fname.slice(0, -3);
+    let body = lstripNewlines(text);
+    let fm;
+    let dest;
+    let kind;
+    if (folder === 'agents') {
+      if (host === 'claude') {
+        fm = claudeAgentFrontmatter(stem, text, ov);
+        dest = path.join(agentsDir, `${stem}.md`);
+      } else if (host === 'copilot') {
+        fm = copilotAgentFrontmatter(stem, text, ov);
+        dest = path.join(agentsDir, `${stem}.agent.md`);
+        // The filename change drags the links with it: a sibling `](skeptic.md)` would
+        // point at a file this dialect never writes.
+        body = body.replace(SIBLING_AGENT_LINK_RE, ']($1.agent.md)');
+      } else {
+        fm = opencodeAgentFrontmatter(stem, text, ov, theme);
+        dest = path.join(agentsDir, `${stem}.md`);
+      }
+      kind = 'agent';
+    } else {
+      // Skills are BYTE-IDENTICAL across hosts: name + description, body link-stripped.
+      fm = [`name: ${stem}`, `description: ${jsonDumps(descOf(text))}`];
+      body = stripSkillBodyLinks(body);
+      dest = path.join(skillsDir, stem, 'SKILL.md');
+      kind = 'skill';
+    }
+    if (!claim(dest)) continue;
+    write(dest, `---\n${fm.join('\n')}\n---\n\n${body}`);
+    if (kind === 'agent') nAgents += 1;
+    else nSkills += 1;
+  }
+  return { nAgents, nSkills, written };
+}
+
+/**
+ * `str.lstrip("\n")` — only newlines, not all whitespace.
+ *
+ * Currently a no-op on every input the generator produces: measured, no file under `src/`
+ * and no rendered spec in any of the 14 themes begins with a newline. Mutating it away
+ * leaves the parity gate green, and that is correct rather than a hole — there is no
+ * reachable behaviour to detect. Kept because it is what the Python does, and a spec
+ * author adding a leading blank line is one commit away from making it matter.
+ */
+function lstripNewlines(text) {
+  return text.replace(/^\n+/, '');
+}