@usine/server 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @usine/server
 
-The foreground CLI for a local [usine](https://github.com/basaltbytes/usine) factory. It is a thin Node adapter over `@usine/orchestrator`: the library owns polling, schedule triggers, durable execution, worker composition, and operator acts; this package serves their JSON and web surfaces.
+The foreground CLI for a local [usine](https://github.com/basaltbytes/usine) factory: a thin Node adapter over `@usine/orchestrator`. The library does the polling, schedule triggers, durable execution, worker composition, and operator actions; this package serves their JSON and web surfaces. The [CLI reference](https://docs.usine.dev/reference/configuration/cli/) lists every command, flag, and variable, and [Operate runs](https://docs.usine.dev/guides/operate-runs/) covers day-to-day use.
 
 Run it from an instance folder:
 
@@ -8,49 +8,65 @@ Run it from an instance folder:
 usine up
 ```
 
-The command prints `http://127.0.0.1:7331` and stays attached to the terminal. Pass `--port <port>` (or set `USINE_PORT`) to listen elsewhere. `usine --help` prints the complete command surface and `usine --version` prints the exact `@usine/server` version pinned by the instance. If the chosen port is occupied, the CLI names the conflict and suggests the override instead of exposing Node's bind failure.
+It prints `http://127.0.0.1:7331` and stays attached to the terminal. `--port <port>` or `USINE_PORT` changes the port; if the port is taken, the CLI names the conflict and suggests the override. `usine --version` prints the `@usine/server` version that the instance pins.
 
-Without GitHub App credentials, it opens the setup screen in the default browser, logs the typed credential error, and leaves both trigger streams idle instead of crashing. The browser command has a two-second timeout; a failed opener produces a warning and does not stop the server. Existing Runs, transcript detail, and database-backed Loop pause state remain observable, while interventions stay unavailable. Credentials may come from `USINE_GITHUB_APP_ID` plus `USINE_GITHUB_PRIVATE_KEY`, or from a mode-0600 `.usine/github-app.json` file with `app_id` and `private_key` fields. The running process reads credentials only at startup, so stop and rerun `usine up` after adding them; the setup screen states that restart requirement explicitly.
+One `usine up` runs per instance folder. It holds `.usine/instance.lock` from startup until every store closes, and writes its pid to `.usine/instance.pid`. A second `usine up` there names the running process and exits nonzero before opening a store. A draining process keeps the folder until it exits.
 
-The local-only UI opens each project as a Board built from its authored or proposed lanes. Proposed lanes are read-only. Configure `repos[].lanes` in `usine.yaml` and restart `usine up` to enable moves; see the [lane configuration example](../../packages/config/README.md). Moving an Item into an authored label-backed lane exchanges only the labels in that map, preserving descriptive labels outside it; normal polling then evaluates label-protocol loops. Board cards show the latest Run and open its existing detail drawer. The UI can also approve, retry, or cancel a Run; pause or unpause a Loop's database runtime state; page backward through older transcript rows; and tail parent and one-level child session activity.
+Without GitHub App credentials, it logs the typed error, leaves both trigger streams idle, and opens the setup screen in the default browser. The browser command times out after two seconds; a failed opener only logs a warning. Runs, transcripts, and loop pause state stay readable, and the instance folder can be reloaded, but interventions are unavailable. Supply `USINE_GITHUB_APP_ID` and `USINE_GITHUB_PRIVATE_KEY`, or `app_id` and `private_key` in a mode-0600 `.usine/github-app.json`. Credentials are read only at startup, so restart `usine up` after adding them, as the setup screen says.
 
-Run conversations remember the reader’s filter, inspected disclosures and reading place when the drawer reopens or the page refreshes. Bookmarks are specific to each Run and browser origin; unread activity remains pending while a saved place is restored. See the [conversation reader behavior](../web/README.md#returning-to-a-conversation) for retention and history-recovery limits.
+## Web UI
 
-Direct browser requests for UI routes serve the application shell, so refreshing or sharing a Project or Configuration URL works. Unknown `/api/*` routes, missing `/assets/*` files, and other file-like paths remain 404 responses.
+Each project opens as a board of authored or proposed lanes; proposed lanes are read-only. To enable moves, define `repos[].lanes` in `usine.yaml` and reload (see the [lane example](../../packages/config/README.md)). Moving an item to an authored label-backed lane swaps only the labels in that map and keeps other labels; polling then evaluates label-driven loops. Cards show the latest run and open its drawer. The UI can approve, retry, or cancel a run, pause or unpause a loop, page back through older transcript rows, and tail parent and first-level child activity.
 
-Run conversations summarize adjacent completed tools by their recorded actions, including the files read or changed and recognized test or build invocations. Expand a group to inspect each tool and its result.
+Run conversations remember the reader's filter, opened disclosures, and reading position across drawer reopens and page refreshes. Bookmarks are per run and browser origin, and unread activity stays pending while a saved position is restored. See [Returning to a conversation](../web/README.md#returning-to-a-conversation) for retention and history-recovery limits. Adjacent completed tools are summarized by their recorded actions, such as files read or changed and recognized test or build commands; expand a group to see each tool and result.
 
-The operator API includes `POST /api/cycle-budgets/reset` with an Ask identity. It uses the same request-origin guard and typed error contract as other interventions; stale Asks return 409 and needs-setup mode rejects resets until the runtime is available.
+Direct browser requests for UI routes serve the app shell, so refreshing or sharing a project or configuration URL works. Unknown `/api/*` routes, missing `/assets/*` files, and other file-like paths return 404.
 
-## Runtime backup and Run evidence
+`POST /api/cycle-budgets/reset` takes an ask identity, with the same origin guard and typed errors as other interventions. A stale ask returns 409, and setup mode rejects resets.
 
-From the instance folder, copy the runtime store while the orchestrator runs:
+After `pnpm build`, reload the page to use the new web bundle; no restart is needed.
+
+## Reload the configuration
+
+**Reload configuration** on any Configuration page, `POST /api/instance/reload`, and `SIGHUP` reload `usine.yaml`, `agents/`, and `loops/` without stopping the process. `SIGHUP` no longer ends the process; stop it with Ctrl+C or `SIGTERM`. The [CLI reference](https://docs.usine.dev/reference/configuration/cli/) describes what a reload applies. A refused reload keeps the running configuration and returns:
+
+- 422 `FactoryConfigError` for an invalid `usine.yaml`;
+- 409 `RestartRequiredError`, naming the field, for a changed `webhooks` block or a `workers` change that needs a restart (a worker's kind or settings, or a rename);
+- 409 `ReloadPreflightError` if a worker, slot count, or agent brain that the reload adds fails preflight, or a new SSH worker's gateway admin token variable is unset.
+
+An accepted reload's response names the loops, agents, labels, repos, and workers it added, removed, or changed. Until a removed worker's last attempt ends, Needs attention counts its running attempts, and `POST /api/workers/:worker/discard-leftovers` returns 409 `LeftoversDiscardRejectedError` with that count. GitHub credentials, the `workers` changes above, and the `webhooks` block apply only at startup.
+
+## Back up and export
+
+While the orchestrator runs, `usine backup` copies `.usine/runtime.sqlite` to the path you give, and `.usine/durable.sqlite` next to it with `.durable` before the extension (`/path/to/runtime-backup.durable.sqlite`):
 
 ```sh
 usine backup /path/to/runtime-backup.sqlite
 ```
 
-`usine backup` copies all runtime tables, including committed WAL data, while the orchestrator runs. It opens the source read-only and doesn't need GitHub credentials.
+Both copies include committed WAL data and are owner-only. The command opens each source read-only, copies the durable storage first, needs no GitHub credentials, and never overwrites a file. Use a new name in an existing writable directory on a file system with hard links. If the runtime copy fails, the durable copy is removed. Without durable storage (no attempt has run yet), it writes only the runtime copy and says so. Errors give the path and cause.
 
-Use a new filename in an existing writable directory on a filesystem that supports hard links. The command writes a complete backup with owner-only permissions and won't overwrite existing files. Errors identify the affected path and cause.
+Keep backups outside the instance folder, and back up the instance files and credentials separately. To restore, stop the orchestrator and restore both files of one backup:
 
-Keep the backup outside the instance folder to protect it against loss of that folder. Back up the authored instance files and credentials separately. To restore, stop the orchestrator, move the existing `.usine/runtime.sqlite` and any `runtime.sqlite-wal` / `runtime.sqlite-shm` files aside, and copy the backup to `.usine/runtime.sqlite`. Restart with the matching instance configuration and engine version. Restoring an older backup also restores its older deduplication ledger, so work performed after that backup can run again.
+1. Move `.usine/runtime.sqlite` and `.usine/durable.sqlite` aside, with their `-wal` and `-shm` files.
+2. Copy the runtime backup to `.usine/runtime.sqlite` and the `.durable` backup to `.usine/durable.sqlite`.
+3. Restart with the matching instance configuration and engine version.
 
-From the instance folder, export one Run into a local JSON file:
+An attempt that was running at backup time reattaches if its checkout under `.usine/workers` still exists. Without its checkout or the durable copy, it fails as interrupted and the run retries. An older backup has an older dedup ledger, so work done after it can run again.
+
+`usine export-run` writes one run to a local JSON file:
 
 ```sh
 usine export-run <runId>
 usine export-run <runId> --output /path/to/evidence.json
 ```
 
-The default destination is `run-<encoded-runId>.json` in the current directory; characters such as `/` in the Run id are percent-encoded. The output directory must already exist. The command writes a complete file with owner-only permissions, preserves existing destinations, and prints its path after success. A missing Run, unreadable runtime store, encoding failure, or write failure returns a nonzero exit status.
-
-The versioned JSON contains `exportedAt`, the full durable Run `snapshot` (Event, effective task and Agent, repository revision, Step result, and all Attempts), and every saved transcript envelope for those Attempts in append order. The snapshot and transcripts come from one database transaction, including history beyond the drawer's current page. Active Runs continue accumulating history, so export a settled Run for its final evidence.
+The default is `run-<encoded-runId>.json` in the current directory, with characters such as `/` percent-encoded; the output directory must exist. The command writes a complete owner-only file, never overwrites one, and prints its path. A missing run, unreadable store, encoding failure, or write failure exits nonzero.
 
-Exporting opens the instance's existing `.usine/runtime.sqlite` in read-only mode, without creating tables, running migrations, starting Attempts, or polling triggers. The command keeps the output local. Transcripts can contain repository content and tool output; inspect the file before sharing it. A Run export preserves selected evidence; use `usine backup <path>` for a restorable runtime database, as described in [ADR 0010](../../docs/adr/0010-single-sqlite-runtime-store.md).
+The versioned JSON has `exportedAt`, the full run `snapshot` (event, effective task and agent, revision, step result, and all attempts), and every saved transcript envelope in append order, from one transaction, including history past the drawer's page. Active runs keep adding history, so export a settled run. The export opens `.usine/runtime.sqlite` read-only, without creating tables, migrating, starting attempts, or polling. Transcripts can contain repo content and tool output; check the file before you share it. For a restorable database, use `usine backup` ([ADR 0010](../../docs/adr/0010-single-sqlite-runtime-store.md)).
 
-## Stopping and updating
+## Stop the server
 
-Send SIGTERM or press Ctrl+C once to stop trigger polling and drain admitted Attempts. The server waits up to `max_attempt_minutes` from the shutdown request before closing the runtime. A second SIGTERM or Ctrl+C stops the wait immediately. Queued Runs and automatic retries remain saved for the next start. An Attempt interrupted by the deadline or force stop uses normal restart recovery.
+Press Ctrl+C or send `SIGTERM` once to stop polling and drain admitted attempts. The server waits up to `max_attempt_minutes` from the request, or indefinitely if unset; a second signal stops the wait. Queued runs and automatic retries stay saved, and an attempt cut off by the deadline uses normal restart recovery. Start the next `usine up` after the process exits.
 
-After `pnpm build`, reload the page to use the rebuilt web bundle; no process restart is required. Instance configuration and GitHub credentials are read at startup.
+To clear a handled failure, select **Mark resolved** in the run drawer, opened from Needs attention or run history. Resolution survives restarts and keeps the failed outcome, transcript, and retry. A later failed attempt asks for attention again. After a question the button reads **Mark answered**; after a question or blocker, the loop then acts on the item's newest state.

package/dist/backend.d.ts

@@ -1,29 +1,52 @@
-import type { LoadedInstance } from "@usine/config/instance";
 import { LoopName } from "@usine/core/loop";
 import { CycleBudgetAskId } from "@usine/core/cycle-budget";
+import { AttemptId } from "@usine/core/attempt";
 import { RunId } from "@usine/core/run";
-import { type BoardMove, type FactoryOverview, type RunDetailView, type TranscriptRequest, type Operator, type OperatorError, type OperatorObservation } from "@usine/orchestrator/operator";
+import { AgentName } from "@usine/core/agent";
+import type { RunAgainResult } from "@usine/engine/engine";
+import type { CurrentInstance, InstanceReload, InstanceReloadError } from "@usine/orchestrator/current-instance";
+import type { WorkerName } from "@usine/core/worker";
+import { type BoardMove, type ConfigurationView, type DeskView, type FactoryOverview, type RunDetailView, type RunGitHubChangesView, type TranscriptRequest, type Operator, type OperatorConfiguration, type OperatorError, type OperatorObservation, type EditAndRetry, type SessionIntervention, type TaskView } from "@usine/orchestrator/operator";
+import type { ItemNumber } from "@usine/core/item";
+import type { RepositoryName } from "@usine/core/repository";
 import { Context, Effect, Layer, Schema } from "effect";
 declare const BackendUnavailableError_base: Schema.Class<BackendUnavailableError, Schema.TaggedStruct<"BackendUnavailableError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 export declare class BackendUnavailableError extends BackendUnavailableError_base {
 }
-export type BackendError = OperatorError | BackendUnavailableError;
+export type BackendError = OperatorError | BackendUnavailableError | InstanceReloadError;
 declare const FactoryBackend_base: Context.ServiceClass<FactoryBackend, "@usine/server/FactoryBackend", {
     readonly overview: Effect.Effect<FactoryOverview, BackendError>;
     readonly detail: (runId: RunId, request: TranscriptRequest) => Effect.Effect<RunDetailView, BackendError>;
+    readonly githubChanges: (runId: RunId) => Effect.Effect<RunGitHubChangesView, BackendError>;
     readonly approve: (runId: RunId) => Effect.Effect<void, BackendError>;
     readonly resetCycleBudget: (askId: CycleBudgetAskId) => Effect.Effect<void, BackendError>;
+    readonly resolveFailure: (runId: RunId, attemptId: AttemptId) => Effect.Effect<void, BackendError>;
     readonly retry: (runId: RunId) => Effect.Effect<void, BackendError>;
+    readonly agents: Effect.Effect<ReadonlyArray<AgentName>, BackendError>;
+    readonly editAndRetry: (runId: RunId, edit: EditAndRetry) => Effect.Effect<void, BackendError>;
+    readonly runAgain: (runId: RunId, edit: EditAndRetry) => Effect.Effect<RunAgainResult, BackendError>;
+    readonly intervene: (runId: RunId, input: SessionIntervention) => Effect.Effect<void, BackendError>;
     readonly cancel: (runId: RunId) => Effect.Effect<void, BackendError>;
+    readonly discardLeftovers: (worker: WorkerName) => Effect.Effect<void, BackendError>;
     readonly moveBoardItem: (move: BoardMove) => Effect.Effect<void, BackendError>;
     readonly pause: (loop: LoopName) => Effect.Effect<void, BackendError>;
     readonly unpause: (loop: LoopName) => Effect.Effect<void, BackendError>;
+    readonly reload: Effect.Effect<InstanceReload, BackendError>;
+    readonly task: (repository: RepositoryName, item: ItemNumber) => Effect.Effect<TaskView, BackendError>;
+    readonly configuration: Effect.Effect<ConfigurationView, BackendError>;
+    readonly desk: Effect.Effect<DeskView, BackendError>;
 }>;
 export declare class FactoryBackend extends FactoryBackend_base {
 }
-export declare const liveBackendLayer: (instance: LoadedInstance, operator: Operator["Service"]) => Layer.Layer<FactoryBackend>;
-export declare const needsSetupBackendLayer: (instance: LoadedInstance, errorTag: string, observation: OperatorObservation["Service"]) => Layer.Layer<FactoryBackend>;
+type BackendInstance = Pick<CurrentInstance["Service"], "get" | "reload">;
+/** Provides the backend of a running factory, which reads the current instance on each request. */
+export declare const liveBackendLayer: (instances: BackendInstance, operator: Operator["Service"], configuration: OperatorConfiguration["Service"]) => Layer.Layer<FactoryBackend>;
+/**
+ * Provides the setup-mode backend, where only the overview, configuration, and reload work. Other
+ * operations fail with `BackendUnavailableError`.
+ */
+export declare const needsSetupBackendLayer: (instances: BackendInstance, errorTag: string, observation: OperatorObservation["Service"], configuration: OperatorConfiguration["Service"]) => Layer.Layer<FactoryBackend>;
 export {};
 //# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EACL,KAAK,SAAS,EACd,KAAK,eAAe,EAEpB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;AAExD,qBAAa,uBAAwB,SAAQ,4BAI3C;CAAG;AAEL,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,uBAAuB,CAAC;;uBAK5C,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC;qBAC9C,CACf,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,KACvB,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,YAAY,CAAC;sBAC7B,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;+BAC1C,CAAC,KAAK,EAAE,gBAAgB,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;oBACzE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;qBAClD,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;4BAC5C,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;oBAC9D,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;sBACnD,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC;;AAd3E,qBAAa,cAAe,SAAQ,mBAgBD;CAAG;AAEtC,eAAO,MAAM,gBAAgB,aACjB,cAAc,YACd,QAAQ,CAAC,SAAS,CAAC,KAC5B,KAAK,CAAC,KAAK,CAAC,cAAc,CAWzB,CAAC;AAEL,eAAO,MAAM,sBAAsB,aACvB,cAAc,YACd,MAAM,eACH,mBAAmB,CAAC,SAAS,CAAC,KAC1C,KAAK,CAAC,KAAK,CAAC,cAAc,CAwB5B,CAAC"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/backend.js

@@ -1,6 +1,8 @@
 import { LoopName } from "@usine/core/loop";
 import { CycleBudgetAskId } from "@usine/core/cycle-budget";
+import { AttemptId } from "@usine/core/attempt";
 import { RunId } from "@usine/core/run";
+import { AgentName } from "@usine/core/agent";
 import { NeedsSetupOverview, } from "@usine/orchestrator/operator";
 import { Context, Effect, Layer, Schema } from "effect";
 export class BackendUnavailableError extends Schema.TaggedError("@usine/server/BackendUnavailableError")("BackendUnavailableError", {
@@ -9,35 +11,61 @@ export class BackendUnavailableError extends Schema.TaggedError("@usine/server/B
 }
 export class FactoryBackend extends Context.Service()("@usine/server/FactoryBackend") {
 }
-export const liveBackendLayer = (instance, operator) => Layer.succeed(FactoryBackend)({
-    overview: operator.overview(instance),
-    detail: operator.detail,
-    approve: operator.approve,
+const rosterOf = (instances) => Effect.map(instances.get, ({ agents }) => agents.map(({ name }) => name));
+/** Provides the backend of a running factory, which reads the current instance on each request. */
+export const liveBackendLayer = (instances, operator, configuration) => Layer.succeed(FactoryBackend)({
+    overview: Effect.flatMap(instances.get, operator.overview),
+    detail: (runId, request) => Effect.flatMap(instances.get, (instance) => operator.detail(instance, runId, request)),
+    githubChanges: operator.githubChanges,
+    approve: (runId) => Effect.flatMap(instances.get, (instance) => operator.approve(instance, runId)),
     resetCycleBudget: operator.resetCycleBudget,
-    retry: operator.retry,
+    retry: (runId) => Effect.flatMap(instances.get, (instance) => operator.retry(instance, runId)),
+    resolveFailure: operator.resolveFailure,
+    agents: rosterOf(instances),
+    editAndRetry: (runId, edit) => Effect.flatMap(instances.get, (instance) => operator.editAndRetry(instance, runId, edit)),
+    runAgain: (runId, edit) => Effect.flatMap(instances.get, (instance) => operator.runAgain(instance, runId, edit)),
+    intervene: (runId, input) => Effect.flatMap(instances.get, (instance) => operator.intervene(instance, runId, input)),
     cancel: operator.cancel,
-    moveBoardItem: (move) => operator.moveBoardItem(instance, move),
+    discardLeftovers: operator.discardLeftovers,
+    moveBoardItem: (move) => Effect.flatMap(instances.get, (instance) => operator.moveBoardItem(instance, move)),
     pause: (loop) => operator.pause(loop).pipe(Effect.asVoid),
     unpause: (loop) => operator.unpause(loop).pipe(Effect.asVoid),
+    reload: instances.reload,
+    task: (repository, item) => Effect.flatMap(instances.get, (instance) => operator.task(instance, repository, item)),
+    configuration: Effect.flatMap(instances.get, configuration.view),
+    desk: Effect.flatMap(instances.get, operator.desk),
 });
-export const needsSetupBackendLayer = (instance, errorTag, observation) => {
+/**
+ * Provides the setup-mode backend, where only the overview, configuration, and reload work. Other
+ * operations fail with `BackendUnavailableError`.
+ */
+export const needsSetupBackendLayer = (instances, errorTag, observation, configuration) => {
     const unavailable = new BackendUnavailableError({
-        message: "GitHub App setup is required before operator actions are available.",
+        message: "The GitHub App is not set up. Set it up to use operator actions.",
     });
-    const overview = observation
-        .overview(instance)
-        .pipe(Effect.map(({ projects, loops, needsYou }) => new NeedsSetupOverview({ errorTag, projects, loops, needsYou })));
+    const overview = Effect.flatMap(instances.get, observation.overview).pipe(Effect.map(({ projects, loops, needsYou }) => new NeedsSetupOverview({ errorTag, projects, loops, needsYou })));
     const fail = () => Effect.fail(unavailable);
     return Layer.succeed(FactoryBackend)({
         overview,
-        detail: observation.detail,
+        detail: (runId, request) => Effect.flatMap(instances.get, (instance) => observation.detail(instance, runId, request)),
+        githubChanges: fail,
         approve: fail,
         resetCycleBudget: fail,
         retry: fail,
+        resolveFailure: fail,
+        agents: rosterOf(instances),
+        editAndRetry: fail,
+        runAgain: fail,
+        intervene: fail,
         cancel: fail,
+        discardLeftovers: fail,
         moveBoardItem: fail,
         pause: fail,
         unpause: fail,
+        reload: instances.reload,
+        task: (repository, item) => Effect.flatMap(instances.get, (instance) => observation.task(instance, repository, item)),
+        configuration: Effect.flatMap(instances.get, configuration.view),
+        desk: Effect.flatMap(instances.get, observation.desk),
     });
 };
 //# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAGL,kBAAkB,GAMnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExD,MAAM,OAAO,uBAAwB,SAAQ,MAAM,CAAC,WAAW,CAC7D,uCAAuC,CACxC,CAAC,yBAAyB,EAAE;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CAAC;CAAG;AAIL,MAAM,OAAO,cAAe,SAAQ,OAAO,CAAC,OAAO,EAgBhD,CAAC,8BAA8B,CAAC;CAAG;AAEtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,QAAwB,EACxB,QAA6B,EACA,EAAE,CAC/B,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;IACrC,MAAM,EAAE,QAAQ,CAAC,MAAM;IACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;IACzB,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;IAC3C,KAAK,EAAE,QAAQ,CAAC,KAAK;IACrB,MAAM,EAAE,QAAQ,CAAC,MAAM;IACvB,aAAa,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC;IAC/D,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IACzD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;CAC9D,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,QAAwB,EACxB,QAAgB,EAChB,WAA2C,EACd,EAAE;IAC/B,MAAM,WAAW,GAAG,IAAI,uBAAuB,CAAC;QAC9C,OAAO,EAAE,qEAAqE;KAC/E,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,WAAW;SACzB,QAAQ,CAAC,QAAQ,CAAC;SAClB,IAAI,CACH,MAAM,CAAC,GAAG,CACR,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,CAChC,IAAI,kBAAkB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAClE,CACF,CAAC;IACJ,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACnC,QAAQ;QACR,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,OAAO,EAAE,IAAI;QACb,gBAAgB,EAAE,IAAI;QACtB,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,IAAI;QACZ,aAAa,EAAE,IAAI;QACnB,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;AACL,CAAC,CAAC"}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/backup.d.ts

@@ -1,4 +1,7 @@
-import { Effect, Path } from "effect";
-/** Copies the current instance's runtime database to `output`, resolved from the working directory. */
-export declare const backup: (output: string) => Effect.Effect<void, import("@usine/engine/local-sqlite").RuntimeStoreBackupError, Path.Path>;
+import { Effect, FileSystem, Path } from "effect";
+/**
+ * Copies the runtime database to `output` and the durable storage next to it, durable storage
+ * first. If the runtime copy fails, removes the durable copy.
+ */
+export declare const backup: (output: string) => Effect.Effect<void, import("@usine/durable/backup").DurableStorageBackupError | import("@usine/engine/local-sqlite").RuntimeStoreBackupError, FileSystem.FileSystem | Path.Path>;
 //# sourceMappingURL=backup.d.ts.map

package/dist/backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE/C,uGAAuG;AACvG,eAAO,MAAM,MAAM,kHAOjB,CAAC"}
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAQ3D;;;GAGG;AACH,eAAO,MAAM,MAAM,sMA6BjB,CAAC"}

package/dist/backup.js

@@ -1,13 +1,33 @@
 import { InstanceDirectory } from "@usine/core/instance";
+import { backup as backupDurableStorage } from "@usine/durable/backup";
 import { backup as backupDatabase } from "@usine/engine/local-sqlite";
-import { Console, Effect, Path } from "effect";
-/** Copies the current instance's runtime database to `output`, resolved from the working directory. */
+import { Console, Effect, FileSystem, Path } from "effect";
+/** Returns the durable storage copy path: `backup.sqlite` becomes `backup.durable.sqlite`. */
+const durableDestination = (path, destination) => {
+    const { dir, name, ext } = path.parse(destination);
+    return path.join(dir, `${name}.durable${ext === "" ? ".sqlite" : ext}`);
+};
+/**
+ * Copies the runtime database to `output` and the durable storage next to it, durable storage
+ * first. If the runtime copy fails, removes the durable copy.
+ */
 export const backup = Effect.fn("Cli.backup")(function* (output) {
     const directory = InstanceDirectory.make(process.cwd());
+    const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const destination = path.resolve(output);
-    yield* Effect.annotateCurrentSpan({ instanceDirectory: directory, destination });
-    yield* backupDatabase(directory, destination);
-    yield* Console.log(`Backed up runtime store to ${destination}`);
+    const durable = durableDestination(path, destination);
+    yield* Effect.annotateCurrentSpan({ instanceDirectory: directory, destination, durable });
+    const copied = yield* backupDurableStorage(directory, durable);
+    yield* backupDatabase(directory, destination).pipe(Effect.tapError(() => copied
+        ? fileSystem.remove(durable).pipe(Effect.tapError((error) => Effect.logWarning("Could not remove the durable copy of a failed backup", {
+            durable,
+            message: error.message,
+        })), Effect.ignore)
+        : Effect.void));
+    yield* Console.log(`Backed up the runtime store to ${destination}`);
+    yield* Console.log(copied
+        ? `Backed up the durable storage to ${durable}`
+        : "No durable storage to back up: .usine/durable.sqlite does not exist");
 });
 //# sourceMappingURL=backup.js.map

package/dist/backup.js.map

@@ -1 +1 @@
-{"version":3,"file":"backup.js","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE/C,uGAAuG;AACvG,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,EAAE,MAAc;IACrE,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IAC9B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,KAAK,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;IACjF,KAAK,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC9C,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,8BAA8B,WAAW,EAAE,CAAC,CAAC;AAClE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,MAAM,IAAI,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE3D,8FAA8F;AAC9F,MAAM,kBAAkB,GAAG,CAAC,IAAe,EAAE,WAAmB,EAAU,EAAE;IAC1E,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,WAAW,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;AAC1E,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,EAAE,MAAc;IACrE,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IAC9B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACtD,KAAK,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/D,KAAK,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,IAAI,CAChD,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CACnB,MAAM;QACJ,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAC7B,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CACxB,MAAM,CAAC,UAAU,CAAC,sDAAsD,EAAE;YACxE,OAAO;YACP,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CACH,EACD,MAAM,CAAC,MAAM,CACd;QACH,CAAC,CAAC,MAAM,CAAC,IAAI,CAChB,CACF,CAAC;IACF,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,kCAAkC,WAAW,EAAE,CAAC,CAAC;IACpE,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAChB,MAAM;QACJ,CAAC,CAAC,oCAAoC,OAAO,EAAE;QAC/C,CAAC,CAAC,qEAAqE,CAC1E,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -2,10 +2,12 @@ import { Duration, Effect, FileSystem, Option, Schema } from "effect";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import type { ServeError } from "effect/unstable/http/HttpServerError";
 export declare const DEFAULT_PORT = 7331;
+/** The address that the HTTP server listens on and the port check probes. */
+export declare const SERVER_HOST = "127.0.0.1";
 export declare const BROWSER_OPEN_TIMEOUT = "2 seconds";
 export declare const Port: Schema.brand<Schema.Int, "ServerPort">;
 export type Port = typeof Port.Type;
-export declare const CLI_USAGE = "Usage:\n  usine up [--port <port>] [--allow-volatile-instance]\n  usine backup <path>\n  usine export-run <runId> [--output <path>]\n  usine --help\n  usine --version\n\nOptions:\n  -p, --port <port>            Listen on this port (default: 7331)\n  --allow-volatile-instance    Start even when the instance folder sits under a temp path\n  -o, --output <path>          Write Run evidence here (default: run-<encoded-runId>.json)\n  -h, --help                   Print this usage\n  -v, --version                Print the pinned @usine/server version\n\nEnvironment:\n  USINE_PORT                     Listen on this port when --port is absent\n  USINE_ALLOW_VOLATILE_INSTANCE  Same as --allow-volatile-instance when set to 1";
+export declare const CLI_USAGE = "Usage:\n  usine up [--port <port>] [--allow-volatile-instance]\n  usine backup <path>\n  usine export-run <runId> [--output <path>]\n  usine --help\n  usine --version\n\nOptions:\n  -p, --port <port>            Listen on this port (default: 7331)\n  --allow-volatile-instance    Start even when the instance folder is in a temporary directory\n  -o, --output <path>          Write the run evidence to this file (default: run-<encoded-runId>.json)\n  -h, --help                   Print this help\n  -v, --version                Print the installed @usine/server version\n\nEnvironment:\n  USINE_PORT                     Listen on this port if --port is not set\n  USINE_ALLOW_VOLATILE_INSTANCE  Set to 1 for the same effect as --allow-volatile-instance";
 declare const CliUsageError_base: Schema.Class<CliUsageError, Schema.TaggedStruct<"CliUsageError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -18,7 +20,10 @@ export declare class CliVersionError extends CliVersionError_base {
 }
 declare const PortInUseError_base: Schema.Class<PortInUseError, Schema.TaggedStruct<"PortInUseError", {
     readonly port: Schema.brand<Schema.Int, "ServerPort">;
+    /** The PID of the listening process, or `None` if lsof can't find it. */
+    readonly holder: Schema.Option<Schema.Int>;
 }>, import("effect/Cause").YieldableError>;
+/** Another process is listening on the HTTP port. */
 export declare class PortInUseError extends PortInUseError_base {
 }
 declare const ServerStartError_base: Schema.Class<ServerStartError, Schema.TaggedStruct<"ServerStartError", {
@@ -31,7 +36,7 @@ declare const VolatileInstanceDirectoryError_base: Schema.Class<VolatileInstance
     readonly directory: Schema.String;
     readonly root: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/** Raised when the instance folder sits under a path the OS may clear, since its runtime store is the only copy of run history. */
+/** The instance folder is in a directory the OS may clear, which would delete the run history. */
 export declare class VolatileInstanceDirectoryError extends VolatileInstanceDirectoryError_base {
 }
 declare const BrowserOpenError_base: Schema.Class<BrowserOpenError, Schema.TaggedStruct<"BrowserOpenError", {
@@ -73,15 +78,23 @@ export declare const CliCommand: Schema.Union<readonly [typeof HelpCommand, type
 export type CliCommand = typeof CliCommand.Type;
 /** Parses process arguments and the environment into one validated CLI command. */
 export declare const parseCli: (args: readonly string[], environment: CliEnvironment) => Effect.Effect<BackupCommand | ExportRunCommand | HelpCommand | UpCommand | VersionCommand, CliUsageError, never>;
-/** Directories the OS may clear: `os.tmpdir()`, `$TMPDIR`, and the usual temp locations. */
+/**
+ * Returns the directories the OS may clear: `os.tmpdir()`, `$TMPDIR`, and common temp locations.
+ */
 export declare const volatileRoots: (environmentTmpdir: Option.Option<string>) => ReadonlyArray<string>;
-/** Returns the volatile root the directory sits under, if any. Paths are compared as given, with symlinks unresolved. */
+/** Returns the volatile root that contains `directory`, if any, without resolving symlinks. */
 export declare const volatileRoot: (directory: string, roots: ReadonlyArray<string>) => Option.Option<string>;
-/** Reads the version of this installed server from its package.json. */
 export declare const packageVersion: () => Effect.Effect<string, CliVersionError, FileSystem.FileSystem>;
-/** Maps a bind failure to the CLI's startup error, so an address already in use is reported as such. */
+/** Returns `PortInUseError` for `EADDRINUSE`, otherwise `ServerStartError`. */
 export declare const serverStartError: (port: Port, error: ServeError) => PortInUseError | ServerStartError;
-/** Opens the setup page in a browser; call it only after the HTTP server has bound. */
+/** Fails with `PortInUseError`, with the listening PID if found. */
+export declare const portInUse: (port: number & import("effect/Brand").Brand<"ServerPort">) => Effect.Effect<never, PortInUseError, ChildProcessSpawner.ChildProcessSpawner>;
+/**
+ * Fails with `PortInUseError` if another process is listening on `port`. Call it before `usine up`
+ * builds its runtime.
+ */
+export declare const refuseTakenPort: (port: number & import("effect/Brand").Brand<"ServerPort">) => Effect.Effect<undefined, PortInUseError | ServerStartError, ChildProcessSpawner.ChildProcessSpawner>;
+/** Opens the setup page in a browser. Call it only after the HTTP server has bound. */
 export declare const openBrowser: (url: string, timeout?: Duration.Input | undefined) => Effect.Effect<undefined, BrowserOpenError, ChildProcessSpawner.ChildProcessSpawner>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,OAAO,EAAW,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC/E,OAAO,EAAgB,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAEvE,eAAO,MAAM,YAAY,OAAQ,CAAC;AAClC,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,eAAO,MAAM,IAAI,wCAEiB,CAAC;AACnC,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC;AAIpC,eAAO,MAAM,SAAS,wtBAgB2D,CAAC;;;;AAElF,qBAAa,aAAc,SAAQ,kBAGlC;CAAG;;;;AAEJ,qBAAa,eAAgB,SAAQ,oBAEW;CAAG;;;;AAEnD,qBAAa,cAAe,SAAQ,mBAED;CAAG;;;;;AAEtC,qBAAa,gBAAiB,SAAQ,qBAEuB;CAAG;;;;;AAEhE,mIAAmI;AACnI,qBAAa,8BAA+B,SAAQ,mCAKlD;CAAG;;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAKpC;CAAG;;AAEL,qBAAa,WAAY,SAAQ,gBAGhC;CAAG;;AAEJ,qBAAa,cAAe,SAAQ,mBAEb;CAAG;;;;;AAE1B,qBAAa,SAAU,SAAQ,cAG9B;CAAG;;;;;AAEJ,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,qBAKpC;CAAG;;;;AAEL,0EAA0E;AAC1E,qBAAa,aAAc,SAAQ,kBAGlC;CAAG;AAEJ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CACvD;AAED,eAAO,MAAM,UAAU,qIAMrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC;AAyEhD,mFAAmF;AACnF,eAAO,MAAM,QAAQ,4KAmBnB,CAAC;AAEH,4FAA4F;AAC5F,eAAO,MAAM,aAAa,sBAAuB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAG,aAAa,CAAC,MAAM,CAW5D,CAAC;AAKlC,yHAAyH;AACzH,eAAO,MAAM,YAAY,cACZ,MAAM,SACV,aAAa,CAAC,MAAM,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,MAAM,CAGtB,CAAC;AAMF,wEAAwE;AACxE,eAAO,MAAM,cAAc,qEAUzB,CAAC;AAIH,wGAAwG;AACxG,eAAO,MAAM,gBAAgB,SAAU,IAAI,SAAS,UAAU,sCAGN,CAAC;AAUzD,uFAAuF;AACvF,eAAO,MAAM,WAAW,4IAyBtB,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAKA,OAAO,EAAyB,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC7F,OAAO,EAAgB,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAEvE,eAAO,MAAM,YAAY,OAAQ,CAAC;AAClC,6EAA6E;AAC7E,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAGhD,eAAO,MAAM,IAAI,wCAEiB,CAAC;AACnC,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC;AAIpC,eAAO,MAAM,SAAS,ovBAgBqE,CAAC;;;;AAE5F,qBAAa,aAAc,SAAQ,kBAGlC;CAAG;;;;AAEJ,qBAAa,eAAgB,SAAQ,oBAEW;CAAG;;;IAOjD,yEAAyE;;;AAL3E,qDAAqD;AACrD,qBAAa,cAAe,SAAQ,mBAMlC;CAAG;;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAEuB;CAAG;;;;;AAEhE,kGAAkG;AAClG,qBAAa,8BAA+B,SAAQ,mCAKlD;CAAG;;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAKpC;CAAG;;AAEL,qBAAa,WAAY,SAAQ,gBAGhC;CAAG;;AAEJ,qBAAa,cAAe,SAAQ,mBAEb;CAAG;;;;;AAE1B,qBAAa,SAAU,SAAQ,cAG9B;CAAG;;;;;AAEJ,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,qBAKpC;CAAG;;;;AAEL,0EAA0E;AAC1E,qBAAa,aAAc,SAAQ,kBAGlC;CAAG;AAEJ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CACvD;AAED,eAAO,MAAM,UAAU,qIAMrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC;AAyEhD,mFAAmF;AACnF,eAAO,MAAM,QAAQ,4KAmBnB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,sBAAuB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAG,aAAa,CAAC,MAAM,CAW5D,CAAC;AAKlC,+FAA+F;AAC/F,eAAO,MAAM,YAAY,cACZ,MAAM,SACV,aAAa,CAAC,MAAM,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,MAAM,CAGtB,CAAC;AAMF,eAAO,MAAM,cAAc,qEAUzB,CAAC;AAIH,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,SAAU,IAAI,SAAS,UAAU,sCAGN,CAAC;AA6BzD,oEAAoE;AACpE,eAAO,MAAM,SAAS,8IAOpB,CAAC;AAkBH;;;GAGG;AACH,eAAO,MAAM,eAAe,qKAE1B,CAAC;AAUH,uFAAuF;AACvF,eAAO,MAAM,WAAW,4IAyBtB,CAAC"}

package/dist/cli.js

@@ -1,11 +1,15 @@
+import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { RunId } from "@usine/core/run";
-import { Console, Duration, Effect, FileSystem, Option, Schema } from "effect";
+import { Array as Arr, Console, Duration, Effect, FileSystem, Option, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 export const DEFAULT_PORT = 7_331;
+/** The address that the HTTP server listens on and the port check probes. */
+export const SERVER_HOST = "127.0.0.1";
 export const BROWSER_OPEN_TIMEOUT = "2 seconds";
+const PORT_HOLDER_TIMEOUT = "2 seconds";
 export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65_535 }, { message: "Expected a TCP port" })).pipe(Schema.brand("ServerPort"));
 const PortFromString = Schema.NumberFromString.pipe(Schema.decodeTo(Port));
 export const CLI_USAGE = `Usage:
@@ -17,23 +21,28 @@ export const CLI_USAGE = `Usage:
 
 Options:
   -p, --port <port>            Listen on this port (default: 7331)
-  --allow-volatile-instance    Start even when the instance folder sits under a temp path
-  -o, --output <path>          Write Run evidence here (default: run-<encoded-runId>.json)
-  -h, --help                   Print this usage
-  -v, --version                Print the pinned @usine/server version
+  --allow-volatile-instance    Start even when the instance folder is in a temporary directory
+  -o, --output <path>          Write the run evidence to this file (default: run-<encoded-runId>.json)
+  -h, --help                   Print this help
+  -v, --version                Print the installed @usine/server version
 
 Environment:
-  USINE_PORT                     Listen on this port when --port is absent
-  USINE_ALLOW_VOLATILE_INSTANCE  Same as --allow-volatile-instance when set to 1`;
+  USINE_PORT                     Listen on this port if --port is not set
+  USINE_ALLOW_VOLATILE_INSTANCE  Set to 1 for the same effect as --allow-volatile-instance`;
 export class CliUsageError extends Schema.TaggedError("@usine/server/CliUsageError")("CliUsageError", { message: Schema.String }) {
 }
 export class CliVersionError extends Schema.TaggedError("@usine/server/CliVersionError")("CliVersionError", { cause: Schema.Defect() }) {
 }
-export class PortInUseError extends Schema.TaggedError("@usine/server/PortInUseError")("PortInUseError", { port: Port }) {
+/** Another process is listening on the HTTP port. */
+export class PortInUseError extends Schema.TaggedError("@usine/server/PortInUseError")("PortInUseError", {
+    port: Port,
+    /** The PID of the listening process, or `None` if lsof can't find it. */
+    holder: Schema.Option(Schema.Int),
+}) {
 }
 export class ServerStartError extends Schema.TaggedError("@usine/server/ServerStartError")("ServerStartError", { port: Port, cause: Schema.Defect() }) {
 }
-/** Raised when the instance folder sits under a path the OS may clear, since its runtime store is the only copy of run history. */
+/** The instance folder is in a directory the OS may clear, which would delete the run history. */
 export class VolatileInstanceDirectoryError extends Schema.TaggedError("@usine/server/VolatileInstanceDirectoryError")("VolatileInstanceDirectoryError", {
     directory: Schema.String,
     root: Schema.String,
@@ -137,7 +146,9 @@ export const parseCli = Effect.fn("Cli.parse")((args, environment) => {
         return Effect.fail(usageError());
     return upCommand(args.slice(1), environment);
 });
-/** Directories the OS may clear: `os.tmpdir()`, `$TMPDIR`, and the usual temp locations. */
+/**
+ * Returns the directories the OS may clear: `os.tmpdir()`, `$TMPDIR`, and common temp locations.
+ */
 export const volatileRoots = (environmentTmpdir) => [
     ...new Set([
         tmpdir(),
@@ -150,13 +161,12 @@ export const volatileRoots = (environmentTmpdir) => [
     .filter((root) => root.length > 0)
     .map((root) => resolve(root));
 const isUnder = (directory, root) => directory === root || directory.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
-/** Returns the volatile root the directory sits under, if any. Paths are compared as given, with symlinks unresolved. */
+/** Returns the volatile root that contains `directory`, if any, without resolving symlinks. */
 export const volatileRoot = (directory, roots) => {
     const resolved = resolve(directory);
     return Option.fromNullishOr(roots.find((root) => isUnder(resolved, root)));
 };
 const PackageMetadataFromJson = Schema.fromJsonString(Schema.Struct({ version: Schema.NonEmptyString }));
-/** Reads the version of this installed server from its package.json. */
 export const packageVersion = Effect.fn("Cli.packageVersion")(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
@@ -167,10 +177,50 @@ export const packageVersion = Effect.fn("Cli.packageVersion")(function* () {
     return metadata.version;
 });
 const AddressInUse = Schema.Struct({ code: Schema.Literal("EADDRINUSE") });
-/** Maps a bind failure to the CLI's startup error, so an address already in use is reported as such. */
+/** Returns `PortInUseError` for `EADDRINUSE`, otherwise `ServerStartError`. */
 export const serverStartError = (port, error) => Schema.is(AddressInUse)(error.cause)
-    ? new PortInUseError({ port })
+    ? new PortInUseError({ port, holder: Option.none() })
     : new ServerStartError({ port, cause: error.cause });
+const ProcessIdFromString = Schema.NumberFromString.pipe(Schema.decodeTo(Schema.Int));
+/**
+ * Returns the PID listening on `port` from lsof, or `None` if lsof is missing or can't see the
+ * process.
+ */
+const portHolder = Effect.fn("Cli.portHolder")(function* (port) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const lines = yield* spawner
+        .lines(ChildProcess.make("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+        stdin: "ignore",
+        stderr: "ignore",
+    }))
+        .pipe(Effect.timeout(PORT_HOLDER_TIMEOUT), Effect.tapError((cause) => Effect.logDebug("Could not look up the process listening on the port", { port, cause })), Effect.orElseSucceed(() => []));
+    return Arr.findFirst(lines, (line) => Schema.decodeUnknownOption(ProcessIdFromString)(line.trim()));
+});
+/** Fails with `PortInUseError`, with the listening PID if found. */
+export const portInUse = Effect.fn("Cli.portInUse")(function* (port) {
+    const holder = yield* portHolder(port);
+    yield* Effect.logWarning("Another process listens on the HTTP port", {
+        port,
+        holder: Option.getOrUndefined(holder),
+    });
+    return yield* new PortInUseError({ port, holder });
+});
+const portTaken = (port) => Effect.callback((resume) => {
+    const server = createServer();
+    server.once("error", (cause) => resume(Schema.is(AddressInUse)(cause)
+        ? Effect.succeed(true)
+        : Effect.fail(new ServerStartError({ port, cause }))));
+    server.listen({ host: SERVER_HOST, port }, () => server.close(() => resume(Effect.succeed(false))));
+    return Effect.sync(() => server.close());
+});
+/**
+ * Fails with `PortInUseError` if another process is listening on `port`. Call it before `usine up`
+ * builds its runtime.
+ */
+export const refuseTakenPort = Effect.fn("Cli.refuseTakenPort")(function* (port) {
+    if (yield* portTaken(port))
+        return yield* portInUse(port);
+});
 const browserCommand = (url) => {
     if (process.platform === "darwin")
         return { command: "open", args: [url] };
@@ -179,7 +229,7 @@ const browserCommand = (url) => {
     }
     return { command: "xdg-open", args: [url] };
 };
-/** Opens the setup page in a browser; call it only after the HTTP server has bound. */
+/** Opens the setup page in a browser. Call it only after the HTTP server has bound. */
 export const openBrowser = Effect.fn("Cli.openBrowser")(function* (url, timeout = BROWSER_OPEN_TIMEOUT) {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const { command, args } = browserCommand(url);