@4fu/arbor-supervisor-process 0.0.0-stage → 2026.1106.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4fuu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# arbor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+arbor is a framework for an agent without sessions: many context windows run
+at once over one shared record, so work moves in parallel, replies come fast,
+and every window can find everything that was ever done.
+
+A deployment composes the pieces it wants and registers plugins for the domains
+it serves. The framework guarantees what an agent cannot guarantee for itself -
+the record, isolation, exactly-once effects, the checks, dispatch - and leaves
+everything that takes judgment, such as git, merges and conflicts, to the agent.
+
+## Core ideas
+
+- **No sessions to manage.** Work runs in disposable context windows. Any
+  number run at the same time; none of them owns anything, and a window that
+  ends loses nothing. The model looks up what it needs instead of carrying it.
+- **One record, shared live.** Every input, tool call, result, send and note
+  revision goes into one journal and is visible to every window as
+  soon as it is written. Records never merge and are never lost.
+- **Dispatch by a judge.** A judge (Jev by default, replaceable) decides which
+  live window takes a new input, or opens a new one. There is no router session
+  and no main line.
+- **Current without locks.** Windows run in parallel. New events on a
+  conversation a window is in are steered into it as they arrive; only a note
+  write is checked against the revision the window read.
+- **Mechanisms in the framework, policy in the agent.** The framework
+  guarantees what an agent cannot guarantee for itself - the record, isolation,
+  exactly-once effects, the checks, dispatch. Everything that takes judgment,
+  such as git, merges and conflicts, is the agent's.
+- **A directory per window.** Each window gets its own directory, and a
+  continuation keeps working in its predecessor's directory in place. It is not
+  bound to a repository; the agent clones and pushes what it needs.
+- **A self-changing environment.** The model adds and changes skills, MCP
+  servers and resident services itself; a `reload` validates the change and
+  broadcasts it to every live window as a delta of names and descriptions.
+- **Minimal limits.** The framework sets no policy. Permissions, privacy
+  review, budgets and approvals belong to deployments built on it, through
+  hooks.
+- **Direct tools plus code mode.** Decisions are direct tools; everything else
+  is a module called from `code_exec`. There is no CLI.
+- **Every module is replaceable.** The agent backend (pi by default), the
+  journal, notes, workspaces, the judge, channels and the rest are interfaces
+  ([docs/architecture.md](docs/architecture.md#interfaces)).
+
+## Install
+
+Node 24 or newer. Every package is published separately, so a deployment
+installs the core and the defaults it wants:
+
+```sh
+npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
+  @4fu/arbor-environment-dir @4fu/arbor-supervisor-process @4fu/arbor-agent-pi \
+  @4fu/arbor-workspace-dir
+```
+
+`@4fu/arbor-plugin-http` is optional; it is the example plugin below.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+
+## A minimal host
+
+The smallest host needs a journal and a backend. Adding the defaults and one
+plugin is what a deployment usually starts from:
+
+```js
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Arbor } from "@4fu/arbor-core";
+import { DirectoryEnvironment } from "@4fu/arbor-environment-dir";
+import { SqliteJournal } from "@4fu/arbor-journal-sqlite";
+import { SqliteNoteStore } from "@4fu/arbor-notes-sqlite";
+import { ProcessSupervisor } from "@4fu/arbor-supervisor-process";
+import { DirectoryWorkspace } from "@4fu/arbor-workspace-dir";
+import { PiAgentBackend } from "@4fu/arbor-agent-pi";
+import { HttpChannel, httpPlugin } from "@4fu/arbor-plugin-http";
+
+const root = await mkdtemp(join(tmpdir(), "arbor-"));
+
+// Every module below is a default implementation of an interface. Replace any
+// one by passing your own; the host does not change.
+const journal = new SqliteJournal({ path: join(root, "journal.sqlite") });
+const notes = new SqliteNoteStore({ path: join(root, "notes.sqlite"), journal });
+const supervisor = new ProcessSupervisor({ root: join(root, "services") });
+const environment = new DirectoryEnvironment({ root: join(root, "env"), supervisor });
+const workspace = new DirectoryWorkspace({ root: join(root, "workspaces") });
+
+// A plugin adds; it never patches the core. This one is a chat channel: a
+// webhook in, a window's sends out, and a page that drives the whole host.
+let arbor;
+const channel = new HttpChannel({ host: "127.0.0.1", port: 8787, board: () => arbor.boardLines() });
+arbor = new Arbor({
+  journal,
+  notes,
+  backend: new PiAgentBackend(),
+  workspace,
+  environment,
+  supervisor,
+  plugins: [httpPlugin({ channel })],
+});
+
+await arbor.start();
+await channel.listen();
+```
+
+`arbor.open(task)` dispatches one task, and the journal is where everything that
+happened can be read back ([docs/journal.md](docs/journal.md)). The workspace a
+window gets, and how a continuation keeps working in it, are in
+[docs/workspaces.md](docs/workspaces.md).
+
+## Packages
+
+| Package | What it is |
+| --- | --- |
+| [`@4fu/arbor-interfaces`](packages/interfaces) | every replaceable interface, plus the core's own shapes. Types only. |
+| [`@4fu/arbor-errors`](packages/errors) | the error shape every refusal uses: the rule and the next action |
+| [`@4fu/arbor-prompt`](packages/prompt) | typed blocks, the one deterministic renderer and the replaceable text table |
+| [`@4fu/arbor-tools`](packages/tools) | the entry points: direct tools, code mode modules, the host API |
+| [`@4fu/arbor-journal-sqlite`](packages/journal-sqlite) | the default `Journal` and `BlobStore` on SQLite |
+| [`@4fu/arbor-notes-sqlite`](packages/notes-sqlite) | the default `NoteStore` on SQLite, beside the journal |
+| [`@4fu/arbor-segmenter-jieba`](packages/segmenter-jieba) | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@4fu/arbor-environment-dir`](packages/environment-dir) | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
+| [`@4fu/arbor-supervisor-process`](packages/supervisor-process) | the default `Supervisor`: one host process per service, restart with backoff, logs |
+| [`@4fu/arbor-judge-jev`](packages/judge-jev) | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
+| [`@4fu/arbor-agent-pi`](packages/agent-pi) | the default `AgentBackend`: pi-agent-core in process |
+| [`@4fu/arbor-plugin-http`](packages/plugin-http) | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| [`@4fu/arbor-core`](packages/core) | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects and schedules |
+
+### Defaults are examples
+
+Every default above is a reference implementation of its interface, written to
+be read and replaced. A real deployment is expected to swap out the ones that do
+not fit: the SQLite journal and notes, the directory workspace, the process
+supervisor, the environment directory, the HTTP test plugin and the Jev judge
+are all examples of what an interface can be satisfied by, not commitments.
+What a deployment keeps is its own choice, and the interfaces are the contract
+([docs/architecture.md](docs/architecture.md#interfaces)).
+
+Each package's own documentation holds the limits of that default, so a
+deployment can see what it would be taking on before it adopts one.
+
+## Documents
+
+| Page | Contents |
+| --- | --- |
+| [docs/overview.md](docs/overview.md) | goals, concepts, principles, routes considered |
+| [docs/architecture.md](docs/architecture.md) | layers, interfaces, stack, models, plugins, hooks, data placement |
+| [docs/journal.md](docs/journal.md) | events and their order, targets, watermarks, external ids, refs, tracing, media, redaction |
+| [docs/windows.md](docs/windows.md) | window lifecycle, prompt layout, reminders, continuation |
+| [docs/dispatch.md](docs/dispatch.md) | task sources, judge decisions, insertion timing, backpressure, scheduled tasks |
+| [docs/coordination.md](docs/coordination.md) | the board, expectations, deliveries and broadcasts, staying current, effects |
+| [docs/environment.md](docs/environment.md) | skills, MCP servers and services: using, changing, reload, built-in skills, deltas |
+| [docs/memory.md](docs/memory.md) | notes, the active set, anchors, links |
+| [docs/workspaces.md](docs/workspaces.md) | per-window directories: isolation, continuity, what the agent does |
+| [docs/tools.md](docs/tools.md) | direct tools and code mode modules |
+| [docs/prompting.md](docs/prompting.md) | how every model-facing text is written: layers, notes, deliveries, errors, judge questions, terms |
+| [docs/release.md](docs/release.md) | calendar versioning, the manual release steps, how a package is published |
+
+## Repository layout
+
+`pnpm check` typechecks and tests every package on its TypeScript sources.
+`pnpm build` emits the `dist` publishing needs, and `pnpm pack` shows what each
+tarball would contain ([docs/release.md](docs/release.md)).
+
+| Path | Layer |
+| --- | --- |
+| `packages/interfaces` | the interfaces layer: every replaceable interface, plus the core's own shapes. Types only. |
+| `packages/errors` | the error shape every refusal uses: the rule and the next action |
+| `packages/journal-sqlite` | the default `Journal` and `BlobStore` on SQLite |
+| `packages/segmenter-jieba` | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| `packages/notes-sqlite` | the default `NoteStore` on SQLite, beside the journal |
+| `packages/judge-jev` | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
+| `packages/workspace-dir` | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place, and the lookup of another window's directory it contributes to the catalog |
+| `packages/environment-dir` | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
+| `packages/supervisor-process` | the default `Supervisor`: one host process per service, restart with backoff, logs |
+| `packages/plugin-http` | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| `packages/prompt` | typed blocks, the one deterministic renderer and the replaceable text table |
+| `packages/agent-pi` | the default `AgentBackend`: pi-agent-core in process |
+| `packages/tools` | the entry points: direct tools, code mode modules, the host API |
+| `packages/core` | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects, schedules and the snapshot epochs |
+
+`mise.toml` pins the toolchain - Node and pnpm - installed under
+`~/.local/share/mise`, and `.agents/setup` prepares a machine from it. A machine
+without mise is expected to carry Node 24 or newer and pnpm 12 already.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @4fu/arbor-supervisor-process - the default `Supervisor`: one host process per
+ * service, restarted with backoff after a crash, with logs, state changes and
+ * quotas (docs/environment.md#services).
+ */
+export { ProcessSupervisor, type ProcessSupervisorOptions } from "./process-supervisor.ts";

package/index.js

@@ -0,0 +1,6 @@
+/**
+ * @4fu/arbor-supervisor-process - the default `Supervisor`: one host process per
+ * service, restarted with backoff after a crash, with logs, state changes and
+ * quotas (docs/environment.md#services).
+ */
+export { ProcessSupervisor } from "./process-supervisor.js";

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@4fu/arbor-supervisor-process",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.1106.0",
+  "type": "module",
+  "description": "The default Supervisor: one host process per service, restarted with backoff after a crash, with logs and state changes reported to the host.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "index.d.ts",
+    "index.js",
+    "process-supervisor.d.ts",
+    "process-supervisor.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/supervisor-process"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "2026.1106.0",
+    "@4fu/arbor-interfaces": "2026.1106.0"
+  }
+}

package/process-supervisor.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The default `Supervisor`: one host process per service, restarted with backoff
+ * after a crash, with logs and state changes reported to the host
+ * (docs/environment.md#services).
+ *
+ * ```text
+ * <root>/logs/<name>.log    the service's own output, appended as it comes
+ * ```
+ *
+ * A service is started with its own directory as its working directory, and its
+ * secrets are injected by name: the configuration names them, the host resolves
+ * their values, and neither is written down here. What a service does to the
+ * outside world directly is outside the effect queue; an action that should be
+ * recorded and guaranteed goes through the host API.
+ *
+ * Quotas are the one approximation: a memory quota is applied with `ulimit -v`,
+ * which bounds address space rather than resident memory, and CPU shares are
+ * not applied, because cgroups need privileges a host process does not have.
+ */
+import type { LogOptions, LogPage, Ref, ServiceHandle, ServiceSpec, ServiceStatus, Supervisor } from "@4fu/arbor-interfaces";
+export interface ProcessSupervisorOptions {
+    /** The directory the logs live in. */
+    root: string;
+    /** Where a secret's value comes from. A configuration names one, never holds it. */
+    secretOf?: (name: string) => string | undefined;
+    /** The clock. Tests pass a fixed one. */
+    now?: () => number;
+    /** Records one state change and answers with its event ref. */
+    record?: (status: ServiceStatus) => Promise<Ref | undefined>;
+}
+export declare class ProcessSupervisor implements Supervisor {
+    private readonly root;
+    private readonly secretOf;
+    private readonly clock;
+    private readonly record;
+    private readonly running;
+    private handler;
+    private logRoot;
+    constructor(options: ProcessSupervisorOptions);
+    /**
+     * Start a service and wait for its health check. An upgrade is another start:
+     * the running revision is stopped first, so the swap is the item's, not the
+     * process's.
+     */
+    start(spec: ServiceSpec): Promise<ServiceHandle>;
+    status(name: string): Promise<ServiceStatus>;
+    stop(name: string): Promise<void>;
+    restart(name: string): Promise<ServiceHandle>;
+    logs(name: string, options?: LogOptions): Promise<LogPage>;
+    /** Report every state change to the host, so it records one and runs its hooks. */
+    onStateChange(handler: (status: ServiceStatus) => void | Promise<void>): void;
+    /** The services this supervisor runs, for `services.list`. */
+    list(): Promise<readonly ServiceStatus[]>;
+    private statusOf;
+    /** Start the process, or record that it never came up. */
+    private spawn;
+    /**
+     * Wait for the health check. A service that never becomes healthy is stopped
+     * and left failed, so `reload` refuses the install.
+     */
+    private healthy;
+    /** True when the process is up. */
+    private alive;
+    /** One health check: a 2xx on the service's own port, on the loopback interface. */
+    private reachable;
+    private kill;
+    /** One state change: recorded by the host, then reported to it. */
+    private move;
+    private logPath;
+    /** The log of a service this host no longer runs, for a restart. */
+    private readLog;
+}

package/process-supervisor.js

@@ -0,0 +1,330 @@
+/**
+ * The default `Supervisor`: one host process per service, restarted with backoff
+ * after a crash, with logs and state changes reported to the host
+ * (docs/environment.md#services).
+ *
+ * ```text
+ * <root>/logs/<name>.log    the service's own output, appended as it comes
+ * ```
+ *
+ * A service is started with its own directory as its working directory, and its
+ * secrets are injected by name: the configuration names them, the host resolves
+ * their values, and neither is written down here. What a service does to the
+ * outside world directly is outside the effect queue; an action that should be
+ * recorded and guaranteed goes through the host API.
+ *
+ * Quotas are the one approximation: a memory quota is applied with `ulimit -v`,
+ * which bounds address space rather than resident memory, and CPU shares are
+ * not applied, because cgroups need privileges a host process does not have.
+ */
+import { spawn } from "node:child_process";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { get } from "node:http";
+import { join } from "node:path";
+import { arborError } from "@4fu/arbor-errors";
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from "@4fu/arbor-interfaces";
+/** How many lines one service keeps in memory for `services.logs`. */
+const LOG_MEMORY_LINES = 2000;
+/** How often the health check runs. */
+const DEFAULT_INTERVAL_MS = 500;
+/** How long a health check may take before the start is refused. */
+const DEFAULT_TIMEOUT_MS = 30000;
+/** How many times a service is restarted before it is left failed. */
+const DEFAULT_MAX_RETRIES = 5;
+/** How long to wait between restarts. */
+const DEFAULT_BACKOFF_MS = 1000;
+export class ProcessSupervisor {
+    root;
+    secretOf;
+    clock;
+    record;
+    running = new Map();
+    handler;
+    logRoot;
+    constructor(options) {
+        this.root = options.root;
+        this.secretOf = options.secretOf;
+        this.clock = options.now ?? (() => Date.now());
+        this.record = options.record;
+    }
+    /**
+     * Start a service and wait for its health check. An upgrade is another start:
+     * the running revision is stopped first, so the swap is the item's, not the
+     * process's.
+     */
+    async start(spec) {
+        const existing = this.running.get(spec.name);
+        if (existing !== undefined)
+            await this.kill(existing);
+        const service = {
+            spec,
+            revision: (existing?.revision ?? 0) + 1,
+            state: "starting",
+            restarts: existing?.restarts ?? 0,
+            since: this.clock(),
+            lines: [],
+            refs: [],
+            stopping: false,
+        };
+        this.running.set(spec.name, service);
+        await this.spawn(service);
+        await this.healthy(service);
+        return { name: spec.name, revision: service.revision, state: service.state };
+    }
+    async status(name) {
+        const service = this.running.get(name);
+        if (service === undefined) {
+            throw arborError({
+                code: "not_found",
+                rule: "service.notfound",
+                message: `服务：没有服务 ${name}`,
+                nextAction: "用 services.list 查看当前的服务。",
+                details: { name },
+            });
+        }
+        return this.statusOf(service);
+    }
+    async stop(name) {
+        const service = this.running.get(name);
+        if (service === undefined)
+            return;
+        service.stopping = true;
+        await this.kill(service);
+        await this.move(service, "stopped");
+    }
+    async restart(name) {
+        const service = this.running.get(name);
+        if (service === undefined) {
+            throw arborError({
+                code: "not_found",
+                rule: "service.notfound",
+                message: `服务：没有服务 ${name}`,
+                nextAction: "用 services.list 查看当前的服务。",
+                details: { name },
+            });
+        }
+        service.stopping = false;
+        service.restarts = 0;
+        await this.kill(service);
+        await this.spawn(service);
+        await this.healthy(service);
+        return { name, revision: service.revision, state: service.state };
+    }
+    async logs(name, options) {
+        const service = this.running.get(name);
+        const limit = clamp(options?.limit ?? options?.tail ?? DEFAULT_PAGE_LIMIT);
+        const lines = service === undefined ? await this.readLog(name) : [...service.lines];
+        const tail = options?.tail === undefined ? lines : lines.slice(-options.tail);
+        const items = tail.slice(-limit);
+        return {
+            items,
+            total: lines.length,
+            limit,
+            name,
+            nextCall: `services.logs({ name: ${JSON.stringify(name)}, tail: ${limit} })`,
+        };
+    }
+    /** Report every state change to the host, so it records one and runs its hooks. */
+    onStateChange(handler) {
+        this.handler = handler;
+    }
+    /** The services this supervisor runs, for `services.list`. */
+    async list() {
+        return [...this.running.values()].map((service) => this.statusOf(service));
+    }
+    statusOf(service) {
+        return {
+            name: service.spec.name,
+            revision: service.revision,
+            state: service.state,
+            restarts: service.restarts,
+            since: service.since,
+            ports: [...(service.spec.ports ?? [])],
+            ...(service.lastError === undefined ? {} : { lastError: service.lastError }),
+            refs: [...service.refs],
+        };
+    }
+    /** Start the process, or record that it never came up. */
+    async spawn(service) {
+        const spec = service.spec;
+        const secrets = {};
+        for (const name of spec.secrets ?? []) {
+            const value = this.secretOf?.(name);
+            if (value !== undefined && value !== "")
+                secrets[name] = value;
+        }
+        if (this.logRoot === undefined) {
+            this.logRoot = mkdir(join(this.root, "logs"), { recursive: true }).then(() => undefined);
+        }
+        await this.logRoot;
+        const command = quotaCommand(spec);
+        const child = spawn(command.bin, command.args, {
+            ...(spec.dir === undefined ? {} : { cwd: spec.dir }),
+            env: { ...process.env, ...(spec.env ?? {}), ...secrets },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        service.child = child;
+        const note = (chunk) => {
+            const text = chunk.toString("utf8");
+            for (const line of text.split("\n")) {
+                if (line === "")
+                    continue;
+                service.lines.push(line);
+                if (service.lines.length > LOG_MEMORY_LINES)
+                    service.lines.shift();
+                void appendFile(this.logPath(spec.name), `${line}\n`, "utf8").catch(() => { });
+            }
+        };
+        child.stdout?.on("data", note);
+        child.stderr?.on("data", note);
+        child.on("error", (error) => {
+            service.lastError = {
+                code: "unavailable",
+                rule: "service.spawn.failed",
+                message: `服务 ${spec.name} 启动失败：${error.message}`,
+                nextAction: "检查 command 和 args 是否可在主机上运行。",
+            };
+        });
+        child.on("exit", (code, signal) => {
+            service.child = undefined;
+            if (service.stopping)
+                return;
+            const max = spec.restart?.maxRetries ?? DEFAULT_MAX_RETRIES;
+            service.lastError = {
+                code: "unavailable",
+                rule: "service.crashed",
+                message: `服务 ${spec.name} 退出（code ${code ?? "null"}${signal === null ? "" : `, signal ${signal}`}）`,
+                nextAction: "用 services.logs 查看输出，修好后用 reload 重新安装。",
+            };
+            if (service.restarts >= max) {
+                void this.move(service, "failed");
+                return;
+            }
+            service.restarts += 1;
+            const backoff = spec.restart?.backoffMs ?? DEFAULT_BACKOFF_MS;
+            service.timer = setTimeout(() => {
+                // A restart that fails is reported through `status`, not through a
+                // rejection nobody is waiting for.
+                void this.spawn(service)
+                    .then(() => this.healthy(service))
+                    .catch(() => { });
+            }, backoff);
+            service.timer.unref();
+        });
+    }
+    /**
+     * Wait for the health check. A service that never becomes healthy is stopped
+     * and left failed, so `reload` refuses the install.
+     */
+    async healthy(service) {
+        const check = service.spec.healthCheck;
+        const timeout = check?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const interval = check?.intervalMs ?? DEFAULT_INTERVAL_MS;
+        const deadline = Date.now() + timeout;
+        for (;;) {
+            const ok = check === undefined || check.port === undefined ? this.alive(service) : await this.reachable(check.port, check.path ?? "/");
+            if (ok) {
+                await this.move(service, "running");
+                return;
+            }
+            if (Date.now() >= deadline || service.state === "failed") {
+                service.lastError = {
+                    code: "unavailable",
+                    rule: "service.health_check",
+                    message: `服务 ${service.spec.name} 没有在 ${timeout} ms 内通过健康检查`,
+                    nextAction: "用 services.logs 查看输出，修好后用 reload 重新安装。",
+                };
+                await this.kill(service);
+                await this.move(service, "failed");
+                throw arborError({
+                    code: "unavailable",
+                    rule: "service.health_check",
+                    message: `服务 ${service.spec.name} 没有通过健康检查`,
+                    nextAction: "用 services.logs 查看服务的输出，修好后重新调用 reload。",
+                    details: { name: service.spec.name },
+                });
+            }
+            await sleep(interval);
+        }
+    }
+    /** True when the process is up. */
+    alive(service) {
+        return service.child !== undefined && service.child.exitCode === null;
+    }
+    /** One health check: a 2xx on the service's own port, on the loopback interface. */
+    reachable(port, path) {
+        return new Promise((resolve) => {
+            const request = get({ host: "127.0.0.1", port, path }, (response) => {
+                response.resume();
+                resolve((response.statusCode ?? 500) >= 200 && (response.statusCode ?? 500) < 300);
+            });
+            request.on("error", () => resolve(false));
+            request.setTimeout(2000, () => {
+                request.destroy();
+                resolve(false);
+            });
+        });
+    }
+    async kill(service) {
+        if (service.timer !== undefined) {
+            clearTimeout(service.timer);
+            service.timer = undefined;
+        }
+        const child = service.child;
+        service.child = undefined;
+        if (child === undefined)
+            return;
+        child.kill("SIGTERM");
+        await new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(() => child.kill("SIGKILL"), 2000);
+            child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    /** One state change: recorded by the host, then reported to it. */
+    async move(service, state) {
+        if (service.state === state)
+            return;
+        service.state = state;
+        service.since = this.clock();
+        const status = this.statusOf(service);
+        const ref = this.record === undefined ? undefined : await this.record(status).catch(() => undefined);
+        if (ref !== undefined)
+            service.refs.push(ref);
+        await this.handler?.(status);
+    }
+    logPath(name) {
+        return join(this.root, "logs", `${name}.log`);
+    }
+    /** The log of a service this host no longer runs, for a restart. */
+    async readLog(name) {
+        const text = await readFile(this.logPath(name), "utf8").catch(() => "");
+        return text.split("\n").filter((line) => line !== "");
+    }
+}
+/** A memory quota is applied with `ulimit`, so the command is wrapped in a shell. */
+function quotaCommand(spec) {
+    const args = [...(spec.args ?? [])];
+    const memory = spec.quota?.memoryBytes;
+    if (memory === undefined || memory <= 0)
+        return { bin: spec.command, args };
+    const kilobytes = Math.max(1, Math.floor(memory / 1024));
+    return {
+        bin: "/bin/sh",
+        args: ["-c", `ulimit -v ${kilobytes}; exec "$@"`, "arbor-service", spec.command, ...args],
+    };
+}
+function clamp(limit) {
+    if (!Number.isFinite(limit))
+        return DEFAULT_PAGE_LIMIT;
+    return Math.min(Math.max(1, Math.floor(limit)), MAX_PAGE_LIMIT);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}