@karma42/agent 0.0.0-stage → 0.1.0-beta.1

package/src/cli.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { VERSION, makePlan, providerName, renderPlan } from './plan.mjs';
+import { doctor } from './doctor.mjs';
+import { createOperations } from './connection.mjs';
+import { terminal } from './terminal.mjs';
+
+const HELP = `Karma42 agent ${VERSION} — beta release
+
+Commands:
+  connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex
+          --mode guarded|bypass [--folder ABSOLUTE_CHECKOUT_PATH]
+  prepare --connection ID
+  start --connection ID
+  reconnect --connection ID
+  permissions --connection ID --mode guarded|bypass [--provider claude|codex]
+  status [--connection ID] [--json]
+  doctor --provider claude|codex [--json]
+  preview --provider claude|codex --mode guarded|bypass
+          --project-url HTTPS_SERVICE/p/PROJECT_ID --repo GITHUB_URL --folder ABSOLUTE_PATH [--json]
+  --version
+
+Connection commands accept --state-dir ABSOLUTE_PRIVATE_DIRECTORY (default ~/.karma42/connections).
+Enter the one-time setup code privately when prompted. Never pass codes or tokens as arguments.
+Connect prepares only. Start requires separate approval and runs in the foreground; Ctrl+C stops.
+status reports local records, not online/working state. See My agents for observed service activity.
+No automatic installation, personal client configuration edits, or background launch.`;
+const selection = { connection: { type: 'string' }, 'state-dir': { type: 'string' } };
+const specs = {
+  connect: { provider: { type: 'string' }, mode: { type: 'string' }, 'project-url': { type: 'string' }, folder: { type: 'string' }, 'state-dir': { type: 'string' } },
+  prepare: selection, start: selection, reconnect: selection,
+  permissions: { ...selection, provider: { type: 'string' }, mode: { type: 'string' } },
+  status: { ...selection, json: { type: 'boolean' } },
+  preview: { provider: { type: 'string' }, mode: { type: 'string' }, 'project-url': { type: 'string' }, repo: { type: 'string' }, folder: { type: 'string' }, json: { type: 'boolean' } },
+  doctor: { provider: { type: 'string' }, json: { type: 'boolean' } },
+};
+export function main(args, out = console.log, err = console.error, runDoctor = doctor) {
+  if (!args.length || (args.length === 1 && ['--help', 'help', '-h'].includes(args[0]))) { out(HELP); return 0; }
+  if (args.length === 1 && args[0] === '--version') { out(VERSION); return 0; }
+  const [command, ...rest] = args;
+  if (!Object.hasOwn(specs, command)) { err('Unknown command. Run --help for details.'); return 2; }
+  try {
+    // Do not echo unknown options or their values: users may accidentally paste a secret.
+    let parsed;
+    try { parsed = parseArgs({ args: rest, options: specs[command], allowPositionals: false, tokens: true }); }
+    catch { throw new Error('Invalid arguments. Run --help. Setup codes and tokens are not accepted as arguments.'); }
+    const names = parsed.tokens.filter(t => t.kind === 'option').map(t => t.name);
+    if (new Set(names).size !== names.length) throw new Error('Supply each option once.');
+    const v = parsed.values;
+    if (command === 'preview') {
+      const plan = makePlan({ provider: v.provider, mode: v.mode, projectUrl: v['project-url'], repo: v.repo, folder: v.folder });
+      out(v.json ? JSON.stringify(plan, null, 2) : renderPlan(plan)); return 0;
+    }
+    if (!['preview', 'doctor'].includes(command)) {
+      if (v['state-dir'] && (!v['state-dir'].startsWith('/') || /[\x00-\x1f\x7f-\x9f]/.test(v['state-dir']))) throw new Error('Choose an absolute private state directory.');
+      const io = terminal(); io.say = out;
+      const operations = createOperations({ home: v['state-dir'], io });
+      return Promise.resolve().then(() => operations[command](v)).then(result => command === 'start' ? result : 0).catch(error => { err(error.message); return 2; });
+    }
+    const report = runDoctor(providerName(v.provider));
+    out(v.json ? JSON.stringify(report, null, 2) : [
+      'Karma42 — local prerequisites',
+      ...report.checks.map(c => `${c.ok ? 'Found' : 'Action required'}: ${c.tool} — ${c.version ?? 'not detected'}${c.minimum ? ` (requires ${c.minimum}+)` : ''}`),
+      'Sign-in and repository access: not checked. No connection or model work was started.',
+      'Passing these checks does not establish that an agent is ready to work.',
+    ].join('\n'));
+    return report.readyForPairingChecks ? 0 : 1;
+  } catch (e) { err(e.message); return 2; }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exitCode = await main(process.argv.slice(2));

package/src/connection.mjs

@@ -0,0 +1,214 @@
+import { join, dirname, relative, isAbsolute, resolve } from 'node:path';
+import { lstatSync, realpathSync, unlinkSync } from 'node:fs';
+import { makePlan, providerName, MODES, COPY_VERSION, VERSION } from './plan.mjs';
+import { defaultHome, canonicalPath, ensureHome, connectionDir, privateDir, readPrivate, writePrivate, load, save, binding, withLock, list, lstatExists } from './state.mjs';
+import { system } from './system.mjs';
+
+export const RUNTIME_POLICY = 'existing-service-managed-v2';
+const TOKEN = /^[\w-]{43}$/;
+export const normalizeRepo = repo => repo.replace(/\.git\/?$/, '').replace(/\/$/, '');
+function safeFolder(folder) {
+  if (typeof folder !== 'string' || !isAbsolute(folder) || folder.length > 2048 || /[\x00-\x1f\x7f-\x9f]/.test(folder)) throw new Error('Choose a valid absolute checkout folder.');
+  return resolve(folder);
+}
+function inside(root, path) {
+  const part = relative(root, path);
+  return part === '' || (!part.startsWith('../') && part !== '..' && !isAbsolute(part));
+}
+function checkoutPath(dir, value) {
+  const folder = safeFolder(value);
+  const state = join(dir, 'agent-state');
+  const actualFolder = canonicalPath(folder);
+  if (inside(actualFolder, dir) || inside(state, actualFolder) || inside(actualFolder, state)) throw new Error('Checkout and private connection state must be separate. Choose a sibling checkout folder.');
+  return folder;
+}
+function validateRecord(record, id) {
+  if (record?.schema !== 1 || record.id !== id || !/^[\w-]{1,64}$/.test(record.agentName ?? '') || !/^[\w-]{1,200}$/.test(record.agentId ?? '') || id.split('/')[1] !== record.agentId) throw new Error('Invalid connection record. Restore the private record or reconnect.');
+  makePlan({ provider: record.provider, mode: record.mode, projectUrl: record.service, repo: record.repo, folder: record.folder });
+  if (new URL(record.service).pathname.split('/')[2] !== id.split('/')[0]) throw new Error('Connection project identity mismatch.');
+  if (record.runtimePolicy !== RUNTIME_POLICY) throw new Error('Unsupported runtime policy. Prepare this connection using a supported package.');
+  return record;
+}
+export function createOperations({ home = defaultHome(), io, sys = system } = {}) {
+  if (lstatExists(home) && lstatSync(home).isSymbolicLink()) throw new Error('Use a real private state directory without a symbolic link.');
+  home = canonicalPath(home);
+  const say = text => io.say(text);
+  const stateOption = resolve(home) === resolve(defaultHome()) ? '' : ` --state-dir '${home.replaceAll("'", "'\\''")}'`;
+  const requireInteractive = () => { if (!io.interactive) throw new Error('Use an interactive terminal. Connection and start require your explicit approval; setup codes are never command arguments.'); };
+  const confirm = async text => {
+    if (!await io.confirm(text)) throw new Error('Cancelled. No agent was started.');
+  };
+  const read = id => validateRecord(load(connectionDir(home, id)), id);
+  const prerequisites = provider => {
+    const report = sys.doctor(provider);
+    if (!report.readyForPairingChecks) throw new Error(`Install or update the required local tools first: ${report.checks.filter(c => !c.ok).map(c => c.tool).join(', ')}. Run doctor for details.`);
+    sys.verifyBundle();
+  };
+  async function consent(record, access) {
+    const plan = makePlan({ provider: record.provider, mode: record.mode, projectUrl: record.service, repo: record.repo, folder: record.folder });
+    say(`\nReview this connection\nProject: ${record.service}\nAgent: ${record.agentName}\nRepository: ${record.repo}\nCheckout: ${record.folder}\nProvider: ${record.provider}\nPermissions: ${plan.permissions.title}\n${plan.permissions.detail}\n${plan.permissions.boundary}`);
+    say(`GitHub account: ${access.githubLogin ?? 'not signed in / not detected'}; repository write access: ${access.github ? 'checked' : 'not confirmed'}. Model sign-in: not checked.`);
+    say('The foreground runner uses service-selected runtime releases and instructions, including compatible updates between turns. Hashes detect corruption; they are not independent publisher signatures. Package updates are a separate manual installation. Existing client trust checks remain in place. No personal client configuration is edited.');
+    say('There is no default time, turn or spending cap. Readiness checks do not verify model sign-in; sign in with your chosen local client before starting.');
+    for (const line of plan.acknowledgements) await confirm(line);
+    await confirm('I understand and accept this service-managed runtime update policy.');
+    if (record.mode === 'bypass' && await io.ask('Type BYPASS to confirm this permission choice:') !== 'BYPASS') throw new Error('Bypass not confirmed. No agent was started.');
+    await confirm('Prepare the checkout and connection now? This may clone the repository; Git can invoke configured hooks and filters. No model will start.');
+    return { binding: binding(record), acknowledgedAt: sys.now(), packageVersion: VERSION, copyVersion: COPY_VERSION };
+  }
+  function checkFolder(record, clone = false) {
+    if (!lstatExists(record.folder)) {
+      if (!clone) throw new Error('Checkout is missing. Run prepare before starting.');
+      if (!lstatExists(dirname(record.folder)) || realpathSync(dirname(record.folder)) !== dirname(record.folder)) throw new Error('Choose a checkout under an existing real directory without symbolic links.');
+      if (sys.run('git', ['clone', '--', record.repo, record.folder]) === null) throw new Error('Could not clone the repository. Check GitHub sign-in and access, then retry prepare.');
+    }
+    if (!lstatSync(record.folder).isDirectory() || lstatSync(record.folder).isSymbolicLink() || realpathSync(record.folder) !== record.folder) throw new Error('Use the real checkout path without symbolic links.');
+    const top = sys.run('git', ['rev-parse', '--show-toplevel'], record.folder);
+    const origin = sys.run('git', ['remote', 'get-url', 'origin'], record.folder);
+    if (top !== record.folder || !origin || normalizeRepo(origin) !== normalizeRepo(record.repo)) throw new Error('Checkout must be the project repository root with the exact HTTPS GitHub origin. Existing files were preserved.');
+  }
+  function github(record) {
+    const raw = sys.run('gh', ['api', 'user']);
+    let login = null, permission = false;
+    try { const value = JSON.parse(raw); if (/^[A-Za-z0-9-]{1,39}$/.test(value.login)) login = value.login; } catch {}
+    const slug = new URL(normalizeRepo(record.repo)).pathname.slice(1);
+    if (login) {
+      try { permission = JSON.parse(sys.run('gh', ['api', `repos/${slug}`]))?.permissions?.push === true; } catch {}
+    }
+    return { github: permission, githubLogin: login };
+  }
+  async function finish(dir, record) {
+    prerequisites(record.provider);
+    const candidate = { ...record, folder: checkoutPath(dir, record.folder), copyVersion: COPY_VERSION, bundleHash: sys.verifyBundle().fingerprint, consent: null, phase: 'paired' };
+    const approved = await consent(candidate, github(candidate));
+    // Mark any older approval invalid before touching the selected checkout.
+    save(dir, candidate);
+    checkFolder(candidate, true);
+    privateDir(join(dir, 'agent-state'));
+    const state = join(dir, 'agent-state', candidate.agentName); privateDir(state);
+    const bundleHash = sys.installBundle(state);
+    const check = { runner: true, folder: true, ...github(candidate) };
+    const token = readPrivate(join(state, 'token')).trim();
+    if (!TOKEN.test(token)) throw new Error('Invalid stored credential. Reconnect in My agents.');
+    await sys.request(candidate.service, 'readiness', check, token);
+    const prepared = { ...candidate, phase: 'prepared', consent: approved, bundleHash, readiness: { ...check, checkedAt: sys.now() } };
+    save(dir, prepared);
+    say(`\nConnection prepared; runner not started.\nConnection ID: ${prepared.id}\nGitHub: ${check.github ? `write access checked for ${check.githubLogin}` : 'action required — sign in with gh and accept the owner’s repository invitation, then prepare again.'}\nStart separately: karma42-agent start --connection ${prepared.id}${stateOption}`);
+    return prepared;
+  }
+  async function pair(service, expected) {
+    await confirm('Exchange a one-time setup code from this project and save its private credential? This rotates the existing connection credential. Stop any previous runner first. No model will start.');
+    const code = await io.secret('Paste the setup code from My agents (hidden):');
+    if (!TOKEN.test(code)) throw new Error('Use the 43-character setup code from My agents.');
+    const response = await sys.request(service, 'exchange', { code });
+    if (!TOKEN.test(response?.token ?? '') || !/^[\w-]{1,200}$/.test(response.agentId ?? '') || !/^[\w-]{1,64}$/.test(response.agentName ?? '')) throw new Error('Unexpected pairing response. Generate a fresh code in My agents.');
+    // Validate authoritative repository before displaying it or using it in a subprocess.
+    const plan = makePlan({ provider: expected.provider, mode: expected.mode, projectUrl: service, repo: response.repoUrl, folder: expected.folder ?? '/placeholder' });
+    const id = `${new URL(service).pathname.split('/')[2]}/${response.agentId}`;
+    const dir = connectionDir(home, id);
+    // Persist a private recovery receipt before attempting preparation: never lose a valid token
+    // on a clone failure, cancelled consent, or a reconnect identity mismatch.
+    if (expected.folder) checkoutPath(dir, expected.folder);
+    const matches = !expected.id || (id === expected.id && response.agentName === expected.agentName && normalizeRepo(plan.repo) === normalizeRepo(expected.repo));
+    const receipt = { schema: 1, id, service, agentId: response.agentId, agentName: response.agentName, repo: plan.repo, folder: safeFolder(matches && expected.folder ? expected.folder : join(dir, 'workspace')), provider: expected.provider, mode: expected.mode, copyVersion: COPY_VERSION, runtimePolicy: RUNTIME_POLICY, token: response.token, pairedAt: sys.now() };
+    writePrivate(join(dir, 'pending-pair.json'), receipt);
+    if (!matches) throw new Error(`That code belongs to a different connection or repository. Existing checkout and saved credential were preserved. A private recovery receipt was saved for connection ${id}; run prepare for that connection ID to review and recover it without another exchange.`);
+    return { id, dir, receipt };
+  }
+  async function applyPair(pairing, options, locked = false) {
+    const { dir, id, receipt } = pairing;
+    const action = async () => {
+      validateRecord(receipt, id);
+      if (!TOKEN.test(receipt.token ?? '')) throw new Error('Invalid recovery receipt. Generate a new setup code.');
+      let previous = null;
+      if (lstatExists(join(dir, 'connection.json'))) previous = read(id);
+      if (previous && (previous.service !== receipt.service || previous.agentName !== receipt.agentName || normalizeRepo(previous.repo) !== normalizeRepo(receipt.repo))) throw new Error('This connection has a different saved identity. Private recovery receipt saved; existing state preserved.');
+      const folder = checkoutPath(dir, options.folder ?? previous?.folder ?? receipt.folder);
+      privateDir(join(dir, 'agent-state'));
+      const state = join(dir, 'agent-state', receipt.agentName); privateDir(state);
+      const { token, ...metadata } = receipt;
+      const record = { ...metadata, folder, provider: options.provider ?? receipt.provider, mode: options.mode ?? receipt.mode, phase: 'paired', consent: null };
+      // Readiness and approval are invalidated when the server credential rotates.
+      save(dir, record);
+      writePrivate(join(state, 'token'), `${token}\n`);
+      writePrivate(join(state, 'service.json'), { service: receipt.service });
+      unlinkSync(join(dir, 'pending-pair.json'));
+      return finish(dir, record);
+    };
+    return locked ? action() : withLock(dir, action);
+  }
+  return {
+    async connect(options) {
+      requireInteractive(); ensureHome(home);
+      const provider = providerName(options.provider);
+      const mode = options.mode;
+      // Use shared URL/permission validators before the first service request.
+      const plan = makePlan({ provider, mode, projectUrl: options['project-url'], repo: 'https://github.com/placeholder/project', folder: options.folder ?? '/placeholder' });
+      if (options.folder && (inside(canonicalPath(safeFolder(options.folder)), home) || inside(home, canonicalPath(safeFolder(options.folder))))) throw new Error('Choose a custom checkout outside private connection storage; it must not contain that storage either.');
+      prerequisites(provider);
+      return withLock(home, async () => applyPair(await pair(plan.projectUrl, { provider, mode, folder: options.folder }), { provider, mode, folder: options.folder }));
+    },
+    async prepare(options) {
+      requireInteractive();
+      const dir = connectionDir(home, options.connection);
+      return withLock(dir, async () => {
+        if (lstatExists(join(dir, 'pending-pair.json'))) {
+          say('A previous pairing was interrupted. Reviewing its saved private credential; no new code will be consumed.');
+          return applyPair({ dir, id: options.connection, receipt: readPrivate(join(dir, 'pending-pair.json'), true) }, {}, true);
+        }
+        return finish(dir, read(options.connection));
+      });
+    },
+    async permissions(options) {
+      requireInteractive();
+      const dir = connectionDir(home, options.connection);
+      return withLock(dir, async () => {
+        const record = read(options.connection);
+        return finish(dir, { ...record, provider: options.provider ? providerName(options.provider) : record.provider, mode: options.mode });
+      });
+    },
+    async reconnect(options) {
+      requireInteractive();
+      const dir = connectionDir(home, options.connection);
+      return withLock(home, () => withLock(dir, async () => {
+        const record = read(options.connection);
+        prerequisites(record.provider);
+        return applyPair(await pair(record.service, record), record, true);
+      }));
+    },
+    async start(options) {
+      requireInteractive();
+      const dir = connectionDir(home, options.connection);
+      return withLock(dir, async () => {
+        const record = read(options.connection);
+        if (lstatExists(join(dir, 'pending-pair.json'))) throw new Error('A saved pairing needs recovery. Run prepare before starting.');
+        if (record.phase !== 'prepared' || record.copyVersion !== COPY_VERSION || record.consent?.binding !== binding(record)) throw new Error('This connection needs preparation or renewed permission approval. Run prepare first.');
+        prerequisites(record.provider);
+        if (sys.verifyInstalled(join(dir, 'agent-state', record.agentName)) !== record.bundleHash) throw new Error('The packaged runtime changed. Run prepare to renew approval.');
+        checkFolder(record);
+        const check = { runner: true, folder: true, ...github(record) };
+        const token = readPrivate(join(dir, 'agent-state', record.agentName, 'token')).trim();
+        if (!TOKEN.test(token)) throw new Error('Invalid stored credential. Reconnect in My agents.');
+        await sys.request(record.service, 'readiness', check, token);
+        say(`\nStart ${record.agentName}\nRepository: ${record.repo}\nCheckout: ${record.folder}\nProvider: ${record.provider}\nPermissions: ${MODES[record.provider][record.mode].title}\n${MODES[record.provider][record.mode].detail}`);
+        say(`GitHub account: ${check.githubLogin ?? 'not signed in / not detected'}; repository write access: ${check.github ? 'checked now' : 'not confirmed'}. Model sign-in is checked by the local client when work starts.`);
+        if (!check.github) await confirm('GitHub write access is not confirmed. Coding and publishing may fail. Start with this limitation?');
+        await confirm('Start this agent now? An active project can begin model work immediately and consume your usage. A preparing or paused project waits. Keep this terminal open; Ctrl+C stops the runner. Completed actions are not undone.');
+        const started = { ...record, readiness: { ...check, checkedAt: sys.now() }, lastLocalStartAt: sys.now(), lastLocalExit: null };
+        save(dir, started);
+        const code = await sys.launch(dir, started);
+        save(dir, { ...started, lastLocalExit: { at: sys.now(), code } });
+        say('Foreground runner exited. Check My agents for service-observed contact and activity.');
+        return code;
+      });
+    },
+    status(options = {}) {
+      const records = options.connection ? list(home).filter(r => r.id === options.connection).map(r => validateRecord(r, r.id)) : list(home).map(r => validateRecord(r, r.id));
+      if (options.connection && !records.length) throw new Error('No saved connection with this ID. Run status to list connections.');
+      const pending = record => lstatExists(join(connectionDir(home, record.id), 'pending-pair.json'));
+      const result = records.map(record => ({ id: record.id, agent: record.agentName, provider: record.provider, permissions: record.mode, service: record.service, repository: record.repo, folder: record.folder, preparation: record.phase, pairingPending: pending(record), approvalCurrent: !pending(record) && record.phase === 'prepared' && record.copyVersion === COPY_VERSION && record.consent?.binding === binding(record), github: record.readiness ?? null, localOperationLock: lstatExists(join(connectionDir(home, record.id), 'operation.lock')), lastLocalStartAt: record.lastLocalStartAt ?? null, lastLocalExit: record.lastLocalExit ?? null, serverContact: 'not checked', modelSignIn: 'not checked' }));
+      say(options.json ? JSON.stringify(result, null, 2) : result.length ? result.map(r => `${r.agent} (${r.provider}, ${r.permissions})\n${r.id}\nPreparation: ${r.pairingPending ? 'pairing recovery needed — run prepare' : r.preparation}; current approval: ${r.approvalCurrent ? 'yes' : 'no'}\nLocal operation lock: ${r.localOperationLock ? 'present — this does not prove a live process' : 'absent'}\nGitHub check: ${r.github?.github ? 'write access checked' : 'not confirmed'}${r.github ? ` at ${r.github.checkedAt}` : ''}\nServer contact and model sign-in: not checked. Open My agents for observed activity.`).join('\n\n') : 'No saved package connections. Legacy setup connections are preserved separately.');
+      return result;
+    },
+  };
+}

package/src/doctor.mjs

@@ -0,0 +1,28 @@
+import { spawnSync } from 'node:child_process';
+import { providerName } from './plan.mjs';
+
+function atLeast(actual, minimum) {
+  const a = actual.split('.').map(Number), b = minimum.split('.').map(Number);
+  for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] > b[i]; }
+  return true;
+}
+export function probeVersion(command) {
+  const result = spawnSync(command, ['--version'], { encoding: 'utf8', timeout: 5000, maxBuffer: 64 * 1024, shell: false, windowsHide: true });
+  if (result.error || result.status !== 0) return null;
+  return result.stdout;
+}
+export function doctor(provider, probe = probeVersion, nodeVersion = process.versions.node) {
+  providerName(provider);
+  const spec = [
+    ['git', /git version (\d+\.\d+\.\d+)/, null],
+    ['gh', /gh version (\d+\.\d+\.\d+)/, null],
+    provider === 'claude' ? ['claude', /(?:^|\n)(\d+\.\d+\.\d+)/, '2.1.259'] : ['codex', /codex-cli (\d+\.\d+\.\d+)/, '0.160.0'],
+  ];
+  const checks = [{ tool: 'node', version: nodeVersion, ok: /^\d+\.\d+\.\d+$/.test(nodeVersion) && atLeast(nodeVersion, '22.0.0'), minimum: '22.0.0' }];
+  for (const [tool, pattern, minimum] of spec) {
+    const output = probe(tool);
+    const version = typeof output === 'string' ? pattern.exec(output)?.[1] ?? null : null;
+    checks.push({ tool, version, minimum, ok: !!version && (!minimum || atLeast(version, minimum)) });
+  }
+  return { checks, readyForPairingChecks: checks.every(c => c.ok), authenticated: 'not checked', repositoryAccess: 'not checked', executionReady: false };
+}

package/src/plan.mjs

@@ -0,0 +1,88 @@
+import { isAbsolute } from 'node:path';
+
+export const VERSION = '0.1.0-beta.1';
+export const COPY_VERSION = '2026-10-09.2';
+// These descriptions reflect pilot/agent-kit/providers.mjs. They are a proposal
+// for the onboarding vocabulary, not a change to the current adapter settings.
+export const MODES = {
+  claude: {
+    guarded: {
+      title: 'Guarded automation',
+      detail: 'Claude can edit files and run the configured Git, GitHub and project commands without asking. Commands needing additional approval are refused by this foreground runner. It cannot pause to ask you for each action.',
+      boundary: 'The command rules are not a system sandbox. Repository scripts, hooks and tools can access files and credentials available to your operating-system account.',
+    },
+    bypass: {
+      title: 'Bypass permissions',
+      detail: 'Claude skips its normal permission checks and may read, edit or delete files and execute potentially destructive commands without asking.',
+      boundary: 'Use an isolated or disposable execution environment. A dedicated repository folder alone does not isolate your machine or its credentials.',
+    },
+  },
+  codex: {
+    guarded: {
+      title: 'Guarded automation',
+      detail: 'Codex uses a workspace-write sandbox with automatic approval review. Some escalated commands can be approved to run outside that sandbox. This runner does not ask you to approve every action.',
+      boundary: 'Automatic approval is not human review. You must supervise the run and review the resulting changes.',
+    },
+    bypass: {
+      title: 'Full access / bypass permissions',
+      detail: 'This adapter disables the Codex sandbox and approval review. Commands run with the access available to your operating-system account without per-action prompts.',
+      boundary: 'Use an isolated or disposable execution environment. A dedicated repository folder alone does not isolate your machine or its credentials.',
+    },
+  },
+};
+
+function clean(value, label) {
+  if (typeof value !== 'string' || !value || value.length > 2048 || /[\x00-\x1f\x7f-\x9f]/.test(value)) throw new Error(`Provide a valid ${label}.`);
+  return value;
+}
+export function providerName(value) {
+  if (!Object.hasOwn(MODES, value ?? '')) throw new Error('Choose --provider claude or codex.');
+  return value;
+}
+export function makePlan(input) {
+  const provider = providerName(input.provider);
+  if (!Object.hasOwn(MODES[provider], input.mode ?? '')) throw new Error('Choose --mode guarded or bypass explicitly.');
+  const raw = clean(input.projectUrl, 'project URL');
+  let url;
+  try { url = new URL(raw); } catch { throw new Error('Use a Karma42 project service URL.'); }
+  const local = ['localhost', '127.0.0.1'].includes(url.hostname);
+  if (!['https:', 'http:'].includes(url.protocol) || (url.protocol === 'http:' && !local)
+    || url.username || url.password || url.search || url.hash || !/^\/p\/[a-f0-9]{64}\/?$/.test(url.pathname)) {
+    throw new Error('Use an HTTPS project service URL ending in /p/PROJECT_ID, without credentials or query parameters. HTTP is allowed only on loopback for local previews.');
+  }
+  const repo = clean(input.repo, 'GitHub repository URL');
+  if (!/^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/?$/.test(repo)) throw new Error('Use a GitHub repository URL without credentials, query parameters or fragments.');
+  if (new URL(repo).pathname.split('/').filter(Boolean).length !== 2 || /\/(?:\.|\.\.)(?:\/|$)/.test(repo)) throw new Error('Use a valid owner and repository in the GitHub URL.');
+  const folder = clean(input.folder, 'absolute checkout folder');
+  if (!isAbsolute(folder)) throw new Error('Choose an absolute checkout folder.');
+  return {
+    draft: true, verified: false, version: VERSION, copyVersion: COPY_VERSION,
+    projectUrl: url.href.replace(/\/$/, ''), repo: repo.replace(/\/$/, ''), folder, provider, mode: input.mode,
+    permissions: MODES[provider][input.mode],
+    acknowledgements: [
+      'I understand that this agent can change files, run commands, use my granted GitHub access and consume my model usage.',
+      'I will monitor its activity, review changes and stop it if it acts unexpectedly.',
+      ...(input.mode === 'bypass' ? ['I understand that bypass skips per-action permission checks. I have chosen an isolated or disposable environment appropriate for this risk.'] : []),
+    ],
+    checks: { account: 'not checked', membership: 'not checked', repositoryAccess: 'not checked', folder: 'not checked', connection: 'not created', runner: 'not started' },
+  };
+}
+export function renderPlan(plan) {
+  return [
+    'Karma42 — onboarding preview',
+    'DRAFT: this is a walkthrough. Nothing is connected and no consent is recorded.',
+    '', '1. Review the proposed connection',
+    `Project service: ${plan.projectUrl}`, `Repository (unverified): ${plan.repo}`, `Folder (unverified): ${plan.folder}`,
+    `Provider: ${plan.provider}`, `Permissions: ${plan.permissions.title}`,
+    '', '2. Understand the permission choice', plan.permissions.detail, plan.permissions.boundary,
+    'Karma42 membership and GitHub permissions still apply. This choice does not grant additional access.',
+    '', '3. Acknowledge before preparing the connection',
+    ...plan.acknowledgements.map(line => `[ ] ${line}`),
+    'Proposed action: Prepare connection. Account, project and repository must first be checked against the service.',
+    '', '4. Start separately when ready',
+    'Proposed confirmation: Start this agent now? If the project is active, it can begin work immediately and consume model usage. If the project is preparing or paused, it waits.',
+    'Keep the foreground terminal open to monitor activity. Ctrl+C stops the runner. Previously completed actions are not undone.',
+    'The runner will report model usage when available; this is not a measured price or a spending cap.',
+    '', 'Preview result: not connected; not started. Connect separately in an interactive terminal.',
+  ].join('\n');
+}

package/src/state.mjs

@@ -0,0 +1,93 @@
+import { constants, lstatSync, realpathSync, fstatSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync, readdirSync } from 'node:fs';
+import { join, dirname, basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID, createHash } from 'node:crypto';
+
+export const defaultHome = () => join(homedir(), '.karma42', 'connections');
+export function canonicalPath(value) {
+  let path = resolve(value);
+  const tail = [];
+  while (!lstatExists(path)) { tail.unshift(basename(path)); path = dirname(path); }
+  return join(realpathSync(path), ...tail);
+}
+export const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function privateDir(path) {
+  try { mkdirSync(path, { mode: 0o700 }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077)) throw new Error('Connection storage must be a private directory, without symbolic links.');
+}
+export function ensureHome(home) {
+  // Only the caller-selected root is created recursively. Existing root must be private.
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  privateDir(home);
+}
+export function readPrivate(path, json = false) {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || (stat.mode & 0o077) || stat.nlink !== 1) throw new Error('Connection files must be private regular files.');
+    const value = readFileSync(fd, 'utf8');
+    if (!json) return value;
+    try { return JSON.parse(value); } catch { throw new Error('Invalid private connection record. Restore its backup or reconnect.'); }
+  } finally { closeSync(fd); }
+}
+export function writePrivate(path, value) {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) || stat.nlink !== 1) throw new Error('Refusing to replace unsafe connection storage.');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const temp = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try { writeFileSync(fd, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`); }
+  finally { closeSync(fd); }
+  try { renameSync(temp, path); } finally { try { unlinkSync(temp); } catch {} }
+}
+export function connectionDir(home, id) {
+  if (!/^[a-f0-9]{64}\/[\w-]{1,200}$/.test(id ?? '')) throw new Error('Choose a connection ID from status.');
+  ensureHome(home);
+  const [project, agent] = id.split('/');
+  privateDir(join(home, project));
+  const dir = join(home, project, agent);
+  privateDir(dir);
+  return dir;
+}
+export function save(dir, record) { writePrivate(join(dir, 'connection.json'), record); }
+export function load(dir) { return readPrivate(join(dir, 'connection.json'), true); }
+export function binding(record) {
+  return digest([record.schema, record.id, record.service, record.agentId, record.agentName, record.repo, record.folder, record.provider, record.mode, record.copyVersion, record.runtimePolicy, record.bundleHash]);
+}
+export function withLock(dir, action) {
+  const lock = join(dir, 'operation.lock');
+  let fd;
+  try { fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Another operation holds this connection. After a crash, check that its process has stopped before removing operation.lock.');
+    throw error;
+  }
+  writeFileSync(fd, `${process.pid}\n`); closeSync(fd);
+  return Promise.resolve().then(action).finally(() => unlinkSync(lock));
+}
+export function list(home) {
+  if (!lstatExists(home)) return [];
+  ensureHome(home);
+  const result = [];
+  for (const project of readdirSync(home)) {
+    if (!/^[a-f0-9]{64}$/.test(project)) continue;
+    privateDir(join(home, project));
+    for (const agent of readdirSync(join(home, project))) {
+      if (!/^[\w-]{1,200}$/.test(agent)) continue;
+      const dir = connectionDir(home, `${project}/${agent}`);
+      if (lstatExists(join(dir, 'connection.json'))) result.push(load(dir));
+      else if (lstatExists(join(dir, 'pending-pair.json'))) {
+        const { token, ...pending } = readPrivate(join(dir, 'pending-pair.json'), true);
+        result.push({ ...pending, phase: 'paired', consent: null });
+      }
+    }
+  }
+  return result;
+}
+export function lstatExists(path) { try { lstatSync(path); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } }
+export function cleanEnvironment(input = process.env) {
+  return Object.fromEntries(Object.entries(input).filter(([key]) => !key.startsWith('PILOT_')));
+}

package/src/supervisor.mjs

@@ -0,0 +1,17 @@
+// Separate process keeps ambient PILOT_* overrides out of the canonical supervisor.
+import { join } from 'node:path';
+import { load, binding } from './state.mjs';
+import { COPY_VERSION } from './plan.mjs';
+import { supervise } from '../runtime/launcher.mjs';
+const dir = process.argv[2];
+const record = load(dir);
+if (record.phase !== 'prepared' || record.copyVersion !== COPY_VERSION || record.consent?.binding !== binding(record)) throw new Error('Prepare this connection and confirm its permissions before starting.');
+process.exitCode = await supervise({
+  service: record.service, agentName: record.agentName, repoDir: record.folder, home: join(dir, 'agent-state'),
+  env: {
+    PILOT_PROVIDER: record.provider,
+    PILOT_PERMISSION_MODE: record.mode === 'bypass' ? 'bypassPermissions' : 'acceptEdits',
+    PILOT_MAX_TURNS_PER_HOUR: '0', PILOT_TURN_SECONDS: '0', PILOT_TURN_BUDGET_USD: '0',
+    PILOT_WORK_INTERVAL_MINUTES: '15',
+  },
+});

package/src/system.mjs

@@ -0,0 +1,75 @@
+import { spawnSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { doctor } from './doctor.mjs';
+import { cleanEnvironment, privateDir, readPrivate, writePrivate } from './state.mjs';
+
+export function run(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, shell: false, encoding: 'utf8', timeout: 120_000, maxBuffer: 1024 * 1024, env: cleanEnvironment(), windowsHide: true });
+  // Do not print raw subprocess errors/output: they can contain credentials or terminal escapes.
+  if (result.error || result.status !== 0) return null;
+  return result.stdout.trim();
+}
+export async function request(service, route, body, token) {
+  let response;
+  try {
+    response = await fetch(`${service}/api/join/${route}`, {
+      method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
+      headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify(body),
+    });
+  } catch { throw new Error(route === 'exchange' ? 'Pairing reply unavailable. The code may have been consumed; generate a fresh code in My agents.' : 'Could not update the readiness check. Retry prepare when the service is available.'); }
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) throw new Error(route === 'exchange' ? 'The setup code is expired, invalid or no longer authorized. Generate a fresh code in My agents.' : 'This connection is no longer authorized. Check membership and reconnect in My agents.');
+    if (response.status === 429) throw new Error('Too many requests. Wait before retrying.');
+    throw new Error('The project service could not complete this request.');
+  }
+  const raw = await response.text();
+  if (raw.length > 16_384) throw new Error('Unexpected project service response.');
+  try { return JSON.parse(raw); } catch { throw new Error('Unexpected project service response.'); }
+}
+export function verifyBundle() {
+  const root = fileURLToPath(new URL('../runtime/', import.meta.url));
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8')); }
+  catch { throw new Error('Packaged runtime missing. Build or reinstall this package before preparing an agent.'); }
+  const names = ['runner.mjs', 'control-v2.mjs', 'runtime.mjs', 'launcher.mjs', 'claude-settings.json', 'AGENT_PROMPT_V2.md', 'providers.mjs'];
+  if (Object.keys(manifest.files ?? {}).sort().join() !== [...names].sort().join()) throw new Error('Invalid packaged runtime manifest.');
+  const files = {};
+  for (const name of names) {
+    const content = readFileSync(join(root, name));
+    if (createHash('sha256').update(content).digest('hex') !== manifest.files[name]) throw new Error('Packaged runtime integrity check failed. Reinstall the package.');
+    files[name] = content;
+  }
+  return { files, fingerprint: createHash('sha256').update(JSON.stringify(manifest.files)).digest('hex') };
+}
+export function installBundle(state) {
+  const bundle = verifyBundle();
+  const kit = join(state, 'kit'); privateDir(kit);
+  for (const [name, content] of Object.entries(bundle.files)) writePrivate(join(kit, name), content.toString('utf8'));
+  return bundle.fingerprint;
+}
+export function verifyInstalled(state) {
+  const bundle = verifyBundle();
+  for (const [name, content] of Object.entries(bundle.files)) {
+    if (readPrivate(join(state, 'kit', name)) !== content.toString('utf8')) throw new Error('Prepared runtime files changed. Run prepare before starting.');
+  }
+  return bundle.fingerprint;
+}
+export function launch(dir, record) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [fileURLToPath(new URL('./supervisor.mjs', import.meta.url)), dir], {
+      shell: false, stdio: 'inherit', env: cleanEnvironment(),
+    });
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    let stopping = false;
+    const handlers = Object.fromEntries(signals.map(signal => [signal, () => { stopping = true; child.kill(signal); }]));
+    for (const [signal, handler] of Object.entries(handlers)) process.on(signal, handler);
+    function cleanup() { for (const [signal, handler] of Object.entries(handlers)) process.off(signal, handler); }
+    child.once('error', () => { cleanup(); reject(new Error('Could not launch the foreground supervisor.')); });
+    child.once('exit', (code, signal) => { cleanup(); resolve(stopping && signal ? 0 : code ?? 1); });
+  });
+}
+export const system = { doctor, run, request, installBundle, verifyBundle, verifyInstalled, launch, now: () => new Date().toISOString() };

package/src/terminal.mjs

@@ -0,0 +1,33 @@
+import { createInterface } from 'node:readline/promises';
+export function terminal(input = process.stdin, output = process.stdout) {
+  return {
+    interactive: !!input.isTTY && !!output.isTTY,
+    say: text => output.write(`${text}\n`),
+    async ask(text) {
+      const rl = createInterface({ input, output });
+      try { return (await rl.question(`${text} `)).trim(); } finally { rl.close(); }
+    },
+    async confirm(text) { return (await this.ask(`${text} [yes/no]`)).toLowerCase() === 'yes'; },
+    secret(text) {
+      if (!input.isTTY || !output.isTTY) throw new Error('Enter the setup code in an interactive terminal.');
+      return new Promise((resolve, reject) => {
+        const wasRaw = input.isRaw; let value = '';
+        input.setRawMode(true); input.resume(); output.write(`${text} `);
+        const finish = (error) => {
+          input.off('data', onData); input.off('end', onEnd); input.setRawMode(wasRaw); input.pause(); output.write('\n');
+          if (error) reject(error); else resolve(value);
+        };
+        const onEnd = () => finish(new Error('Code entry cancelled.'));
+        const onData = chunk => {
+          for (const char of chunk.toString('utf8')) {
+            if (char === '\x03' || char === '\x04') { finish(new Error('Code entry cancelled.')); return; }
+            if (char === '\r' || char === '\n') { finish(); return; }
+            if (char === '\x7f' || char === '\b') value = value.slice(0, -1);
+            else if (/[\w-]/.test(char) && value.length < 100) value += char;
+          }
+        };
+        input.on('data', onData); input.once('end', onEnd);
+      });
+    },
+  };
+}