@aifabrix/builder 2.57.0 → 2.59.0

package/lib/agent-kit/codex-app-server.js

@@ -0,0 +1,44 @@
+/** Discover and stop direct Codex app servers owned by the current user. */
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+function parseServerLine(line) {
+  const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+  if (!match) return null;
+  const args = match[3];
+  if (!/(?:^|\s)(?:\S*\/)?codex(?:\s|$)/.test(args) ||
+      !/(?:^|\s)app-server\s+--listen(?:\s|$)/.test(args)) return null;
+  return { pid: Number(match[1]), parentPid: Number(match[2]) };
+}
+
+function listCodexAppServers(options = {}) {
+  if (typeof process.getuid !== 'function') return [];
+  const exec = options.execFileSync || execFileSync;
+  const output = exec('ps', ['-u', String(process.getuid()), '-ww', '-o', 'pid=,ppid=,args='], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']
+  });
+  const candidates = String(output).split('\n').map(parseServerLine).filter(Boolean);
+  const pids = new Set(candidates.map(server => server.pid));
+  return candidates.filter(server => !pids.has(server.parentPid)).map((server) => {
+    try {
+      const startTime = String(exec('ps', ['-p', String(server.pid), '-o', 'lstart='], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']
+      })).trim();
+      return startTime ? { pid: server.pid, startTime } : null;
+    } catch (error) {
+      if (error.status === 1) return null;
+      throw error;
+    }
+  }).filter(Boolean);
+}
+
+function stopCodexAppServer(server, options = {}) {
+  const current = listCodexAppServers(options)
+    .find(item => item.pid === server.pid && item.startTime === server.startTime);
+  if (!current) throw new Error('Codex app server changed or exited. Run agent-kit list and retry.');
+  (options.kill || process.kill)(current.pid, 'SIGTERM');
+  return { command: 'kill', kind: 'codex-app-server', pid: current.pid, stopped: true };
+}
+
+module.exports = { parseServerLine, listCodexAppServers, stopCodexAppServer };

package/lib/agent-kit/init.js

@@ -122,8 +122,7 @@ function runInit(options) {
   const cwd = options.cwd || process.cwd();
   const dryRun = Boolean(options.dryRun);
   const scm = normalizeScm(options.scm);
-  const interactive =
-    typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
+  const interactive = typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
   const { targetAbs, workspaceName } = resolveWorkspaceTarget(options.nameOrPath, cwd);
   assertSafeTarget(targetAbs, Boolean(options.force));
   assertRemoteFlags(options, interactive);
@@ -160,15 +159,7 @@ function runInit(options) {
 
   const remote = remotePhase({ options, targetAbs, workspaceName, dryRun, phases });
 
-  return buildInitReport({
-    dryRun,
-    targetAbs,
-    workspaceName,
-    scm,
-    kit,
-    remote,
-    phases
-  });
+  return buildInitReport({ dryRun, targetAbs, workspaceName, scm, kit, remote, phases });
 }
 
 /**
@@ -258,8 +249,7 @@ function buildInitReport(p) {
 function runRemoteCreate(options) {
   const cwd = options.cwd || process.cwd();
   const dryRun = Boolean(options.dryRun);
-  const interactive =
-    typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
+  const interactive = typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
   const targetAbs = path.resolve(cwd);
   if (isUnsafeRoot(targetAbs)) {
     throw new Error(
@@ -285,10 +275,7 @@ function runRemoteCreate(options) {
     throw new Error('Non-interactive remote create requires --org <owner>.');
   }
   checkRemoteAuth(options);
-  const commit = ensureInitialCommit(targetAbs, {
-    dryRun,
-    execFileSync: options.execFileSync
-  });
+  const commit = ensureInitialCommit(targetAbs, { dryRun, execFileSync: options.execFileSync });
   const name = options.name || path.basename(targetAbs);
   const remote = createGithubRemote({
     name,

package/lib/agent-kit/session-report.js

@@ -41,17 +41,22 @@ function formatSessionList(report) {
   const lines = [sectionTitle(`Tmux sessions — ${sessions.length} active:`), ''];
   if (sessions.length === 0) {
     lines.push(metadata('  No active tmux sessions.'));
-    return lines.join('\n');
+  } else {
+    const widths = columnWidths(sessions);
+    const header = `${pad('Name', widths.name)}${pad('Status', widths.status)}Windows`;
+    lines.push(metadata(header));
+    lines.push(metadata('-'.repeat(widths.name + widths.status + widths.windows)));
+    sessions.forEach((session) => {
+      const status = session.attached ? 'attached' : 'detached';
+      lines.push(`${pad(session.name, widths.name)}${pad(status, widths.status)}${session.windows}`);
+    });
+  }
+  const servers = Array.isArray(report.codexServers) ? report.codexServers : [];
+  if (servers.length) {
+    lines.push('', sectionTitle(`Codex app servers — ${servers.length} active:`), '');
+    lines.push(metadata('  Started by Codex clients, independently of af onboarding.'));
+    servers.forEach(server => lines.push(`  PID ${server.pid}  ${server.startTime}`));
   }
-
-  const widths = columnWidths(sessions);
-  const header = `${pad('Name', widths.name)}${pad('Status', widths.status)}Windows`;
-  lines.push(metadata(header));
-  lines.push(metadata('-'.repeat(widths.name + widths.status + widths.windows)));
-  sessions.forEach((session) => {
-    const status = session.attached ? 'attached' : 'detached';
-    lines.push(`${pad(session.name, widths.name)}${pad(status, widths.status)}${session.windows}`);
-  });
   return lines.join('\n');
 }
 

package/lib/agent-kit/setup-auth.js

@@ -0,0 +1,131 @@
+/** Reuse Controller device login and delegate provider login to official CLIs. */
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const config = require('../core/config');
+const paths = require('../utils/paths');
+const { checkDeviceToken } = require('../commands/auth-status');
+const { handleDeviceCodeLogin } = require('../commands/login-device');
+const { capture, checked, interactive, available } = require('./setup-process');
+const { assertDirectory } = require('./setup-context');
+const logger = require('../utils/logger');
+
+const PROVIDERS = {
+  codex: { package: '@openai/codex', status: ['login', 'status'], login: ['login', '--device-auth'] },
+  claude: { package: '@anthropic-ai/claude-code', status: ['auth', 'status'], login: ['auth', 'login'] }
+};
+
+async function ensureController(context) {
+  const environment = await config.getCurrentEnvironment();
+  let auth;
+  try {
+    auth = await checkDeviceToken(context.controller);
+  } catch {
+    auth = null;
+  }
+  if (!auth || !auth.authenticated) {
+    await handleDeviceCodeLogin(context.controller, environment, false, undefined, {
+      compact: true, exitOnFailure: false
+    });
+    auth = await checkDeviceToken(context.controller);
+  }
+  if (!auth || !auth.authenticated) {
+    throw new Error('Controller authentication could not be verified. Run aifabrix login, then retry.');
+  }
+  await config.setControllerUrl(context.controller);
+  return environment;
+}
+
+function ensureGithubLogin(options) {
+  try {
+    capture('gh', ['auth', 'status', '--hostname', 'github.com'], options);
+    return;
+  } catch {
+    const loginOptions = options.managed
+      ? { ...options, env: { ...process.env, ...options.env, GH_BROWSER: 'true' } } : options;
+    if (options.managed) {
+      logger.log('GitHub sign-in: open https://github.com/login/device on your computer and enter the code shown below.');
+    }
+    interactive('gh', ['auth', 'login', '--hostname', 'github.com', '--git-protocol', 'https', '--web'],
+      'GitHub login did not complete. Open https://github.com/login/device on your computer, then retry.', loginOptions);
+  }
+  checked('gh', ['auth', 'status', '--hostname', 'github.com'], 'GitHub authentication could not be verified.', options);
+}
+
+function providerEnvironment(options) {
+  const prefix = path.join(paths.getAifabrixSystemDir(), 'agent-tools');
+  const env = { ...process.env, ...options.env };
+  const localBin = path.join(options.homedir || os.homedir(), '.local', 'bin');
+  env.PATH = [path.join(prefix, 'bin'), localBin, env.PATH || ''].join(path.delimiter);
+  return { ...options, env, prefix };
+}
+
+function installClaudeNative(runtime) {
+  if (!available('curl', runtime) || !available('bash', runtime)) {
+    throw new Error('Install curl and bash to install Claude Code, then retry.');
+  }
+  logger.log('Installing Claude Code for the current user...');
+  const script = checked('curl', ['-fsSL', 'https://claude.ai/install.sh'],
+    'Could not download the Claude Code installer. Check network access, then retry.', runtime);
+  const result = (runtime.spawnSync || spawnSync)('bash', ['-s', 'stable'], {
+    cwd: runtime.cwd, env: runtime.env, input: script, encoding: 'utf8',
+    stdio: ['pipe', 'inherit', 'inherit']
+  });
+  if (!result || result.error || result.signal || result.status !== 0) {
+    throw new Error('Could not install Claude Code. Check user-directory permissions, then retry.');
+  }
+}
+
+function exposeManagedProvider(binary, code, options = {}) {
+  const localDir = path.join(options.homedir || os.homedir(), '.local');
+  const binDir = path.join(localDir, 'bin');
+  assertDirectory(localDir);
+  fs.mkdirSync(localDir, { recursive: true });
+  assertDirectory(binDir);
+  fs.mkdirSync(binDir, { recursive: true });
+  const link = path.join(binDir, code);
+  let existing;
+  try {
+    existing = fs.lstatSync(link);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (existing) {
+    if (path.resolve(binary) === path.resolve(link)) return link;
+    if (existing.isSymbolicLink() && fs.readlinkSync(link) === binary) return link;
+    throw new Error(`Cannot expose ${code} on PATH because ${link} already exists. Preserve it and resolve the conflict.`);
+  }
+  fs.symlinkSync(binary, link);
+  return link;
+}
+
+function ensureProvider(context, options = {}) {
+  const provider = PROVIDERS[context.code];
+  const runtime = providerEnvironment(options);
+  if (!available(context.code, runtime)) {
+    if (context.code === 'claude') {
+      installClaudeNative(runtime);
+    } else {
+      if (!available('npm', runtime)) throw new Error('Install npm to install the selected coding CLI, then retry.');
+      logger.log(`Installing ${context.code} for the current user...`);
+      checked('npm', ['install', '--global', '--prefix', runtime.prefix, provider.package],
+        `Could not install ${context.code}. Check npm access and user-directory permissions, then retry.`, runtime);
+    }
+  }
+  const binary = available(context.code, runtime);
+  if (!binary) throw new Error(`The ${context.code} executable was not found after installation.`);
+  checked(binary, ['--version'], `The ${context.code} executable is not usable. Reinstall it, then retry.`, runtime);
+  try {
+    capture(binary, provider.status, runtime);
+  } catch {
+    interactive(binary, provider.login, `${context.code} login did not complete. Sign in and retry.`, runtime);
+  }
+  checked(binary, provider.status, `${context.code} authentication could not be verified.`, runtime);
+  if (options.managed) exposeManagedProvider(binary, context.code, options);
+  return { binary, env: runtime.env };
+}
+
+module.exports = { ensureController, ensureGithubLogin, ensureProvider, providerEnvironment, exposeManagedProvider };

package/lib/agent-kit/setup-context.js

@@ -0,0 +1,118 @@
+/** Validate the minimal onboarding inputs and resolve the configured workspace root. */
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const inquirer = require('inquirer');
+const fs = require('../internal/fs-real-sync');
+const config = require('../core/config');
+const paths = require('../utils/paths');
+const { isUnsafeRoot } = require('./repo-guard');
+const { available } = require('./setup-process');
+
+function controllerUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('A valid Controller URL is required.');
+  }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('Controller URL must use HTTP(S) without credentials, query parameters, or a fragment.');
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+function setupName(options, repository) {
+  if (options.managed && options.name !== undefined) return options.name;
+  return repository === undefined ? 'workspace' : repository;
+}
+
+function validFolderName(name) {
+  return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]{0,99}$/i.test(name) && !name.endsWith('.git');
+}
+
+function normalizeSetup(options) {
+  const controller = controllerUrl(options.controllerUrl);
+  const code = options.code || 'codex';
+  const hosts = options.managed ? ['codex', 'claude', 'cursor'] : ['codex', 'claude'];
+  if (!hosts.includes(code)) throw new Error(options.managed
+    ? 'Managed codingPlatform must be codex, claude, or cursor.' : 'Use codex or claude for --code.');
+  if (options.repo !== undefined && (typeof options.repo !== 'string' || options.repo.split('/').length !== 2)) {
+    throw new Error('Use --repo owner/name for a GitHub repository.');
+  }
+  const [org, repository] = options.repo === undefined ? [] : options.repo.split('/');
+  const name = setupName(options, repository);
+  if (org !== undefined && !/^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/i.test(org)) {
+    throw new Error('Invalid GitHub organization or user name.');
+  }
+  if (!validFolderName(name)) {
+    throw new Error(options.managed
+      ? 'Invalid --name. Use one folder name without slashes or a .git suffix.'
+      : 'Invalid repository name. Use a simple folder name without a .git suffix.');
+  }
+  return { controller, code, name, fullName: org ? `${org}/${name}` : null };
+}
+
+function preflight(context, options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  if (!['linux', 'darwin'].includes(platform) || !['x64', 'arm64'].includes(arch)) {
+    throw new Error('Agent onboarding supports Linux/macOS on x64 or arm64.');
+  }
+  const tty = options.isTTY === undefined ? process.stdin.isTTY && process.stdout.isTTY : options.isTTY;
+  if (!tty) throw new Error(options.managed
+    ? 'Run onboarding in an interactive terminal for account login.'
+    : 'Run agent-kit setup in an interactive terminal for login and agent attachment.');
+  for (const bin of ['git', ...(!options.managed || context.code === 'claude' ? ['tmux'] : []),
+    ...(context.fullName ? ['gh'] : [])]) {
+    if (!available(bin, options)) throw new Error(`${bin} is required on PATH. Install it, then retry onboarding.`);
+  }
+}
+
+function assertDirectory(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`Expected a directory, not a link or file: ${file}`);
+  }
+}
+
+function workspaceName(context, options, root, home) {
+  if (options.managed && root === home && options.name === undefined && !context.fullName) {
+    return 'agent-kit-workspace';
+  }
+  return context.name;
+}
+
+async function resolveWork(context, options = {}) {
+  let root = (options.getWork || paths.getAifabrixWork)();
+  if (!root && options.managed) root = path.join(options.homedir || os.homedir(), 'aifabrix-work');
+  if (!root) {
+    const answer = await (options.prompt || inquirer.prompt)([{
+      type: 'input', name: 'work', message: 'AI Fabrix work directory:',
+      default: path.join(os.homedir(), 'aifabrix-work'),
+      validate: value => path.isAbsolute(String(value).trim()) || 'Enter an absolute directory path.'
+    }]);
+    root = String(answer.work || '').trim();
+    if (!path.isAbsolute(root)) throw new Error('Work directory must be an absolute path.');
+    await (options.setWork || config.setAifabrixWorkOverride)(root);
+  }
+  root = path.resolve(root);
+  assertDirectory(root);
+  fs.mkdirSync(root, { recursive: true });
+  root = fs.realpathSync(root);
+  const home = fs.realpathSync(options.homedir || os.homedir());
+  const name = workspaceName(context, options, root, home);
+  const target = path.join(root, name);
+  if (isUnsafeRoot(target)) throw new Error('Refusing to use home or the filesystem root as a workspace.');
+  assertDirectory(target);
+  return { ...context, name, root, target };
+}
+
+module.exports = { normalizeSetup, preflight, resolveWork, assertDirectory };

package/lib/agent-kit/setup-github.js

@@ -0,0 +1,70 @@
+/** Optional GitHub onboarding; API creation arbitrates missing/private repository names. */
+'use strict';
+
+const { capture, checked } = require('./setup-process');
+
+function githubOptions(options = {}) {
+  return { ...options, env: { ...process.env, ...options.env, GH_HOST: 'github.com' } };
+}
+
+function lookupRepository(fullName, options) {
+  options = githubOptions(options);
+  try {
+    return JSON.parse(capture('gh', ['api', `repos/${fullName}`], options));
+  } catch (error) {
+    // gh's included HTTP response allows status checking without exposing its body/errors.
+    try {
+      capture('gh', ['api', '--include', `repos/${fullName}`], options);
+    } catch (probe) {
+      if (/^HTTP\/\S+ 404(?:\s|$)/m.test(String(probe.stdout || ''))) return null;
+    }
+    throw new Error('Cannot inspect the GitHub repository. Check account access and connectivity, then retry.');
+  }
+}
+
+function createRepository(fullName, options) {
+  checked('gh', ['repo', 'create', fullName, '--private'],
+    'GitHub could not create the private repository. It may already exist without access, or creation is denied. No push was attempted.', githubOptions(options));
+}
+
+function cloneRepository(context, options) {
+  checked('gh', ['repo', 'clone', context.fullName, context.target, '--', '--origin', 'origin'],
+    'Repository clone failed. Preserve any partial folder and inspect GitHub access before retrying.', githubOptions(options));
+}
+
+function originIdentity(target, options) {
+  let origin;
+  try {
+    origin = String(capture('git', ['remote', 'get-url', 'origin'], { ...options, cwd: target })).trim();
+  } catch {
+    return null;
+  }
+  const match = /^(?:https:\/\/github\.com\/|git@github\.com:)([a-z0-9-]+\/[a-z0-9._-]+?)(?:\.git)?$/i.exec(origin);
+  return match ? match[1].toLowerCase() : 'unrecognized';
+}
+
+function assertOrigin(context, options) {
+  if (originIdentity(context.target, options) !== context.fullName.toLowerCase()) {
+    throw new Error('The existing origin does not match the requested GitHub repository. No remote was changed.');
+  }
+}
+
+function pushInitialCommit(context, progress, save, options) {
+  const opts = { ...githubOptions(options), cwd: context.target };
+  assertOrigin(context, options);
+  const expected = progress.state.initialCommit;
+  if (!/^[0-9a-f]{40,64}$/.test(expected || '')) throw new Error('Missing initial commit identity; refusing to push.');
+  const credentials = ['-c', 'credential.helper=', '-c', 'credential.https://github.com.helper=!gh auth git-credential'];
+  const remote = String(checked('git', [...credentials, 'ls-remote', 'origin', 'refs/heads/main'],
+    'Cannot verify the remote branch before initial push.', opts)).trim();
+  if (remote && remote.split(/\s/)[0] !== expected) {
+    throw new Error('Remote branch changed during onboarding. Reconcile it with Git before retrying.');
+  }
+  if (!remote) {
+    checked('git', [...credentials, 'push', 'origin', `${expected}:refs/heads/main`],
+      'Initial push failed. Local files and the private repository are preserved; retry setup.', opts);
+  }
+  save(progress, { pushed: true });
+}
+
+module.exports = { lookupRepository, createRepository, cloneRepository, originIdentity, assertOrigin, pushInitialCommit };

package/lib/agent-kit/setup-managed.js

@@ -0,0 +1,79 @@
+/** Read the provisioned user config for zero-argument managed onboarding. */
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const os = require('os');
+const yaml = require('js-yaml');
+const config = require('../core/config');
+const { normalizeSetup } = require('./setup-context');
+
+function assertConfigFile(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error('Managed config.yaml is missing. Ask your administrator to provision this workspace.');
+    }
+    throw error;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error('Managed config.yaml must be a regular file. Ask your administrator to repair it.');
+  }
+}
+
+function assertManagedKeys(file) {
+  let raw;
+  try {
+    raw = yaml.load(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new Error('Managed config.yaml is invalid. Ask your administrator to repair it.');
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) ||
+      !['controller', 'environment', 'codingPlatform'].every(key => Object.hasOwn(raw, key))) {
+    throw new Error('Managed config.yaml needs controller, environment, and codingPlatform. Ask your administrator to repair it.');
+  }
+}
+
+function assertManagedOverrides(options) {
+  if (options.code !== undefined || options.controllerUrl !== undefined) {
+    throw new Error('Managed onboarding uses the provisioned Controller; --code and --controller overrides are not allowed.');
+  }
+  if (options.repo !== undefined && options.name !== undefined) {
+    throw new Error('Use either --repo owner/name or --name folder for managed onboarding.');
+  }
+  if (options.coding !== undefined && !['claude', 'codex', 'cursor'].includes(options.coding)) {
+    throw new Error('Use --coding claude, codex, or cursor.');
+  }
+}
+
+function assertManagedValues(values) {
+  if (!values || typeof values !== 'object' || typeof values.controller !== 'string' ||
+      typeof values.environment !== 'string' || !values.environment.trim() ||
+      !['codex', 'claude', 'cursor'].includes(values.codingPlatform)) {
+    throw new Error('Managed config.yaml needs controller, environment, and codingPlatform. Ask your administrator to repair it.');
+  }
+}
+
+async function managedSetupOptions(options = {}) {
+  assertManagedOverrides(options);
+  const file = options.configFile || config.CONFIG_FILE;
+  assertConfigFile(file);
+  assertManagedKeys(file);
+  const values = await (options.getConfig || config.getConfig)();
+  assertManagedValues(values);
+  let context;
+  try {
+    context = normalizeSetup({ controllerUrl: values.controller,
+      code: options.coding || values.codingPlatform, managed: true });
+  } catch {
+    throw new Error('Managed config.yaml has an invalid Controller URL or coding platform. Ask your administrator to repair it.');
+  }
+  const sshHost = values['sync-ssh-host'];
+  const remoteHost = typeof sshHost === 'string' && /^[a-z0-9.-]+$/i.test(sshHost)
+    ? sshHost : os.hostname();
+  return { controllerUrl: context.controller, code: context.code,
+    remoteHost, managed: true };
+}
+
+module.exports = { managedSetupOptions, assertConfigFile, assertManagedKeys };

package/lib/agent-kit/setup-process.js

@@ -0,0 +1,42 @@
+/** Process boundary for onboarding: argv only and no credential-bearing errors. */
+'use strict';
+
+const { execFileSync, spawnSync } = require('child_process');
+
+function capture(bin, args, options = {}) {
+  return (options.execFileSync || execFileSync)(bin, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+}
+
+function checked(bin, args, message, options = {}) {
+  try {
+    return capture(bin, args, options);
+  } catch {
+    throw new Error(message);
+  }
+}
+
+function interactive(bin, args, message, options = {}) {
+  const result = (options.spawnSync || spawnSync)(bin, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    stdio: 'inherit'
+  });
+  if (!result || result.error || result.signal || result.status !== 0) {
+    throw new Error(message);
+  }
+}
+
+function available(bin, options = {}) {
+  try {
+    return String(capture('which', [bin], options)).trim();
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { capture, checked, interactive, available };

package/lib/agent-kit/setup-session.js

@@ -0,0 +1,53 @@
+/** Start or reattach only to a session belonging to this workspace and selected agent. */
+'use strict';
+
+const { createHash } = require('crypto');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+const { runStart, hostUserPrefix, resolveRemoteControlName, resolveSessionName } = require('./start');
+const { tmuxSessionExists } = require('./tmux-sessions');
+const { checked, interactive } = require('./setup-process');
+
+function sessionIdentity(context, options = {}) {
+  const key = `${context.target}\n${context.controller}\n${context.code}`;
+  const hash = createHash('sha256').update(key).digest('hex').slice(0, 16);
+  const legacyName = `aifabrix-${context.code}-${hash}`;
+  const name = options.managed && context.code === 'claude'
+    ? resolveSessionName(undefined, context.target) : legacyName;
+  return { name, key, legacyName };
+}
+
+function verifySession(name, key, options) {
+  const saved = String(checked('tmux', ['show-options', '-v', '-t', name, '@aifabrix-setup'],
+    'Cannot verify existing agent session ownership.', options)).trim();
+  if (saved !== key) throw new Error('Existing session ownership does not match. No session was replaced.');
+}
+
+function prepareSession(context, provider, options = {}) {
+  const { name, key, legacyName } = sessionIdentity(context, options);
+  const exec = (bin, args, extra) => (options.execFileSync || execFileSync)(bin, args, { ...extra, env: provider.env });
+  const spawn = (bin, args, extra) => (options.spawnSync || spawnSync)(bin, args, { ...extra, env: provider.env });
+  const opts = { ...options, env: provider.env };
+  if (tmuxSessionExists(name, exec)) {
+    verifySession(name, key, opts);
+  } else if (name !== legacyName && tmuxSessionExists(legacyName, exec)) {
+    verifySession(legacyName, key, opts);
+    checked('tmux', ['rename-session', '-t', legacyName, name],
+      'Could not rename the existing agent session. Inspect agent-kit list before retrying.', opts);
+  } else {
+    const remoteControlName = context.code === 'claude'
+      ? resolveRemoteControlName(hostUserPrefix(options), path.basename(context.target)) : undefined;
+    runStart({ app: context.code, cwd: context.target, name, detach: true, skipApproveAll: true,
+      binary: provider.binary, remoteControlName, execFileSync: exec, spawnSync: spawn });
+    checked('tmux', ['set-option', '-t', name, '@aifabrix-setup', key],
+      'Agent started but its session could not be marked. Inspect agent-kit list before retrying.', opts);
+  }
+  return name;
+}
+
+function attachSession(name, provider, options = {}) {
+  interactive('tmux', ['attach-session', '-t', `=${name}`],
+    'Could not attach the agent session. Inspect aifabrix agent-kit list.', { ...options, env: provider.env });
+}
+
+module.exports = { prepareSession, attachSession, sessionIdentity };