@gcunharodrigues/wrxn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guilherme Cunha Rodrigues
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# wrxn
+
+The WRXN Kernel — an installable AI operating system. One kernel, two install profiles
+(`project` | `workspace`), pull-based updates, and a managed/seeded/state file-class engine
+so an update can never overwrite your config or touch your data.
+
+> **Status: walking skeleton** (wrxn-kernel-05). This is the first tracer — the file-class
+> install engine plus a minimal payload. The full pipeline, intelligence layer, worktree
+> lifecycle, and `wrxn update`/`connect` land in later slices. PRD provenance: the WRXN Kernel
+> extraction grill (12 locked decisions, 2026-06-12).
+
+## Usage
+
+```sh
+wrxn --version                       # print the kernel version
+wrxn init [--project] [--root <dir>] # lay the kernel payload into <dir> (default: cwd)
+```
+
+## File classes
+
+Every shipped file is classified in `manifest.json`:
+
+| Class | On install | On update | Example |
+|-------|-----------|-----------|---------|
+| **managed** | laid | overwritten (kernel-owned) | `.claude/constitution.md`, hooks, skills |
+| **seeded** | created once | never overwritten | `.claude/constitution.local.md` |
+| **state** | created empty | never touched | `.wrxn/wiki/` |
+
+The installer refuses any payload file the manifest cannot classify.
+
+## Develop
+
+```sh
+npm test    # node:test — engine + idempotency + packed-tarball e2e
+```
+
+The kernel self-hosts: it is built with its own installed pipeline, and `npm test` green is the
+push gate (Constitution Art. III).

package/bin/wrxn.cjs

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { init } = require('../lib/install.cjs');
+const { update } = require('../lib/update.cjs');
+const worktree = require('../lib/worktree.cjs');
+const executor = require('../lib/executor.cjs');
+const onboard = require('../lib/onboard.cjs');
+const connect = require('../lib/connect.cjs');
+
+const PKG_ROOT = path.join(__dirname, '..');
+
+function version() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--version' || a === '-v') {
+      args.flags.version = true;
+    } else if (a === '--help' || a === '-h') {
+      args.flags.help = true;
+    } else if (a === '--project') {
+      args.flags.profile = 'project';
+    } else if (a === '--workspace') {
+      args.flags.profile = 'workspace';
+    } else if (a === '--root') {
+      args.flags.root = argv[++i];
+    } else if (a === '--base') {
+      args.flags.base = argv[++i];
+    } else if (a === '--path') {
+      args.flags.path = argv[++i];
+    } else if (a === '--executor') {
+      args.flags.executor = argv[++i];
+    } else if (a === '--transport') {
+      args.flags.transport = argv[++i];
+    } else if (a === '--command') {
+      args.flags.command = argv[++i];
+    } else if (a === '--args') {
+      args.flags.args = argv[++i];
+    } else if (a === '--scopes') {
+      args.flags.scopes = argv[++i];
+    } else if (a === '--credential') {
+      args.flags.credential = argv[++i];
+    } else if (a === '--owner') {
+      args.flags.owner = argv[++i];
+    } else if (a === '--probe') {
+      args.flags.probe = argv[++i];
+    } else if (a === '--check-report') {
+      args.flags['check-report'] = true;
+    } else if (a.startsWith('--')) {
+      args.flags[a.slice(2)] = true;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+const USAGE = `wrxn — WRXN Kernel installer
+
+Usage:
+  wrxn --version                 print the kernel version
+  wrxn init [--project] [--root <dir>]
+                                 lay the kernel payload into <dir> (default: cwd).
+                                 brownfield-safe: an existing file is never overwritten —
+                                 it is preserved and reported as a collision.
+  wrxn update [--root <dir>]     update an install: replace managed files, keep
+                                 seeded + state; refuses a downgrade
+  wrxn worktree <sub> [--root <repo>] [--base <branch>] [--path <dir>]
+                                 worktree lifecycle (two faces, one engine):
+      list                       show the repo's worktrees
+      add <name>                 ephemeral AFK track on track/<name> (temp path, off base)
+      new <name>                 named durable worktree on wt/<name> (persistent path)
+      status <name>              clean/dirty + ahead/behind for a worktree
+      integrate <name>          merge <name> back to base, then auto-prune
+      prune <name> [--force]    remove a worktree + branch (refuses unmerged unless --force)
+      check <tracks.json>       refuse an overlapping disjoint-file split
+  wrxn dispatch <issue-file> [--executor <type>]
+                                 print the dispatch spec for a ready-for-agent issue — the
+                                 structured order a thin subagent of <type> follows (skill or
+                                 instructions, ACs, isolation, boundary gates). <type> is one of:
+                                 builder (default) | reviewer | security | qa-walker | researcher |
+                                 devops. Only devops passes the push gate.
+  wrxn dispatch --check-report <report.json> [--executor <type>]
+                                 validate an executor's structured report against the contract +
+                                 boundary gates (rejects a non-devops report that claims a push)
+
+  wrxn connect <sub> [--root <dir>]
+                                 connections registry — the workspace nervous system. MCP is the
+                                 socket, CLI is the floor, credentials are state.
+      add <name> --transport <mcp|cli> --command <cmd> [--args a,b] [--scopes a,b]
+                 [--credential env:NAME|state:relpath] [--owner who] [--probe <arg>]
+                                 register a tool only AFTER validating its interface by invocation;
+                                 an unreachable interface is rejected. Stores the credential POINTER,
+                                 never the secret (registry is per-install state, never shipped).
+      list                       print all registered connections (agent-readable JSON)
+      get <name>                 print one connection by name
+
+  wrxn onboard [--root <dir>]    scaffold the Day-1 operator file set under context/ from a filled
+                                 aios-intake.md (the deterministic half of the onboard skill;
+                                 workspace installs only). Idempotent.
+
+Profiles: --project (default, the dev pipeline + intelligence + enforcement) |
+          --workspace (adds the operator layer: onboard/audit/level-up + intake + decisions log +
+          connections registry).`;
+
+function main(argv) {
+  const args = parseArgs(argv);
+
+  if (args.flags.version) {
+    process.stdout.write(version() + '\n');
+    return 0;
+  }
+
+  const cmd = args._[0];
+
+  if (!cmd || args.flags.help) {
+    process.stdout.write(USAGE + '\n');
+    return cmd ? 0 : (args.flags.help ? 0 : 2);
+  }
+
+  // An explicit --root must carry a real path. An empty/missing value (e.g. an unset
+  // shell var expanding to "") must NOT silently fall through to cwd — that footgun
+  // writes into whatever dir you happen to be standing in. Shared by init + update.
+  if ('root' in args.flags) {
+    const r = args.flags.root;
+    if (typeof r !== 'string' || r.trim() === '') {
+      process.stderr.write('wrxn: --root requires a non-empty directory path\n');
+      return 2;
+    }
+  }
+
+  if (cmd === 'init') {
+    const target = path.resolve(args.flags.root || process.cwd());
+    const profile = args.flags.profile || 'project';
+    const report = init({ pkgRoot: PKG_ROOT, target, profile });
+    process.stdout.write(`wrxn init (${profile}) → ${target}\n`);
+    for (const f of report.laid) {
+      process.stdout.write(`  laid    [${f.class}] ${f.path}\n`);
+    }
+    for (const f of report.skipped) {
+      process.stdout.write(`  skipped [${f.class}] ${f.path} (${f.collision ? 'collision — existing file preserved' : 'exists'})\n`);
+    }
+    process.stdout.write(`${report.laid.length} laid, ${report.skipped.length} unchanged.\n`);
+    if (report.brownfield) {
+      process.stdout.write(`brownfield install — ${report.collisions.length} existing file(s) preserved (never overwritten): ${report.collisions.map((c) => c.path).join(', ')}\n`);
+    }
+    return 0;
+  }
+
+  if (cmd === 'update') {
+    const target = path.resolve(args.flags.root || process.cwd());
+    let report;
+    try {
+      report = update({ pkgRoot: PKG_ROOT, target });
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+    process.stdout.write(`wrxn update ${report.from} → ${report.to} (${target})\n`);
+    for (const f of report.updated) {
+      process.stdout.write(`  ${f.reason === 'new-in-version' ? 'added  ' : 'updated'} [${f.class}] ${f.path}\n`);
+    }
+    for (const f of report.preserved) {
+      process.stdout.write(`  kept    [${f.class}] ${f.path}\n`);
+    }
+    process.stdout.write(`${report.updated.length} updated, ${report.preserved.length} kept.\n`);
+    if (report.migrationsRan && report.migrationsRan.length) {
+      process.stdout.write(`migrations applied: ${report.migrationsRan.join(', ')}\n`);
+    }
+    return 0;
+  }
+
+  if (cmd === 'worktree') {
+    const sub = args._[1];
+    const repo = path.resolve(args.flags.root || process.cwd());
+    const base = args.flags.base || 'main';
+    const name = args._[2];
+    // A name resolves to a named (wt/) worktree if one exists, else the ephemeral (track/) face.
+    const detectPrefix = (n) => worktree.listWorktrees(repo).some((w) => w.branch === worktree.NAMED_PREFIX + n)
+      ? worktree.NAMED_PREFIX : worktree.BRANCH_PREFIX;
+    try {
+      if (sub === 'list') {
+        for (const w of worktree.listWorktrees(repo)) {
+          process.stdout.write(`  ${w.branch || '(detached)'}\t${w.path}\n`);
+        }
+        return 0;
+      }
+      if (sub === 'add') {
+        if (!name) { process.stderr.write('wrxn: worktree add requires <name>\n'); return 2; }
+        const r = worktree.createWorktree(repo, name, { base, path: args.flags.path });
+        process.stdout.write(`worktree ${r.branch} → ${r.path}\n`);
+        return 0;
+      }
+      if (sub === 'new') {
+        if (!name) { process.stderr.write('wrxn: worktree new requires <name>\n'); return 2; }
+        const r = worktree.createNamedWorktree(repo, name, { base, path: args.flags.path });
+        process.stdout.write(`named worktree ${r.branch} → ${r.path}\n`);
+        return 0;
+      }
+      if (sub === 'status') {
+        if (!name) { process.stderr.write('wrxn: worktree status requires <name>\n'); return 2; }
+        const s = worktree.worktreeStatus(repo, name, { base, prefix: detectPrefix(name) });
+        process.stdout.write(`${s.branch}\t${s.clean ? 'clean' : 'dirty'}\tahead ${s.ahead}, behind ${s.behind}\t${s.path || '(no worktree)'}\n`);
+        return 0;
+      }
+      if (sub === 'integrate') {
+        if (!name) { process.stderr.write('wrxn: worktree integrate requires <name>\n'); return 2; }
+        const r = worktree.integrateWorktree(repo, name, { base, prefix: detectPrefix(name) });
+        process.stdout.write(`integrated ${r.branch} → ${r.base}, worktree + branch pruned\n`);
+        return 0;
+      }
+      if (sub === 'prune') {
+        if (!name) { process.stderr.write('wrxn: worktree prune requires <name>\n'); return 2; }
+        const r = worktree.pruneWorktree(repo, name, { base, force: !!args.flags.force, prefix: detectPrefix(name) });
+        process.stdout.write(`pruned ${r.branch}${r.forced ? ' (forced)' : ''}\n`);
+        return 0;
+      }
+      if (sub === 'check') {
+        const spec = args._[2];
+        if (!spec) { process.stderr.write('wrxn: worktree check requires <tracks.json>\n'); return 2; }
+        const tracks = JSON.parse(fs.readFileSync(path.resolve(spec), 'utf8'));
+        worktree.verifyDisjoint(tracks);
+        process.stdout.write(`disjoint OK (${tracks.length} tracks)\n`);
+        return 0;
+      }
+      process.stderr.write(`wrxn: unknown worktree subcommand "${sub || ''}"\n\n${USAGE}\n`);
+      return 2;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  if (cmd === 'dispatch') {
+    const file = args._[1];
+    if (!file) { process.stderr.write('wrxn: dispatch requires <issue-file> (or --check-report <report.json>)\n'); return 2; }
+    const type = args.flags.executor || 'builder';
+    if (!executor.EXECUTOR_TYPES.includes(type)) {
+      process.stderr.write(`wrxn: unknown executor "${type}" (one of ${executor.EXECUTOR_TYPES.join(', ')})\n`);
+      return 2;
+    }
+    // --check-report <report.json>: validate an executor's structured report against the contract + gates.
+    if (args.flags['check-report']) {
+      let report;
+      try {
+        report = JSON.parse(fs.readFileSync(path.resolve(file), 'utf8'));
+      } catch (err) {
+        process.stderr.write(`wrxn: cannot read report: ${err.message}\n`);
+        return 2;
+      }
+      const result = executor.validateReport(report, type);
+      if (result.ok) {
+        process.stdout.write('report OK\n');
+        return 0;
+      }
+      process.stderr.write(`report INVALID:\n${result.errors.map((e) => `  - ${e}`).join('\n')}\n`);
+      return 2;
+    }
+    // Default: print the dispatch spec for the issue (what the subagent of this type is ordered to do).
+    let issueText;
+    try {
+      issueText = fs.readFileSync(path.resolve(file), 'utf8');
+    } catch (err) {
+      process.stderr.write(`wrxn: cannot read issue: ${err.message}\n`);
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(executor.buildDispatchSpec(issueText, type), null, 2) + '\n');
+    return 0;
+  }
+
+  if (cmd === 'onboard') {
+    const root = path.resolve(args.flags.root || process.cwd());
+    let report;
+    try {
+      report = onboard.scaffold(root);
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+    process.stdout.write(`wrxn onboard → ${root}\n`);
+    for (const f of report.scaffolded) process.stdout.write(`  scaffolded ${f}\n`);
+    for (const f of report.skipped) process.stdout.write(`  skipped    ${f} (no filled intake answer)\n`);
+    process.stdout.write(`${report.scaffolded.length} scaffolded, ${report.skipped.length} skipped.\n`);
+    return 0;
+  }
+
+  if (cmd === 'connect') {
+    const sub = args._[1];
+    const root = path.resolve(args.flags.root || process.cwd());
+    try {
+      if (sub === 'add') {
+        const name = args._[2];
+        if (!name) { process.stderr.write('wrxn: connect add requires <name>\n'); return 2; }
+        const entry = {
+          name,
+          transport: args.flags.transport,
+          command: args.flags.command,
+          scopes: args.flags.scopes ? String(args.flags.scopes).split(',').map((s) => s.trim()).filter(Boolean) : [],
+          credential: args.flags.credential || null,
+          owner: args.flags.owner || null,
+        };
+        if (args.flags.probe) entry.probe = args.flags.probe;
+        // An mcp socket launcher usually needs args (e.g. `node <server> serve`). Comma-separated.
+        if (args.flags.args) entry.args = String(args.flags.args).split(',').map((s) => s.trim()).filter(Boolean);
+        const res = connect.registerConnection(root, entry);
+        process.stdout.write(`connected ${res.entry.name} [${res.entry.transport}] — ${res.validated.detail}\n`);
+        process.stdout.write(`  credential: ${res.entry.credential || '(none)'} → ${res.credential.resolved ? 'resolved' : 'UNRESOLVED'}\n`);
+        return 0;
+      }
+      if (sub === 'list') {
+        process.stdout.write(JSON.stringify(connect.listConnections(root), null, 2) + '\n');
+        return 0;
+      }
+      if (sub === 'get') {
+        const name = args._[2];
+        if (!name) { process.stderr.write('wrxn: connect get requires <name>\n'); return 2; }
+        const found = connect.findConnection(root, name);
+        if (!found) { process.stderr.write(`wrxn: no connection named "${name}"\n`); return 2; }
+        process.stdout.write(JSON.stringify(found, null, 2) + '\n');
+        return 0;
+      }
+      process.stderr.write(`wrxn: unknown connect subcommand "${sub || ''}"\n\n${USAGE}\n`);
+      return 2;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  process.stderr.write(`wrxn: unknown command "${cmd}"\n\n${USAGE}\n`);
+  return 2;
+}
+
+process.exit(main(process.argv.slice(2)));

package/lib/connect.cjs

@@ -0,0 +1,216 @@
+'use strict';
+
+// WRXN connect + connections registry (wrxn-kernel-21) — the workspace nervous system.
+//
+// A schema'd registry of every interface the AIOS can reach, plus a `connect` command that
+// REGISTERS a tool only after VALIDATING its interface by invocation. The governing rule:
+//   MCP is the socket, CLI is the floor, credentials are state.
+// - transport 'mcp'  → a socket: a stdio launch command that must spawn (the socket opens).
+// - transport 'cli'  → a floor: a binary that must run when probed.
+// - credential       → a POINTER into state (env:NAME | state:relpath), never the secret value.
+//                      The secret is NEVER stored in the registry and NEVER shipped.
+//
+// The registry lives in the install's STATE tier (.wrxn/connections.json) — never in the payload,
+// so it is per-install and never published. It is agent-readable structured JSON (lookup, not a
+// briefing): findConnection / listConnections.
+//
+// lib/connect.cjs is package code (invoked via bin/wrxn.cjs), NOT payload — no manifest entry,
+// consistent with lib/executor.cjs and lib/onboard.cjs.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const TRANSPORTS = ['mcp', 'cli'];
+const REGISTRY_REL = path.join('.wrxn', 'connections.json');
+const PROBE_TIMEOUT_MS = 5000;
+
+/**
+ * Validate a registry entry against the schema.
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+function validateEntry(entry) {
+  const errors = [];
+  const e = entry || {};
+  if (typeof e.name !== 'string' || e.name.trim() === '') {
+    errors.push('name is required (non-empty string)');
+  }
+  if (!TRANSPORTS.includes(e.transport)) {
+    errors.push(`transport must be one of ${TRANSPORTS.join('|')} (got ${JSON.stringify(e.transport)})`);
+  }
+  if (typeof e.command !== 'string' || e.command.trim() === '') {
+    errors.push('command is required (the mcp socket launcher or the cli binary to invoke)');
+  }
+  if ('scopes' in e && !Array.isArray(e.scopes)) {
+    errors.push('scopes must be an array of strings');
+  }
+  if ('credential' in e && e.credential != null && typeof e.credential !== 'string') {
+    errors.push('credential must be a pointer string (env:NAME | state:relpath)');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Resolve a credential POINTER to its location in state — never the secret value itself.
+ * - "env:NAME"      → { kind:'env',   ref:'NAME', resolved: NAME is set in the environment }
+ * - "state:relpath" → { kind:'state', ref:'relpath', resolved: the file exists under root }
+ * - falsy / absent  → { kind:'none',  ref:null, resolved:true } (no credential required)
+ * The secret VALUE is deliberately never read or returned.
+ */
+function resolveCredential(pointer, root) {
+  if (!pointer) return { kind: 'none', ref: null, resolved: true };
+  const idx = pointer.indexOf(':');
+  const kind = idx === -1 ? pointer : pointer.slice(0, idx);
+  const ref = idx === -1 ? '' : pointer.slice(idx + 1);
+  if (kind === 'env') {
+    return { kind: 'env', ref, resolved: Object.prototype.hasOwnProperty.call(process.env, ref) && process.env[ref] !== '' };
+  }
+  if (kind === 'state') {
+    // f2: constrain resolution to within the install root — a `../` escape never resolves.
+    const abs = path.resolve(root, ref);
+    const rootAbs = path.resolve(root);
+    if (abs !== rootAbs && !abs.startsWith(rootAbs + path.sep)) {
+      return { kind: 'state', ref, resolved: false, escaped: true };
+    }
+    return { kind: 'state', ref, resolved: fs.existsSync(abs) };
+  }
+  return { kind: 'unknown', ref: pointer, resolved: false };
+}
+
+/**
+ * Default interface invoker — proves the interface by invocation.
+ * cli: spawn `command <probe>`; reachable iff it actually ran (not ENOENT).
+ * mcp: spawn `command [args]`; reachable iff the socket launcher spawned (not ENOENT). The process
+ *      is killed immediately — we only confirm the socket opens, we do not drive a session.
+ * @returns {{ ok: boolean, detail: string }}
+ */
+function defaultInvoke(entry) {
+  if (entry.transport === 'cli') {
+    const probe = entry.probe || '--version';
+    const r = spawnSync(entry.command, [probe], { timeout: PROBE_TIMEOUT_MS, stdio: 'ignore' });
+    if (r.error) {
+      return { ok: false, detail: `cli "${entry.command} ${probe}" did not run: ${r.error.code || r.error.message}` };
+    }
+    return { ok: true, detail: `cli "${entry.command}" responded (exit ${r.status})` };
+  }
+  // mcp — confirm the socket launcher spawns and stays up, then kill it.
+  const args = Array.isArray(entry.args) ? entry.args : [];
+  const r = spawnSync(entry.command, args, { timeout: PROBE_TIMEOUT_MS, stdio: 'ignore', killSignal: 'SIGKILL' });
+  if (r.error && r.error.code === 'ENOENT') {
+    return { ok: false, detail: `mcp socket "${entry.command}" not found: ENOENT` };
+  }
+  // A timeout means the launcher is alive and waiting on the stdio socket — that IS reachable
+  // (the healthy long-lived server never exits during the probe window).
+  if (r.error && r.error.code === 'ETIMEDOUT') {
+    return { ok: true, detail: `mcp socket "${entry.command}" launched (alive)` };
+  }
+  if (r.error) {
+    return { ok: false, detail: `mcp socket "${entry.command}" failed to launch: ${r.error.code || r.error.message}` };
+  }
+  // f1: the launcher exited on its own within the probe window. A real server would have stayed up
+  // (→ timeout). A non-zero exit means it crashed on launch — reject it (NOTE: full protocol-level
+  // validation, e.g. an MCP `initialize` handshake, stays out of scope — a non-MCP process that
+  // merely stays alive still reads as reachable).
+  if (typeof r.status === 'number' && r.status !== 0) {
+    return { ok: false, detail: `mcp socket "${entry.command}" crashed on launch (exit ${r.status})` };
+  }
+  return { ok: true, detail: `mcp socket "${entry.command}" launched` };
+}
+
+/**
+ * Probe an interface. The invoker is injectable so unit tests are deterministic; the CLI layer
+ * wires defaultInvoke (a real spawn) — that is what makes registration "validated by invocation".
+ * @returns {{ ok: boolean, detail: string }}
+ */
+function probeInterface(entry, { invoke } = {}) {
+  return (invoke || defaultInvoke)(entry);
+}
+
+function registryPath(root) {
+  return path.join(root, REGISTRY_REL);
+}
+
+/**
+ * Read the registry. A MISSING file is an empty registry (not an error). A PRESENT-but-corrupt
+ * file throws (f3) — silently treating it as empty would clobber it on the next register.
+ */
+function readRegistry(root) {
+  let raw;
+  try {
+    raw = fs.readFileSync(registryPath(root), 'utf8');
+  } catch {
+    return { connections: [] }; // absent → legitimately empty
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`connections registry at ${REGISTRY_REL} is corrupt (${err.message}) — fix or remove it`);
+  }
+  return Array.isArray(parsed.connections) ? parsed : { connections: [] };
+}
+
+function writeRegistry(root, registry) {
+  const dir = path.dirname(registryPath(root));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(registryPath(root), JSON.stringify(registry, null, 2) + '\n');
+}
+
+/** List all registered connections (agent lookup). */
+function listConnections(root) {
+  return readRegistry(root).connections;
+}
+
+/** Find one connection by name, or null (agent lookup, not a briefing). */
+function findConnection(root, name) {
+  return readRegistry(root).connections.find((c) => c.name === name) || null;
+}
+
+/**
+ * Register (or re-register) a connection. Schema is validated first, then the interface is probed
+ * by invocation — an unreachable interface is REJECTED with a useful error. Only the credential
+ * POINTER is stored; the secret value is never read or persisted.
+ * @returns {{ entry: object, validated: {ok, detail}, credential: {kind, ref, resolved} }}
+ * @throws on schema error or unreachable interface.
+ */
+function registerConnection(root, entry, { invoke } = {}) {
+  const schema = validateEntry(entry);
+  if (!schema.ok) {
+    throw new Error(`invalid connection: ${schema.errors.join('; ')}`);
+  }
+  const validated = probeInterface(entry, { invoke });
+  if (!validated.ok) {
+    throw new Error(`interface unreachable — ${validated.detail} (not registered)`);
+  }
+  const stored = {
+    name: entry.name,
+    transport: entry.transport,
+    command: entry.command,
+    scopes: Array.isArray(entry.scopes) ? entry.scopes : [],
+    credential: entry.credential || null, // POINTER only — never the secret value
+    owner: entry.owner || null,
+  };
+  if (Array.isArray(entry.args) && entry.args.length) stored.args = entry.args;
+
+  const registry = readRegistry(root);
+  const i = registry.connections.findIndex((c) => c.name === stored.name);
+  if (i === -1) registry.connections.push(stored);
+  else registry.connections[i] = stored; // upsert by name
+  writeRegistry(root, registry);
+
+  return { entry: stored, validated, credential: resolveCredential(stored.credential, root) };
+}
+
+module.exports = {
+  TRANSPORTS,
+  REGISTRY_REL,
+  validateEntry,
+  resolveCredential,
+  probeInterface,
+  defaultInvoke,
+  readRegistry,
+  listConnections,
+  findConnection,
+  registerConnection,
+  registryPath,
+};