@ucsandman/legcli 0.8.0 → 0.9.0

package/src/harness/vendor/agnostic-ai/engine/harness/apply.cjs

@@ -0,0 +1,247 @@
+/**
+ * engine/harness/apply.cjs — render the captured bundle into every other client.
+ *
+ * One guarded write per file, one ComponentResult per component, one row per
+ * target. The source client is never written to: it is the thing being copied.
+ * Everything a target could not take lands in `dropped` with a reason, which is
+ * what `npm run explain` prints.
+ *
+ * Contract for `ctx` and ComponentResult: engine/harness/README.md.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const common = require('./common.cjs');
+const bundleMod = require('./bundle.cjs');
+const { loadRegistry, loadPort } = require('./capture.cjs');
+
+const ROOT = common.ROOT;
+const DEFAULT_STORAGE = path.join(ROOT, 'storage');
+const TARGETS_DIR = path.join(__dirname, 'targets');
+
+const GLYPH = { synced: '✓', written: '●', stale: '✗', skipped: '!', unsupported: '-', error: 'E', source: '=' };
+const ABBR = { rules: 'ru', identity: 'id', hooks: 'ho', skills: 'sk', agents: 'ag', commands: 'cm', mcp: 'mc', permissions: 'pm' };
+// Worst-first: a target's headline status is the worst thing that happened to it.
+const SEVERITY = ['error', 'stale', 'skipped', 'written', 'synced', 'unsupported'];
+
+const LEGEND = `legend: ${GLYPH.synced} synced  ${GLYPH.written} written  ${GLYPH.stale} stale  ${GLYPH.skipped} skipped (hand-edited)  ${GLYPH.unsupported} unsupported  ${GLYPH.error} error  ${GLYPH.source} source`;
+
+function readState(file) {
+  const state = common.readJSON(file);
+  if (!state || typeof state !== 'object' || !state.targets) return { version: 1, targets: {} };
+  return state;
+}
+
+/** Load `targets/<adapter>.cjs`, naming the missing module when it is not there. */
+function loadTargetAdapter(adapterId) {
+  const file = path.join(TARGETS_DIR, `${adapterId}.cjs`);
+  try {
+    return require(file);
+  } catch (err) {
+    if (!fs.existsSync(file)) {
+      throw new Error(`missing module engine/harness/targets/${adapterId}.cjs — no render adapter for "${adapterId}" (it must export { id, components, <component>(ctx) })`);
+    }
+    throw err;
+  }
+}
+
+/** Which registry entries this run writes to, and why. Throws on an unknown --to id. */
+function selectTargets(registry, { to, port }) {
+  if (Array.isArray(to) && to.length) {
+    const known = new Set(registry.map((t) => t.id));
+    const unknown = to.filter((id) => !known.has(id));
+    if (unknown.length) throw new Error(`unknown target id(s): ${unknown.join(', ')} (known: ${registry.map((t) => t.id).join(', ')})`);
+    return registry.filter((t) => to.includes(t.id));
+  }
+  const policy = (port && port.targets) || 'installed';
+  if (Array.isArray(policy)) return registry.filter((t) => policy.includes(t.id));
+  if (policy === 'all') return registry.slice();
+  return registry.filter((t) => t.installed);
+}
+
+function rollUp(components) {
+  const seen = new Set(Object.values(components).map((r) => r.status));
+  for (const status of SEVERITY) if (seen.has(status)) return status;
+  return 'synced';
+}
+
+function countFiles(report) {
+  const totals = { written: 0, wouldWrite: 0, unchanged: 0, skipped: 0, dropped: 0 };
+  for (const target of Object.values(report.targets)) {
+    for (const result of Object.values(target.components || {})) {
+      for (const file of result.files || []) {
+        if (file.action === 'written' || file.action === 'linked') totals.written++;
+        else if (file.action === 'would-write' || file.action === 'would-link') totals.wouldWrite++;
+        else if (file.action === 'unchanged') totals.unchanged++;
+        else if (String(file.action || '').startsWith('skipped')) totals.skipped++;
+      }
+      totals.dropped += (result.dropped || []).length;
+    }
+  }
+  return totals;
+}
+
+/** The compact matrix: one row per target, one cell per component. */
+function formatTable(report) {
+  const ids = Object.keys(report.targets);
+  const nameWidth = Math.max(6, ...ids.map((id) => report.targets[id].name.length));
+  const head = ['Target'.padEnd(nameWidth), ...bundleMod.COMPONENTS.map((c) => ABBR[c])].join(' ') + '  dropped';
+  const lines = [head, '-'.repeat(head.length)];
+  for (const id of ids) {
+    const t = report.targets[id];
+    const cells = bundleMod.COMPONENTS.map((c) => {
+      if (t.status === 'source') return GLYPH.source.padEnd(2);
+      const result = (t.components || {})[c];
+      return (result ? GLYPH[result.status] || '?' : GLYPH.unsupported).padEnd(2);
+    });
+    const dropped = String(t.dropped || 0).padStart(7);
+    const note = t.status === 'source' ? '  source of truth' : t.installed ? (t.note ? `  ${t.note}` : '') : '  not installed';
+    lines.push(`${t.name.padEnd(nameWidth)} ${cells.join(' ')} ${dropped}${note}`);
+  }
+  const totals = report.totals;
+  const verb = report.mode === 'apply' ? 'files written' : 'files would change';
+  const changed = report.mode === 'apply' ? totals.written : totals.wouldWrite;
+  lines.push('');
+  lines.push(`${ids.length} targets, ${changed} ${verb}, ${totals.unchanged} unchanged, ${totals.skipped} skipped, ${totals.dropped} dropped  [${report.mode}]`);
+  lines.push(LEGEND);
+  return lines.join('\n');
+}
+
+/**
+ * apply({ bundle, bundleDir, home, port, to, check, dryRun, force, storageDir, adapters, registry, log, quiet }) -> report
+ *
+ * `adapters` maps a target id (or an adapter id) to an already-loaded module and
+ * replaces the require — the tests inject stubs through it. `registry` is an
+ * already-expanded target list for a host that ships its own.
+ */
+function apply(options = {}) {
+  const {
+    bundleDir, home = os.homedir(), to, check = false, dryRun = false, force = false,
+    adapters = {}, quiet = false, registry: givenRegistry = null,
+  } = options;
+  const log = options.log || ((line) => { if (!quiet) console.log(line); });
+  const storageDir = options.storageDir || DEFAULT_STORAGE;
+
+  const bundle = options.bundle || bundleMod.load(bundleDir || bundleMod.DEFAULT_DIR);
+  if (!bundle) throw new Error('no bundle captured yet; run npm run capture');
+  const port = options.port || loadPort();
+
+  const registry = givenRegistry || loadRegistry(home);
+  const selected = selectTargets(registry, { to: Array.isArray(to) ? to : to ? String(to).split(',') : null, port });
+  const sourceId = bundle.manifest && bundle.manifest.source;
+
+  const stateFile = path.join(storageDir, 'harness-state.json');
+  const backupsDir = path.join(storageDir, 'backups');
+  const state = readState(stateFile);
+  const readOnly = Boolean(check || dryRun);
+
+  const report = {
+    appliedAt: new Date().toISOString(),
+    source: sourceId || null,
+    mode: check ? 'check' : dryRun ? 'dry-run' : 'apply',
+    bundle: {
+      source: sourceId || null,
+      capturedAt: (bundle.manifest && bundle.manifest.capturedAt) || null,
+      components: (bundle.manifest && bundle.manifest.components) || {},
+    },
+    targets: {},
+  };
+
+  for (const target of selected) {
+    const row = {
+      id: target.id,
+      name: target.name,
+      category: target.category || 'Agent',
+      installed: target.installed,
+      adapter: target.adapter || 'generic',
+      home: target.home || null,
+      status: 'synced',
+      components: {},
+      dropped: 0,
+    };
+    report.targets[target.id] = row;
+
+    if (target.id === sourceId) {
+      row.status = 'source';
+      row.note = 'source of truth; never written';
+      continue;
+    }
+
+    let adapter = adapters[target.id] || adapters[target.adapter || 'generic'];
+    if (!adapter) {
+      try {
+        adapter = loadTargetAdapter(target.adapter || 'generic');
+      } catch (err) {
+        row.status = 'error';
+        row.error = err.message;
+        row.note = err.message;
+        for (const component of bundleMod.COMPONENTS) row.components[component] = { status: 'error', files: [], dropped: [], error: err.message };
+        continue;
+      }
+    }
+
+    const targetState = state.targets[target.id] || (state.targets[target.id] = {});
+    targetState.files = targetState.files || {};
+    targetState.drift = targetState.drift || {};
+    targetState.owned = targetState.owned || {};
+
+    const ctx = {
+      target,
+      bundle,
+      port,
+      home,
+      // check is the "write nothing" flag adapters gate every deletion and prune
+      // on, so a --dry-run must set it too. dryRun stays separate: it only means
+      // "say more about what would change".
+      check: readOnly,
+      dryRun: Boolean(dryRun),
+      force: Boolean(force),
+      state: targetState,
+      write: common.makeWriter({ state: targetState, backupsDir, tag: target.id, check: readOnly, force, log }),
+      // a generated file about to be pruned gets the same backup an overwrite gets
+      backup: (file) => (fs.existsSync(file) ? common.backupFile(backupsDir, target.id, file) : null),
+      link: (src, dest) => common.link(src, dest, { check: readOnly }),
+      log,
+    };
+
+    for (const component of bundleMod.COMPONENTS) {
+      if (typeof adapter[component] !== 'function') {
+        row.components[component] = { status: 'unsupported', files: [], dropped: [], note: `adapter has no ${component}` };
+        continue;
+      }
+      let result;
+      try {
+        result = adapter[component](ctx) || {};
+      } catch (err) {
+        result = { status: 'error', error: err.message };
+      }
+      result.files = result.files || [];
+      result.dropped = result.dropped || [];
+      result.status = result.status || 'synced';
+      row.components[component] = result;
+      row.dropped += result.dropped.length;
+    }
+    row.status = rollUp(row.components);
+  }
+
+  report.totals = Object.assign({ targets: selected.length }, countFiles(report));
+  report.totals.syncedTargets = Object.values(report.targets).filter((t) => t.status === 'synced' || t.status === 'source').length;
+  report.stale = Object.values(report.targets).some((t) =>
+    Object.values(t.components || {}).some((r) =>
+      r.status === 'stale' || r.status === 'written' ||
+      (r.files || []).some((f) => f.action === 'would-write' || f.action === 'would-link')));
+
+  if (!readOnly) {
+    fs.mkdirSync(storageDir, { recursive: true });
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  }
+  fs.mkdirSync(storageDir, { recursive: true });
+  fs.writeFileSync(path.join(storageDir, 'harness-report.json'), JSON.stringify(report, null, 2) + '\n', 'utf8');
+
+  log(formatTable(report));
+  return report;
+}
+
+module.exports = { apply, selectTargets, formatTable, loadTargetAdapter, readState, GLYPH, ABBR, LEGEND, DEFAULT_STORAGE };

package/src/harness/vendor/agnostic-ai/engine/harness/bundle.cjs

@@ -0,0 +1,243 @@
+/**
+ * engine/harness/bundle.cjs — the client-neutral harness bundle.
+ *
+ * On disk: <repo>/harness/ (gitignored by default; it holds machine paths).
+ * In memory: the object returned by createBundle(). See README.md for the shape.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { ROOT, looksSecret, findSecrets, redactSecrets, urlCarriesCredential, parseFrontmatter, renderFrontmatter } = require('./common.cjs');
+
+const BUNDLE_VERSION = '1';
+const DEFAULT_DIR = path.join(ROOT, 'harness');
+const COMPONENTS = ['rules', 'identity', 'hooks', 'skills', 'agents', 'commands', 'mcp', 'permissions'];
+const MODEL_TIERS = ['fable', 'opus', 'sonnet', 'haiku', 'inherit'];
+
+function createBundle(source = 'unknown', sourceHome = '') {
+  return {
+    manifest: { version: BUNDLE_VERSION, source, sourceHome, capturedAt: null, components: {} },
+    rules: '',
+    identity: '',
+    hooks: { dialect: 'claude', events: {} },
+    mcp: { servers: {} },
+    agents: [],      // [{ name, meta: { name, description, model, tools, readonly }, body }]
+    commands: [],    // [{ name, meta: { description, 'argument-hint' }, body }]
+    skills: { sourceDir: '', skills: [] },  // [{ name, path }]
+    permissions: { allow: [], deny: [], ask: [] },
+  };
+}
+
+function counts(bundle) {
+  const hookCount = Object.values(bundle.hooks.events || {}).reduce((n, groups) => n + groups.reduce((m, g) => m + (g.hooks || []).length, 0), 0);
+  return {
+    rules: bundle.rules ? 1 : 0,
+    identity: bundle.identity ? 1 : 0,
+    hooks: hookCount,
+    skills: bundle.skills.skills.length,
+    agents: bundle.agents.length,
+    commands: bundle.commands.length,
+    mcp: Object.keys(bundle.mcp.servers).length,
+    permissions: bundle.permissions.allow.length + bundle.permissions.deny.length + bundle.permissions.ask.length,
+  };
+}
+
+// A long value with no key context is only called a credential when it also
+// has the shape of one (findSecrets covers the known prefixes).
+const highLike = (v) => v.length >= 32 && !/\s/.test(v) && !/[\\/]/.test(v);
+
+/** Structural validation. Returns an array of problems (empty = valid). */
+function validate(bundle) {
+  const problems = [];
+  if (!bundle || typeof bundle !== 'object') return ['bundle is not an object'];
+  if (typeof bundle.rules !== 'string' || !bundle.rules.trim()) problems.push('rules.md is empty');
+  if (!bundle.hooks || typeof bundle.hooks.events !== 'object') problems.push('hooks.json needs an events object');
+  for (const [event, groups] of Object.entries((bundle.hooks && bundle.hooks.events) || {})) {
+    if (!Array.isArray(groups)) { problems.push(`hooks.events.${event} must be an array`); continue; }
+    groups.forEach((g, i) => {
+      if (!Array.isArray(g.hooks)) problems.push(`hooks.events.${event}[${i}].hooks must be an array`);
+      else g.hooks.forEach((h, j) => {
+        if (h.type !== 'command' || typeof h.command !== 'string' || !h.command) problems.push(`hooks.events.${event}[${i}].hooks[${j}] needs type "command" and a command string`);
+      });
+    });
+  }
+  // A credential anywhere in the bundle is a credential copied into every
+  // client: every free-text field and every command line is scanned, not only
+  // the two env maps.
+  if (findSecrets(bundle.rules).length) problems.push('rules.md carries a credential-shaped value');
+  if (findSecrets(bundle.identity).length) problems.push('identity.md carries a credential-shaped value');
+  for (const [event, groups] of Object.entries((bundle.hooks && bundle.hooks.events) || {})) {
+    if (!Array.isArray(groups)) continue;
+    groups.forEach((g, i) => (g.hooks || []).forEach((h, j) => {
+      if (h && typeof h.command === 'string' && findSecrets(h.command).length) problems.push(`hooks.events.${event}[${i}].hooks[${j}].command carries a credential-shaped value`);
+    }));
+  }
+  for (const [name, s] of Object.entries((bundle.mcp && bundle.mcp.servers) || {})) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(name)) problems.push(`mcp server name "${name}" is not a safe identifier`);
+    for (const a of s.args || []) if (typeof a === 'string' && (findSecrets(a).length || looksSecret('arg', a) && highLike(a))) problems.push(`mcp.${name}.args carries a credential-shaped value`);
+    if (typeof s.url === 'string' && (findSecrets(s.url).length || urlCarriesCredential(s.url))) problems.push(`mcp.${name}.url carries a credential (userinfo, a secret query value or a token in the path)`);
+    if (!['stdio', 'http', 'sse'].includes(s.transport)) problems.push(`mcp.${name}.transport must be stdio, http or sse`);
+    if (s.transport === 'stdio' && !s.command) problems.push(`mcp.${name} (stdio) needs a command`);
+    if (s.transport !== 'stdio' && !s.url) problems.push(`mcp.${name} (${s.transport}) needs a url`);
+    for (const [k, v] of Object.entries(s.env || {})) if (looksSecret(k, v)) problems.push(`mcp.${name}.env.${k} looks like a secret; capture must replace it with \${${k}}`);
+    for (const [k, v] of Object.entries(s.headers || {})) if (looksSecret(k, v)) problems.push(`mcp.${name}.headers.${k} looks like a secret; capture must replace it with \${${k}}`);
+  }
+  for (const a of bundle.agents || []) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(a.name)) problems.push(`agent name "${a.name}" must be kebab-case`);
+    if (!a.meta || typeof a.meta.description !== 'string') problems.push(`agent ${a.name} needs a description`);
+    if (findSecrets(a.body).length) problems.push(`agent ${a.name} carries a credential-shaped value`);
+  }
+  for (const c of bundle.commands || []) {
+    if (!/^[A-Za-z0-9_-]+$/.test(c.name)) problems.push(`command name "${c.name}" is not a safe file name`);
+    if (findSecrets(c.body).length) problems.push(`command ${c.name} carries a credential-shaped value`);
+  }
+  for (const s of (bundle.skills && bundle.skills.skills) || []) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(s.name) || s.name === '.' || s.name === '..') problems.push(`skill name "${s.name}" is not a safe directory name`);
+    if (!path.isAbsolute(s.path || '')) problems.push(`skill ${s.name} needs an absolute path`);
+  }
+  return problems;
+}
+
+/**
+ * Make a captured bundle saveable without losing the harness: free text is
+ * redacted in place, and a hook handler, an MCP argument or URL, an agent or a
+ * command that cannot be carried safely is dropped. Returns the warnings, one
+ * per change, so the operator sees exactly what did not travel and why.
+ * capture() calls this before save(); validate() still refuses what remains.
+ */
+function sanitize(bundle) {
+  const warnings = [];
+  const redactText = (label, text) => {
+    const hits = findSecrets(text);
+    if (!hits.length) return text;
+    warnings.push(`${label}: ${hits.length} credential-shaped value(s) redacted; the bundle carries [REDACTED] instead`);
+    return redactSecrets(text);
+  };
+  bundle.rules = redactText('rules', bundle.rules);
+  bundle.identity = redactText('identity', bundle.identity);
+  for (const [event, groups] of Object.entries((bundle.hooks && bundle.hooks.events) || {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const g of groups) {
+      const kept = [];
+      for (const h of g.hooks || []) {
+        if (h && typeof h.command === 'string' && findSecrets(h.command).length) warnings.push(`hooks.${event}: a handler command carries a credential-shaped value; the hook is not carried`);
+        else kept.push(h);
+      }
+      g.hooks = kept;
+    }
+    bundle.hooks.events[event] = groups.filter((g) => (g.hooks || []).length);
+    if (!bundle.hooks.events[event].length) delete bundle.hooks.events[event];
+  }
+  for (const [name, s] of Object.entries((bundle.mcp && bundle.mcp.servers) || {})) {
+    const badArg = (s.args || []).some((a) => typeof a === 'string' && (findSecrets(a).length || (looksSecret('arg', a) && highLike(a))));
+    const badUrl = typeof s.url === 'string' && (findSecrets(s.url).length || urlCarriesCredential(s.url));
+    if (badArg || badUrl) {
+      warnings.push(`mcp.${name}: ${badUrl ? 'the url' : 'an argument'} carries a credential; the server is not carried (move it to an env reference)`);
+      delete bundle.mcp.servers[name];
+    }
+  }
+  bundle.agents = (bundle.agents || []).filter((a) => {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(a.name)) { warnings.push(`agent "${a.name}" is not kebab-case; not carried`); return false; }
+    a.body = redactText(`agent ${a.name}`, a.body);
+    return true;
+  });
+  bundle.commands = (bundle.commands || []).filter((c) => {
+    if (!/^[A-Za-z0-9_-]+$/.test(c.name)) { warnings.push(`command "${c.name}" is not a safe file name; not carried`); return false; }
+    c.body = redactText(`command ${c.name}`, c.body);
+    return true;
+  });
+  bundle.skills.skills = (bundle.skills.skills || []).filter((s) => {
+    if (!/^[A-Za-z0-9_.-]+$/.test(s.name) || s.name === '.' || s.name === '..') { warnings.push(`skill "${s.name}" is not a safe directory name; not carried`); return false; }
+    return true;
+  });
+  return warnings;
+}
+
+function canonical(v) {
+  if (Array.isArray(v)) return v.map(canonical);
+  if (v && typeof v === 'object') {
+    const o = {};
+    for (const k of Object.keys(v).sort()) o[k] = canonical(v[k]);
+    return o;
+  }
+  return v;
+}
+
+/**
+ * A content hash of everything a target renders from: the same source state
+ * captured twice gives the same fingerprint, whatever the capture time. The
+ * manifest is left out (it carries the timestamp). A host uses it to answer
+ * "did the harness change since the last sync" without diffing files.
+ */
+function fingerprint(bundle) {
+  const body = canonical({
+    rules: bundle.rules, identity: bundle.identity, hooks: bundle.hooks, mcp: bundle.mcp,
+    skills: bundle.skills, permissions: bundle.permissions,
+    agents: (bundle.agents || []).map((a) => ({ name: a.name, meta: a.meta, body: a.body })),
+    commands: (bundle.commands || []).map((c) => ({ name: c.name, meta: c.meta, body: c.body })),
+  });
+  return crypto.createHash('sha256').update(JSON.stringify(body), 'utf8').digest('hex');
+}
+
+function save(bundle, dir = DEFAULT_DIR) {
+  const problems = validate(bundle);
+  if (problems.length) throw new Error(`refusing to save an invalid bundle:\n  - ${problems.join('\n  - ')}`);
+  bundle.manifest.capturedAt = bundle.manifest.capturedAt || new Date().toISOString();
+  bundle.manifest.components = counts(bundle);
+  bundle.manifest.fingerprint = fingerprint(bundle);
+  fs.mkdirSync(dir, { recursive: true });
+  const w = (name, text) => fs.writeFileSync(path.join(dir, name), text, 'utf8');
+  w('manifest.json', JSON.stringify(bundle.manifest, null, 2) + '\n');
+  w('rules.md', bundle.rules.trimEnd() + '\n');
+  if (bundle.identity) w('identity.md', bundle.identity.trimEnd() + '\n');
+  else if (fs.existsSync(path.join(dir, 'identity.md'))) fs.unlinkSync(path.join(dir, 'identity.md'));
+  w('hooks.json', JSON.stringify(bundle.hooks, null, 2) + '\n');
+  w('mcp.json', JSON.stringify(bundle.mcp, null, 2) + '\n');
+  w('skills.json', JSON.stringify(bundle.skills, null, 2) + '\n');
+  w('permissions.json', JSON.stringify(bundle.permissions, null, 2) + '\n');
+  for (const [sub, items] of [['agents', bundle.agents], ['commands', bundle.commands]]) {
+    const subdir = path.join(dir, sub);
+    fs.rmSync(subdir, { recursive: true, force: true });
+    fs.mkdirSync(subdir, { recursive: true });
+    for (const it of items) fs.writeFileSync(path.join(subdir, `${it.name}.md`), renderFrontmatter(it.meta, it.body), 'utf8');
+  }
+  return dir;
+}
+
+function load(dir = DEFAULT_DIR) {
+  if (!fs.existsSync(path.join(dir, 'manifest.json'))) return null;
+  const read = (name, fallback) => (fs.existsSync(path.join(dir, name)) ? fs.readFileSync(path.join(dir, name), 'utf8') : fallback);
+  const json = (name, fallback) => { const t = read(name, null); return t == null ? fallback : JSON.parse(t); };
+  const bundle = createBundle();
+  bundle.manifest = json('manifest.json', bundle.manifest);
+  bundle.rules = read('rules.md', '');
+  bundle.identity = read('identity.md', '');
+  bundle.hooks = json('hooks.json', bundle.hooks);
+  bundle.mcp = json('mcp.json', bundle.mcp);
+  bundle.skills = json('skills.json', bundle.skills);
+  bundle.permissions = json('permissions.json', bundle.permissions);
+  for (const sub of ['agents', 'commands']) {
+    const subdir = path.join(dir, sub);
+    if (!fs.existsSync(subdir)) continue;
+    for (const f of fs.readdirSync(subdir).filter((n) => n.endsWith('.md')).sort()) {
+      const { meta, body } = parseFrontmatter(fs.readFileSync(path.join(subdir, f), 'utf8'));
+      bundle[sub].push({ name: f.replace(/\.md$/, ''), meta, body: body.trim() });
+    }
+  }
+  const problems = validate(bundle);
+  if (problems.length) throw new Error(`harness bundle at ${dir} is invalid:\n  - ${problems.join('\n  - ')}`);
+  return bundle;
+}
+
+/**
+ * Normalise a model reference into a tier when possible. "claude-opus-5" -> "opus",
+ * "sonnet" -> "sonnet", "gpt-5.6-terra" -> unchanged (raw id, targets map by ladder or pass through).
+ */
+function modelTier(model) {
+  const m = String(model || 'inherit').toLowerCase();
+  for (const tier of MODEL_TIERS) if (m === tier || m.includes(tier)) return tier;
+  return model;
+}
+
+module.exports = { BUNDLE_VERSION, DEFAULT_DIR, COMPONENTS, MODEL_TIERS, createBundle, counts, validate, sanitize, save, load, modelTier, fingerprint };

package/src/harness/vendor/agnostic-ai/engine/harness/capture.cjs

@@ -0,0 +1,119 @@
+/**
+ * engine/harness/capture.cjs — read ONE live client into the neutral bundle.
+ *
+ * The source client is the harness the user actually drives. Everything else is
+ * a rendering of it. Nothing here knows a client format: the per-client reader
+ * is `sources/<id>.cjs` and the contract is engine/harness/README.md.
+ *
+ * Also the home of `loadRegistry()` — the target list with every path expanded
+ * and `installed` decided by what is on disk. apply and status both read it.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { ROOT, expandPath } = require('./common.cjs');
+const bundleMod = require('./bundle.cjs');
+
+const TARGETS_FILE = path.join(ROOT, 'core', 'templates', 'targets.json');
+const PORT_FILE = path.join(ROOT, 'core', 'port.json');
+const SOURCES_DIR = path.join(__dirname, 'sources');
+
+/** Registry fields that hold a path and therefore get expanded against `home`. */
+const PATH_FIELDS = [
+  'home', 'rulesFile', 'traitsFile', 'hooksConfigFile', 'skillsDir',
+  'agentsDir', 'commandsDir', 'mcpConfigFile', 'permissionsFile',
+];
+
+/**
+ * The target registry with every path field expanded to an absolute path and
+ * `installed` read from disk. A target with no `home` (the generic system card)
+ * is a file we own, so it is always installed.
+ */
+function loadRegistry(home = os.homedir(), { file = TARGETS_FILE, targets = null } = {}) {
+  const raw = Array.isArray(targets) ? { targets } : JSON.parse(fs.readFileSync(file, 'utf8'));
+  return (raw.targets || []).map((t) => {
+    const target = Object.assign({}, t);
+    for (const field of PATH_FIELDS) if (t[field]) target[field] = expandPath(t[field], home);
+    if (Array.isArray(t.sharedSkillDirs)) target.sharedSkillDirs = t.sharedSkillDirs.map((p) => expandPath(p, home));
+    target.installed = t.home ? fs.existsSync(target.home) : true;
+    return target;
+  });
+}
+
+/** core/port.json — the port policy. Missing file = defaults, never a crash. */
+function loadPort(file = PORT_FILE) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) {
+    return { source: 'auto', targets: 'installed' };
+  }
+}
+
+/**
+ * Which client is the source of truth, decided from disk alone: the rules file
+ * a user of that client necessarily has. Returns null when neither is present.
+ */
+function detectSource(home = os.homedir()) {
+  if (fs.existsSync(path.join(home, '.claude', 'CLAUDE.md'))) return 'claude';
+  if (fs.existsSync(path.join(home, '.codex', 'AGENTS.md'))) return 'codex';
+  return null;
+}
+
+function resolveSourceId({ from, port, home }) {
+  if (from) return from;
+  if (port && port.source && port.source !== 'auto') return port.source;
+  const detected = detectSource(home);
+  if (detected) return detected;
+  throw new Error('no source client found; pass --from');
+}
+
+/** Load `sources/<id>.cjs`, telling the user exactly which module is missing. */
+function loadSourceAdapter(id) {
+  const file = path.join(SOURCES_DIR, `${id}.cjs`);
+  try {
+    return require(file);
+  } catch (err) {
+    if (!fs.existsSync(file)) {
+      throw new Error(`missing module engine/harness/sources/${id}.cjs — no capture adapter for source client "${id}" (it must export { id, capture({ home, target, port }) })`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * capture({ from, home, port, outDir, registry, sources }) -> { bundle, warnings, dir }
+ * Reads the source client and writes <repo>/harness/ (or outDir).
+ *
+ * `registry` is an already-expanded target list (loadRegistry()) for a host
+ * that ships its own; `sources` maps a source id to an adapter module and
+ * replaces the require, the way `adapters` does for apply().
+ */
+function capture({ from, home = os.homedir(), port, outDir, registry, sources = {} } = {}) {
+  const policy = port || loadPort();
+  const id = resolveSourceId({ from, port: policy, home });
+  const target = (registry || loadRegistry(home)).find((t) => t.id === id);
+  if (!target) throw new Error(`source client "${id}" is not in the target registry`);
+
+  const adapter = sources[id] || loadSourceAdapter(id);
+  if (typeof adapter.capture !== 'function') throw new Error(`engine/harness/sources/${id}.cjs does not export capture()`);
+
+  const result = adapter.capture({ home, target, port: policy }) || {};
+  const bundle = result.bundle;
+  if (!bundle) throw new Error(`engine/harness/sources/${id}.cjs returned no bundle`);
+  const warnings = result.warnings || [];
+  // Whatever the adapter kept, a credential does not travel: free text is
+  // redacted, an unsafe handler or server or a malformed item is dropped with
+  // a warning, and save() still refuses anything that slipped through.
+  warnings.push(...bundleMod.sanitize(bundle));
+
+  bundle.manifest.source = bundle.manifest.source && bundle.manifest.source !== 'unknown' ? bundle.manifest.source : id;
+  bundle.manifest.sourceHome = bundle.manifest.sourceHome || (target.home || home);
+  bundle.manifest.capturedAt = new Date().toISOString();
+
+  const dir = bundleMod.save(bundle, outDir || bundleMod.DEFAULT_DIR);
+  return { bundle, warnings, dir };
+}
+
+module.exports = { capture, detectSource, resolveSourceId, loadRegistry, loadPort, TARGETS_FILE, PORT_FILE };