@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/src/commands/machine-binary.js

@@ -1,16 +1,18 @@
 /**
  * Resolve the agentsam-machine native binary.
  * Preference order:
- *   1. AGENTSAM_MACHINE_BIN
- *   2. agentsam-machine on PATH
- *   3. Built binary under native/agentsam-machine/target/{release,debug}
- *   4. cargo run --manifest-path … (dev fallback inside the SDK repo)
+ *   1. AgentSam-managed user runtime under ~/.agentsam/runtimes/machine
+ *   2. AGENTSAM_MACHINE_BIN explicit override
+ *   3. agentsam-machine on PATH
+ *   4. Built binary under native/agentsam-machine/target/{release,debug}
+ *   5. cargo run --manifest-path (SDK contributor fallback)
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { findExecutable, managedMachineResolution } from './machine-runtime.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const sdkRoot = path.resolve(here, '../..');
@@ -18,7 +20,7 @@ const machineCrate = path.join(sdkRoot, 'native/agentsam-machine');
 const machineManifest = path.join(machineCrate, 'Cargo.toml');
 
 /**
- * @typedef {{ kind: 'binary', path: string, source: string } | { kind: 'cargo', manifest: string, source: string } | { kind: 'missing', tried: string[] }} MachineBinaryResolution
+ * @typedef {{ kind: 'binary', path: string, source: string, version?: string } | { kind: 'cargo', manifest: string, source: string } | { kind: 'missing', tried: string[] }} MachineBinaryResolution
  */
 
 /**
@@ -27,6 +29,17 @@ const machineManifest = path.join(machineCrate, 'Cargo.toml');
 export function resolveMachineBinary(env = process.env) {
   const tried = [];
 
+  const managed = managedMachineResolution(env);
+  tried.push(...managed.tried);
+  if (managed.available) {
+    return {
+      kind: 'binary',
+      path: managed.path,
+      source: 'managed-runtime',
+      version: managed.state.current_version,
+    };
+  }
+
   const explicit = String(env.AGENTSAM_MACHINE_BIN || '').trim();
   if (explicit) {
     tried.push(explicit);
@@ -35,25 +48,25 @@ export function resolveMachineBinary(env = process.env) {
     }
   }
 
-  const pathHit = which('agentsam-machine');
-  if (pathHit) {
-    return { kind: 'binary', path: pathHit, source: 'PATH' };
-  }
+  const pathHit = findExecutable('agentsam-machine', env);
+  if (pathHit) return { kind: 'binary', path: pathHit, source: 'PATH' };
   tried.push('PATH:agentsam-machine');
 
   for (const rel of ['target/release/agentsam-machine', 'target/debug/agentsam-machine']) {
     const candidate = path.join(machineCrate, rel);
     tried.push(candidate);
     if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
-      return { kind: 'binary', path: candidate, source: rel.includes('release') ? 'crate-release' : 'crate-debug' };
+      return {
+        kind: 'binary',
+        path: candidate,
+        source: rel.includes('release') ? 'crate-release' : 'crate-debug',
+      };
     }
   }
 
   if (fs.existsSync(machineManifest)) {
-    const cargo = which('cargo');
-    if (cargo) {
-      return { kind: 'cargo', manifest: machineManifest, source: 'cargo-run' };
-    }
+    const cargo = findExecutable('cargo', env);
+    if (cargo) return { kind: 'cargo', manifest: machineManifest, source: 'cargo-run' };
     tried.push('cargo');
   }
 
@@ -62,7 +75,7 @@ export function resolveMachineBinary(env = process.env) {
 
 /**
  * @param {MachineBinaryResolution} resolution
- * @param {string[]} machineArgv  args after `agentsam machine` (e.g. ['inspect', './site', '--json'])
+ * @param {string[]} machineArgv
  * @param {{ stdio?: import('node:child_process').StdioOptions, env?: NodeJS.ProcessEnv }} [options]
  */
 export function spawnMachine(resolution, machineArgv, options = {}) {
@@ -73,6 +86,7 @@ export function spawnMachine(resolution, machineArgv, options = {}) {
   if (resolution.kind === 'binary') {
     return spawnSync(resolution.path, machineArgv, { stdio, env, encoding: 'utf8', maxBuffer });
   }
+
   if (resolution.kind === 'cargo') {
     return spawnSync(
       'cargo',
@@ -80,24 +94,16 @@ export function spawnMachine(resolution, machineArgv, options = {}) {
       { stdio, env, encoding: 'utf8', maxBuffer },
     );
   }
+
   const err = new Error(
-    `agentsam-machine binary not found. Tried: ${(resolution.tried || []).join(', ') || '(none)'}. Build with: cargo build --manifest-path native/agentsam-machine/Cargo.toml --release`,
+    'agentsam-machine is not installed. Run: agentsam machine install. ' +
+    'Standalone Cargo users can run: cargo install agentsam-machine-cli. ' +
+    'Tried: ' + ((resolution.tried || []).join(', ') || '(none)'),
   );
   err.code = 'AGENTSAM_MACHINE_BINARY_MISSING';
   throw err;
 }
 
-function which(cmd) {
-  const probe = process.platform === 'win32' ? ['where', [cmd]] : ['which', [cmd]];
-  const result = spawnSync(probe[0], probe[1], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-  if (result.status !== 0) return null;
-  const line = String(result.stdout || '')
-    .split(/\r?\n/)
-    .map((s) => s.trim())
-    .find(Boolean);
-  return line || null;
-}
-
 export function machineSdkRoot() {
   return sdkRoot;
 }

package/src/commands/machine-runtime.js

@@ -0,0 +1,266 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const MACHINE_RUNTIME_SCHEMA = 'agentsam.machine.runtime.v1';
+export const MACHINE_PACKAGE = 'agentsam-machine-cli';
+
+function expandHome(value, home) {
+  if (!value) return value;
+  if (value === '~') return home;
+  if (value.startsWith('~/')) return path.join(home, value.slice(2));
+  return value;
+}
+
+export function agentsamHome(env = process.env) {
+  const home = os.homedir();
+  const configured = String(env.AGENTSAM_HOME || '').trim();
+  return configured ? path.resolve(expandHome(configured, home)) : path.join(home, '.agentsam');
+}
+
+export function machineRuntimeRoot(env = process.env) {
+  return path.join(agentsamHome(env), 'runtimes', 'machine');
+}
+
+export function machineRuntimeStatePath(env = process.env) {
+  return path.join(machineRuntimeRoot(env), 'current.json');
+}
+
+export function machineBinaryName() {
+  return process.platform === 'win32' ? 'agentsam-machine.exe' : 'agentsam-machine';
+}
+
+export function machineManagedAliasPath(env = process.env) {
+  return path.join(agentsamHome(env), 'bin', machineBinaryName());
+}
+
+export function readMachineRuntimeState(env = process.env) {
+  const file = machineRuntimeStatePath(env);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (parsed?.schema !== MACHINE_RUNTIME_SCHEMA) return null;
+    if (typeof parsed?.current_version !== 'string' || !parsed.current_version.trim()) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function managedMachineResolution(env = process.env) {
+  const statePath = machineRuntimeStatePath(env);
+  const state = readMachineRuntimeState(env);
+  const tried = [statePath];
+  if (!state) return { available: false, state: null, path: null, tried };
+
+  const binary = path.join(
+    machineRuntimeRoot(env),
+    'versions',
+    state.current_version,
+    'bin',
+    machineBinaryName(),
+  );
+  tried.push(binary);
+
+  if (!fs.existsSync(binary) || !fs.statSync(binary).isFile()) {
+    return { available: false, state, path: binary, tried };
+  }
+  return { available: true, state, path: binary, tried };
+}
+
+export function findExecutable(command, env = process.env) {
+  const probe = process.platform === 'win32' ? ['where', [command]] : ['which', [command]];
+  const result = spawnSync(probe[0], probe[1], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    env,
+  });
+  if (result.status !== 0) return null;
+  return String(result.stdout || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean) || null;
+}
+
+export function machineBinaryVersion(binary, env = process.env) {
+  const result = spawnSync(binary, ['--version'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+  if (result.status !== 0) return null;
+  const output = String(result.stdout || result.stderr || '').trim();
+  const match = output.match(/(?:^|\s)(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?:\s|$)/);
+  return match?.[1] || null;
+}
+
+export function machineRuntimeStatus(env = process.env) {
+  const managed = managedMachineResolution(env);
+  const cargo = findExecutable('cargo', env);
+  return {
+    schema: MACHINE_RUNTIME_SCHEMA,
+    manager: 'agentsam',
+    runtime_root: machineRuntimeRoot(env),
+    state_path: machineRuntimeStatePath(env),
+    installed: managed.available,
+    current_version: managed.state?.current_version || null,
+    binary: managed.path,
+    source: managed.state?.source || null,
+    installed_at_iso: managed.state?.installed_at_iso || null,
+    stable_alias: machineManagedAliasPath(env),
+    cargo: { available: Boolean(cargo), path: cargo },
+  };
+}
+
+export function discoverLatestMachineVersion(env = process.env) {
+  const cargo = findExecutable('cargo', env);
+  if (!cargo) {
+    const error = new Error('Cargo is required to install the current agentsam-machine crates.io distribution.');
+    error.code = 'AGENTSAM_MACHINE_CARGO_MISSING';
+    throw error;
+  }
+
+  const result = spawnSync(cargo, ['search', MACHINE_PACKAGE, '--limit', '1'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+  if (result.status !== 0) {
+    const error = new Error(
+      String(result.stderr || '').trim() ||
+      'Unable to resolve latest ' + MACHINE_PACKAGE + ' version from crates.io.',
+    );
+    error.code = 'AGENTSAM_MACHINE_REGISTRY_LOOKUP_FAILED';
+    throw error;
+  }
+
+  const match = String(result.stdout || '').match(/^agentsam-machine-cli\s*=\s*"([^"]+)"/m);
+  if (!match) {
+    const error = new Error('Unable to parse crates.io version for ' + MACHINE_PACKAGE + '.');
+    error.code = 'AGENTSAM_MACHINE_REGISTRY_PARSE_FAILED';
+    throw error;
+  }
+  return match[1];
+}
+
+function writeCurrentState(version, env = process.env) {
+  const root = machineRuntimeRoot(env);
+  fs.mkdirSync(root, { recursive: true });
+  const state = {
+    schema: MACHINE_RUNTIME_SCHEMA,
+    manager: 'agentsam',
+    package: MACHINE_PACKAGE,
+    current_version: version,
+    source: 'crates.io',
+    installed_at_iso: new Date().toISOString(),
+  };
+  const target = machineRuntimeStatePath(env);
+  const temp = target + '.tmp-' + process.pid;
+  fs.writeFileSync(temp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(temp, target);
+  return state;
+}
+
+function syncManagedAlias(binary, env = process.env) {
+  const alias = machineManagedAliasPath(env);
+  fs.mkdirSync(path.dirname(alias), { recursive: true });
+  try { fs.rmSync(alias, { force: true }); } catch {}
+  if (process.platform === 'win32') fs.copyFileSync(binary, alias);
+  else fs.symlinkSync(binary, alias);
+  return alias;
+}
+
+export function installManagedMachine({
+  env = process.env,
+  version = null,
+  force = false,
+  write = () => {},
+} = {}) {
+  const cargo = findExecutable('cargo', env);
+  if (!cargo) {
+    const error = new Error(
+      'Cargo is required by the current Machine distribution. Install Rust/Cargo, then rerun agentsam machine install.',
+    );
+    error.code = 'AGENTSAM_MACHINE_CARGO_MISSING';
+    throw error;
+  }
+
+  const desired = version || discoverLatestMachineVersion(env);
+  const root = machineRuntimeRoot(env);
+  const versionsRoot = path.join(root, 'versions');
+  const finalRoot = path.join(versionsRoot, desired);
+  const finalBinary = path.join(finalRoot, 'bin', machineBinaryName());
+  fs.mkdirSync(versionsRoot, { recursive: true });
+
+  if (!force && fs.existsSync(finalBinary)) {
+    const actual = machineBinaryVersion(finalBinary, env);
+    if (actual === desired) {
+      const state = writeCurrentState(desired, env);
+      const alias = syncManagedAlias(finalBinary, env);
+      return { changed: false, version: desired, binary: finalBinary, alias, state, source: 'managed-cache' };
+    }
+  }
+
+  const stage = fs.mkdtempSync(path.join(root, '.install-'));
+  write('Installing ' + MACHINE_PACKAGE + '@' + desired + ' from crates.io…\n');
+
+  const result = spawnSync(
+    cargo,
+    ['install', MACHINE_PACKAGE, '--root', stage, '--version', desired, '--locked', '--force'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env },
+  );
+  if (result.status !== 0) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    const error = new Error(
+      String(result.stderr || result.stdout || '').trim() ||
+      'cargo install failed for ' + MACHINE_PACKAGE + '@' + desired,
+    );
+    error.code = 'AGENTSAM_MACHINE_INSTALL_FAILED';
+    throw error;
+  }
+
+  const stagedBinary = path.join(stage, 'bin', machineBinaryName());
+  if (!fs.existsSync(stagedBinary)) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    const error = new Error('cargo install completed without ' + machineBinaryName());
+    error.code = 'AGENTSAM_MACHINE_INSTALL_BINARY_MISSING';
+    throw error;
+  }
+
+  const actual = machineBinaryVersion(stagedBinary, env);
+  if (actual !== desired) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    const error = new Error(
+      'installed Machine version mismatch: expected ' + desired + ', received ' + (actual || 'unknown'),
+    );
+    error.code = 'AGENTSAM_MACHINE_INSTALL_VERSION_MISMATCH';
+    throw error;
+  }
+
+  if (fs.existsSync(finalRoot)) fs.rmSync(finalRoot, { recursive: true, force: true });
+  fs.renameSync(stage, finalRoot);
+  const state = writeCurrentState(desired, env);
+  const alias = syncManagedAlias(finalBinary, env);
+  return { changed: true, version: desired, binary: finalBinary, alias, state, source: 'crates.io' };
+}
+
+export function updateManagedMachine({
+  env = process.env,
+  force = false,
+  write = () => {},
+} = {}) {
+  const latest = discoverLatestMachineVersion(env);
+  const status = machineRuntimeStatus(env);
+  if (!force && status.installed && status.current_version === latest) {
+    return {
+      changed: false,
+      version: latest,
+      binary: status.binary,
+      alias: machineManagedAliasPath(env),
+      state: readMachineRuntimeState(env),
+      source: 'already-current',
+    };
+  }
+  return installManagedMachine({ env, version: latest, force, write });
+}

package/src/commands/machine.js

@@ -1,81 +1,164 @@
 /**
- * agentsam machine — graduate the native Machine engine to the product CLI.
- *
- * Graduation rule: capability is complete when reachable through
- * `agentsam machine …`, emits bounded deterministic receipts, and preserves evidence.
- *
- * Asset perception rule: discovery is read-only and network-free by default.
+ * agentsam machine — deterministic native Machine lifecycle + perception.
  */
 
+import os from 'node:os';
 import path from 'node:path';
+import pc from 'picocolors';
 import { resolveMachineBinary, spawnMachine } from './machine-binary.js';
+import {
+  installManagedMachine,
+  machineBinaryVersion,
+  machineRuntimeStatus,
+  updateManagedMachine,
+} from './machine-runtime.js';
 
 function usage() {
-  return `agentsam machine — deterministic local perception (native engine)
-
-Usage:
-  agentsam machine inspect <path> [--json] [--run-id <id>] [--include-generated]
-  agentsam machine doctor [--json]
-  agentsam machine --help
-
-Notes:
-  Default inspect is read-only and network-free.
-  Large detail is externalized under <target>/.agentsam/machine/runs/<run_id>/.
-  Generated/cache trees are summarized unless --include-generated is set.
-  Remote fetch/probe, optimization, storage, and reference rewriting are separate explicit actions.
-  Set AGENTSAM_MACHINE_BIN to force a specific agentsam-machine binary.`;
+  return [
+    `${pc.bold('agentsam machine')} — deterministic local perception (native engine)`,
+    '',
+    pc.bold('Usage'),
+    `  ${pc.cyan('agentsam machine status')}                         Show the active runtime`,
+    `  ${pc.cyan('agentsam machine doctor')}                         Diagnose runtime resolution`,
+    `  ${pc.cyan('agentsam machine install')} [--version <semver>]   Install the managed runtime`,
+    `  ${pc.cyan('agentsam machine update')}                        Update the managed runtime`,
+    `  ${pc.cyan('agentsam machine inspect <path>')}                Inspect a repository or directory`,
+    '',
+    pc.bold('Options'),
+    `  ${pc.dim('--json')}                  Machine-readable output`,
+    `  ${pc.dim('--force')}                 Replace an existing managed version`,
+    `  ${pc.dim('--run-id <id>')}           Reuse an externalized inspection run`,
+    `  ${pc.dim('--include-generated')}    Include generated and cache trees`,
+    `  ${pc.dim('--help')}                 Show this help`,
+    '',
+    pc.bold('Runtime authority'),
+    '  AgentSam manages one user-level Machine runtime under ~/.agentsam/runtimes/machine/.',
+    '  Resolution order: managed runtime → explicit override → PATH → SDK source.',
+    '  Install and update are explicit; entering a repository never changes the host.',
+    '',
+    pc.bold('Behavior'),
+    '  Inspect is read-only and network-free by default.',
+    '  Large detail is externalized under <target>/.agentsam/machine/runs/<run_id>/.',
+    '  Generated and cache trees are summarized unless --include-generated is set.',
+    '  Install/update use the crates.io distribution and require Cargo.',
+    '',
+  ].join('\n');
 }
 
 function parseArgs(argv = []) {
   const out = {
     help: false,
     json: false,
+    force: false,
     includeGenerated: false,
     runId: null,
+    version: null,
     subcommand: null,
     target: null,
     positionals: [],
   };
+
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') out.help = true;
     else if (arg === '--json') out.json = true;
+    else if (arg === '--force') out.force = true;
     else if (arg === '--include-generated') out.includeGenerated = true;
     else if (arg === '--run-id') {
       const value = argv[++i];
-      if (value == null || value.startsWith('--')) {
-        throw new Error('--run-id requires a value');
-      }
+      if (value == null || value.startsWith('--')) throw new Error('--run-id requires a value');
       out.runId = value;
+    } else if (arg === '--version') {
+      const value = argv[++i];
+      if (value == null || value.startsWith('--')) throw new Error('--version requires a value');
+      out.version = value;
     } else if (arg.startsWith('-')) {
-      throw new Error(`unknown machine option: ${arg}`);
+      throw new Error('unknown machine option: ' + arg);
     } else {
       out.positionals.push(arg);
     }
   }
+
   out.subcommand = out.positionals[0] || null;
   out.target = out.positionals[1] || null;
   return out;
 }
 
-function printTextDoctor(resolution) {
-  if (resolution.kind === 'binary') {
-    console.log(`agentsam-machine available (${resolution.source}): ${resolution.path}`);
-    console.log('capability: machine.inspect');
-    return;
+function statusPayload() {
+  const managed = machineRuntimeStatus();
+  const resolution = resolveMachineBinary();
+  let effectiveVersion = null;
+  if (resolution.kind === 'binary') effectiveVersion = machineBinaryVersion(resolution.path);
+
+  return {
+    capability: 'machine.status',
+    managed,
+    effective: {
+      ...resolution,
+      version: resolution.version || effectiveVersion,
+    },
+  };
+}
+
+function compactPath(value) {
+  const raw = String(value || '—');
+  const home = os.homedir();
+  return home && (raw === home || raw.startsWith(home + path.sep))
+    ? '~' + raw.slice(home.length)
+    : raw;
+}
+
+function stateLabel(installed) {
+  return installed ? pc.green('installed') : pc.yellow('not installed');
+}
+
+function printTextStatus(payload) {
+  const managed = payload.managed;
+  const effective = payload.effective;
+  console.log(pc.bold('AgentSam Machine'));
+  console.log(pc.dim('Deterministic local perception · native runtime'));
+  console.log('');
+  console.log(pc.bold('Managed runtime'));
+  console.log(`  status       ${stateLabel(managed.installed)}`);
+  console.log(`  version      ${managed.current_version || pc.dim('—')}`);
+  console.log(`  runtime      ${compactPath(managed.runtime_root)}`);
+  console.log(`  binary       ${compactPath(managed.binary)}`);
+  console.log('');
+  console.log(pc.bold('Active resolution'));
+  console.log(`  source       ${effective.source || pc.dim('unavailable')}`);
+  console.log(`  version      ${effective.version || pc.dim('unknown')}`);
+  console.log(`  cargo        ${managed.cargo.available ? compactPath(managed.cargo.path) : pc.dim('not found')}`);
+  if (!managed.installed) {
+    console.log('');
+    console.log(`  ${pc.yellow('Next step')}  agentsam machine install`);
   }
-  if (resolution.kind === 'cargo') {
-    console.log(`agentsam-machine via cargo run (${resolution.source}): ${resolution.manifest}`);
-    console.log('capability: machine.inspect (dev fallback)');
-    return;
+}
+
+function printTextDoctor(payload) {
+  printTextStatus(payload);
+  console.log('');
+  console.log(pc.bold('Doctor'));
+  if (payload.effective.kind === 'missing') {
+    console.log(`  ${pc.red('✕')} Machine unavailable`);
+    console.log(`    tried      ${(payload.effective.tried || []).map(compactPath).join(', ') || pc.dim('none')}`);
+  } else if (payload.managed.installed) {
+    console.log(`  ${pc.green('✓')} Managed Machine runtime is available`);
+  } else {
+    console.log(`  ${pc.yellow('○')} Fallback runtime is active: ${payload.effective.source}`);
+    console.log('    install the managed runtime for consistent resolution across repositories');
   }
-  console.log('agentsam-machine unavailable');
-  console.log(`tried: ${(resolution.tried || []).join(', ')}`);
 }
 
-/**
- * @param {string[]} argv
- */
+function printInstallResult(action, result) {
+  console.log(pc.bold(`AgentSam Machine · ${action}`));
+  console.log('');
+  console.log(`  ${pc.green('✓')} Runtime ${result.changed ? 'installed' : 'already current'}`);
+  console.log(`  version      ${result.version}`);
+  console.log(`  source       ${result.source}`);
+  console.log(`  binary       ${compactPath(result.binary)}`);
+  console.log(`  alias        ${compactPath(result.alias)}`);
+}
+
 export async function runMachine(argv = []) {
   const args = parseArgs(argv);
   if (args.help || !args.subcommand) {
@@ -83,20 +166,43 @@ export async function runMachine(argv = []) {
     return 0;
   }
 
-  const resolution = resolveMachineBinary();
+  if (args.subcommand === 'status') {
+    const payload = statusPayload();
+    if (args.json) console.log(JSON.stringify(payload));
+    else printTextStatus(payload);
+    return 0;
+  }
 
   if (args.subcommand === 'doctor') {
-    const payload = {
-      capability: 'machine.doctor',
-      available: resolution.kind !== 'missing',
-      resolution,
-    };
-    if (args.json) console.log(JSON.stringify(payload));
-    else printTextDoctor(resolution);
-    return resolution.kind === 'missing' ? 1 : 0;
+    const payload = statusPayload();
+    if (args.json) console.log(JSON.stringify({ ...payload, capability: 'machine.doctor' }));
+    else printTextDoctor(payload);
+    return payload.effective.kind === 'missing' ? 1 : 0;
+  }
+
+  if (args.subcommand === 'install') {
+    const result = installManagedMachine({
+      version: args.version,
+      force: args.force,
+      write: args.json ? () => {} : (value) => process.stdout.write(value),
+    });
+    if (args.json) console.log(JSON.stringify({ capability: 'machine.install', ...result }));
+    else printInstallResult('install', result);
+    return 0;
+  }
+
+  if (args.subcommand === 'update') {
+    const result = updateManagedMachine({
+      force: args.force,
+      write: args.json ? () => {} : (value) => process.stdout.write(value),
+    });
+    if (args.json) console.log(JSON.stringify({ capability: 'machine.update', ...result }));
+    else printInstallResult('update', result);
+    return 0;
   }
 
   if (args.subcommand === 'inspect') {
+    const resolution = resolveMachineBinary();
     const target = args.target || process.cwd();
     const abs = path.resolve(target);
     const machineArgv = ['inspect', abs];
@@ -106,7 +212,6 @@ export async function runMachine(argv = []) {
 
     const result = spawnMachine(resolution, machineArgv, {
       stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-      // Large donors still emit bounded compact JSON; raise buffer for safety.
       maxBuffer: 32 * 1024 * 1024,
     });
 
@@ -115,13 +220,12 @@ export async function runMachine(argv = []) {
       const stdout = String(result.stdout || '');
       const stderr = String(result.stderr || '');
       if (result.status && result.status !== 0) {
-        const err = new Error(stderr.trim() || `agentsam-machine exited with code ${result.status}`);
+        const err = new Error(stderr.trim() || 'agentsam-machine exited with code ' + result.status);
         err.exitCode = result.status;
         throw err;
       }
       try {
-        const parsed = JSON.parse(stdout);
-        console.log(JSON.stringify(parsed));
+        console.log(JSON.stringify(JSON.parse(stdout)));
       } catch {
         process.stdout.write(stdout);
       }
@@ -131,7 +235,7 @@ export async function runMachine(argv = []) {
   }
 
   console.log(usage());
-  const err = new Error(`Unknown machine subcommand: ${args.subcommand}`);
+  const err = new Error('Unknown machine subcommand: ' + args.subcommand);
   err.exitCode = 1;
   throw err;
 }