@amenophis1er/foreman 0.1.2 → 0.1.4

package/README.md

@@ -60,6 +60,19 @@ which account pays, the Claude Code install, Ollama and Codex if present, the
 browser missions will use, the port, Tailscale, the data directory — and
 exits. Nothing blocks unless it says so.
 
+**Environment.** Everything the CLI reads; `foreman --help` prints the same list.
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `PORT` | listen port | `4177` |
+| `FOREMAN_HOME` | state directory: runs, settings, logs | `~/.foreman` |
+| `FOREMAN_BIND` | `auto` (loopback + Tailscale when present), `local`, or `all` | `auto` |
+| `FOREMAN_BROWSER` | browser for missions: `chrome`, `chromium`, `msedge`, `firefox` | `chrome` |
+| `FOREMAN_CLAUDE_CONFIG_DIR` | the Claude Code install missions run under | inherited |
+| `FOREMAN_CLAUDE_EXECUTABLE` | the Claude Code executable | bundled |
+| `FOREMAN_AUTH_MODE` | assert `api-key` or `subscription`; fail at start on mismatch | unset |
+| `FOREMAN_NO_TELEGRAM` | `1` to start without the Telegram bot: for a second server beside the main one, since Telegram allows one poller per bot | unset |
+
 ## A mission, start to finish
 
 1. **Fleet.** The board: what needs you (answerable right there), what is
@@ -213,6 +226,16 @@ npm run dev                  # API + Vite together
 scripts/dev-restart.sh       # restarts the server only when nothing would be lost
 ```
 
+To run a checkout beside an installed Foreman on the same machine, give it its
+own port and leave the bot to the installed one:
+
+```sh
+PORT=4178 FOREMAN_BIND=local FOREMAN_NO_TELEGRAM=1 npm start
+```
+
+Both read `~/.foreman`; look from the second, drive from the first — two
+servers running missions against one store is the one case nothing guards.
+
 Releases: `npm version <patch|minor|major> && git push --follow-tags` — CI
 tests, publishes to npm with provenance, and creates the GitHub release.
 

package/bin/foreman.mjs

@@ -25,6 +25,7 @@ const USAGE = `foreman ${pkg.version}
   foreman logs               Tail the log
   foreman open               Open the dashboard in your browser
   foreman doctor             Check credentials, providers, browser, port, Tailscale — and exit
+  foreman update             Install the latest version and restart the same way (refuses mid-mission; --force)
 
   foreman service install    Keep Foreman running: start at login, restart if it dies
   foreman service start|stop|restart|status|logs
@@ -42,6 +43,7 @@ Environment:
   FOREMAN_CLAUDE_CONFIG_DIR   Claude Code install missions run under
   FOREMAN_CLAUDE_EXECUTABLE   Claude Code executable (default: bundled)
   FOREMAN_AUTH_MODE           Assert 'api-key' or 'subscription'; fail on mismatch
+  FOREMAN_NO_TELEGRAM=1       Do not attach the Telegram bot (a second server beside the main one)
 `;
 
 const [command = 'start', ...rest] = process.argv.slice(2);
@@ -53,7 +55,7 @@ if (command === '--help' || command === '-h' || command === 'help') {
 } else if (command === 'start') {
   register();
   await import(new URL('../src/server.ts', import.meta.url).href);
-} else if (['doctor', 'open', 'service', 'up', 'down', 'stop', 'restart', 'status', 'logs', 'uninstall'].includes(command)) {
+} else if (['doctor', 'open', 'service', 'up', 'down', 'stop', 'restart', 'status', 'logs', 'uninstall', 'update'].includes(command)) {
   register();
   const { runCli } = await import(new URL('../src/cli.ts', import.meta.url).href);
   process.exitCode = await runCli(command, rest, { version: pkg.version, bin: new URL(import.meta.url) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amenophis1er/foreman",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Autonomous mission runner on the Claude Agent SDK: a director plans, delegates to workers, verifies, and reports — from one dashboard, your phone, or the CLI.",
   "keywords": [
     "claude",

package/src/cli.ts

@@ -13,13 +13,14 @@
  *           be up when the laptop lid is closed; this is that.
  */
 import { execFile, spawn } from 'node:child_process';
-import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { access, chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { openSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { preflight, reportPreflight } from './preflight.js';
 import { detectTailscale } from './tailscale.js';
+import { PACKAGE, checkForUpdate, currentVersion } from './update.js';
 
 const PORT = Number(process.env.PORT ?? 4177);
 const HOME_DIR = process.env.FOREMAN_HOME || path.join(os.homedir(), '.foreman');
@@ -169,8 +170,12 @@ async function serviceUninstall(): Promise<number> {
 /** Is the service registered, and is it running? Null pid when registered but idle. */
 async function serviceState(): Promise<{ installed: boolean; running: boolean; pid?: number }> {
   if (process.platform === 'darwin') {
+    // Installed means the plist is on disk; a stopped service (booted out
+    // by `service stop`) is still installed, and `service start` brings it
+    // back. launchctl only knows about loaded jobs, so it answers "running".
+    const installed = await access(path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`)).then(() => true, () => false);
     const r = await sh('launchctl', ['print', `gui/${os.userInfo().uid}/${LABEL}`]);
-    if (r.code !== 0) return { installed: false, running: false };
+    if (r.code !== 0) return { installed, running: false };
     const pid = Number(/pid = (\d+)/.exec(r.out)?.[1]);
     return { installed: true, running: Number.isFinite(pid) && pid > 0, ...(pid ? { pid } : {}) };
   }
@@ -229,7 +234,11 @@ async function serviceRestart(): Promise<number> {
 async function serviceStatus(): Promise<number> {
   if (process.platform === 'darwin') {
     const r = await sh('launchctl', ['print', `gui/${os.userInfo().uid}/${LABEL}`]);
-    if (r.code !== 0) { console.log('Not installed. `foreman service install` keeps Foreman running.'); return 1; }
+    if (r.code !== 0) {
+      const st = await serviceState();
+      console.log(st.installed ? 'Installed · stopped — `foreman service start` starts it (it also comes back at next login).' : 'Not installed. `foreman service install` keeps Foreman running.');
+      return 1;
+    }
     const state = /state = (\w+)/.exec(r.out)?.[1] ?? 'unknown';
     const pid = /pid = (\d+)/.exec(r.out)?.[1];
     console.log(`Installed · ${state}${pid ? ` · pid ${pid}` : ''} · http://localhost:${PORT}`);
@@ -253,6 +262,62 @@ async function serviceLogs(): Promise<number> {
   return new Promise((r) => child.on('exit', (c) => r(c ?? 0)));
 }
 
+/** One quiet line when a newer version exists; nothing when current or unknown. */
+async function updateHint(): Promise<void> {
+  const u = await checkForUpdate(currentVersion(), 2_000);
+  if (u?.newer) console.log(`\nForeman ${u.latest} is available (you have ${u.current}) — \`foreman update\``);
+}
+
+/** Anything a restart would cut off: a run, an ask waiting, a planner mid-reply. */
+async function liveWork(): Promise<string | null> {
+  try {
+    const d = await fetch(`http://127.0.0.1:${PORT}/projects`, { signal: AbortSignal.timeout(2000) }).then((r) => r.json()) as { projects: Array<{ id: string; name: string; activeRun?: unknown; needs?: unknown[] }> };
+    const running = d.projects.filter((p) => p.activeRun).map((p) => p.name);
+    const needs = d.projects.reduce((n, p) => n + (p.needs?.length ?? 0), 0);
+    const thinking: string[] = [];
+    for (const p of d.projects) {
+      try {
+        const c = await fetch(`http://127.0.0.1:${PORT}/chat?projectId=${encodeURIComponent(p.id)}`, { signal: AbortSignal.timeout(2000) }).then((r) => r.json()) as { thinking?: boolean };
+        if (c.thinking) thinking.push(p.name);
+      } catch { /* a project whose chat cannot be read is not live work */ }
+    }
+    if (!running.length && !needs && !thinking.length) return null;
+    return [running.length ? `running: ${running.join(', ')}` : '', needs ? `${needs} ask(s) waiting` : '', thinking.length ? `planner replying: ${thinking.join(', ')}` : ''].filter(Boolean).join(' · ');
+  } catch { return null; } // not up — nothing to cut off
+}
+
+/**
+ * Update the installed package and restart Foreman the way it is running.
+ * Refuses while anything would be cut off; --force overrides, eyes open.
+ * Never automatic: this is the one place the code under a mission changes,
+ * and it happens by a human's hand.
+ */
+async function update(bin: string, flags: string[]): Promise<number> {
+  const u = await checkForUpdate(currentVersion(), 5_000);
+  if (!u) { console.error('Could not reach the npm registry to check for a newer version.'); return 1; }
+  if (!u.newer) { console.log(`Already on the latest version (${u.current}).`); return 0; }
+  const busy = await liveWork();
+  if (busy && !flags.includes('--force')) {
+    console.error(`Not updating: ${busy}. An update restarts the server and would cut that off. Wait, or \`foreman update --force\`.`);
+    return 2;
+  }
+  console.log(`Updating ${u.current} → ${u.latest}…`);
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const code = await new Promise<number>((r) => {
+    const c = spawn(npm, ['install', '-g', `${PACKAGE}@${u.latest}`, '--no-audit', '--no-fund'], { stdio: 'inherit' });
+    c.on('exit', (x) => r(x ?? 1)); c.on('error', () => r(1));
+  });
+  if (code !== 0) { console.error('npm install failed; nothing was restarted.'); return code; }
+  // Restart by the means it is running, so the new code actually serves.
+  const pid = await readPid();
+  if (pid && alive(pid)) { console.log('Restarting the background server…'); const c = await down(); if (c !== 0) return c; return up(bin); }
+  const svc = await serviceState();
+  if (svc.running || svc.installed) { console.log('Restarting the service…'); return serviceRestart(); }
+  if (await listening(PORT)) { console.log(`Installed ${u.latest}. The server on :${PORT} runs in a terminal — restart it there to pick it up.`); return 0; }
+  console.log(`Installed ${u.latest}. Start it with \`foreman\`, \`foreman up\` or \`foreman service install\`.`);
+  return 0;
+}
+
 async function doctor(): Promise<number> {
   const tailnet = await detectTailscale();
   const distDir = fileURLToPath(new URL('../ui/dist', import.meta.url));
@@ -262,6 +327,7 @@ async function doctor(): Promise<number> {
     if (c.name.startsWith('Port') && c.status === 'error') { c.status = 'warn'; c.detail = 'in use — Foreman is probably already running'; c.fix = `foreman open · or PORT=${PORT + 1} foreman`; }
   }
   const ok = reportPreflight(checks);
+  await updateHint();
   return ok ? 0 : 1;
 }
 
@@ -342,6 +408,7 @@ async function status(): Promise<number> {
     const svc = await serviceState();
     const how = pid && alive(pid) ? `background, pid ${pid}` : svc.running ? `the service${svc.pid ? `, pid ${svc.pid}` : ''}` : 'a terminal';
     console.log(`Up at http://localhost:${PORT} (${how})`);
+    await updateHint();
     return 0;
   }
   if (pid) await rm(PID_FILE, { force: true });
@@ -419,6 +486,7 @@ export async function runCli(command: string, rest: string[], ctx: { version: st
   switch (command) {
     case 'up': return up(bin);
     case 'down': return down();
+    case 'update': return update(bin, rest);
     case 'stop': return stop();
     case 'restart': return restart(bin);
     case 'logs': return logs();

package/src/server.ts

@@ -55,6 +55,7 @@ import {
 import { DEFAULT_TOOL_POLICY } from './policy.js';
 import { saveAttachments } from './attachments.js';
 import { detectTailscale, tailnetUrl } from './tailscale.js';
+import { checkForUpdate, currentVersion, type UpdateInfo } from './update.js';
 import { ServiceRegistry, SVC_PREFIX, parseServicePath, portOpen, proxyToService, servicePath } from './services.js';
 import { HELP_TEXT, parseCommand, projectsRoot, slug } from './notify/commands.js';
 import { escapeHtml as escTg } from './notify.js';
@@ -421,6 +422,15 @@ const BIND = (process.env.FOREMAN_BIND ?? 'auto') as 'auto' | 'all' | 'local';
 const tailnet = BIND === 'local' ? null : await detectTailscale();
 /** Dev servers the crew put behind /svc/ — see services.ts. */
 const services = new ServiceRegistry();
+/**
+ * Whether a newer Foreman exists, for the header's quiet pill. Checked at
+ * start and every six hours, never acted on: updating is `foreman update`,
+ * by hand, and never under a running mission.
+ */
+let updateInfo: UpdateInfo | null = null;
+const refreshUpdateInfo = () => { void checkForUpdate(currentVersion(), 4_000).then((u) => { updateInfo = u; }); };
+refreshUpdateInfo();
+setInterval(refreshUpdateInfo, 6 * 60 * 60_000).unref();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = path.join(__dirname, '..', 'ui', 'dist');
 const ROOT_ASSETS = new Set(['/favicon.svg']);
@@ -598,6 +608,11 @@ let telegramBot: TelegramBot | null = null;
 /** (Re)build the Telegram side from the stored token and linked chat. */
 async function reattachTelegram(): Promise<boolean> {
   notifyHub.detach('telegram');
+  // A second server beside the installed one (a dev checkout on another
+  // port) must not start a second poller: Telegram allows one per bot, and
+  // two fight over getUpdates. FOREMAN_NO_TELEGRAM=1 leaves the channel to
+  // whichever server does not set it.
+  if (process.env.FOREMAN_NO_TELEGRAM === '1') return false;
   const s = await notifySettings();
   const token = await getSecret(store.root, 'telegram');
   if (!token) { void telegramBot?.stop(); telegramBot = null; return false; }
@@ -1338,6 +1353,7 @@ const server = http.createServer(async (req, res) => {
           providerHasKey: await providerHasKeyOf(p),
           activeRun: run ? { ...run.meta } : null,
           lastRun: lastRun && {
+            id: lastRun.id,
             mission: lastRun.mission, title: lastRun.title, status: lastRun.status,
             createdAt: lastRun.createdAt, costUsd: lastRun.costUsd,
             // The card may print a dollar only where the dollar was real.
@@ -1377,6 +1393,8 @@ const server = http.createServer(async (req, res) => {
         authMode: auth.mode,
         authSource: auth.source,
         authAccount: auth.account ?? null,
+        version: currentVersion(),
+        update: updateInfo?.newer ? { latest: updateInfo.latest } : null,
         projects: cards.sort(fleetOrder),
       });
 

package/src/update.test.ts

@@ -0,0 +1,27 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { compareVersions, latestVersion } from './update.js';
+
+test('compareVersions: numeric, not lexical; pre-release below release', () => {
+  assert.equal(compareVersions('0.1.2', '0.1.10'), -1);
+  assert.equal(compareVersions('1.0.0', '0.9.9'), 1);
+  assert.equal(compareVersions('v0.1.2', '0.1.2'), 0);
+  assert.equal(compareVersions('1.0.0-beta.1', '1.0.0'), -1);
+  assert.equal(compareVersions('1.0.0', '1.0.0-rc.1'), 1);
+  assert.equal(compareVersions('0.2', '0.2.0'), 0);
+});
+
+test('latestVersion: reads the latest tag; a silent registry is null, not an error', async () => {
+  const srv = http.createServer((req, res) => {
+    if (req.url === '/@x%2Fy/latest') { res.writeHead(200, { 'content-type': 'application/json' }); res.end(JSON.stringify({ version: '9.9.9' })); }
+    else { res.writeHead(404); res.end(); }
+  });
+  await new Promise<void>((r) => srv.listen(0, '127.0.0.1', r));
+  const port = (srv.address() as { port: number }).port;
+  try {
+    assert.equal(await latestVersion('@x/y', 2000, `http://127.0.0.1:${port}`), '9.9.9');
+    assert.equal(await latestVersion('@x/missing', 2000, `http://127.0.0.1:${port}/nope`), null);
+  } finally { srv.close(); }
+  assert.equal(await latestVersion('@x/y', 200, 'http://127.0.0.1:9'), null);
+});

package/src/update.ts

@@ -0,0 +1,60 @@
+/**
+ * "Is there a newer Foreman?" — asked of the npm registry, answered quietly.
+ *
+ * Read-only and best-effort: a registry that does not answer within the
+ * timeout means "unknown", never an error, and nothing here ever installs
+ * anything. Installing is `foreman update`'s job, on purpose and by hand;
+ * Foreman runs agents on your files while you are away, and it must never
+ * change under a running mission without a human's hand.
+ */
+import { readFileSync } from 'node:fs';
+
+export const PACKAGE = '@amenophis1er/foreman';
+
+export interface UpdateInfo {
+  current: string;
+  latest: string;
+  /** `latest` is strictly newer than `current`. */
+  newer: boolean;
+}
+
+/** `1.2.3` vs `1.10.0` the numeric way; a pre-release tag sorts below its release. */
+export function compareVersions(a: string, b: string): number {
+  const parse = (v: string) => {
+    const [core, pre] = v.replace(/^v/, '').split('-', 2);
+    return { nums: core.split('.').map((n) => parseInt(n, 10) || 0), pre: pre ?? '' };
+  };
+  const A = parse(a), B = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (A.nums[i] ?? 0) - (B.nums[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;   // release > pre-release
+  if (!B.pre) return -1;
+  return A.pre < B.pre ? -1 : 1;
+}
+
+/** The version of the package this code runs from. */
+export function currentVersion(pkgUrl = new URL('../package.json', import.meta.url)): string {
+  try { return String(JSON.parse(readFileSync(pkgUrl, 'utf8')).version ?? '0.0.0'); } catch { return '0.0.0'; }
+}
+
+/** The registry's `latest` tag, or null when it cannot be reached in time. */
+export async function latestVersion(pkg = PACKAGE, timeoutMs = 2_500, registry = 'https://registry.npmjs.org'): Promise<string | null> {
+  try {
+    const r = await fetch(`${registry}/${encodeURIComponent(pkg).replace('%40', '@')}/latest`, {
+      signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' },
+    });
+    if (!r.ok) return null;
+    const d = await r.json() as { version?: string };
+    return typeof d.version === 'string' ? d.version : null;
+  } catch { return null; }
+}
+
+/** Current vs latest, or null when the registry did not answer. */
+export async function checkForUpdate(current = currentVersion(), timeoutMs?: number): Promise<UpdateInfo | null> {
+  const latest = await latestVersion(PACKAGE, timeoutMs);
+  if (!latest) return null;
+  return { current, latest, newer: compareVersions(latest, current) > 0 };
+}