devchain-cli 0.24.1 → 0.25.0

package/README.md

@@ -45,7 +45,7 @@ DevChain opens in your browser:
 2. Import the `teams-dev` template: a Planning team (Brainstormer and Architects), a Builders team (Epic Manager and Coders), and a Code Reviewer.
 3. Start the Brainstormer and describe what you want to build.
 
-`devchain start --help` lists the port, host, and foreground options. `devchain stop` stops the server. CI tests DevChain on Linux x64 with Node 24, plus a Node 26 compatibility lane. The install checks that SQLite loads on your platform and stops if it does not; `DEVCHAIN_SKIP_POSTINSTALL=1` skips that check.
+`devchain start --help` lists the port, host, and foreground options. `devchain stop` stops the server. The install checks that SQLite loads on your platform and stops if it does not; `DEVCHAIN_SKIP_POSTINSTALL=1` skips that check.
 
 ## Remote VMs
 
@@ -92,7 +92,16 @@ The Local App serves the web UI and keeps all state in a local SQLite database.
 
 ## Mobile app
 
-Follow and steer your agent teams from your phone. The app is in open beta on [iOS (TestFlight)](https://testflight.apple.com/join/VSbfE1c6) and [Android (Play Store)](https://play.google.com/apps/testing/com.twitech.devchain.mobile).
+<p align="center">
+  <img src=".github/assets/mobile-app-phones.png" alt="The DevChain mobile app: the Board, Agents and chat, and Notifications screens" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://apps.apple.com/app/devchain/id6778791584"><img src=".github/assets/badge-app-store.png" alt="Download on the App Store" height="72"></a>
+  <a href="https://play.google.com/store/apps/details?id=com.twitech.devchain.mobile"><img src=".github/assets/badge-google-play.png" alt="Get it on Google Play" height="72"></a>
+</p>
+
+Follow and steer your agent teams from your phone, on iPhone and Android.
 
 Chat with agents, answer their questions as they ask, reassign epics, comment on the board, watch a live terminal, and get a push notification when a session stops or needs you. Review and merge stay on the web. Everything between your PC and your phone is end-to-end encrypted.
 

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "commit": "1f8af83038304b62ddd5bff0f4eb5703f9826e65",
+  "commit": "da58aa986f626b5ebf4bb2e9ae506bd77cae0179",
   "dirty": false,
-  "builtAt": "2026-10-02T22:58:40.935Z"
+  "builtAt": "2026-10-11T14:13:29.114Z"
 }

package/dist/cli.js

@@ -16,6 +16,8 @@ const { spawn, execSync, execFileSync } = require('child_process');
 const { pathToFileURL } = require('url');
 const { InteractiveCLI } = require('./lib/interactive-cli');
 const { runHostInstallCommand } = require('./lib/host-install');
+const { runGitOwnerCommand } = require('./lib/git-owner');
+const { getLocalApiBaseUrl } = require('./lib/local-api');
 const { runHostApiKeyReset } = require('./lib/host-api-key');
 const { QUEUE_NAME, runExclusive } = require('./lib/exclusive-run');
 const readline = require('readline');
@@ -1412,6 +1414,34 @@ async function main(argv) {
       });
     });
 
+  const git = program.command('git').description('Move Git control between this PC and the VM');
+  for (const name of ['status', 'take', 'return']) {
+    const command = git
+      .command(name)
+      .description(
+        {
+          status: 'Show Git control and any unfinished switch',
+          take: 'Move Git control to this PC',
+          return: 'Move Git control back to the VM',
+        }[name],
+      )
+      .option('--project <path>', 'Project folder (defaults to the current folder)');
+    if (name === 'take') {
+      command.option('--force', "Stop this project's agent sessions on the VM before the switch");
+    }
+    command.action(async (options) => {
+      process.exitCode = await runGitOwnerCommand(name, options, {
+        getMachineRole,
+        getLocalApiBaseUrl: () =>
+          getLocalApiBaseUrl({
+            readPidFile,
+            isProcessRunning,
+            resolveSharedModuleSpecifier,
+          }),
+      });
+    });
+  }
+
   const host = program.command('host').description('Manage DevChain hosts');
 
   host
@@ -1424,7 +1454,10 @@ async function main(argv) {
     .option('--passphrase-stdin', 'Read the SSH key passphrase from one line of stdin')
     .option('--sudo-password-stdin', 'Read the optional sudo password from one line of stdin')
     .option('--projects <project-ids...>', 'Project ids to include in the disk estimate')
-    .option('--no-docker', 'Do not install Docker Engine and Compose on the VM (installed by default)')
+    .option(
+      '--no-docker',
+      'Do not install Docker Engine and Compose on the VM (installed by default)',
+    )
     .option(
       '--provider-auth <provider=choice>',
       'Provider login choice: skip, generate, or reuse:<entry-id> (repeatable)',
@@ -1432,15 +1465,12 @@ async function main(argv) {
     )
     .action(async (options) => {
       const exitCode = await runHostInstallCommand(options, {
-        getLocalApiBaseUrl: async () => {
-          const pidData = readPidFile();
-          if (!pidData || !isProcessRunning(pidData.pid)) return null;
-          const { HostResolver } = await import(resolveSharedModuleSpecifier());
-          return HostResolver.buildInternalBaseUrl({
-            host: pidData.host || '127.0.0.1',
-            port: pidData.port,
-          });
-        },
+        getLocalApiBaseUrl: () =>
+          getLocalApiBaseUrl({
+            readPidFile,
+            isProcessRunning,
+            resolveSharedModuleSpecifier,
+          }),
       });
       process.exitCode = exitCode;
     });

package/dist/host-install/pins.json

@@ -5,7 +5,7 @@
   "bootstrap": {
     "package": "devchain-host-bootstrap",
     "version": "0.1.0",
-    "sha256": "724d4664ff9bc77d5d6be21de949022cb8e3a01cbb8ad525fef971136db65f96"
+    "sha256": "e350fb9897fa3d1902ee4bde76d868bf1244addae7423e0417b40534fb3681f0"
   },
   "aptPackages": [
     "qemu-guest-agent",
@@ -17,6 +17,11 @@
     "build-essential",
     "python3",
     "jq",
+    "openssl",
+    "procps",
+    "libcap2-bin"
+  ],
+  "toolPackages": [
     "ripgrep",
     "python-is-python3",
     "python3-pip",
@@ -26,6 +31,31 @@
     "bsdextrautils",
     "rsync",
     "unzip",
-    "openssl"
+    "screen",
+    "psmisc",
+    "time",
+    "lsof",
+    "strace",
+    "htop",
+    "less",
+    "nano",
+    "vim-tiny",
+    "tree",
+    "zip",
+    "net-tools",
+    "iputils-ping",
+    "inetutils-telnet",
+    "netcat-openbsd",
+    "bind9-dnsutils",
+    "traceroute",
+    "mtr-tiny",
+    "tcpdump",
+    "socat",
+    "fd-find",
+    "universal-ctags",
+    "gawk",
+    "shellcheck",
+    "cloc",
+    "git-lfs"
   ]
 }

package/dist/lib/exclusive-run.js

@@ -1,11 +1,23 @@
 const fs = require("node:fs");
-const { spawn } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 const { randomBytes } = require("node:crypto");
 const { homedir, constants } = require("node:os");
-const { join, resolve } = require("node:path");
+const { delimiter, join, resolve } = require("node:path");
 
 const QUEUE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+// systemd-run execs the command in place: pid, process group, stdio and exit
+// code stay the same. systemd 258 and later expand $VAR in the arguments
+// unless told not to.
+const SCOPE_ARGS = [
+  "--user",
+  "--scope",
+  "--quiet",
+  "--collect",
+  "--expand-environment=no",
+  "--",
+];
+let scopeAvailable;
 
 function isPid(value) {
   return Number.isInteger(value) && value > 0;
@@ -150,13 +162,49 @@ function formatWait(ms) {
   return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
 }
 
+function findExecutable(command, env) {
+  const candidates = command.includes("/")
+    ? [resolve(command)]
+    : (env.PATH || "")
+        .split(delimiter)
+        .filter(Boolean)
+        .map((dir) => join(dir, command));
+  return candidates.find((file) => {
+    try {
+      fs.accessSync(file, fs.constants.X_OK);
+      return fs.statSync(file).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+// In a user scope of its own, a command that systemd-oomd kills does not take
+// the caller's scope down with it, e.g. an agent's tmux pane.
+function scopedSpawnArgs(command, args, env) {
+  if (process.platform !== "linux") return [command, args];
+  const executable = findExecutable(command, env);
+  // An unknown command spawns directly, so its start error still names it.
+  if (!executable) return [command, args];
+  scopeAvailable ??=
+    spawnSync("systemd-run", [...SCOPE_ARGS, "true"], {
+      env,
+      stdio: "ignore",
+      timeout: 5000,
+    }).status === 0;
+  return scopeAvailable
+    ? ["systemd-run", [...SCOPE_ARGS, executable, ...args]]
+    : [command, args];
+}
+
 async function spawnAndForward(
   { command, args, env, pollMs, name },
   state,
   onSpawn,
 ) {
   if (state.signal) return signalCode(state.signal);
-  const child = spawn(command, args, { env, stdio: "inherit", detached: true });
+  const [file, argv] = scopedSpawnArgs(command, args, env);
+  const child = spawn(file, argv, { env, stdio: "inherit", detached: true });
   state.pgid = child.pid || null;
   const result = new Promise((done) => {
     child.once("error", (error) => {

package/dist/lib/git-owner.js

@@ -0,0 +1,284 @@
+const { dirname, resolve } = require("node:path");
+const {
+  LocalApiHttpError,
+  POLL_INTERVAL_MS,
+  getOperation,
+  printOperationSteps,
+  requestJson,
+  writeLine,
+} = require("./local-api");
+
+// The server checks the VM before it starts a switch; each check can take 15 seconds.
+const START_TIMEOUT_MS = 120_000;
+
+class GitCommandRefusedError extends Error {}
+
+async function findProject(fetchImpl, baseUrl, path) {
+  let candidate = resolve(path);
+  for (;;) {
+    try {
+      const project = await requestJson(
+        fetchImpl,
+        baseUrl,
+        `/api/projects/by-path?path=${encodeURIComponent(candidate)}`,
+      );
+      if (!project || typeof project.id !== "string") {
+        throw new Error("DevChain returned an invalid project.");
+      }
+      return project;
+    } catch (error) {
+      if (!(error instanceof LocalApiHttpError) || error.status !== 404)
+        throw error;
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) {
+      throw new GitCommandRefusedError(
+        `No registered project contains ${resolve(path)}.`,
+      );
+    }
+    candidate = parent;
+  }
+}
+
+function recoveryCommand(owner, force, projectPath) {
+  const command =
+    owner === "home"
+      ? `devchain git take${force ? " --force" : ""}`
+      : "devchain git return";
+  return projectPath
+    ? `${command} --project '${projectPath.replace(/'/g, "'\\''")}'`
+    : command;
+}
+
+function ownerMessage(owner, remoteName, already = false) {
+  const side = owner === "home" ? "this PC" : `the VM '${remoteName}'`;
+  return `Git for this project is ${already ? "already " : ""}on ${side}.`;
+}
+
+function printStatus(status, stdout, projectPath) {
+  writeLine(
+    stdout,
+    status.connected
+      ? ownerMessage(status.owner, status.remoteName)
+      : "This project is not connected to a VM.",
+  );
+  if (!status.open) return;
+  const open = status.open;
+  writeLine(stdout, `Git switch ${open.operationId}: ${open.state}.`);
+  writeLine(
+    stdout,
+    `Target: ${open.owner === "home" ? "this PC" : `the VM '${status.remoteName}'`}.`,
+  );
+  if (open.step) writeLine(stdout, `Step: ${open.step}.`);
+  if (open.error)
+    writeLine(
+      stdout,
+      `Error: ${open.error.message}${open.error.code ? ` (${open.error.code})` : ""}`,
+    );
+  writeLine(
+    stdout,
+    `To finish the switch, run \`${recoveryCommand(open.owner, open.force, projectPath)}\`.`,
+  );
+}
+
+function printDetails(operation, seen, stderr) {
+  const details = operation.details ?? {};
+  const emit = (line) => {
+    if (seen.has(line)) return;
+    seen.add(line);
+    writeLine(stderr, line);
+  };
+  const unknownAgents = details.unknownAgents ?? [];
+  if (unknownAgents.length > 0)
+    emit(
+      "These agents on the VM have an unknown state. They do not block the switch:",
+    );
+  for (const agent of unknownAgents) {
+    emit(`  - ${agent.agentName} (state unknown)`);
+  }
+  for (const warning of [details.guardWarning, details.vmGuardWarning]) {
+    if (warning) emit(`WARNING: ${warning}`);
+  }
+  for (const [field, side] of [
+    ["pcGuardRemove", "PC"],
+    ["vmGuardRemove", "VM"],
+  ]) {
+    const result = details[field];
+    if (!result) continue;
+    if (result.warning) emit(`WARNING: ${result.warning}`);
+    if (result.indexRefreshed !== true)
+      emit(`WARNING: The ${side} Git index was not rebuilt.`);
+  }
+}
+
+function printBusyAgents(error, remoteName, context, projectPath) {
+  const agents = error.details?.agents ?? [];
+  writeLine(
+    context.stderr,
+    `Git stays on the VM '${remoteName}': ${agents.length} ${agents.length === 1 ? "agent is" : "agents are"} working in this project.`,
+  );
+  for (const agent of agents) {
+    const elapsed = context.wallNow() - Date.parse(agent.since);
+    const minutes = Number.isFinite(elapsed)
+      ? Math.max(0, Math.floor(elapsed / 60_000))
+      : null;
+    const duration =
+      minutes === null
+        ? "time unknown"
+        : minutes < 1
+          ? "less than 1 min"
+          : `${minutes} min`;
+    const state =
+      agent.state === "busy" ? `busy for ${duration}` : `starting, ${duration}`;
+    writeLine(context.stderr, `  - ${agent.agentName} (${state})`);
+  }
+  writeLine(
+    context.stderr,
+    `Wait until they finish, then run \`${recoveryCommand("home", false, projectPath)}\` again.`,
+  );
+  writeLine(
+    context.stderr,
+    `To stop this project's agent sessions on the VM now, run \`${recoveryCommand("home", true, projectPath)}\`.`,
+  );
+}
+
+async function runGitOwnerCommand(command, options = {}, dependencies = {}) {
+  const stdout = dependencies.stdout ?? process.stdout;
+  const stderr = dependencies.stderr ?? process.stderr;
+  const fetchImpl = dependencies.fetch ?? globalThis.fetch;
+  const context = {
+    stdout: stderr,
+    stderr,
+    secrets: [],
+    now: dependencies.now ?? (() => performance.now()),
+    wallNow: dependencies.wallNow ?? Date.now,
+    sleep:
+      dependencies.sleep ??
+      ((ms) => new Promise((done) => setTimeout(done, ms))),
+  };
+  let status;
+  try {
+    if (dependencies.getMachineRole?.() === "remote VM") {
+      throw new GitCommandRefusedError(
+        "Run this command on the PC that connected this project.",
+      );
+    }
+    if (
+      !["status", "take", "return"].includes(command) ||
+      (command !== "take" && options.force)
+    ) {
+      throw new GitCommandRefusedError(
+        "Use devchain git status, take [--force], or return.",
+      );
+    }
+    const baseUrl = await dependencies.getLocalApiBaseUrl?.();
+    if (!baseUrl) {
+      writeLine(stderr, "Start DevChain first (devchain start).");
+      return 1;
+    }
+    const project = await findProject(
+      fetchImpl,
+      baseUrl,
+      options.project ?? dependencies.cwd ?? process.cwd(),
+    );
+    status = await requestJson(
+      fetchImpl,
+      baseUrl,
+      `/api/remotes/git-owner?projectId=${encodeURIComponent(project.id)}`,
+    );
+    if (command === "status") {
+      printStatus(status, stdout, options.project);
+      return 0;
+    }
+    if (!status.connected || !status.remoteId) {
+      throw new GitCommandRefusedError(
+        "This project is not connected to a VM.",
+      );
+    }
+    const owner = command === "take" ? "home" : "vm";
+    let operation = await requestJson(
+      fetchImpl,
+      baseUrl,
+      `/api/remotes/${encodeURIComponent(status.remoteId)}/git-owner`,
+      {
+        method: "POST",
+        body: { projectId: project.id, owner, force: options.force === true },
+        timeoutMs: START_TIMEOUT_MS,
+      },
+    );
+    if (operation?.changed === false) {
+      if (operation.cancelledOperationId) {
+        writeLine(
+          stdout,
+          `Cancelled the failed switch ${operation.cancelledOperationId}.`,
+        );
+      }
+      writeLine(stdout, ownerMessage(operation.owner, status.remoteName, true));
+      return 0;
+    }
+    const steps = new Map();
+    const details = new Set();
+    let announced = false;
+    for (;;) {
+      if (
+        !operation ||
+        typeof operation.id !== "string" ||
+        !Array.isArray(operation.steps) ||
+        !["running", "failed", "done", "cancelled"].includes(operation.state)
+      ) {
+        throw new Error("DevChain returned an invalid Git switch operation.");
+      }
+      const target = operation.details?.owner ?? owner;
+      const repeat = recoveryCommand(
+        target,
+        operation.details?.force === true,
+        options.project,
+      );
+      context.recoveryHint = `Run \`${repeat}\` again to follow or retry operation ${operation.id}.`;
+      if (!announced) {
+        writeLine(stderr, `Git switch started (operation ${operation.id}).`);
+        announced = true;
+      }
+      printOperationSteps(operation, steps, context);
+      printDetails(operation, details, stderr);
+      if (operation.state === "done") {
+        writeLine(stdout, ownerMessage(target, status.remoteName));
+        return 0;
+      }
+      if (operation.state === "failed" || operation.state === "cancelled") {
+        const failed = operation.steps.find((step) => step.state === "failed");
+        writeLine(
+          stderr,
+          failed?.error?.message ?? `Git switch ${operation.state}.`,
+        );
+        writeLine(stderr, context.recoveryHint);
+        return 1;
+      }
+      await context.sleep(POLL_INTERVAL_MS);
+      operation = await getOperation(fetchImpl, baseUrl, operation.id, context);
+    }
+  } catch (error) {
+    const code = error.details?.code ?? error.code;
+    if (code === "GIT_TAKE_AGENTS_BUSY") {
+      printBusyAgents(error, status?.remoteName, context, options.project);
+      return 2;
+    }
+    writeLine(stderr, error.message ?? "Git command failed.");
+    if (
+      code === "REMOTE_OPERATION_CANCEL_FAILED" ||
+      (error instanceof LocalApiHttpError && error.status >= 500)
+    ) {
+      writeLine(stderr, "Run the same command again.");
+      return 1;
+    }
+    if (
+      error instanceof GitCommandRefusedError ||
+      (error instanceof LocalApiHttpError &&
+        [400, 403, 404, 409, 422].includes(error.status))
+    )
+      return 2;
+    return 1;
+  }
+}
+
+module.exports = { runGitOwnerCommand };