@amenophis1er/foreman 0.1.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@amenophis1er/foreman",
+  "version": "0.1.0",
+  "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",
+    "agent",
+    "agents",
+    "orchestrator",
+    "autonomous",
+    "mission",
+    "claude-code",
+    "dashboard"
+  ],
+  "homepage": "https://github.com/amenophis1er/foreman#readme",
+  "bugs": {
+    "url": "https://github.com/amenophis1er/foreman/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amenophis1er/foreman.git"
+  },
+  "license": "ISC",
+  "author": "Amen AMOUZOU",
+  "type": "module",
+  "bin": {
+    "foreman": "./bin/foreman.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts/prepare.mjs",
+    "ui/dist",
+    "skills",
+    "README.md",
+    "DESIGN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "start": "tsx src/server.ts",
+    "dev": "node scripts/dev.mjs",
+    "ui:dev": "npm --prefix ui run dev",
+    "ui:build": "npm --prefix ui run build",
+    "prepack": "node scripts/prepare.mjs --force",
+    "typecheck": "tsc --noEmit -p . && npm --prefix ui run typecheck",
+    "doctor": "node bin/foreman.mjs doctor",
+    "setup": "node scripts/prepare.mjs --force"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.259",
+    "@playwright/mcp": "^0.0.80",
+    "qrcode": "^1.5.4",
+    "tsx": "^4.23.13",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "@types/qrcode": "^1.5.6",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/prepare.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Builds the dashboard so the package ships with one:
+//   npm publish        runs it via prepack (--force) — every tarball has ui/dist
+//   npm run setup      in a checkout, after npm ci
+// Not a `prepare`/`postinstall` hook on purpose: npm 11 warns about (and
+// blocks) lifecycle scripts on global installs, and the tarball already has
+// the build. Skips when nothing changed; `--force` always builds.
+// Never fails an install that cannot build: the API still works without the
+// dashboard, and the preflight says so on start.
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ui = path.join(root, 'ui');
+const dist = path.join(ui, 'dist', 'index.html');
+const force = process.argv.includes('--force');
+const quiet = process.env.FOREMAN_SKIP_UI_BUILD === '1';
+
+if (quiet) process.exit(0);
+if (!existsSync(path.join(ui, 'package.json'))) process.exit(0); // not shipped with sources — nothing to build
+
+function newest(dir) {
+  let t = 0;
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name === 'dist') continue;
+    const p = path.join(dir, e.name);
+    t = Math.max(t, e.isDirectory() ? newest(p) : statSync(p).mtimeMs);
+  }
+  return t;
+}
+
+const stale = force || !existsSync(dist) || newest(path.join(ui, 'src')) > statSync(dist).mtimeMs
+  || statSync(path.join(ui, 'package.json')).mtimeMs > statSync(dist).mtimeMs;
+if (!stale) process.exit(0);
+
+try {
+  if (!existsSync(path.join(ui, 'node_modules'))) {
+    console.log('foreman: installing dashboard dependencies…');
+    execSync('npm ci --no-audit --no-fund', { cwd: ui, stdio: 'inherit' });
+  }
+  console.log('foreman: building the dashboard…');
+  execSync('npm run build', { cwd: ui, stdio: 'inherit' });
+} catch (err) {
+  if (force) { console.error('foreman: dashboard build failed — refusing to pack without it'); process.exit(1); }
+  console.warn(`foreman: dashboard build skipped (${err.message.split('\n')[0]}). The API works; the dashboard will not until \`npm run ui:build\`.`);
+}

package/skills/director/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: director
+description: Kick off a Foreman mission for the current project — ensures the Foreman server is running, links the session's cwd as a project, starts a director-led mission with the given brief, and opens the dashboard. Usage - /director <mission brief> [--budget N] [--worker sonnet|haiku|opus] [--director opus|sonnet|haiku]
+---
+
+# /director — launch a Foreman mission from this session
+
+You are the launcher only. The mission itself runs in Foreman's own director
+and worker sessions with budgets, approval cards, and MISSION.md governance;
+the human supervises from the dashboard, not from this session. Do NOT do the
+mission's work yourself here.
+
+Foreman serves `http://localhost:4177` and is started with the `foreman`
+command. Set `FOREMAN_URL` to point at a different host or port.
+
+## Steps
+
+1. **Safety guard.** If the current working directory is inside a Foreman
+   checkout, STOP and tell the user: Foreman must never run missions on itself
+   (oversight-infrastructure rule). A directory whose `package.json` has a
+   `foreman` bin, or which contains `src/orchestrator.ts` alongside
+   `src/policy.ts`, is a Foreman checkout.
+
+2. **Parse the arguments.** Everything except the flags is the mission brief.
+   Flags: `--budget N` (default 5), `--worker <model>`, `--director <model>`
+   (models: opus | sonnet | haiku; omit for default). If there is no brief at
+   all, skip steps 4–5: just ensure the server (step 3), link the project
+   (step 4's curl), and open the dashboard.
+
+3. **Ensure the server is up** (start detached if not):
+   ```bash
+   curl -sf -m 2 "${FOREMAN_URL:-http://localhost:4177}/projects" >/dev/null || \
+     (nohup foreman start > /tmp/foreman-server.log 2>&1 & disown; sleep 3)
+   ```
+
+4. **Link the cwd as a project** (idempotent — relinking returns the existing
+   project). Capture the project id from the JSON response:
+   ```bash
+   curl -s -X POST "${FOREMAN_URL:-http://localhost:4177}/projects" \
+     -H 'content-type: application/json' \
+     -d "{\"folder\": \"$PWD\"}"
+   ```
+
+5. **Start the mission** (include directorModel/workerModel keys only when
+   the flags were given):
+   ```bash
+   curl -s -X POST "${FOREMAN_URL:-http://localhost:4177}/run" \
+     -H 'content-type: application/json' \
+     -d '{"projectId": "<id>", "mission": "<brief>", "budgetUsd": <budget>}'
+   ```
+   A 409 means this project already has an active mission — report that and
+   still open the dashboard.
+
+6. **Open the dashboard and hand off.** Auto-open the project view
+   (ignore failure — e.g. over SSH):
+   ```bash
+   open "${FOREMAN_URL:-http://localhost:4177}/#/p/<projectId>" 2>/dev/null || true
+   ```
+   Then ALWAYS print the control URL verbatim in your final message — it is
+   the single place to approve tools and answer the director's questions:
+
+   > Mission running under a $N budget.
+   > **Control it here: http://localhost:4177/#/p/<projectId>**
+   > Approvals and questions wait there indefinitely (nothing expires);
+   > this terminal session is free for other work.

package/src/anthropic-models.ts

@@ -0,0 +1,54 @@
+/**
+ * The Anthropic model list — the one catalogue Foreman cannot ask for.
+ *
+ * **Edit this file when Anthropic ships or retires a model.** It is the only
+ * hardcoded model list in the product, and it is deliberately in a file of its
+ * own so it is obvious where to look.
+ *
+ * Every other provider is queried live: Ollama answers `/api/tags`, an
+ * OpenAI-compatible endpoint answers `/v1/models`, and Codex keeps its own
+ * `models_cache.json` that the CLI maintains. Anthropic has an API for this
+ * too — `GET /v1/models` — but it needs an API key, and Foreman's common case
+ * is a Claude Code *subscription*, which has no key to send. So this list is
+ * the fallback for the case nothing can be queried.
+ *
+ * What actually reaches the SDK is the `id` — the alias. Aliases keep
+ * resolving as Anthropic updates the models behind them, so a stale `model`
+ * string here misleads the eye without breaking a run. That is the reason this
+ * list drifting is survivable, not a reason to leave it wrong.
+ *
+ * `cost` is a 1–4 relative rank for the picker's bars, not a price.
+ */
+export interface CatalogModel {
+  /** Sent to the SDK as `options.model`. An alias, so it survives model updates. */
+  id: string;
+  label: string;
+  /** The concrete model behind the alias, shown in mono. Display only. */
+  model: string;
+  cost: 1 | 2 | 3 | 4;
+  note: string;
+}
+
+export const ANTHROPIC_MODELS: CatalogModel[] = [
+  {
+    id: 'fable', label: 'Fable', model: 'claude-fable-5-1', cost: 4,
+    note: 'Frontier. Long-horizon planning and verification.',
+  },
+  {
+    id: 'opus', label: 'Opus', model: 'claude-opus-5', cost: 3,
+    note: 'Deep reasoning for hard refactors.',
+  },
+  {
+    id: 'sonnet', label: 'Sonnet', model: 'claude-sonnet-5', cost: 2,
+    note: 'Balanced. The usual worker.',
+  },
+  {
+    id: 'haiku', label: 'Haiku', model: 'claude-haiku-4-5', cost: 1,
+    note: 'Fast and cheap for reads and mechanical edits.',
+  },
+];
+
+/** Aliases, for the places that need to know a choice is an Anthropic one. */
+export const ANTHROPIC_ALIASES: ReadonlySet<string> = new Set(
+  ANTHROPIC_MODELS.map((m) => m.id),
+);

package/src/ask.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Asking a human — the mechanics every ask surface shares.
+ *
+ * What is pinned here is not the picker; it is the contract between a model
+ * that asked in structured form and the prose it gets back, plus the one rule
+ * with no exceptions: every ask carries an unattended default, and `0` means
+ * "never", not "immediately".
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { armAskTimeout, formatAnswers, normaliseQuestions } from './ask.js';
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+test('answers are echoed question by question, in the order asked', () => {
+  const qs = normaliseQuestions([
+    { question: 'Stack?', options: ['plain HTML', 'React'] },
+    { question: 'Imagery?', options: ['stock photos', 'you provide assets'] },
+  ]);
+  const out = formatAnswers(qs, { 'Stack?': 'plain HTML', 'Imagery?': 'stock photos' });
+  assert.equal(out, '• Stack?\n  → plain HTML\n• Imagery?\n  → stock photos');
+});
+
+test('an unanswered question is said to be unanswered, never silently dropped', () => {
+  // Silence must not read as agreement with the recommended option; the
+  // model is told to decide, which is the same instruction the timeout gives.
+  const qs = normaliseQuestions([{ question: 'Scope?', options: ['one page', 'multi-page'] }]);
+  assert.match(formatAnswers(qs, {}), /no answer — decide yourself/);
+  assert.match(formatAnswers(qs, { 'Scope?': '   ' }), /no answer — decide yourself/);
+});
+
+test('options may be strings or {label, hint}, and are trimmed', () => {
+  const [q] = normaliseQuestions([{
+    question: '  Stack?  ',
+    options: [' plain HTML ', { label: 'React', hint: 'needs a build step' }, { label: '  ' }, 42],
+    multi: true,
+  }]);
+  assert.equal(q.question, 'Stack?');
+  // A string option carries no hint key at all — not `hint: undefined` —
+  // so the JSON the picker receives is exactly as small as what was sent.
+  assert.deepEqual(q.options, [
+    { label: 'plain HTML' },
+    { label: 'React', hint: 'needs a build step' },
+  ]);
+  assert.equal(q.multi, true);
+});
+
+test('at most three questions and six options each, and a blank question is dropped', () => {
+  const qs = normaliseQuestions([
+    { question: 'a', options: ['1', '2', '3', '4', '5', '6', '7', '8'] },
+    { question: '', options: ['x'] },
+    { question: 'b', options: ['1'] },
+    { question: 'c', options: ['1'] },
+    { question: 'd', options: ['1'] },
+  ]);
+  // 'a', (blank dropped), 'b', 'c' — the fourth real question is past the cap
+  // because the cap applies to what the model sent, not to what survived.
+  assert.deepEqual(qs.map((q) => q.question), ['a', 'b']);
+  assert.equal(qs[0].options.length, 6);
+});
+
+test('non-array input yields no questions rather than throwing', () => {
+  assert.deepEqual(normaliseQuestions(undefined), []);
+  assert.deepEqual(normaliseQuestions('Stack?'), []);
+  assert.deepEqual(normaliseQuestions({ question: 'Stack?' }), []);
+});
+
+test('the ask timer fires once, cancel prevents it, and zero never arms', async () => {
+  let fired = 0;
+  armAskTimeout(15, () => fired++);
+  await sleep(60);
+  assert.equal(fired, 1);
+
+  const b = armAskTimeout(15, () => fired++);
+  b.cancel();
+  await sleep(40);
+  assert.equal(fired, 1, 'a cancelled ask must not fire');
+
+  const c = armAskTimeout(0, () => fired++);
+  await sleep(30);
+  assert.equal(fired, 1, '0 means never, not immediately');
+  c.cancel(); // must be safe on a timer that was never armed
+
+  armAskTimeout(NaN, () => fired++);
+  armAskTimeout(-5, () => fired++);
+  await sleep(30);
+  assert.equal(fired, 1, 'nonsense durations never arm either');
+});

package/src/ask.ts

@@ -0,0 +1,95 @@
+/**
+ * Asking a human — the small mechanics shared by every place Foreman does it.
+ *
+ * Three surfaces ask: the director's `ask_human`, a permission prompt, and
+ * the planner's `ask_user`. They differ in what they ask and what a good
+ * unattended default is; they must not differ in the mechanics, because the
+ * mechanics are where the rule lives: **every ask carries an unattended
+ * default.** Foreman is an autonomous orchestrator, and a question that
+ * blocks indefinitely turns a governance feature into an outage.
+ */
+
+/**
+ * One structured question, the shape a picker renders.
+ *
+ * Options are what make a question fast to answer — a click instead of a
+ * sentence — and putting the recommended one first is what makes the common
+ * case one click. `multi` is for "which of these" questions; the default is a
+ * single choice because most genuinely blocking questions are forks.
+ */
+export interface AskOption {
+  label: string;
+  /** One line under the label: what choosing this implies. */
+  hint?: string;
+}
+
+export interface AskQuestion {
+  question: string;
+  options: AskOption[];
+  multi?: boolean;
+}
+
+/** A batch of questions with one id, answered together. */
+export interface PendingAsk {
+  id: string;
+  questions: AskQuestion[];
+  askedAt: number;
+}
+
+/** Answers keyed by question text; a multi answer joins its labels with ", ". */
+export type AskAnswers = Record<string, string>;
+
+/**
+ * Arms a timer that fires `onTimeout` once after `ms`, or never when `ms` is
+ * zero. Trivial on purpose: the rule "0 disables, otherwise it fires" is worth
+ * being explicit and testable, since forgetting the zero case would make a
+ * per-run override of "never time out" silently time out anyway.
+ */
+export function armAskTimeout(ms: number, onTimeout: () => void): { cancel(): void } {
+  if (!Number.isFinite(ms) || ms <= 0) return { cancel() { /* never armed */ } };
+  let fired = false;
+  const t = setTimeout(() => { fired = true; onTimeout(); }, ms);
+  t.unref?.();
+  return { cancel() { if (!fired) clearTimeout(t); } };
+}
+
+/**
+ * Renders answers back to the agent as prose it cannot misread.
+ *
+ * The agent asked in structured form and gets a structured echo: question,
+ * arrow, answer. An unanswered question is said to be unanswered rather than
+ * omitted, so the agent does not assume silence meant agreement with its
+ * recommended option.
+ */
+export function formatAnswers(questions: AskQuestion[], answers: AskAnswers): string {
+  return questions
+    .map((q) => {
+      const a = answers[q.question];
+      return `• ${q.question}\n  → ${a && a.trim() ? a.trim() : '(no answer — decide yourself)'}`;
+    })
+    .join('\n');
+}
+
+/** Validates and normalises what a model sent to an ask tool. */
+export function normaliseQuestions(raw: unknown): AskQuestion[] {
+  const arr = Array.isArray(raw) ? raw : [];
+  const out: AskQuestion[] = [];
+  for (const q of arr.slice(0, 3) as Array<Record<string, unknown>>) {
+    const question = typeof q?.question === 'string' ? q.question.trim() : '';
+    if (!question) continue;
+    const options: AskOption[] = [];
+    for (const o of (Array.isArray(q.options) ? q.options : []).slice(0, 6)) {
+      if (typeof o === 'string' && o.trim()) options.push({ label: o.trim() });
+      else if (o && typeof o === 'object' && typeof (o as AskOption).label === 'string') {
+        const { label, hint } = o as AskOption;
+        if (label.trim()) options.push({ label: label.trim(), hint: typeof hint === 'string' ? hint : undefined });
+      }
+    }
+    // A question with fewer than two options is not a choice; it is a prompt
+    // for free text, and the picker still offers "something else", so it is
+    // kept rather than rejected — but a model that sends none is told so by
+    // the tool's own validation upstream.
+    out.push({ question, options, multi: q.multi === true });
+  }
+  return out;
+}

package/src/attachments.test.ts

@@ -0,0 +1,33 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { attachmentLines, safeName, saveAttachments } from './attachments.js';
+
+test('safeName keeps the extension and drops what a shell or a path would choke on', () => {
+  assert.equal(safeName('my screenshot (1).png'), 'my-screenshot-1-.png'.replace('-1-.png', '-1-.png'));
+  assert.equal(safeName('../../etc/passwd'), 'passwd');
+  assert.equal(safeName(''), 'file');
+  assert.equal(safeName('..'), 'file');
+});
+
+test('saveAttachments writes under .foreman/attachments and reports project-relative paths', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'attach-'));
+  const saved = await saveAttachments(dir, [
+    { name: 'spec.md', data: Buffer.from('# spec').toString('base64') },
+    { name: 'shot.png', data: Buffer.from([0x89, 0x50]).toString('base64') },
+  ], new Date(2026, 8, 5, 19, 44, 12));
+  assert.equal(saved.length, 2);
+  assert.equal(saved[0].path, '.foreman/attachments/20260905-194412-1-spec.md');
+  assert.equal(saved[1].path, '.foreman/attachments/20260905-194412-2-shot.png');
+  assert.equal(await readFile(path.join(dir, saved[0].path), 'utf8'), '# spec');
+  assert.match(attachmentLines(saved), /Attached files.*\n- \.foreman\/attachments\/20260905-194412-1-spec\.md\n- /s);
+});
+
+test('saveAttachments refuses empty, oversized and too many files with a plain message', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'attach-'));
+  await assert.rejects(saveAttachments(dir, [{ name: 'x', data: '' }]), /is empty/);
+  await assert.rejects(saveAttachments(dir, Array.from({ length: 11 }, () => ({ name: 'x', data: 'AA==' }))), /at most 10/);
+  assert.deepEqual(await saveAttachments(dir, []), []);
+});

package/src/attachments.ts

@@ -0,0 +1,60 @@
+/**
+ * Files a person hands to the planner or the director: a screenshot of the
+ * bug, a spec, a CSV. They land in the project folder — `.foreman/attachments/`
+ * — because that is the one place both the planner (read-only) and the crew
+ * can reach without any new permission, and the message that carries them
+ * names the paths. The folder self-ignores in git, so nothing leaks into the
+ * user's history. Files, not blobs in a database: the deck lists them as
+ * artifacts, and the human can find them with a file manager.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const ATTACHMENTS_DIR = path.join('.foreman', 'attachments');
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export const MAX_ATTACHMENTS = 10;
+
+export interface IncomingAttachment { name: string; data: string /* base64 */; type?: string }
+export interface SavedAttachment { path: string; size: number; name: string }
+
+/** A file name the filesystem and a shell both accept, keeping the extension. */
+export function safeName(name: string): string {
+  const base = path.basename(String(name || 'file')).replace(/[^\w.\-]+/g, '-').replace(/^-+|-+$/g, '');
+  return base && base !== '.' && base !== '..' ? base.slice(0, 120) : 'file';
+}
+
+/** `20260905-194412-` — sortable, unique enough for a human's pace, readable. */
+function stamp(d = new Date()): string {
+  const p = (n: number, l = 2) => String(n).padStart(l, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/**
+ * Writes the files under the folder and returns their project-relative
+ * paths. Throws with a plain message on anything a person can fix (too many,
+ * too big, empty), so the route can hand it back as a 400.
+ */
+export async function saveAttachments(folder: string, files: IncomingAttachment[], now = new Date()): Promise<SavedAttachment[]> {
+  if (!Array.isArray(files) || files.length === 0) return [];
+  if (files.length > MAX_ATTACHMENTS) throw new Error(`at most ${MAX_ATTACHMENTS} files per message`);
+  const dir = path.join(folder, ATTACHMENTS_DIR);
+  await mkdir(dir, { recursive: true });
+  const out: SavedAttachment[] = [];
+  const prefix = stamp(now);
+  for (const [i, f] of files.entries()) {
+    if (!f || typeof f.data !== 'string') throw new Error('each file needs base64 data');
+    const buf = Buffer.from(f.data, 'base64');
+    if (buf.length === 0) throw new Error(`${f.name || 'a file'} is empty`);
+    if (buf.length > MAX_ATTACHMENT_BYTES) throw new Error(`${f.name || 'a file'} is over ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB`);
+    const name = `${prefix}${files.length > 1 ? `-${i + 1}` : ''}-${safeName(f.name)}`;
+    await writeFile(path.join(dir, name), buf, { flag: 'wx' });
+    out.push({ path: path.posix.join('.foreman', 'attachments', name), size: buf.length, name: safeName(f.name) });
+  }
+  return out;
+}
+
+/** The lines appended to a message so an agent knows what came with it. */
+export function attachmentLines(saved: SavedAttachment[]): string {
+  if (!saved.length) return '';
+  return '\n\nAttached files (in the project folder — read them):\n' + saved.map((s) => `- ${s.path}`).join('\n');
+}

package/src/cli.test.ts

@@ -0,0 +1,27 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { launchdPlist, servicePath, systemdUnit } from './cli.js';
+
+test('launchdPlist: label, node + bin + start, env, keepalive, one log', () => {
+  const p = launchdPlist({ label: 'dev.foreman.server', node: '/usr/local/bin/node', bin: '/x/bin/foreman.mjs', home: '/Users/a/.foreman', logDir: '/Users/a/.foreman/logs', env: { PATH: '/a:/b', PORT: '4177', X: 'a<b&c' } });
+  assert.match(p, /<key>Label<\/key><string>dev\.foreman\.server<\/string>/);
+  assert.match(p, /<string>\/usr\/local\/bin\/node<\/string>\s*<string>\/x\/bin\/foreman\.mjs<\/string>\s*<string>start<\/string>/);
+  assert.match(p, /<key>KeepAlive<\/key><true\/>/);
+  assert.match(p, /<key>X<\/key><string>a&lt;b&amp;c<\/string>/);
+  assert.match(p, /server\.log/);
+});
+
+test('systemdUnit: restart always, env lines, default target', () => {
+  const u = systemdUnit({ node: '/usr/bin/node', bin: '/x/bin/foreman.mjs', home: '/home/a/.foreman', env: { PORT: '4177' } });
+  assert.match(u, /ExecStart=\/usr\/bin\/node \/x\/bin\/foreman\.mjs start/);
+  assert.match(u, /Restart=always/);
+  assert.match(u, /Environment=PORT=4177/);
+  assert.match(u, /WantedBy=default\.target/);
+});
+
+test('servicePath: node dir first, usual prefixes, no duplicates', () => {
+  const p = servicePath('/opt/homebrew/Cellar/node/26/bin/node', '/usr/bin:/bin').split(':');
+  assert.equal(p[0], '/opt/homebrew/Cellar/node/26/bin');
+  assert.ok(p.includes('/opt/homebrew/bin') && p.includes('/usr/local/bin'));
+  assert.equal(new Set(p).size, p.length);
+});