@amenophis1er/foreman 0.1.0 → 0.1.2

package/README.md

@@ -1,133 +1,221 @@
 # Foreman
 
-An autonomous mission runner on the [Claude Agent SDK]. You link project
-folders, write a mission, and Foreman's **director** agent plans it into
-`.foreman/MISSION.md`, delegates implementation to **worker** sessions,
-answers or escalates their questions, verifies the result independently, and
-reports back — all from one browser dashboard, no terminal.
-
-Foreman is the standalone evolution of [claude-golden-eye]'s director mode:
-same director/worker doctrine, but the agents are embedded SDK sessions
-driven by this app instead of terminal sessions observed by a plugin.
-(Golden-eye still observes Foreman's agents for free — they are real Claude
-Code sessions.)
+Foreman runs software missions without you in the loop, and shows you
+everything when you come back.
+
+You link a project folder and say what you want. A **director** agent talks
+it through with you (or not — you can skip the talk), writes the plan into
+`.foreman/MISSION.md`, delegates the work to **worker** sessions, watches them,
+verifies the result on its own terms, and reports. You watch from one
+dashboard, or from your phone, or from nowhere at all: every question the crew
+could ask has an unattended default, every run has a budget it cannot cross,
+and every file it touched is on record when you return.
+
+The agents are real [Claude Agent SDK] sessions. The models behind them can be
+Anthropic's, or anything that speaks OpenAI's wire: a local Ollama, Ollama
+Cloud, OpenRouter, vLLM, a Codex login. Foreman never holds a credential it did
+not find already on your machine.
+
+Foreman grew out of [claude-golden-eye]'s director mode. Same doctrine —
+one director, scoped workers, independent verification — but the agents are
+embedded sessions driven by this app, not terminal sessions watched by a
+plugin.
+
+## See it
+
+<p align="center">
+  <img src="assets/readme/fleet-needs-you.jpg" alt="The fleet: one approval waiting, answerable in place; one mission running with its crew and meter; recent outcomes" width="900">
+</p>
+
+The planner asks with options and ends in a proposal you can edit; a run is
+one screen with the checklist ticking live and the crew beside it; anything
+that blocks a run sits above the transcript, answerable right there.
+
+| Plan | Run | Review |
+|---|---|---|
+| [![The planner asking three questions with clickable options](assets/readme/planner-asks.jpg)](assets/readme/planner-asks.jpg) | [![A running mission: transcript, timeline, DONE WHEN and crew](assets/readme/run.jpg)](assets/readme/run.jpg) | [![The files viewer stepping through a run's fixtures](assets/readme/files-viewer.jpg)](assets/readme/files-viewer.jpg) |
+| [![The proposal card: brief, DONE WHEN, budget, models, browser](assets/readme/proposal.jpg)](assets/readme/proposal.jpg) | [![An approval pinned above the transcript, waiting](assets/readme/needs-you.jpg)](assets/readme/needs-you.jpg) | [![The fleet at rest: all quiet](assets/readme/fleet-quiet.jpg)](assets/readme/fleet-quiet.jpg) |
 
 ## Install
 
-Foreman needs Node 20 or newer and a Claude Code login (or an API key) on the
-machine it runs on. Then:
+Node 20 or newer, and a Claude Code login (or an API key) on the machine that
+will run it.
 
 ```sh
-npx @amenophis1er/foreman            # try it — starts the server, serves http://localhost:4177
-npm install -g @amenophis1er/foreman # keep it — then `foreman` from any shell
+npx @amenophis1er/foreman            # try it: starts the server, serves http://localhost:4177
+npm install -g @amenophis1er/foreman # keep it: then `foreman` from any shell
 ```
 
 ```sh
 foreman doctor             # what this machine can run, what is missing, how to fix it
 foreman                    # start in this terminal (Ctrl+C stops it)
-foreman up                 # …or in the background; foreman down stops it, foreman status asks
+foreman up                 # …or in the background; `foreman down` stops it, `foreman status` asks
 foreman open               # the dashboard, in your browser
 foreman service install    # keep it running for good: start at login, restart if it dies
 foreman --help             # the rest, and the environment variables
 ```
 
-`foreman doctor` prints the same checklist the server prints on start —
-credentials and 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.
+`doctor` prints the checklist the server prints on start — credentials and
+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.
+
+## A mission, start to finish
+
+1. **Fleet.** The board: what needs you (answerable right there), what is
+   running with its crew and its meter, what finished. An idle fleet says
+   "all quiet" and means it.
+2. **Plan.** Open a project and talk to the planner. It reads the folder —
+   never changes it — asks with clickable options when it needs to, and ends
+   with a **proposal card**: the brief, the DONE WHEN checklist, a budget, the
+   models it suggests and why, browser on or off. Edit anything, start.
+   Or skip the talk and write the brief yourself.
+3. **Run.** One screen, one spine: the transcript, with anything that blocks
+   the run pinned above it and answerable in place. On the right, the
+   mission's checklist ticking live, the crew and what each worker last said,
+   the run's facts, and the project's settings.
+4. **Files.** What the run changed, against a baseline taken at start (git
+   ref or snapshot), with diffs; what it produced — screenshots, logs, work
+   files — viewable in place, arrow keys to step through; any dev server the
+   crew exposed, one click away. HTML renders in a sandbox with its own
+   scripts, so a built page is a page, not a source listing.
+5. **Next.** A finished run is a starting point: **Plan the next step** opens
+   a new planning conversation already seeded with what was built, the
+   mission doc, and the director's final report.
+
+Every run persists under `~/.foreman/`: refresh-proof, replayable, resumable.
+An interrupted run restores the director's session and re-verifies before it
+continues. `.foreman/` git-ignores itself, so missions in real repositories
+leave no trace but the work.
+
+## Providers, and what a dollar means
+
+A provider is one choice, not three: **who is billed, which credential, and
+which wire**. Foreman offers these, each read from what is already on the
+machine:
+
+| Provider | Credential | Wire |
+|---|---|---|
+| Claude Code | its own login — subscription or `ANTHROPIC_API_KEY` | Anthropic |
+| Anthropic API | a key named by environment variable, never stored | Anthropic |
+| Codex | the `codex login` in `~/.codex` | OpenAI-compatible, through a local gateway |
+| OpenAI-compatible | whatever the endpoint wants | Ollama (local or cloud), OpenRouter, vLLM, OpenAI, … |
+
+The director and the workers can run on different providers; a mission on
+Sonnet with workers on a local model is one click in the composer, and the
+planner recommends pairings with a reason.
+
+**Cost is never invented.** A run is `priced` only when the endpoint that
+sends the bill also published the rate, or when Anthropic reported the cost
+itself. A local model is `free`. A cloud model with no published price is
+`unpriced`, and the meter shows what is true instead: tokens in, tokens out,
+turns. The one exception is a dated table of OpenAI's list prices, visible in
+`src/openai-prices.ts` with the day it was checked. Budget caps bind on
+dollars where dollars are real and on wall clock always.
+
+Which account pays is printed at startup and shown wherever a mission can be
+started. Pin it with `FOREMAN_CLAUDE_CONFIG_DIR`; assert it with
+`FOREMAN_AUTH_MODE=api-key|subscription` so an unset key fails loudly instead
+of billing the other account. A project can pin its own provider, which is
+how personal and work projects share one server.
+
+## Unattended by design
+
+Foreman is meant to run while you are away, so it does not stop to ask unless
+a human's judgement is required *and* being wrong is expensive.
+
+- **Three classes of "outside the folder".** Scratch output that lands in a
+  temp directory is denied on the spot and redirected to `.foreman/work/`.
+  A path that is knowably wrong is denied. A path only you can judge asks —
+  with a default, because "no answer" is also an answer the run must survive.
+- **Every ask has a deadline and a default.** An approval nobody answers is
+  denied with a message that says where to go instead; a question nobody
+  answers is handed back to the director with "decide and record". You set
+  the timeouts, per project if you like.
+- **Watchdogs.** A silent worker, a director looping on the same call, a run
+  past its wall clock: each is detected, reported in plain words, and bounded.
+- **Notify → wait → default.** Link the Telegram bot and the ask reaches your
+  phone with buttons. The default is what happens when you truly cannot
+  answer, not what happens because you never knew.
+
+## From your phone
+
+With the Telegram bot linked (Settings → Notifications, scan the QR):
+
+- Approvals, questions and the planner's multiple-choice asks arrive with
+  inline buttons; a tap answers. Remote answers are allow, deny, pick or type
+  — never an "always" grant. That stays a decision for the desk.
+- `/projects`, `/status`, `/new <name>`, `/plan <project> <what you want>`,
+  `/run <project> <brief>`, `/stop`. After `/new`, just keep typing: the
+  planner's replies come back to the phone, and its proposal arrives as a
+  card with **Start mission** and **Discard**.
+- When the crew exposes a dev server, you get the link, and it opens from
+  anywhere your tailnet reaches.
+
+If the machine is on [Tailscale], Foreman listens on the tailnet address too —
+and never on every interface, since there is no login. The phone's links use
+the tailnet name. `foreman service install` keeps the server up with the lid
+closed.
+
+## What Foreman will not do
+
+- **It is not a chat client.** Planning talks; missions work. The dashboard
+  is a control room, not a conversation.
+- **It is not an editor or a file manager.** Files shows diffs and artifacts,
+  read-only, path-jailed to the project.
+- **It mints no credentials and reimplements no OAuth.** It reads what
+  `claude`, `codex` and your environment already hold. No key is ever
+  returned by an API route or written to a project file.
+- **It never guesses a price**, and it never grants standing permissions
+  from a phone.
+
+## Platforms
+
+macOS is where Foreman is developed and tested. Linux is verified on Debian
+with Node 22 — install, `doctor`, `up`/`status`/`down`, the dashboard;
+`service install` needs a systemd user session, and browser missions need
+Google Chrome or `npx playwright install chromium` with
+`FOREMAN_BROWSER=chromium`. Windows is not yet tested natively — use WSL2;
+`foreman service` has no Windows implementation, `foreman up` works.
+
+## Under the hood
 
-**On the move.** If the machine is on a [Tailscale] tailnet, Foreman listens
-on the tailnet address too (never on every interface — there is no login),
-and the links it sends to your phone use the tailnet name. Link the Telegram
-bot in Settings → Notifications and the phone can answer asks, plan and start
-missions, and open what the crew built. `foreman service install` is what
-keeps the server up while the lid is closed.
+```
+bin/foreman.mjs        the CLI: start · up/down/status · doctor · open · service
+src/server.ts          HTTP + SSE, routes, the run and planner drivers
+src/orchestrator.ts    MissionRun: director, workers, budget, watchdogs, asks
+src/planner.ts         the planning conversation: ask_user, propose_mission, forks
+src/policy.ts          what auto-allows, what is denied, what asks — and the defaults
+src/provider.ts        provider + credential + wire, resolved once per role
+src/gateway/           the OpenAI-compatible gateway and its token ledger
+src/notify.ts          the notification hub · src/notify/telegram.ts the bot
+src/deck.ts            baselines, diffs, artifacts · src/services.ts exposed servers
+src/store.ts           ~/.foreman: append-only event logs, atomic meta
+ui/                    React + Vite dashboard; design system under ui/src/ds
+```
+
+One active mission per project, many across projects. Every event is an
+envelope `{runId, projectId}` on one SSE stream; the persisted log is replayed
+through the same reducer that renders live events, which is why a refresh
+shows exactly what a watcher saw. The director's tools are in-process MCP
+tools; a worker's report lands in the director's context as an ordinary tool
+result.
 
-**Platforms.** macOS is where Foreman is developed and tested. Linux is
-verified on Debian with Node 22: install, `foreman doctor`, `foreman up` /
-`status` / `down` and the dashboard all work; `foreman service install` needs
-a systemd user session (a desktop, or `loginctl enable-linger`), and browser
-missions need Google Chrome or `npx playwright install chromium` with
-`FOREMAN_BROWSER=chromium`. Windows is not yet tested natively — use WSL2 for
-now; `foreman service` has no Windows implementation, `foreman up` works.
 
-**From a checkout** (contributing):
+## Contributing
 
 ```sh
 npm ci && npm run setup      # dependencies, then the dashboard build
 npm start                    # serves http://localhost:4177
-npm test · npm run typecheck · npm run dev   # tests · both tsconfigs · API + Vite together
+npm test                     # 299 tests, node:test
+npm run typecheck            # server and dashboard
+npm run dev                  # API + Vite together
+scripts/dev-restart.sh       # restarts the server only when nothing would be lost
 ```
 
-[Tailscale]: https://tailscale.com
-
-### Which account pays
-
-The SDK spawns your local Claude Code engine, so missions run on whatever that
-install is logged in with — a Claude subscription or an `ANTHROPIC_API_KEY`.
-Both report real per-run cost, so budgets bind either way.
-
-A machine can hold more than one login, and `CLAUDE_CONFIG_DIR` inherited from
-the launching shell silently decides which one is used. So startup prints the
-account it resolved to, and the dashboard shows it beside every place a mission
-can be started:
-
-```
-✓ Credentials     Claude subscription — you@example.com · Your Org
-✓ Claude Code     /Users/you/.claude · bundled executable
-```
-
-Pin it explicitly with `FOREMAN_CLAUDE_CONFIG_DIR`, and assert the mode you
-intend with `FOREMAN_AUTH_MODE=api-key|subscription` so an unset key fails at
-startup instead of quietly billing the other account. A project can pin its own
-install, and choose whether it inherits the server's billing or uses that
-install's own login — which is what makes personal and work projects coexist on
-one server.
-
-Dev loop: `npm run dev` (API + Vite, proxied to :4177) · `npm test` ·
-`npm run typecheck` · `scripts/dev-restart.sh` (restarts the server only when
-no run, ask or planner turn would be lost).
-
-## Using it
-
-1. **Fleet** (`/`): link a folder as a project. Cards show status, live
-   mission cost, and a pulsing **needs you** strip when approvals or
-   questions wait.
-2. **Project view**: write the mission in the composer (say what DONE looks
-   like; flag decisions the director must ask you about), set a budget cap
-   and optional director/worker models, Start.
-3. While running: approve/deny tool cards (or **Always** per tool per run),
-   answer director questions, watch the plan board tick as MISSION.md
-   updates. Interrupt anytime.
-4. Every run persists (`~/.foreman/`): refresh-proof, browsable history with
-   full replay, and a **⟳ Resume** button on interrupted runs that restores
-   the director's session and re-verifies state before continuing.
-
-Missions in real repositories are fine: `.foreman/` git-ignores itself, the
-repo's `CLAUDE.md` loads into workers, and git operations go through your
-approval cards.
-
-## Architecture
-
-```
-ui/            React 19 + Vite dashboard (design tokens in src/design/)
-src/server.ts  HTTP + SSE wiring only
-src/orchestrator.ts  MissionRun: director + workers + budget + escalation
-src/policy.ts  permission policy (what auto-allows vs. asks you)
-src/store.ts   ~/.foreman persistence: append-only event logs, atomic meta
-src/types.ts   shared contracts
-```
-
-- **One active mission per project; many across projects.** SSE frames carry
-  `{runId, projectId}` envelopes; persisted logs are replayed through the
-  same reducer that renders live events.
-- The director's tools (`spawn_worker`, `message_worker`, `ask_human`) are
-  in-process MCP tools; worker calls block inside the director's tool call,
-  so reports land in its context as ordinary tool results.
-- Budgets are enforced before any new worker work; guarded asks (e.g. writes
-  outside the folder) always prompt, even after "Always".
-
-Design history and roadmap: [DESIGN.md](DESIGN.md).
+Releases: `npm version <patch|minor|major> && git push --follow-tags` — CI
+tests, publishes to npm with provenance, and creates the GitHub release.
 
 [Claude Agent SDK]: https://code.claude.com/docs/en/agent-sdk
-[claude-golden-eye]: ../claude-golden-eye
+[claude-golden-eye]: https://github.com/amenophis1er/claude-golden-eye
+[Tailscale]: https://tailscale.com

package/bin/foreman.mjs

@@ -19,14 +19,19 @@ const USAGE = `foreman ${pkg.version}
 
   foreman                    Start in this terminal (same as "start"); Ctrl+C stops it
   foreman up                 Start in the background; logs to ~/.foreman/logs/server.log
-  foreman down               Stop a background server started with "up"
-  foreman status             Is a server up? Which port, which pid?
-  foreman doctor             Check credentials, providers, browser, port, Tailscale — and exit
+  foreman stop               Stop it, however it was started (background server, or the service)
+  foreman restart            Stop and start it again the same way
+  foreman status             Is a server up? Which port, how was it started?
+  foreman logs               Tail the log
   foreman open               Open the dashboard in your browser
+  foreman doctor             Check credentials, providers, browser, port, Tailscale — and exit
+
   foreman service install    Keep Foreman running: start at login, restart if it dies
+  foreman service start|stop|restart|status|logs
   foreman service uninstall  Remove that
-  foreman service status     Is the service registered and running?
-  foreman service logs       Tail the service's log
+
+  foreman uninstall          Remove the service and the background server; keeps ~/.foreman
+  foreman uninstall --purge --yes   …and delete ~/.foreman (every run's history) too
   foreman --version | --help
 
 Environment:
@@ -48,7 +53,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', 'status'].includes(command)) {
+} else if (['doctor', 'open', 'service', 'up', 'down', 'stop', 'restart', 'status', 'logs', 'uninstall'].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.0",
+  "version": "0.1.2",
   "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",
@@ -24,7 +24,7 @@
   "author": "Amen AMOUZOU",
   "type": "module",
   "bin": {
-    "foreman": "./bin/foreman.mjs"
+    "foreman": "bin/foreman.mjs"
   },
   "files": [
     "bin",
@@ -33,14 +33,13 @@
     "ui/dist",
     "skills",
     "README.md",
-    "DESIGN.md",
     "LICENSE"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "test": "node --import tsx --test src/*.test.ts src/gateway/*.test.ts src/notify/*.test.ts",
     "start": "tsx src/server.ts",
     "dev": "node scripts/dev.mjs",
     "ui:dev": "npm --prefix ui run dev",

package/skills/director/SKILL.md

@@ -29,8 +29,7 @@ command. Set `FOREMAN_URL` to point at a different host or port.
 
 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)
+   curl -sf -m 2 "${FOREMAN_URL:-http://localhost:4177}/projects" >/dev/null || foreman up
    ```
 
 4. **Link the cwd as a project** (idempotent — relinking returns the existing

package/src/ask.ts

@@ -48,8 +48,11 @@ export type AskAnswers = Record<string, string>;
 export function armAskTimeout(ms: number, onTimeout: () => void): { cancel(): void } {
   if (!Number.isFinite(ms) || ms <= 0) return { cancel() { /* never armed */ } };
   let fired = false;
+  // Ref'd on purpose: a pending ask with a deadline is work the process owes,
+  // and it must hold the event loop until it settles. Unref'd, Node 22's
+  // test runner saw an empty loop under an awaited ask and failed the test;
+  // a server that must exit does so through its signal handlers regardless.
   const t = setTimeout(() => { fired = true; onTimeout(); }, ms);
-  t.unref?.();
   return { cancel() { if (!fired) clearTimeout(t); } };
 }
 

package/src/cli.ts

@@ -102,6 +102,14 @@ function serviceEnv(): Record<string, string> {
 async function serviceInstall(bin: string): Promise<number> {
   const logDir = path.join(HOME_DIR, 'logs');
   await mkdir(logDir, { recursive: true });
+  // A background server started with `foreman up` would keep the port and
+  // make the new service crash-loop against it; hand over first.
+  const pid = await readPid();
+  if (pid && alive(pid)) { console.log('Stopping the background server so the service can take the port…'); await down(); }
+  else if (await listening(PORT)) {
+    console.error(`Something else answers on :${PORT} (a terminal session?). Stop it first, or the service will keep failing to bind.`);
+    return 1;
+  }
   const env = serviceEnv();
   if (process.platform === 'darwin') {
     const dir = path.join(os.homedir(), 'Library', 'LaunchAgents');
@@ -158,6 +166,66 @@ async function serviceUninstall(): Promise<number> {
   return 2;
 }
 
+/** 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') {
+    const r = await sh('launchctl', ['print', `gui/${os.userInfo().uid}/${LABEL}`]);
+    if (r.code !== 0) return { installed: false, running: false };
+    const pid = Number(/pid = (\d+)/.exec(r.out)?.[1]);
+    return { installed: true, running: Number.isFinite(pid) && pid > 0, ...(pid ? { pid } : {}) };
+  }
+  if (process.platform === 'linux') {
+    const enabled = await sh('systemctl', ['--user', 'is-enabled', 'foreman']);
+    const active = await sh('systemctl', ['--user', 'is-active', 'foreman']);
+    return { installed: enabled.out.trim() === 'enabled' || active.out.trim() === 'active', running: active.out.trim() === 'active' };
+  }
+  return { installed: false, running: false };
+}
+
+/** Stop the service without removing it; `service start` brings it back. */
+async function serviceStop(): Promise<number> {
+  const st = await serviceState();
+  if (!st.installed) { console.log('The service is not installed.'); return 1; }
+  if (process.platform === 'darwin') {
+    // bootout unloads the job until the next login or `service start`; a plain
+    // kill would be undone by KeepAlive within seconds.
+    const r = await sh('launchctl', ['bootout', `gui/${os.userInfo().uid}/${LABEL}`]);
+    if (r.code !== 0 && st.running) { console.error(`launchctl bootout failed: ${r.err.trim() || r.out.trim()}`); return 1; }
+  } else if (process.platform === 'linux') {
+    const r = await sh('systemctl', ['--user', 'stop', 'foreman']);
+    if (r.code !== 0) { console.error(`systemctl stop failed: ${r.err.trim() || r.out.trim()}`); return 1; }
+  }
+  console.log('Service stopped. `foreman service start` starts it again; it also comes back at next login.');
+  return 0;
+}
+
+async function serviceStart(): Promise<number> {
+  if (process.platform === 'darwin') {
+    const file = path.join(os.homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+    const r = await sh('launchctl', ['bootstrap', `gui/${os.userInfo().uid}`, file]);
+    if (r.code !== 0 && !/already/i.test(r.err)) { console.error(`launchctl bootstrap failed: ${r.err.trim() || r.out.trim() || 'is the service installed?'}`); return 1; }
+  } else if (process.platform === 'linux') {
+    const r = await sh('systemctl', ['--user', 'start', 'foreman']);
+    if (r.code !== 0) { console.error(`systemctl start failed: ${r.err.trim() || r.out.trim()}`); return 1; }
+  } else { return 2; }
+  for (let i = 0; i < 40; i++) { if (await listening(PORT)) break; await new Promise((r) => setTimeout(r, 250)); }
+  console.log((await listening(PORT)) ? `Service started · http://localhost:${PORT}` : `Service started; not answering yet — see ${LOG_FILE}`);
+  return 0;
+}
+
+async function serviceRestart(): Promise<number> {
+  if (process.platform === 'darwin') {
+    const r = await sh('launchctl', ['kickstart', '-k', `gui/${os.userInfo().uid}/${LABEL}`]);
+    if (r.code !== 0) { console.error(`launchctl kickstart failed: ${r.err.trim() || r.out.trim() || 'is the service installed?'}`); return 1; }
+  } else if (process.platform === 'linux') {
+    const r = await sh('systemctl', ['--user', 'restart', 'foreman']);
+    if (r.code !== 0) { console.error(`systemctl restart failed: ${r.err.trim() || r.out.trim()}`); return 1; }
+  } else { return 2; }
+  for (let i = 0; i < 40; i++) { if (await listening(PORT)) break; await new Promise((r) => setTimeout(r, 250)); }
+  console.log((await listening(PORT)) ? `Service restarted · http://localhost:${PORT}` : `Service restarted; not answering yet — see ${LOG_FILE}`);
+  return 0;
+}
+
 async function serviceStatus(): Promise<number> {
   if (process.platform === 'darwin') {
     const r = await sh('launchctl', ['print', `gui/${os.userInfo().uid}/${LABEL}`]);
@@ -223,6 +291,14 @@ function alive(pid: number): boolean {
 
 async function up(bin: string): Promise<number> {
   if (await listening(PORT)) { console.log(`Already up at http://localhost:${PORT}`); return 0; }
+  // One owner per port. With the service installed, a second server started
+  // here would hold the port and leave launchd/systemd retrying its own copy
+  // every few seconds against the preflight's "already in use".
+  const svc = await serviceState();
+  if (svc.installed) {
+    console.log('The service runs Foreman on this machine. Use `foreman service start` (or `restart`); `foreman service uninstall` if you would rather run it by hand.');
+    return 1;
+  }
   await mkdir(path.dirname(LOG_FILE), { recursive: true });
   const out = openSync(LOG_FILE, 'a');
   const child = spawn(process.execPath, [bin, 'start'], {
@@ -263,7 +339,8 @@ async function status(): Promise<number> {
   const pid = await readPid();
   const isUp = await listening(PORT);
   if (isUp) {
-    const how = pid && alive(pid) ? `background, pid ${pid}` : 'a terminal or the service';
+    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})`);
     return 0;
   }
@@ -272,11 +349,80 @@ async function status(): Promise<number> {
   return 1;
 }
 
+/**
+ * Stop whatever is serving :PORT, by the means it was started with. A
+ * background server (pid file) is signalled; a service is stopped through
+ * its manager, since killing it would only make KeepAlive restart it; a
+ * terminal session is yours to Ctrl+C, and it says so.
+ */
+async function stop(): Promise<number> {
+  const pid = await readPid();
+  if (pid && alive(pid)) return down();
+  const svc = await serviceState();
+  if (svc.running) return serviceStop();
+  if (await listening(PORT)) {
+    console.log(`Something answers on :${PORT} that neither \`foreman up\` nor the service started — a terminal session, most likely. Stop it there (Ctrl+C).`);
+    return 1;
+  }
+  await rm(PID_FILE, { force: true });
+  console.log('Not up.');
+  return 0;
+}
+
+async function restart(bin: string): Promise<number> {
+  const pid = await readPid();
+  if (pid && alive(pid)) { const c = await down(); if (c !== 0) return c; return up(bin); }
+  const svc = await serviceState();
+  if (svc.running) return serviceRestart();
+  if (await listening(PORT)) {
+    console.log(`The server on :${PORT} was started in a terminal; restart it there. (\`foreman up\` and \`foreman service install\` are the restartable ways to run it.)`);
+    return 1;
+  }
+  return up(bin);
+}
+
+async function logs(): Promise<number> {
+  const svc = await serviceState();
+  if (process.platform === 'linux' && svc.installed) return serviceLogs();
+  const child = spawn('tail', ['-n', '100', '-f', LOG_FILE], { stdio: 'inherit' });
+  return new Promise((r) => child.on('exit', (c) => r(c ?? 0)));
+}
+
+/**
+ * Take Foreman off this machine, in the right order: the service, then a
+ * background server, then — only with --purge, which destroys every run's
+ * history — the data directory. The package itself is npm's to remove; the
+ * last line says how, because a bin cannot uninstall the package it lives in.
+ */
+async function uninstall(flags: string[]): Promise<number> {
+  const purge = flags.includes('--purge');
+  const svc = await serviceState();
+  if (svc.installed) await serviceUninstall();
+  const pid = await readPid();
+  if (pid && alive(pid)) await down();
+  if (purge) {
+    if (!flags.includes('--yes')) {
+      console.error(`--purge deletes ${HOME_DIR}: every run, its transcripts and settings, the Telegram link. Add --yes to confirm.`);
+      return 2;
+    }
+    await rm(HOME_DIR, { recursive: true, force: true });
+    console.log(`Removed ${HOME_DIR}.`);
+  } else {
+    console.log(`Kept ${HOME_DIR} (runs, settings). \`foreman uninstall --purge --yes\` removes it too.`);
+  }
+  console.log('Now remove the package:\n  npm uninstall -g @amenophis1er/foreman');
+  return 0;
+}
+
 export async function runCli(command: string, rest: string[], ctx: { version: string; bin: URL }): Promise<number> {
   const bin = fileURLToPath(ctx.bin);
   switch (command) {
     case 'up': return up(bin);
     case 'down': return down();
+    case 'stop': return stop();
+    case 'restart': return restart(bin);
+    case 'logs': return logs();
+    case 'uninstall': return uninstall(rest);
     case 'status': return status();
     case 'doctor': return doctor();
     case 'open': return open();
@@ -284,9 +430,12 @@ export async function runCli(command: string, rest: string[], ctx: { version: st
       const sub = rest[0];
       if (sub === 'install') return serviceInstall(bin);
       if (sub === 'uninstall') return serviceUninstall();
+      if (sub === 'start') return serviceStart();
+      if (sub === 'stop') return serviceStop();
+      if (sub === 'restart') return serviceRestart();
       if (sub === 'status') return serviceStatus();
       if (sub === 'logs') return serviceLogs();
-      console.error('foreman service <install|uninstall|status|logs>');
+      console.error('foreman service <install|uninstall|start|stop|restart|status|logs>');
       return 1;
     }
     default: return 1;

package/src/deck.ts

@@ -1,7 +1,7 @@
 /**
  * Deck — what a mission changed, and what it produced.
  *
- * DESIGN.md §11 fixes the boundary: "The deck is diff and artifacts, not a
+ * The product's non-goals fix the boundary: "The deck is diff and artifacts, not a
  * file manager and not an editor. Its job is to show what this mission
  * changed, which is something your editor cannot tell you and Foreman can."
  * Everything here is read-only with respect to the user's project. The only