@magclaw/cli-core 0.1.28 → 0.1.30

package/README.md

@@ -5,3 +5,9 @@ Shared local MagClaw CLI implementation.
 This package owns the reusable command implementation used by
 `@magclaw/daemon` and `@magclaw/computer`. Install the public entry packages
 instead of using this package directly.
+
+Public entry commands:
+
+- `magclaw`: daemon/profile operations.
+- `magclaw-computer`: browser-approved Computer setup and control-plane
+  operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magclaw/cli-core",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Shared local MagClaw CLI implementation used by daemon and computer packages.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -385,6 +385,10 @@ function rootLockPaths(env = process.env) {
   };
 }
 
+function computerChannelPath(env = process.env) {
+  return path.join(daemonRoot(env), 'channel');
+}
+
 export function profilePaths(profile = DEFAULT_PROFILE, env = process.env) {
   const profileName = safeProfileName(profile);
   const dir = path.join(daemonRoot(env), 'profiles', profileName);
@@ -541,6 +545,10 @@ export function parseCli(argv = process.argv) {
       flags.help = true;
       continue;
     }
+    if (item === '-V') {
+      flags.version = true;
+      continue;
+    }
     if (!item.startsWith('--')) {
       positionals.push(item);
       continue;
@@ -580,7 +588,7 @@ function renderHelp() {
     '  status       Show daemon status for one profile',
     '  list         List local daemon profiles and connected Computers',
     '  logs         Print recent daemon logs for one profile',
-    '  install-cli  Install or repair the durable magclaw command shim',
+    '  install-cli  Install or repair durable magclaw command shims',
     '  upgrade      Upgrade the background daemon package',
     '  doctor       Show runtime and environment diagnostics',
     '  uninstall    Stop and remove the background daemon service',
@@ -612,6 +620,150 @@ function renderHelp() {
   ].join('\n');
 }
 
+function renderComputerHelp(subcommand = '') {
+  const command = String(subcommand || '').trim();
+  const usage = {
+    login: [
+      'Usage: magclaw-computer login [options] <serverSlug>',
+      '',
+      'Start MagClaw browser approval for one server. This is an alias for setup.',
+      '',
+      'Options:',
+      '  --server-url <url>  MagClaw Cloud URL',
+      '  --name <name>       Computer display name',
+      '  --no-start          Save the approved profile without starting the daemon',
+      '  -h, --help          Show this help',
+    ],
+    attach: [
+      'Usage: magclaw-computer attach [options] <serverSlug>',
+      '',
+      'Attach this Computer to one MagClaw server using browser approval.',
+      '',
+      'Options:',
+      '  --server-url <url>  MagClaw Cloud URL',
+      '  --name <name>       Computer display name',
+      '  --no-run            Save the approved profile without starting the daemon',
+      '  --foreground        Run foreground if background service cannot start',
+      '  -h, --help          Show this help',
+    ],
+    setup: [
+      'Usage: magclaw-computer setup [options] <serverSlug>',
+      '',
+      'Set up this Computer for one server, then start its daemon unless --no-start is set.',
+      '',
+      'Options:',
+      '  --server-url <url>  MagClaw Cloud URL',
+      '  --name <name>       Computer display name',
+      '  --no-start          Save the approved profile without starting the daemon',
+      '  --foreground        Run foreground if background service cannot start',
+      '  -h, --help          Show this help',
+    ],
+    detach: [
+      'Usage: magclaw-computer detach <serverSlug>',
+      '',
+      'Stop one local profile and remove its local attachment state.',
+    ],
+    status: [
+      'Usage: magclaw-computer status [options] [serverSlug]',
+      '',
+      'Show aggregate Computer state, or one server profile when a slug is provided.',
+      '',
+      'Options:',
+      '  --json      Emit the machine-readable report',
+      '  -h, --help  Show this help',
+    ],
+    start: [
+      'Usage: magclaw-computer start [options] [serverSlug]',
+      '',
+      'Start one saved background daemon profile, or all saved profiles when no slug is provided.',
+      '',
+      'Options:',
+      '  --foreground  Run in this terminal for one selected profile',
+    ],
+    stop: [
+      'Usage: magclaw-computer stop [options] [serverSlug]',
+      '',
+      'Stop one daemon profile, or all saved profiles when no slug is provided.',
+      '',
+      'Options:',
+      '  --disable  Suppress background relaunch until the next start',
+    ],
+    doctor: [
+      'Usage: magclaw-computer doctor [options] [serverSlug]',
+      '',
+      'Diagnose local profiles, service state, runtime availability, and stale pidfiles.',
+      '',
+      'Options:',
+      '  --json      Emit the machine-readable report',
+      '  --cleanup   Clear stale local locks while diagnosing',
+      '  --fix       Alias for --cleanup',
+    ],
+    logs: [
+      'Usage: magclaw-computer logs [options] [serverSlug]',
+      '',
+      'Print recent daemon logs for one attached server profile.',
+      '',
+      'Options:',
+      '  --lines <n>      Number of trailing lines to print (default 120)',
+      '  --server <slug>  Select a server profile',
+    ],
+    runners: [
+      'Usage: magclaw-computer runners <command> [options]',
+      '',
+      'Computer runner control plane.',
+      '',
+      'Commands:',
+      '  list            List local daemon profiles and known Computer bindings',
+      '  stop <agentId>  Not available locally; stop Agents from the MagClaw web console',
+    ],
+    channel: [
+      'Usage: magclaw-computer channel [set <channel>]',
+      '',
+      'Show or set the local Computer release channel (latest | alpha | pinned:<semver>).',
+    ],
+    upgrade: [
+      'Usage: magclaw-computer upgrade [options]',
+      '',
+      'Upgrade the background Computer package for a saved profile.',
+      '',
+      'Options:',
+      '  --dry-run                  Preview upgrade actions',
+      '  --channel <name>           latest | alpha | pinned:<semver>',
+      '  --target-version <semver>  Explicit target version',
+      '  --force                    Accepted for Slock parity; currently maps to the normal upgrade path',
+    ],
+  };
+  if (command && usage[command]) return `${usage[command].join('\n')}\n`;
+  return [
+    `MagClaw Computer CLI ${DAEMON_VERSION}`,
+    '',
+    'Usage: magclaw-computer [options] [command]',
+    '',
+    'MagClaw Computer - local-machine control plane (browser approval + per-server profiles).',
+    '',
+    'Options:',
+    '  -V, --version                        output the version number',
+    '  -h, --help                           show help for command',
+    '',
+    'Commands:',
+    '  login [options] <serverSlug>          Browser-approved login for one server (alias for setup)',
+    '  attach [options] <serverSlug>         Attach this Computer to one server',
+    '  setup [options] <serverSlug>          Login/attach if needed, then start',
+    '  adopt-legacy [options] <serverSlug>   Migrate from legacy pair-token style setup when possible',
+    '  detach <serverSlug>                   Remove one local server attachment',
+    '  status [options] [serverSlug]         Show aggregate or per-profile state',
+    '  start [options] [serverSlug]          Start one or all saved profiles',
+    '  stop [options] [serverSlug]           Stop one or all saved profiles',
+    '  doctor [options] [serverSlug]         Diagnose local profiles and runtime state',
+    '  logs [options] [serverSlug]           Print one profile daemon log',
+    '  runners                              Computer runner control plane',
+    '  channel                              Show or set release channel',
+    '  upgrade [options]                    Upgrade the Computer package',
+    '  help [command]                       show help for command',
+    '',
+  ].join('\n');
+}
+
 async function readJsonFile(file, fallback = {}) {
   if (!existsSync(file)) return fallback;
   try {
@@ -710,6 +862,27 @@ async function clearRemoteClosedServiceState(profile = DEFAULT_PROFILE, env = pr
   }, env);
 }
 
+export function daemonRunLaunchedByBackgroundService(env = process.env) {
+  return String(env.MAGCLAW_DAEMON_BACKGROUND_SERVICE || '').trim() === '1';
+}
+
+function backgroundServiceModeForPlatform(platform = process.platform) {
+  if (platform === 'darwin') return 'launchd';
+  if (platform === 'linux') return 'systemd';
+  if (platform === 'win32') return 'schtasks';
+  return 'foreground';
+}
+
+export function serviceStatePatchForDaemonRun(service = {}, env = process.env, platform = process.platform) {
+  if (daemonRunLaunchedByBackgroundService(env)) {
+    return {
+      mode: service.mode || backgroundServiceModeForPlatform(platform),
+      background: true,
+    };
+  }
+  return { mode: 'foreground', background: false };
+}
+
 async function markForegroundServiceState(profile = DEFAULT_PROFILE, env = process.env) {
   const packageInfo = runtimePackageInfo(env);
   return writeServiceState(profile, {
@@ -726,6 +899,22 @@ async function markForegroundServiceState(profile = DEFAULT_PROFILE, env = proce
   }, env);
 }
 
+async function markDaemonRunServiceState(profile = DEFAULT_PROFILE, env = process.env) {
+  if (!daemonRunLaunchedByBackgroundService(env)) return markForegroundServiceState(profile, env);
+  const service = await readServiceState(profile, env);
+  const packageInfo = runtimePackageInfo(env, service);
+  return writeServiceState(profile, {
+    ...serviceStatePatchForDaemonRun(service, env),
+    packageSpec: packageInfo.spec,
+    packageName: packageInfo.name,
+    packageVersion: packageInfo.version,
+    packageKind: packageInfo.kind,
+    packageBin: packageInfo.bin,
+    installedDaemonVersion: packageInfo.version || DAEMON_VERSION,
+    installedPackageVersion: packageInfo.version || DAEMON_VERSION,
+  }, env);
+}
+
 async function readUpgradeHandoff(profile = DEFAULT_PROFILE, env = process.env) {
   const paths = profilePaths(profile, env);
   const handoff = await readJsonFile(paths.upgradeHandoff, null);
@@ -921,64 +1110,88 @@ function defaultCliPackageSpec(env = process.env) {
   return String(env.MAGCLAW_CLI_PACKAGE_SPEC || '@magclaw/cli-core@latest').trim() || '@magclaw/cli-core@latest';
 }
 
+function defaultComputerCliPackageSpec(env = process.env) {
+  return String(env.MAGCLAW_COMPUTER_CLI_PACKAGE_SPEC || '@magclaw/computer@latest').trim() || '@magclaw/computer@latest';
+}
+
 function defaultCliNpmPath(env = process.env) {
   return commandExists('npm', env) || (process.platform === 'win32' ? 'npm.cmd' : 'npm');
 }
 
-export function renderCliShimFiles({ platform = process.platform, npmPath = '', packageSpec = '@magclaw/cli-core@latest' } = {}) {
+function cliShimTargets({ packageSpec = '@magclaw/cli-core@latest', computerPackageSpec = '@magclaw/computer@latest' } = {}) {
+  return [
+    {
+      command: 'magclaw',
+      packageSpec: String(packageSpec || '@magclaw/cli-core@latest').trim() || '@magclaw/cli-core@latest',
+    },
+    {
+      command: 'magclaw-computer',
+      packageSpec: String(computerPackageSpec || '@magclaw/computer@latest').trim() || '@magclaw/computer@latest',
+    },
+  ];
+}
+
+export function renderCliShimFiles({
+  platform = process.platform,
+  npmPath = '',
+  packageSpec = '@magclaw/cli-core@latest',
+  computerPackageSpec = '@magclaw/computer@latest',
+} = {}) {
   const targetPackage = String(packageSpec || '@magclaw/cli-core@latest').trim() || '@magclaw/cli-core@latest';
+  const targetComputerPackage = String(computerPackageSpec || '@magclaw/computer@latest').trim() || '@magclaw/computer@latest';
   const targetNpm = String(npmPath || (platform === 'win32' ? 'npm.cmd' : 'npm')).trim() || (platform === 'win32' ? 'npm.cmd' : 'npm');
+  const targets = cliShimTargets({ packageSpec: targetPackage, computerPackageSpec: targetComputerPackage });
   if (platform === 'win32') {
     const fallback = path.win32.basename(targetNpm) || 'npm.cmd';
-    return [
+    return targets.flatMap((target) => [
       {
-        name: 'magclaw.cmd',
+        name: `${target.command}.cmd`,
         executable: true,
         content: [
           '@echo off',
           'setlocal',
           `set "NPM_BIN=${cmdEnvValue(targetNpm)}"`,
           `if not exist "%NPM_BIN%" set "NPM_BIN=${cmdEnvValue(fallback)}"`,
-          `set "PACKAGE_SPEC=${cmdEnvValue(targetPackage)}"`,
+          `set "PACKAGE_SPEC=${cmdEnvValue(target.packageSpec)}"`,
           'set "ARGS=%*"',
-          '"%NPM_BIN%" exec --yes --package "%PACKAGE_SPEC%" -- magclaw %ARGS%',
+          `"%NPM_BIN%" exec --yes --package "%PACKAGE_SPEC%" -- ${target.command} %ARGS%`,
           'exit /b %ERRORLEVEL%',
           '',
         ].join('\r\n'),
       },
       {
-        name: 'magclaw.ps1',
+        name: `${target.command}.ps1`,
         executable: true,
         content: [
           `$npmBin = ${psSingleQuote(targetNpm)}`,
           `if (-not (Test-Path -LiteralPath $npmBin)) { $npmBin = ${psSingleQuote(fallback)} }`,
-          `$packageSpec = ${psSingleQuote(targetPackage)}`,
-          '& $npmBin exec --yes --package $packageSpec -- magclaw @args',
+          `$packageSpec = ${psSingleQuote(target.packageSpec)}`,
+          `& $npmBin exec --yes --package $packageSpec -- ${target.command} @args`,
           'exit $LASTEXITCODE',
           '',
         ].join('\n'),
       },
-    ];
+    ]);
   }
   const fallback = path.basename(targetNpm) || 'npm';
-  return [
+  return targets.map((target) => (
     {
-      name: 'magclaw',
+      name: target.command,
       executable: true,
       content: [
         '#!/bin/sh',
         'set -eu',
         '# MagClaw CLI shim generated by @magclaw/cli-core.',
         `NPM_BIN=${shSingleQuote(targetNpm)}`,
-        `PACKAGE_SPEC=${shSingleQuote(targetPackage)}`,
+        `PACKAGE_SPEC=${shSingleQuote(target.packageSpec)}`,
         'if [ ! -x "$NPM_BIN" ]; then',
         `  NPM_BIN=${shSingleQuote(fallback)}`,
         'fi',
-        'exec "$NPM_BIN" exec --yes --package "$PACKAGE_SPEC" -- magclaw "$@"',
+        `exec "$NPM_BIN" exec --yes --package "$PACKAGE_SPEC" -- ${target.command} "$@"`,
         '',
       ].join('\n'),
-    },
-  ];
+    }
+  ));
 }
 
 async function chooseCliShimBinDir(options = {}, env = process.env) {
@@ -1014,17 +1227,21 @@ async function chooseCliShimBinDir(options = {}, env = process.env) {
   return { dir: fallback, explicit: false, pathReady: directoryIsInPath(fallback, env) };
 }
 
-async function existingDurableMagclawCommand(env = process.env) {
-  const existing = commandExists('magclaw', env);
+function isGeneratedMagClawShim(content = '') {
+  return Boolean(
+    content.includes('MagClaw CLI shim generated by @magclaw/cli-core')
+    || content.includes('MagClaw CLI shim generated by @magclaw/daemon')
+    || content.includes('@magclaw/cli-core@')
+    || content.includes('@magclaw/daemon@')
+    || content.includes('@magclaw/computer@')
+  );
+}
+
+async function existingDurableMagclawCommand(command = 'magclaw', env = process.env) {
+  const existing = commandExists(command, env);
   if (!existing || pathLooksEphemeralCli(existing)) return '';
   const content = await readFile(existing, 'utf8').catch(() => '');
-  if (
-    content
-    && !content.includes('MagClaw CLI shim generated by @magclaw/cli-core')
-    && !content.includes('MagClaw CLI shim generated by @magclaw/daemon')
-    && !content.includes('@magclaw/cli-core@')
-    && !content.includes('@magclaw/daemon@')
-  ) {
+  if (content && !isGeneratedMagClawShim(content)) {
     return '';
   }
   return existing;
@@ -1033,12 +1250,7 @@ async function existingDurableMagclawCommand(env = process.env) {
 async function writeCliShimFile(file, content, { force = false } = {}) {
   if (existsSync(file) && !force) {
     const existing = await readFile(file, 'utf8').catch(() => '');
-    if (
-      !existing.includes('MagClaw CLI shim generated by @magclaw/cli-core')
-      && !existing.includes('MagClaw CLI shim generated by @magclaw/daemon')
-      && !existing.includes('@magclaw/cli-core@')
-      && !existing.includes('@magclaw/daemon@')
-    ) {
+    if (!isGeneratedMagClawShim(existing)) {
       const error = new Error(`Refusing to overwrite existing non-MagClaw command: ${file}`);
       error.code = 'EEXIST';
       throw error;
@@ -1052,16 +1264,39 @@ async function installCliShim(options = {}, env = process.env) {
   if (env.MAGCLAW_INSTALL_CLI === '0' || options.installCli === false || options.noInstallCli) {
     return { ok: true, command: 'magclaw', installed: false, skipped: true, reason: 'disabled' };
   }
-  const existing = await existingDurableMagclawCommand(env);
-  if (existing && !options.binDir && !options.cliBinDir && !options.force) {
-    return { ok: true, command: 'magclaw', installed: false, path: existing, files: [existing], pathReady: true, reason: 'already_available' };
+  const existing = await existingDurableMagclawCommand('magclaw', env);
+  const existingComputer = await existingDurableMagclawCommand('magclaw-computer', env);
+  const existingCommandsShareDir = Boolean(
+    existing
+    && existingComputer
+    && path.dirname(existing) === path.dirname(existingComputer)
+  );
+  if (existingCommandsShareDir && !options.binDir && !options.cliBinDir && !options.force) {
+    return {
+      ok: true,
+      command: 'magclaw',
+      commands: ['magclaw', 'magclaw-computer'],
+      installed: false,
+      path: existing,
+      files: [existing, existingComputer],
+      pathReady: true,
+      reason: 'already_available',
+    };
   }
 
-  const target = await chooseCliShimBinDir(options, env);
+  const target = (existing || existingComputer) && !options.binDir && !options.cliBinDir && !options.force
+    ? { dir: path.dirname(existing || existingComputer), explicit: false, pathReady: true }
+    : await chooseCliShimBinDir(options, env);
   await mkdir(target.dir, { recursive: true });
   const npmPath = String(options.npmPath || defaultCliNpmPath(env)).trim() || (process.platform === 'win32' ? 'npm.cmd' : 'npm');
   const packageSpec = String(options.packageSpec || options.cliPackageSpec || defaultCliPackageSpec(env)).trim() || '@magclaw/cli-core@latest';
-  const shimFiles = renderCliShimFiles({ platform: process.platform, npmPath, packageSpec });
+  const computerPackageSpec = String(options.computerPackageSpec || options.computerCliPackageSpec || defaultComputerCliPackageSpec(env)).trim() || '@magclaw/computer@latest';
+  const shimFiles = renderCliShimFiles({
+    platform: process.platform,
+    npmPath,
+    packageSpec,
+    computerPackageSpec,
+  });
   const written = [];
   for (const shim of shimFiles) {
     const file = path.join(target.dir, shim.name);
@@ -1071,12 +1306,14 @@ async function installCliShim(options = {}, env = process.env) {
   return {
     ok: true,
     command: 'magclaw',
+    commands: ['magclaw', 'magclaw-computer'],
     installed: true,
     binDir: target.dir,
     files: written,
     path: written[0] || '',
     pathReady: Boolean(target.pathReady),
     packageSpec,
+    computerPackageSpec,
     npmPath,
   };
 }
@@ -3249,6 +3486,8 @@ class MagClawDaemon {
     this.pendingUpgradeRequest = null;
     this.upgradeIdleTimer = null;
     this.upgradeWorkerStarting = false;
+    this.runtimeStatusTimer = null;
+    this.runtimeStatusInFlight = false;
   }
 
   send(payload) {
@@ -3619,7 +3858,6 @@ class MagClawDaemon {
   }
 
   async readyPayload() {
-    const runtimes = await detectRuntimes(this.env);
     const owner = await ensureMachineFingerprint(this.paths.profile, this.env);
     const service = await readServiceState(this.paths.profile, this.env);
     const serviceStatus = backgroundServiceStatus(this.paths.profile, this.env);
@@ -3658,8 +3896,7 @@ class MagClawDaemon {
         cliCoreVersion: CLI_CORE_VERSION,
       },
       upgrade: upgrade || null,
-      runtimes: runtimes.filter((runtime) => runtime.installed).map((runtime) => runtime.id),
-      runtimeDetails: runtimes,
+      runtimeScanPending: true,
       runningAgents: [...this.sessions.keys()],
       capabilities: CAPABILITIES,
     };
@@ -3670,10 +3907,68 @@ class MagClawDaemon {
     const sent = this.send(payload);
     logInfo(
       'daemon',
-      `Sent ready payload for computer ${payload.computerId || 'unpaired'} (runtimes=${payload.runtimes.join(', ') || 'none'}, runningAgents=${payload.runningAgents.length}, sent=${sent}).`,
+      `Sent ready payload for computer ${payload.computerId || 'unpaired'} (runtimes=deferred, runningAgents=${payload.runningAgents.length}, sent=${sent}).`,
     );
   }
 
+  runtimeStatusDelayMs() {
+    return envInteger(this.env, 'MAGCLAW_DAEMON_RUNTIME_STATUS_DELAY_MS', 1000, { min: 0, max: 60_000 });
+  }
+
+  clearRuntimeStatusTimer() {
+    if (!this.runtimeStatusTimer) return;
+    clearTimeout(this.runtimeStatusTimer);
+    this.runtimeStatusTimer = null;
+  }
+
+  scheduleRuntimeStatus(reason = 'ready_ack') {
+    if (this.closed || this.runtimeStatusTimer || this.runtimeStatusInFlight) return;
+    this.runtimeStatusTimer = setTimeout(() => {
+      this.runtimeStatusTimer = null;
+      this.sendRuntimeStatus(reason).catch((error) => {
+        logWarning('daemon', `Failed to send runtime status: ${error.message}`);
+      });
+    }, this.runtimeStatusDelayMs());
+    this.runtimeStatusTimer.unref?.();
+  }
+
+  async runtimeStatusPayload(reason = 'ready_ack') {
+    const runtimes = await detectRuntimes(this.env);
+    const packageInfo = runtimePackageInfo(this.env);
+    return {
+      type: 'daemon:runtime_status',
+      time: now(),
+      reason,
+      computerId: this.config.computerId || null,
+      daemonVersion: packageInfo.version || DAEMON_VERSION,
+      packageName: packageInfo.name,
+      packageVersion: packageInfo.version,
+      packageKind: packageInfo.kind,
+      packageSpec: packageInfo.spec,
+      packageBin: packageInfo.bin,
+      cliCoreVersion: CLI_CORE_VERSION,
+      runtimes: runtimes.filter((runtime) => runtime.installed).map((runtime) => runtime.id),
+      runtimeDetails: runtimes,
+      runningAgents: [...this.sessions.keys()],
+    };
+  }
+
+  async sendRuntimeStatus(reason = 'ready_ack') {
+    if (this.closed || this.runtimeStatusInFlight) return false;
+    this.runtimeStatusInFlight = true;
+    try {
+      const payload = await this.runtimeStatusPayload(reason);
+      const sent = this.send(payload);
+      logInfo(
+        'daemon',
+        `Sent runtime status for computer ${payload.computerId || 'unpaired'} (runtimes=${payload.runtimes.join(', ') || 'none'}, sent=${sent}).`,
+      );
+      return sent;
+    } finally {
+      this.runtimeStatusInFlight = false;
+    }
+  }
+
   sendHeartbeat() {
     const packageInfo = runtimePackageInfo(this.env);
     const sent = this.send({
@@ -3801,6 +4096,7 @@ class MagClawDaemon {
         break;
       case 'ready:ack':
         logInfo('daemon', `MagClaw daemon ready for computer ${message.computerId || this.config.computerId}.`);
+        this.scheduleRuntimeStatus('ready_ack');
         break;
       case 'ping':
         this.send({ type: 'pong', time: now() });
@@ -4162,6 +4458,7 @@ class MagClawDaemon {
     this.sessions.clear();
     this.stopHeartbeat();
     this.clearInboundWatchdog();
+    this.clearRuntimeStatusTimer();
     if (this.agentStartPumpTimer) {
       clearTimeout(this.agentStartPumpTimer);
       this.agentStartPumpTimer = null;
@@ -4214,6 +4511,7 @@ class MagClawDaemon {
         settled = true;
         this.stopHeartbeat();
         this.clearInboundWatchdog();
+        this.clearRuntimeStatusTimer();
         if (this.socket && this.socket.destroyed) this.socket = null;
         if (this.request === req) this.request = null;
         callback(value);
@@ -4437,6 +4735,7 @@ async function writeLauncher(profile, env = process.env) {
     "  MAGCLAW_DAEMON_PACKAGE_SPEC: packageSpec,",
     "  MAGCLAW_DAEMON_PACKAGE_KIND: packageKind,",
     "  MAGCLAW_DAEMON_PACKAGE_BIN: packageBin,",
+    "  MAGCLAW_DAEMON_BACKGROUND_SERVICE: '1',",
     "  PATH: launchPath,",
     "};",
     "if (packageKind === 'computer') childEnv.MAGCLAW_COMPUTER_DAEMON = '1';",
@@ -4591,17 +4890,40 @@ async function startBackground(profile, env = process.env) {
   return { ok: false, mode: 'foreground', message: 'Background daemon is only automated on macOS launchd, Linux user systemd, and Windows schtasks.' };
 }
 
+export function parseLaunchdPrintStatus(result = {}) {
+  const stdout = String(result.stdout || '');
+  const stderr = String(result.stderr || '');
+  const state = (stdout.match(/^\s*state\s*=\s*(.+?)\s*$/m)?.[1] || '').trim();
+  const activeCountValue = Number(stdout.match(/^\s*active count\s*=\s*(\d+)\s*$/m)?.[1] || NaN);
+  const stateStatus = state || (result.status === 0 ? 'loaded' : 'inactive');
+  const active = result.status === 0 && (
+    stateStatus.toLowerCase() === 'running'
+    || (!state && Number.isFinite(activeCountValue) && activeCountValue > 0)
+  );
+  return {
+    active,
+    status: active ? 'running' : stateStatus,
+    state,
+    activeCount: Number.isFinite(activeCountValue) ? activeCountValue : null,
+    error: result.status === 0 ? '' : String(stderr || stdout || '').trim(),
+  };
+}
+
 function backgroundServiceStatus(profile, env = process.env) {
   const paths = profilePaths(profile, env);
   if (process.platform === 'darwin') {
     const label = launchAgentLabel(paths.profile);
     const result = spawnSync('launchctl', ['print', `gui/${process.getuid()}/${label}`], { encoding: 'utf8' });
+    const parsed = parseLaunchdPrintStatus(result);
     return {
       mode: 'launchd',
-      active: result.status === 0,
+      active: parsed.active,
       label,
       file: path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`),
-      error: result.status === 0 ? '' : String(result.stderr || result.stdout || '').trim(),
+      status: parsed.status,
+      state: parsed.state,
+      activeCount: parsed.activeCount,
+      error: parsed.error,
     };
   }
   if (process.platform === 'linux') {
@@ -4811,14 +5133,15 @@ async function status(profile) {
   };
 }
 
-async function logs(profile) {
+async function logs(profile, options = {}) {
   const paths = profilePaths(profile);
+  const lines = Math.max(1, Math.min(5000, Number(options.lines || 120) || 120));
   const files = [path.join(paths.logDir, 'daemon.log'), path.join(paths.logDir, 'daemon.err.log')];
   for (const file of files) {
     if (!existsSync(file)) continue;
     process.stdout.write(`\n==> ${file} <==\n`);
     const text = await readFile(file, 'utf8').catch(() => '');
-    process.stdout.write(text.split(/\r?\n/).slice(-120).join('\n'));
+    process.stdout.write(text.split(/\r?\n/).slice(-lines).join('\n'));
     process.stdout.write('\n');
   }
 }
@@ -4857,6 +5180,9 @@ async function listProfiles(env = process.env) {
         label: service.label || '',
         serviceName: service.serviceName || '',
         taskName: service.taskName || '',
+        status: service.status || '',
+        state: service.state || '',
+        activeCount: service.activeCount ?? null,
       },
       createdAt: config.createdAt || '',
       updatedAt: config.updatedAt || '',
@@ -5289,8 +5615,12 @@ function normalizeSetupServerSlug(value = '') {
   return String(value || '').trim().replace(/^\/+/, '').replace(/\/+$/, '');
 }
 
+function normalizeSetupServerUrl(value = '') {
+  return String(value || DEFAULT_SERVER_URL).replace(/\/+$/, '');
+}
+
 async function postSetupJson(serverUrl, pathname, body = {}) {
-  const url = `${String(serverUrl || DEFAULT_SERVER_URL).replace(/\/+$/, '')}${pathname}`;
+  const url = `${normalizeSetupServerUrl(serverUrl)}${pathname}`;
   const response = await fetch(url, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
@@ -5303,15 +5633,144 @@ async function postSetupJson(serverUrl, pathname, body = {}) {
   return data;
 }
 
+function hasComputerTarget(flags = {}) {
+  return Boolean(flags.profileExplicit || flags.server || flags.serverSlug || flags.slug || flags._?.[1]);
+}
+
+function profileFromComputerTarget(value = '') {
+  return safeProfileName(normalizeSetupServerSlug(value) || value || DEFAULT_PROFILE);
+}
+
+function computerTargetProfile(flags = {}, fallback = DEFAULT_PROFILE) {
+  return profileFromComputerTarget(flags.server || flags.serverSlug || flags.slug || flags._?.[1] || flags.profile || fallback);
+}
+
+function savedComputerSetupMatches(config = {}, target = {}) {
+  const token = String(config.token || config.machineToken || config.apiKey || '').trim();
+  const computerId = String(config.computerId || '').trim();
+  if (!token || !computerId) return false;
+  if (normalizeSetupServerUrl(config.serverUrl) !== normalizeSetupServerUrl(target.serverUrl)) return false;
+
+  const targetProfile = safeProfileName(target.profile || target.serverSlug || DEFAULT_PROFILE);
+  const configProfile = safeProfileName(config.profile || targetProfile);
+  if (configProfile !== targetProfile) return false;
+
+  const targetSlug = normalizeSetupServerSlug(target.serverSlug);
+  const configSlug = normalizeSetupServerSlug(config.serverSlug || config.slug || '');
+  if (configSlug && targetSlug && configSlug !== targetSlug) return false;
+  return true;
+}
+
+async function reusableComputerSetupProfile(target = {}, env = process.env) {
+  if (target.force || target.relogin || target.reauthorize) return null;
+  const profile = safeProfileName(target.profile || target.serverSlug || DEFAULT_PROFILE);
+  const config = await readProfile(profile, env);
+  if (!savedComputerSetupMatches(config, { ...target, profile })) return null;
+  const service = await readServiceState(profile, env);
+  if (service.remoteClosed) return null;
+  return {
+    config: {
+      ...config,
+      profile,
+      serverUrl: normalizeSetupServerUrl(config.serverUrl || target.serverUrl),
+      token: String(config.token || config.machineToken || config.apiKey || '').trim(),
+      pairToken: '',
+    },
+    service,
+    serviceStatus: backgroundServiceStatus(profile, env),
+  };
+}
+
+async function finishReusableComputerSetup(existing, flags = {}, env = process.env) {
+  const requestedSlug = normalizeSetupServerSlug(flags._?.[1] || flags.server || flags.serverSlug || flags.slug);
+  const serverSlug = existing.config.serverSlug || requestedSlug;
+  const config = await buildConfig({
+    ...flags,
+    profile: existing.config.profile,
+    serverUrl: existing.config.serverUrl,
+    apiKey: existing.config.token,
+    computerId: existing.config.computerId,
+    workspaceId: existing.config.workspaceId || existing.config.workspace,
+    name: existing.config.name,
+    serverName: existing.config.serverName || serverSlug,
+    serverSlug,
+    fingerprint: existing.config.fingerprint,
+  }, env);
+  await saveProfile(config.profile, config, env);
+  const cli = await tryInstallCliShim(flags, env);
+  const computerName = config.computerName || config.name || os.hostname();
+  const basePayload = {
+    cli,
+    computerId: config.computerId,
+    computerName,
+    profile: config.profile,
+    serverName: config.serverName,
+    serverSlug: config.serverSlug,
+    reused: true,
+    reason: 'already_configured',
+  };
+  if (flags.noStart || flags.noRun) {
+    printJson({
+      ok: true,
+      started: false,
+      ...basePayload,
+      next: `Run magclaw-computer start ${config.profile} when ready.`,
+    });
+    return;
+  }
+
+  const serviceStatus = existing.serviceStatus || backgroundServiceStatus(config.profile, env);
+  let result;
+  if (serviceStatus.active) {
+    result = {
+      ok: true,
+      mode: serviceStatus.mode,
+      active: true,
+      alreadyRunning: true,
+      started: false,
+      label: serviceStatus.label,
+      serviceName: serviceStatus.serviceName,
+      taskName: serviceStatus.taskName,
+      file: serviceStatus.file,
+      status: serviceStatus.status,
+      state: serviceStatus.state,
+    };
+  } else {
+    const started = await startBackground(config.profile, env);
+    result = {
+      ...started,
+      started: Boolean(started.ok),
+    };
+  }
+  printJson({
+    ...result,
+    ...basePayload,
+  });
+  if (!result.ok) {
+    logWarning('daemon', 'Falling back to foreground mode.');
+    await runForegroundDaemon(config, env);
+  }
+}
+
 async function runComputerSetup(flags, env = process.env) {
   const subcommand = String(flags._?.[0] || '').trim();
-  if (subcommand !== 'setup') {
-    throw new Error('Usage: magclaw computer setup /<server-slug> --server-url <url>');
+  if (!['setup', 'attach', 'login'].includes(subcommand)) {
+    throw new Error('Usage: magclaw-computer setup /<server-slug> --server-url <url>');
   }
   const serverSlug = normalizeSetupServerSlug(flags._?.[1] || flags.server || flags.serverSlug || flags.slug);
   if (!serverSlug) throw new Error('Run computer setup with a server slug, for example: magclaw computer setup /my-server');
-  const serverUrl = String(flags.serverUrl || env.MAGCLAW_PUBLIC_URL || DEFAULT_SERVER_URL).replace(/\/+$/, '');
+  const serverUrl = normalizeSetupServerUrl(flags.serverUrl || env.MAGCLAW_PUBLIC_URL || DEFAULT_SERVER_URL);
   const profile = safeProfileName(flags.profile && flags.profile !== DEFAULT_PROFILE ? flags.profile : serverSlug);
+  const existing = await reusableComputerSetupProfile({
+    ...flags,
+    profile,
+    serverSlug,
+    serverUrl,
+  }, env);
+  if (existing) {
+    await finishReusableComputerSetup(existing, flags, env);
+    return;
+  }
   const owner = await ensureMachineFingerprint(profile, env);
   const displayName = String(flags.displayName || flags.name || os.hostname()).trim();
   const packageInfo = runtimePackageInfo(env);
@@ -5367,6 +5826,20 @@ async function runComputerSetup(flags, env = process.env) {
   await saveProfile(config.profile, config, env);
   await clearRemoteClosedServiceState(config.profile, env);
   const cli = await tryInstallCliShim(flags, env);
+  if (flags.noStart || flags.noRun) {
+    printJson({
+      ok: true,
+      started: false,
+      cli,
+      computerId: config.computerId,
+      computerName: config.computerName || config.name || displayName,
+      profile: config.profile,
+      serverName: config.serverName,
+      serverSlug: approved.serverSlug || serverSlug,
+      next: `Run magclaw-computer start ${config.profile} when ready.`,
+    });
+    return;
+  }
   const result = await startBackground(config.profile, env);
   printJson({
     ...result,
@@ -5383,6 +5856,255 @@ async function runComputerSetup(flags, env = process.env) {
   }
 }
 
+async function renderComputerAggregateStatus(env = process.env) {
+  const report = await listProfiles(env);
+  return {
+    ok: true,
+    root: report.root,
+    loggedIn: report.profiles.some((profile) => profile.configured),
+    supervisor: {
+      model: 'per-profile-service',
+      running: report.profiles.some((profile) => profile.running || profile.service?.active),
+      managedProfiles: report.profiles.length,
+    },
+    profiles: report.profiles,
+  };
+}
+
+function formatComputerStatus(report = {}) {
+  const profiles = report.profiles || [];
+  if (report.profile) {
+    return [
+      `Profile:      ${report.profile}`,
+      `Configured:   ${report.configured ? 'yes' : 'no'}`,
+      `Daemon:       ${report.running ? `running (pid ${report.pid})` : 'stopped'}`,
+      `Service:      ${report.service?.mode || 'foreground'}${report.service?.active ? ' active' : ''}`,
+      `Server URL:   ${report.serverUrl || '-'}`,
+      `Computer ID:  ${report.computerId || '-'}`,
+      `Config:       ${report.configPath}`,
+      '',
+    ].join('\n');
+  }
+  return [
+    'MagClaw Computers',
+    `Profiles: ${profiles.length}  Running: ${profiles.filter((profile) => profile.running || profile.service?.active).length}`,
+    `Root: ${report.root || '-'}`,
+    '',
+    ...profiles.map((profile) => [
+      `${profile.running || profile.service?.active ? 'online ' : 'offline'}  ${profile.profile}`,
+      `  server=${profile.serverSlug || profile.serverName || '-'} computer=${profile.computerId || '-'} service=${profile.service?.mode || 'foreground'}`,
+    ].join('\n')),
+    profiles.length ? '' : 'No profiles. Run `magclaw-computer setup /<serverSlug>` first.',
+    '',
+  ].join('\n');
+}
+
+async function computerStatus(flags = {}, env = process.env) {
+  if (hasComputerTarget(flags)) return status(computerTargetProfile(flags, flags.profile || DEFAULT_PROFILE));
+  return renderComputerAggregateStatus(env);
+}
+
+async function startAllComputerProfiles(env = process.env) {
+  const report = await listProfiles(env);
+  const results = [];
+  for (const profile of report.profiles) {
+    if (!profile.configured) continue;
+    results.push({ profile: profile.profile, ...(await startSavedBackground({ profile: profile.profile }, env)) });
+  }
+  return { ok: results.every((item) => item.ok), count: results.length, results };
+}
+
+async function stopAllComputerProfiles(flags = {}, env = process.env) {
+  const report = await listProfiles(env);
+  const results = [];
+  for (const profile of report.profiles) {
+    results.push({ profile: profile.profile, ...(await stopDaemon(profile.profile, env, { disable: Boolean(flags.disable) })) });
+  }
+  return { ok: results.every((item) => item.ok), count: results.length, results };
+}
+
+async function detachComputerProfile(flags = {}, env = process.env) {
+  const profile = computerTargetProfile(flags);
+  if (!profile || profile === DEFAULT_PROFILE && !hasComputerTarget(flags)) {
+    throw new Error('Usage: magclaw-computer detach <serverSlug>');
+  }
+  const paths = profilePaths(profile, env);
+  const stopped = await uninstallBackground(profile, env);
+  await rm(paths.dir, { recursive: true, force: true });
+  return { ok: true, profile, detached: true, stopped };
+}
+
+async function cleanupComputerResidue(env = process.env) {
+  const report = await listProfiles(env);
+  const cleaned = [];
+  await activeComputerLock(env);
+  for (const profile of report.profiles) {
+    const paths = profilePaths(profile.profile, env);
+    const before = existsSync(paths.lockFile);
+    await activeDaemonLock(profile.profile, env);
+    if (before && !existsSync(paths.lockFile)) cleaned.push(paths.lockFile);
+  }
+  return cleaned;
+}
+
+async function computerDoctor(flags = {}, env = process.env) {
+  const cleanup = Boolean(flags.cleanup || flags.fix);
+  const target = hasComputerTarget(flags) ? computerTargetProfile(flags, flags.profile || DEFAULT_PROFILE) : '';
+  const runtime = await doctor(env);
+  const aggregate = await renderComputerAggregateStatus(env);
+  const selected = target ? await status(target) : null;
+  const cleaned = cleanup ? await cleanupComputerResidue(env) : [];
+  const checks = [
+    { name: 'MAGCLAW_DAEMON_HOME', ok: true, detail: aggregate.root },
+    { name: 'profiles', ok: aggregate.profiles.length > 0, detail: `${aggregate.profiles.length} configured` },
+    { name: 'runtime', ok: runtime.runtimes.some((item) => item.available), detail: runtime.runtimes.filter((item) => item.available).map((item) => item.id).join(', ') || 'none detected' },
+  ];
+  if (selected) {
+    checks.push(
+      { name: `profile ${target}`, ok: selected.configured, detail: selected.configPath },
+      { name: `daemon ${target}`, ok: selected.running || selected.service?.active, detail: selected.running ? `running (pid ${selected.pid})` : (selected.service?.active ? 'service active' : 'stopped') },
+    );
+  }
+  return {
+    ok: checks.every((check) => check.ok !== false),
+    checks,
+    runtime,
+    aggregate,
+    ...(selected ? { profile: selected } : {}),
+    cleanup: { requested: cleanup, staleLocksCleared: cleaned },
+  };
+}
+
+async function readComputerChannel(env = process.env) {
+  const file = computerChannelPath(env);
+  const value = existsSync(file) ? String(await readFile(file, 'utf8')).trim() : 'latest';
+  return value || 'latest';
+}
+
+function validateComputerChannel(value = '') {
+  const channel = String(value || '').trim();
+  if (channel === 'latest' || channel === 'alpha' || /^pinned:[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(channel)) return channel;
+  throw new Error('Channel must be latest, alpha, or pinned:<semver>.');
+}
+
+async function setComputerChannel(value, env = process.env) {
+  const channel = validateComputerChannel(value);
+  const file = computerChannelPath(env);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${channel}\n`);
+  return channel;
+}
+
+async function computerChannel(flags = {}, env = process.env) {
+  const action = String(flags._?.[1] || flags._?.[0] || '').trim();
+  const value = String(flags._?.[2] || flags.channel || '').trim();
+  if (action === 'set') {
+    const channel = await setComputerChannel(value, env);
+    return { ok: true, channel };
+  }
+  return { ok: true, channel: await readComputerChannel(env), file: computerChannelPath(env) };
+}
+
+async function computerRunners(flags = {}, env = process.env) {
+  const action = String(flags._?.[1] || 'list').trim();
+  if (action === 'list') {
+    const aggregate = await renderComputerAggregateStatus(env);
+    return {
+      ok: true,
+      note: 'MagClaw local CLI can list Computer profiles. Per-agent runner stop/list remains a cloud console or agent-tool operation.',
+      profiles: aggregate.profiles.map((profile) => ({
+        profile: profile.profile,
+        serverSlug: profile.serverSlug,
+        computerId: profile.computerId,
+        running: profile.running || profile.service?.active,
+      })),
+    };
+  }
+  if (action === 'stop') {
+    throw new Error('Local runner stop is not available yet. Stop Agents from the MagClaw web console or agent runtime controls.');
+  }
+  throw new Error(`Unknown runners command: ${action}`);
+}
+
+async function computerUpgrade(flags = {}, env = process.env) {
+  const channel = flags.channel ? validateComputerChannel(flags.channel) : await readComputerChannel(env);
+  const targetVersion = flags.targetVersion || flags.to || flags.version || (String(channel).startsWith('pinned:') ? String(channel).slice('pinned:'.length) : channel);
+  await runManualUpgrade({
+    ...flags,
+    to: targetVersion,
+    targetVersion,
+    packageName: COMPUTER_PACKAGE_NAME,
+    packageBin: 'magclaw-computer',
+  }, {
+    ...env,
+    MAGCLAW_ENTRY_PACKAGE_NAME: COMPUTER_PACKAGE_NAME,
+    MAGCLAW_DAEMON_PACKAGE_NAME: COMPUTER_PACKAGE_NAME,
+    MAGCLAW_DAEMON_PACKAGE_KIND: 'computer',
+    MAGCLAW_DAEMON_PACKAGE_BIN: 'magclaw-computer',
+  });
+}
+
+async function runComputerCommand(flags, env = process.env) {
+  const subcommand = String(flags._?.[0] || 'help').trim();
+  if (subcommand === 'help' || flags.help) {
+    process.stdout.write(renderComputerHelp(subcommand === 'help' ? flags._?.[1] : subcommand));
+    return;
+  }
+  switch (subcommand) {
+    case 'login':
+    case 'attach':
+    case 'setup':
+      await runComputerSetup(flags, env);
+      break;
+    case 'adopt-legacy':
+      throw new Error('MagClaw legacy adoption is handled by `magclaw-computer setup /<serverSlug>` or `magclaw connect --pair-token <token>`.');
+    case 'detach':
+      printJson(await detachComputerProfile(flags, env));
+      break;
+    case 'status': {
+      const report = await computerStatus(flags, env);
+      if (flags.json) printJson(report);
+      else process.stdout.write(formatComputerStatus(report));
+      break;
+    }
+    case 'start':
+      if (hasComputerTarget(flags)) {
+        if (flags.foreground) {
+          await runForegroundDaemon(await buildConfig({ ...flags, profile: computerTargetProfile(flags) }, env), env);
+        } else {
+          printJson(await startSavedBackground({ ...flags, profile: computerTargetProfile(flags) }, env));
+        }
+      } else {
+        printJson(await startAllComputerProfiles(env));
+      }
+      break;
+    case 'stop':
+      if (hasComputerTarget(flags)) printJson(await stopDaemon(computerTargetProfile(flags), env, { disable: Boolean(flags.disable) }));
+      else printJson(await stopAllComputerProfiles(flags, env));
+      break;
+    case 'doctor': {
+      const report = await computerDoctor(flags, env);
+      if (flags.json) printJson(report);
+      else process.stdout.write(`${report.checks.map((check) => `${check.ok ? 'ok' : 'fail'}  ${check.name}: ${check.detail}`).join('\n')}\n`);
+      break;
+    }
+    case 'logs':
+      await logs(computerTargetProfile(flags), { lines: flags.lines || flags.lineCount });
+      break;
+    case 'runners':
+      printJson(await computerRunners(flags, env));
+      break;
+    case 'channel':
+      printJson(await computerChannel(flags, env));
+      break;
+    case 'upgrade':
+      await computerUpgrade(flags, env);
+      break;
+    default:
+      throw new Error(`Unknown computer command: ${subcommand}`);
+  }
+}
+
 async function buildConfig(flags, env = process.env) {
   const diskConfig = await readProfile(flags.profile, env);
   const profile = flags.profile || diskConfig.profile || DEFAULT_PROFILE;
@@ -5405,7 +6127,7 @@ async function buildConfig(flags, env = process.env) {
 
 async function runForegroundDaemon(config, env = process.env) {
   const releaseLock = await acquireDaemonLock(config.profile, config, env);
-  await markForegroundServiceState(config.profile, env);
+  await markDaemonRunServiceState(config.profile, env);
   const daemon = new MagClawDaemon(config, env);
   let forceExitTimer = null;
   const shutdown = (signal) => {
@@ -5482,6 +6204,14 @@ function requireExplicitProfile(command, flags = {}) {
 
 export async function main(argv = process.argv, env = process.env) {
   const { command, flags } = parseCli(argv);
+  if (flags.version) {
+    process.stdout.write(`${DAEMON_VERSION}\n`);
+    return;
+  }
+  if (command === 'computer' && flags.help) {
+    process.stdout.write(renderComputerHelp(flags._?.[0] || ''));
+    return;
+  }
   if (command === 'help' || flags.help) {
     process.stdout.write(renderHelp());
     return;
@@ -5491,7 +6221,7 @@ export async function main(argv = process.argv, env = process.env) {
       await runConnect(flags, env);
       break;
     case 'computer':
-      await runComputerSetup(flags, env);
+      await runComputerCommand(flags, env);
       break;
     case 'start': {
       printJson(await startSavedBackground(flags, env));

package/src/list-renderer.js

@@ -57,7 +57,8 @@ function statusLabel(profile, color) {
 
 function serviceLabel(profile) {
   const mode = fallback(profile.service?.mode, 'foreground');
-  return profile.service?.active ? `${mode}: active` : `${mode}: inactive`;
+  const status = fallback(profile.service?.status || (profile.service?.active ? 'active' : 'inactive'), 'inactive');
+  return `${mode}: ${status}`;
 }
 
 export function shouldUseColor({ env = process.env, stream = process.stdout, flags = {} } = {}) {