@jr2/orchestrator 0.5.1 → 0.7.0

package/src/worktree.ts

@@ -0,0 +1,249 @@
+// `worktree()`, the kit Effect that cuts a Worktree, and the
+// path types that carry a body's Repo Slots to every Worktree input.
+//
+// A Worktree is a folder, `/work/<slot>/<name>`. The Workspace clones only; the Machine cuts. The cut
+// runs on the `command` machinery: a kit program (`packages/harness/src/cut.ts`) on the runtime
+// volume, no new wire kind, marked idempotent, so a restore that finds no exec sends it again with
+// the same id. What an Agent's param can cause settles as `refused`, never `onError` (ADR-0067). A
+// settled `ready` row keeps the slot, the path and the branch as fields: a push reads its branch
+// there, because the row's output drops its tail and a name in an input is a Chart's word.
+
+import { z } from "zod";
+import type { Duration, EffectLogic, ExecPortFactory, LaterOutcome, Unknown } from "./effect.ts";
+import { commandWith } from "./effect.ts";
+import { createExecPort } from "./harness-client.ts";
+
+/** What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path. */
+type NameStart =
+  | "a"
+  | "b"
+  | "c"
+  | "d"
+  | "e"
+  | "f"
+  | "g"
+  | "h"
+  | "i"
+  | "j"
+  | "k"
+  | "l"
+  | "m"
+  | "n"
+  | "o"
+  | "p"
+  | "q"
+  | "r"
+  | "s"
+  | "t"
+  | "u"
+  | "v"
+  | "w"
+  | "x"
+  | "y"
+  | "z"
+  | "A"
+  | "B"
+  | "C"
+  | "D"
+  | "E"
+  | "F"
+  | "G"
+  | "H"
+  | "I"
+  | "J"
+  | "K"
+  | "L"
+  | "M"
+  | "N"
+  | "O"
+  | "P"
+  | "Q"
+  | "R"
+  | "S"
+  | "T"
+  | "U"
+  | "V"
+  | "W"
+  | "X"
+  | "Y"
+  | "Z"
+  | "0"
+  | "1"
+  | "2"
+  | "3"
+  | "4"
+  | "5"
+  | "6"
+  | "7"
+  | "8"
+  | "9"
+  | "_";
+
+/** A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the
+ * slots of the body. */
+export type AnyWorktreePath = `/work/${string}/${string}`;
+/** A Worktree of the Repo Slots `S`. One segment below the slot, that starts with a letter, a
+ * digit or `_`: `${context.workspace.repos.app}/run`. The compiler sees the start of the name; a
+ * `/` further on is the Effect's own refusal. */
+export type WorktreePath<S extends string> = `/work/${S}/${NameStart}${string}`;
+/** A Turn's Frame: a Worktree, or `/work`, stated. `jr2Setup` narrows it to the body's slots. */
+export type AnyFramePath = "/work" | `/work/${string}`;
+/** A Turn's Frame in a Workspace with the Repo Slots `S`. */
+export type FramePath<S extends string> = WorktreePath<S> | "/work";
+
+/** A pick param that names a branch: the rule the cut and the push share, as one JSON-schema
+ * pattern, so that a bad name is refused at the Menu, and the Agent can correct it. */
+export const BRANCH_NAME =
+  /^(?!\/)(?!HEAD$)(?!refs\/)(?!origin\/)(?![0-9a-f]{7,40}$)(?!.*\.\.)(?!.*\/\/)(?!(?:.*\/)?[.-])(?!.*\.lock(?:\/|$))(?!.*[./]$)[A-Za-z0-9._/-]+$/;
+
+/** A kit schema for a pick param that names a branch. For example:
+ * `input: z.object({ branch: branchName })`. */
+export const branchName = z.string().regex(BRANCH_NAME, "a branch name git and jr2's push both take");
+
+/** The input of a `worktree()`: a branch Worktree, or a detached one. */
+export type WorktreeInput =
+  | {
+      /** The root of the Worktree: `${context.workspace.repos.app}/<name>`, a constant word. */
+      path: AnyWorktreePath;
+      /** The branch. It resolves as a local branch, then `origin/<branch>` (tracked), then a new
+       * branch. */
+      branch: string;
+      /** Where a new branch starts. Default: the Binding's base. On a branch that exists, it must
+       * be that branch's tip, or the cut is `refused`. */
+      from?: string;
+      detach?: never;
+      expect?: never;
+    }
+  | {
+      path: AnyWorktreePath;
+      /** The commit to check out, with no branch. The Worktree is forced to it and cleaned on each
+       * cut. Ignored files stay, so that a reviewer can run the tests. */
+      detach: string;
+      branch?: never;
+      from?: never;
+      expect?: never;
+    };
+
+/** What a cut found. `held`: a cut made this Worktree earlier, so what is in it is earlier work;
+ * `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no
+ * upstream; `commit`, a detached cut. Open: a later value does not break an author's code. */
+export type WorktreeFound = "held" | "local" | "remote" | "none" | "commit" | (string & {});
+
+export type WorktreeReady<S extends string = string> = {
+  outcome: "ready";
+  slot: S;
+  path: WorktreePath<S>;
+  /** The branch of the cut, from git and the cut's record, never from the folder or HEAD. `null`
+   * when the Worktree is detached. */
+  branch: string | null;
+  /** The tip of `branch` (of the commit, when detached). Never HEAD. */
+  head: string;
+  found: WorktreeFound;
+  /** ADR-0053's words when the remote did not answer. The cut used what the clone holds. */
+  stale?: string;
+};
+
+/** No Worktree, and nothing changed. The cause is a bad path, a name git or the push refuses, a
+ * re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
+ * name that the remote cannot confirm. */
+export type WorktreeRefused = { outcome: "refused"; reason: string };
+
+/** The output of a `worktree()`. `unknown`: its state exited while it ran, or the cut did not end. */
+export type WorktreeOutput<S extends string = string> = WorktreeReady<S> | WorktreeRefused | Unknown | LaterOutcome;
+
+/** Is it `ready`? For a guard. A Chart's form is the guard `jr2.ready`. */
+export const isReady = <O extends { outcome: string }>(output: O): output is Extract<O, { outcome: "ready" }> =>
+  output.outcome === "ready";
+
+/** The `ready` output of an `onDone` arm that `isReady` guards. xstate carries no guard's narrowing
+ * to its actions, so an `assign` reads the output through this. */
+export function readyOf<O extends { outcome: string }>(output: O): Extract<O, { outcome: "ready" }> {
+  if (output.outcome !== "ready") throw new Error("readyOf: the output is not ready: guard the arm with isReady");
+  return output as Extract<O, { outcome: "ready" }>;
+}
+
+/** The options of `worktree()`. */
+export type WorktreeOptions = {
+  /** `"new"`: refuse a branch that exists, local or on the remote. For a name that a planner or a
+   * door chose for new work: a collision is a refusal, not someone else's branch. `"existing"`:
+   * refuse a branch that does not exist, and make nothing. For a run that must continue a branch.
+   * A Chart cannot change it, and a cut lent to a Chart must state it. */
+  expect?: "new" | "existing";
+  /** How long the fetch and the cut can take. Default `"10m"`. */
+  timeout?: Duration;
+};
+
+/** Over an injected port: the seam of the tests. */
+export function worktreeWith(
+  portFactory: ExecPortFactory,
+  options: WorktreeOptions = {},
+): EffectLogic<WorktreeInput, WorktreeOutput> {
+  return commandWith(
+    portFactory,
+    ["/opt/jr2/bin/node", "/opt/jr2/src/cut.ts"],
+    { timeout: options.timeout ?? "10m" },
+    undefined,
+    { ...(options.expect !== undefined ? { expect: options.expect } : {}) },
+  ) as unknown as EffectLogic<WorktreeInput, WorktreeOutput>;
+}
+
+/**
+ * Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there. Put it
+ * in `actors`, and invoke it from a `workspace()` body.
+ *
+ * With `{ path, branch, from? }`, the branch resolves in this order, after a fetch: a local branch;
+ * `origin/<branch>`, tracked; a new branch from `from` or the Binding's base, with no upstream. With
+ * `{ path, detach }`, the Worktree is forced to that commit and cleaned, each time. `path` is exactly
+ * `/work/<slot>/<name>`. Each outcome is output: `ready`, `refused`, `unknown`.
+ *
+ * `expect` says if the branch can exist: `worktree({ expect: "new" })` refuses a branch that exists,
+ * and `worktree({ expect: "existing" })` refuses a branch that does not exist. A run cannot change it.
+ *
+ * A cut needs a Repo Slot. Under a Workspace with no Repo Slot, `jr2 up` refuses it, and the invoke
+ * fails with `worktree "<slot>" runs under a Workspace with no Repo Slot: a cut makes a Worktree of a
+ * Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`.
+ *
+ * @param options - Optional. `expect`, and `timeout`, how long the fetch and the cut can take.
+ *   Default: `"10m"`.
+ * @returns The actor logic of the Effect's slot. Its output is a {@link WorktreeOutput}.
+ *
+ * @example
+ * ```ts
+ * import { fail, isReady, jr2Setup, worktree, type Workspaced } from "@jr2/orchestrator";
+ *
+ * type BodyInput = Workspaced<{ branch: string }, "app">;
+ * const tree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+ *
+ * export const body = jr2Setup({
+ *   types: {} as { input: BodyInput; context: BodyInput },
+ *   actors: { cut: worktree({ expect: "new" }), fail: fail() },
+ * }).createMachine({
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".notCut" },
+ *   initial: "cutting",
+ *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: tree(context), branch: context.branch }),
+ *         // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "done" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     done: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/guides/cut-a-worktree.md
+ * @see docs/concepts/workspaces.md
+ * @see docs/concepts/effects.md
+ * @see docs/reference/decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md
+ */
+export function worktree(options: WorktreeOptions = {}): EffectLogic<WorktreeInput, WorktreeOutput> {
+  return worktreeWith(
+    (endpoint, bearer) => createExecPort({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
+    options,
+  );
+}

package/docs/reference/authoring-surface/type-noslotspec.md

@@ -1,26 +0,0 @@
----
-title: NoSlotSpec
-description: "What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`."
----
-
-# `NoSlotSpec`
-
-Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
-
-```ts
-type NoSlotSpec = Pick<WorkspaceSpec, "workGroup"> & { branch?: never; reviewSha?: never };
-```
-
-What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`. There is no
-branch and no review Worktree, because the Workspace has no Repo Slot.
-
-**Fields**
-
-- `workGroup` (optional): `number`
-
-  The group id that owns the files in `/work`. With it, the Sandbox Image and the User
-  Container can both write those files when they run as different users. Default: 2000. Set it
-  to a group id that the User Container's sessions already have, for example when a root sshd
-  builds their groups from `/etc/group`. A non-negative integer.
-- `branch` (optional): `never`
-- `reviewSha` (optional): `never`

package/docs/reference/authoring-surface/type-workspacespec.md

@@ -1,37 +0,0 @@
----
-title: WorkspaceSpec
-description: "What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields."
----
-
-# `WorkspaceSpec`
-
-Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
-
-```ts
-type WorkspaceSpec = {
-  branch: string;
-  workGroup?: number;
-  reviewSha?: string;
-};
-```
-
-What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two
-optional fields. jr2 calls `spec` with the run input when the run enters the Workspace.
-
-**Fields**
-
-- `branch`: `string`
-
-  The branch that the Workspace works on: each Repo Slot gets a Worktree for it, at
-  `/work/<slot>/<branch>`, with each `/` in the branch written as `-`. Required, and not
-  `default`, which is the directory of the clone. Your Machine decides its name.
-- `workGroup` (optional): `number`
-
-  The group id that owns the files in `/work`. With it, the Sandbox Image and the User
-  Container can both write those files when they run as different users. Default: 2000. Set it
-  to a group id that the User Container's sessions already have, for example when a root sshd
-  builds their groups from `/etc/group`. A non-negative integer.
-- `reviewSha` (optional): `string`
-
-  A commit to check out in a second, detached Worktree beside each branch Worktree, for a
-  reviewer: `/work/<slot>/<branch>-review`. The body gets its paths as `workspace.review`.

package/docs/reference/decisions/0032-the-console-unlocks-with-the-instance-token.md

@@ -1,61 +0,0 @@
-# The Console unlocks with the Instance token, and the bands do not move
-
-[ADR-0014](0014-observation-is-open-run-state-is-not.md) built the three-band HTTP surface on one premise: the
-visualizer page is a browser, and a browser holds no token — so it got a projection instead of a credential, and "give
-the page a token" was explicitly rejected. That page is now growing into the **Console**: it starts runs and answers
-Gates, both of which are writes on the guarded surface. This ADR records how a browser earns those writes without moving
-a single band — and it can stay this small because of a fact ADR-0014 did not lean on: the Instance token is already one
-`kubectl get secret` away for exactly the audience the Console serves. There is no new distribution problem, only a new
-presentation surface.
-
-## Decision
-
-- **The human presents the token; the page never ships with one.** The Console's nav carries a password field. Empty,
-  the page is precisely ADR-0014's observer: open structure and observation, no control rendered. Filled, the page sends
-  `Authorization: Bearer` on the guarded surface — which unlocks both directions at once: the writes
-  (`POST /workflows/:name/runs`, `POST /runs/:id/gates/:gate/events`) and the `instanceOnly` reads the control UI needs
-  anyway (`GET /runs`, and `GET /runs/:id` — where `GateView` lives). The page as _served_ stays open and inert;
-  ADR-0014's rejection stands, because what it rejected was baking the credential into the page.
-- **The token lives in `sessionStorage`** — survives a reload, dies with the tab, never a cookie (no ambient credential,
-  no CSRF surface). It is validated on entry with a cheap guarded read so the field shows live/invalid immediately; any
-  later 401 drops the UI back to observer mode rather than failing per-widget.
-- **Gate discovery is a frame-triggered guarded read, not an open-band extension.** A Gate exists exactly while its
-  invoking state is entered (ADR-0011), and every entry/exit lands a status frame on the open workflow feed (ADR-0022) —
-  so on each frame, a token-holding Console re-fetches `GET /runs/:id` for the affected run and folds `gates` into its
-  store. Perfectly synchronized, no polling loop, and the observation projection is untouched. A delivery's success is
-  likewise confirmed by the next frame emptying the card, never by local bookkeeping.
-- **Page addresses content-negotiate; JSON is the default dialect.** `/` and `/workflows/:name` serve the Console shell
-  to `Accept: text/html` and JSON to everything else — so the workflow-detail resource keeps its natural address (the
-  run-input schema's home, [ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)) and no future page has to
-  squat on a mangled sibling path. Nothing existing moves: EventSource asks `text/event-stream`, and the Harness's Menu
-  and the CLI never ask for HTML. `/viz/*` is deleted (greenfield, no redirects); assets move to `/assets/*`, which also
-  retires the "a workflow named `assets` is shadowed" hazard.
-
-## Considered options
-
-- **`jr2 ui` — the CLI opens the browser through an authenticated local proxy.** A convenience layer worth building _on
-  top of_ the token field later, not a substitute: it has no answer for the deployed jr2 Application behind an ingress,
-  where the browser talks to the Service directly and the CLI is not in the path.
-- **A fourth, scoped credential** ("may answer gates, may not cancel or read context"). Still rejected, as in ADR-0014 —
-  but the calculus has narrowed: it becomes worth writing only when gate-answering is delegated to people who must _not_
-  hold cluster RBAC. That is a real future (an approval inbox for non-operators); it is not this one.
-- **Announce gates on the open observation feed** (even just `{runId, gate}`). Rejected: it widens the projection for a
-  convenience the token already solves, and the open band has an unresolved exposure question as it stands (spawn ids —
-  the ADR-0014 open call). The projection stays the one place the line is drawn.
-- **A `/ui` path prefix, or moving the API under `/api`.** Rejected for negotiation: the first is ceremony on the
-  address a human types, the second churns the Harness's Menu, the Custodian's route allowlist, the CLI, and the
-  ADR-0009/0013 route tables for cosmetics.
-
-## Consequences
-
-- **Zero new server surface except negotiation.** No new token, no new band, no new route class; `auth.test.ts`'s
-  boundary assertions are untouched. The server-side diff is: negotiate two addresses, serve the shell, retire `/viz/*`.
-- **Possession remains cluster RBAC.** Whoever can read the instance Secret could already do everything the Console
-  unlocks; the field changes where the token is typed, not who holds it.
-- **The XSS caveat is the real one and is bounded by what the page is:** a token in `sessionStorage` is readable by
-  scripts on the page, so the Console must keep serving only its own assets — no CDN, no third-party script, exactly the
-  constraint the viz page already lives under.
-- **GLOSSARY.md**: **Console** becomes a glossary term (visualizer, dashboard, UI, viz on its Avoid list).
-- **The Console's UX gets a browser tier** — `@console`-tagged Cucumber scenarios holding a Playwright page, in
-  `@jr2/e2e`, excluded from the default profile ([ADR-0010](0010-bdd-acceptance-tests.md) as amended). What the page
-  _believes_ stays unit-tested in `console-store.test.ts`; the browser tier asserts what a user does and sees.

package/docs/reference/decisions/0065-a-persist-survives-a-crash-and-history-is-a-week.md

@@ -1,65 +0,0 @@
-# A persist survives a crash, and history is a week
-
-Every transition of a run persists its whole snapshot (ADR-0007). The scaling review (R6) read the store and listed its
-costs: `JSON.stringify` of the whole run, a synchronous upsert with an fsync on the event loop, a Pool's run as one blob
-holding every worker, terminal rows never deleted, and `restore()` parsing every row before the server listens. It also
-found the words "Postgres opt-in" in GLOSSARY.md, ADR-0008 and ADR-0009, with no such store in the code. Measured on the
-home cluster's chaos Instance (2026-09-30, `local-path` volume): a persist costs **4.5 ms, whatever the blob's size** (1
-KB or 100 KB), because the cost is the fsync, not the JSON; with the write-ahead log and `synchronous=NORMAL` the same
-upserts cost 0.04 ms (1 KB) and 0.18 ms (100 KB). A run's blob is about 1 KB; a Pool of 40 workers is about 100 KB.
-
-## Decision
-
-- **A persist survives a process crash, not a power loss.** The store runs sqlite in WAL mode with `synchronous=NORMAL`:
-  a write is durable once the OS holds it, and sqlite fsyncs only at a checkpoint. A node's power loss can lose the
-  transitions since the last checkpoint; the file stays consistent, and `restore()` treats the older snapshot as it
-  treats any restart — reconcile against the live world, re-attach, or `lost`. The window in which a crash re-POSTs a
-  prompt (ADR-0007's at-most-once sliver) widens from one microtask to one checkpoint, and only on a power loss, which
-  also ends every Sandbox on that node.
-- **The write stays synchronous and on the event loop.** At 0.2 ms for a Pool's blob there is nothing to move off the
-  loop, and the ordering matters: the row is on disk before the Machine's next side effect runs, which is what lets an
-  epoch bump (ADR-0057), an admission (ADR-0016) or an Effect's intent row (ADR-0067) be saved "at the write" — the
-  intent row before its call leaves. A worker thread, an asynchronous driver or a network store would land the row after
-  the next `invoke` fires, on every persist.
-- **One blob per run stays.** The snapshot is a tree that xstate restores from its root, and one row keeps it atomic —
-  with the ledgers beside it (admissions, epochs, notices, timers, outstanding picks, Effects); a Pool's cost at 40
-  workers is 0.2 ms, so its workers do not become rows of their own. The Effect ledger keeps a row for every Effect the
-  run started (ADR-0067), so a Machine that loops through an Effect grows its blob by one row per pass: id, kind and
-  outcome. The output's tail is dropped once the save that carries the Effect's transition is on disk; a push row keeps
-  its published commit, its source, its `squashed` and its sync's answer whole — every later push of its Repo Slot sends
-  them as one of its pairs — and its bundle only while it is its Repo Slot's newest push and its sync did not finish —
-  one bundle per Repo Slot at most. An outstanding pick's hold is the one place tails accumulate: its `chain` keeps
-  every reply since the pick whole until the pick is answered, then it is dropped (ADR-0067).
-- **`restore()` reads live rows only.** The store answers `WHERE status = 'live'`; terminal rows are not parsed at boot.
-- **A finished run's row lives 7 days, fixed.** Every non-live status — `done`, `failed`, `error`, `cancelled`, `lost`,
-  `drifted` — ages from its terminal write, and a sweep at boot and every hour deletes what is older. A `live` row is
-  never swept: a run parked on a Gate for a month stays and is restored. The value is fixed like the Sandbox idle
-  timeout, not config: jr2 is not the record of a run's results (a Machine sends its output where it belongs — a PR, a
-  Source), and `jr2 status` on an old run is a debugging act. A swept id frees its abbreviations (ADR-0009).
-- **The store is sqlite on the Instance's volume. No Postgres is owed.** The `SnapshotStore` interface stays as the
-  seam, with one implementation. `DATABASE_URL` is not a thing jr2 reads.
-
-## Considered options
-
-- **Keep `synchronous=FULL`, move the write to a worker thread.** Rejected: the thread hides 4.5 ms from the loop but
-  does not make the disk faster, so writes queue under load and the loop no longer knows how far behind the store is —
-  and it opens the ordering gap on every write, which NORMAL opens only on a power loss.
-- **Batch persists in a window.** Rejected: one persist per macrostep already coalesces a transition's events, and with
-  the fsync gone there is nothing left to amortize.
-- **A row per worker.** Rejected: it splits an atomic tree across rows (a worker's row saved, the Pool's not), makes
-  restore reassemble what xstate restores whole, and buys nothing measurable at 0.2 ms per blob.
-- **Configurable retention (`runs.retain`), or a count cap per workflow.** Rejected: a count cap does not bound a busy
-  workflow's disk and punishes a quiet one; a config key is owed only when a history surface (a list, a query) exists to
-  use it, and none does — `jr2 runs` and the Console list live runs.
-- **Build the Postgres store.** Rejected: the only thing it buys is an Orchestrator pod that reschedules without its
-  volume, which is a storage-class question (a network RWO volume follows the pod) and belongs to the Orchestrator pod's
-  own decision (R10), not to the store. Its cost is a dependency the owner operates, a second store in every test tier,
-  and the asynchronous write above.
-
-## Consequences
-
-- ADR-0008 and ADR-0009 lose "Postgres opt-in" and `DATABASE_URL`; ADR-0008's Orchestrator persists its snapshots "to
-  sqlite on its volume". ADR-0007 points here for the store's durability.
-- The Instance's volume gains `state.db-wal` and `state.db-shm` beside `state.db`.
-- A `drifted` run (ADR-0030) is swept a week after the deploy that changed its Machine, not a week after it ended; a
-  week is the time a human has to read it.