@cabane/companion 0.6.156 → 0.6.157

package/README.md

@@ -106,6 +106,8 @@ A freshly paired device runs nothing yet: pairing doesn't put any agent on it. I
 | `pair [--server <url>]`                  | Pair this device with a short code entered in Cabane, without starting the Companion. Refuses, like `start`, until an agent is signed in. `start` pairs by itself, so `pair` is rarely needed.                                                                                                                                      |
 | `start [--foreground] [--daemon]`        | Offer the signed-in agents, pair if needed, and run in the background; refuse, pairing nothing, when none is usable. `--daemon` is an accepted compatibility alias for the default. `--foreground` stays attached for a terminal or supervisor and never refuses. A non-interactive `start` on a paired device also stays attached. |
 | `connect <claude-code\|codex\|opencode>` | Connect a signed-in agent; with the Companion running, it checks and connects over its control socket, no restart. Refuses a signed-out agent and changes nothing.                                                                                                                                                                  |
+| `update [--auto on\|off]`                | Update to the version Cabane names now, between turns; with `--auto`, set whether the Companion keeps itself up to date.                                                                                                                                                                                                            |
+| `service install\|uninstall\|status`     | Run the Companion as a systemd user service or a LaunchAgent that starts at boot and restarts if it stops; remove it; show its state and how updates are going.                                                                                                                                                                     |
 | `stop`                                   | Stop a foreground or detached Companion cleanly. Idempotent — "nothing running" is a success.                                                                                                                                                                                                                                       |
 | `status`                                 | Print the version and install, the paired device, whether it's running, each agent's sign-in, log and transcript paths, declared secret names, and local overrides. Works unpaired.                                                                                                                                                 |
 | `logs [-n N] [-f]`                       | Show recent log lines or follow new ones.                                                                                                                                                                                                                                                                                           |
@@ -128,119 +130,15 @@ If `cabane start` says the Companion is running but the device stays **Offline**
 
 ## Background and supervised operation
 
-In an interactive terminal, `cabane start` backgrounds itself, returns the prompt, and keeps running after the terminal closes:
+In an interactive terminal, `cabane start` backgrounds itself, returns the prompt, and keeps running after the terminal closes. The first time, it asks once whether to keep Cabane running and up to date on this computer.
 
-```sh
-cabane start
-#   ✓ Cabane is running in the background.
-#     Stop:  cabane stop        Logs:  cabane logs
-```
-
-`start --daemon` takes the same path for compatibility. This detached process does not survive logout or reboot and Cabane does not install, enable, or update a login service. Use `cabane status` to check it and `cabane stop` to stop it.
-
-If you want restart or login persistence, configure your own supervisor to run `cabane start --foreground`. The supervisor owns when the process starts and restarts; the Companion never writes these files for you.
-
-### Find the executable paths
-
-The examples below need absolute paths because service managers do not load your interactive shell setup:
-
-```sh
-command -v node
-printf '%s\n' "$(npm root -g)/@cabane/companion/dist/cli.js"
-```
-
-Confirm both paths exist, then substitute them for `/absolute/path/to/node` and `/absolute/path/to/cli.js`. NVM and global npm paths are often versioned and can move after a Node or package upgrade. After every upgrade, run these commands again, update both paths in your supervisor config, and reload/restart it.
-
-### macOS LaunchAgent
-
-Save this as `~/Library/LaunchAgents/ai.cabane.companion.plist`, replacing both paths:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key><string>ai.cabane.companion</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>/absolute/path/to/node</string>
-    <string>/absolute/path/to/cli.js</string>
-    <string>start</string>
-    <string>--foreground</string>
-  </array>
-  <key>RunAtLoad</key><true/>
-  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
-  <key>StandardOutPath</key><string>/tmp/cabane-companion.out.log</string>
-  <key>StandardErrorPath</key><string>/tmp/cabane-companion.err.log</string>
-</dict>
-</plist>
-```
-
-Load it with `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.cabane.companion.plist`. Adding a login-persistent LaunchAgent is security-sensitive behavior and may be reported by macOS or endpoint-security tooling. Cabane cannot prevent or hide that report.
-
-To update moved executable paths, unload it, edit the two paths, then load it again:
-
-```sh
-launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.cabane.companion.plist
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.cabane.companion.plist
-```
-
-To remove it completely:
-
-```sh
-launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.cabane.companion.plist
-rm ~/Library/LaunchAgents/ai.cabane.companion.plist
-```
-
-### Linux systemd user unit
-
-Save this as `~/.config/systemd/user/cabane-companion.service`, replacing both paths:
-
-```ini
-[Unit]
-Description=Cabane Companion
-After=network-online.target
-
-[Service]
-Type=simple
-ExecStart=/absolute/path/to/node /absolute/path/to/cli.js start --foreground
-Restart=on-failure
-RestartSec=5
-
-[Install]
-WantedBy=default.target
-```
-
-Load it with:
-
-```sh
-systemctl --user daemon-reload
-systemctl --user enable --now cabane-companion.service
-```
-
-A user service normally stops when its login session ends. If this machine must keep running it after logout, an administrator can enable lingering with `sudo loginctl enable-linger "$USER"`; that is a separate operating-system persistence decision.
-
-After an NVM/npm upgrade, stop the unit, rediscover and replace both executable paths, then reload and restart it:
-
-```sh
-systemctl --user stop cabane-companion.service
-systemctl --user daemon-reload
-systemctl --user start cabane-companion.service
-```
-
-To remove it completely:
-
-```sh
-systemctl --user disable --now cabane-companion.service
-rm ~/.config/systemd/user/cabane-companion.service
-systemctl --user daemon-reload
-```
+Yes, or `cabane service install` later, runs it as a service: a systemd user unit (`~/.config/systemd/user/cabane-companion.service`) on Linux, a LaunchAgent (`~/Library/LaunchAgents/ai.cabane.companion.plist`) on macOS, with auto-update on. It runs `<node> ~/.cabane/boot-guard.mjs start --foreground` on its own copy of this install under `~/.cabane/versions`, restarts it whatever it exits with, and reads `~/.cabane/service.env`, which holds your login shell's PATH and any headless sign-in (`CLAUDE_CODE_OAUTH_TOKEN=…`). `<node>` is the install script's `~/.cabane/node/bin/node` when it's there, otherwise the Node that ran `service install`; `cabane service status` says if it's gone. On Linux it tells you when lingering is off and a logout would stop it. With a service installed, `cabane start` and `cabane stop` start and stop the service; `cabane service uninstall` removes it.
 
-If you enabled lingering only for this Companion, undo it separately with `sudo loginctl disable-linger "$USER"`.
+Updates need the service: it's what restarts the Companion into a new version. The Companion follows the version Cabane names on each heartbeat: it installs it under `~/.cabane/versions/<version>`, checks it starts and still has the bundled agents this device uses, points `~/.cabane/current` at it between turns, and exits for the service to restart it. A version that stops three times before connecting, or can't connect within ten minutes of Cabane answering, is rolled back by the boot guard. `cabane update --auto off|on` stops or resumes updates under the service. Without the service, `cabane update` installs the latest version and the next `cabane start` runs it.
 
 ### Other supervisors
 
-Run `cabane start --foreground`. Configure the supervisor itself for restart and login/boot behavior, and use absolute executable paths when it does not load your interactive shell. Removing the supervisor configuration removes the persistence; no Cabane-managed service remains.
+Run `cabane start --foreground` with `CABANE_COMPANION_SUPERVISED=1` in its environment. Configure the supervisor itself for restart and login/boot behavior, and use absolute executable paths when it does not load your interactive shell: `~/.cabane/node/bin/node` and `~/.cabane/current/dist/bin.js` don't move on an update. Without the boot guard a supervisor of your own doesn't roll back a release that fails before it starts.
 
 ## Configuring an agent: what's in Cabane vs. on this machine
 
@@ -489,4 +387,4 @@ It renders the conversation step by step — `🔧 tool(input) → ok/ERROR: res
 
 ## What v0 doesn't do yet
 
-There's no OS-service install — an interactive `start` runs detached but doesn't survive logout/reboot or auto-restart on crash. A non-interactive `start` stays attached for a supervisor or provisioner. There's no per-tool permissioning for an agent with host access yet. And there's no self-update; re-run `npm i -g @cabane/companion@latest` to pick up a new version.
+Windows has no service install and no self-update. There's no per-tool permissioning for an agent with host access yet.

package/dist/bin.js

@@ -10,4 +10,5 @@ if (!(major >= MIN_NODE_MAJOR)) {
   );
   process.exit(1);
 }
-await import("./cli.js");
+var { launch } = await import("./launch.js");
+await launch();

package/dist/boot-guard.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+// src/boot-guard.ts
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { pathToFileURL } from "url";
+
+// src/boot-rule.ts
+import {
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname, join } from "path";
+var UNCONFIRMED_WINDOW_MS = 10 * 6e4;
+var MAX_UNCONFIRMED_BOOTS = 3;
+var MAX_STAGE_ATTEMPTS = 3;
+function bootVerdict(pending, version, lastCrash) {
+  if (!pending || pending.to !== version) return { kind: "run" };
+  if (pending.boots >= MAX_UNCONFIRMED_BOOTS) {
+    return {
+      kind: "rollback",
+      pending,
+      reason: lastCrash ?? `it stopped ${pending.boots} times before connecting to Cabane`
+    };
+  }
+  return { kind: "run", pending: { ...pending, boots: pending.boots + 1 } };
+}
+function superseded(pending, ...running) {
+  return !!pending && !running.includes(pending.to);
+}
+function rolledBackState(state, pending, reason, now) {
+  const { pending: _done, ...rest } = state;
+  return {
+    ...rest,
+    lastResult: {
+      kind: "rolled_back",
+      from: pending.from,
+      to: pending.to,
+      at: now.toISOString(),
+      reason: reason.replace(/\s+/g, " ").trim().slice(0, 400)
+    },
+    failed: { version: pending.to, attempts: MAX_STAGE_ATTEMPTS, at: now.toISOString() }
+  };
+}
+function guardBoot(dir, now = Date.now()) {
+  const link = join(dir, "current");
+  let root2;
+  try {
+    root2 = realpathSync(link);
+  } catch {
+    return null;
+  }
+  const statePath = join(dir, "update.json");
+  const state = readJson(statePath);
+  const version = readJson(join(root2, "package.json")).version ?? "";
+  const crash = readJson(join(dir, "last-error.json")).reason ?? null;
+  if (superseded(state.pending, version)) {
+    const { pending: _gone, ...rest } = state;
+    writeJson(statePath, rest);
+    return root2;
+  }
+  const verdict = bootVerdict(state.pending, version, crash);
+  if (verdict.kind === "rollback") {
+    const back = verdict.pending.fromRoot;
+    const fresh = `${link}.${process.pid}.${now}`;
+    symlinkSync(back, fresh);
+    renameSync(fresh, link);
+    writeJson(statePath, rolledBackState(state, verdict.pending, verdict.reason, new Date(now)));
+    process.stderr.write(
+      `Cabane ${verdict.pending.to} didn't come up (${verdict.reason}); going back to ${verdict.pending.from}.
+`
+    );
+    return back;
+  }
+  if (verdict.pending) writeJson(statePath, { ...state, pending: verdict.pending });
+  return root2;
+}
+function readJson(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+// src/boot-guard.ts
+var root = guardBoot(join2(process.env.CABANE_COMPANION_HOME || homedir(), ".cabane"));
+if (!root) {
+  process.stderr.write(
+    "Cabane isn't installed where the service expects it (~/.cabane/current). Run  cabane service install  again.\n"
+  );
+  process.exit(1);
+}
+await import(pathToFileURL(join2(root, "dist", "bin.js")).href);