@theford/runly 0.0.0-stage → 0.20.0

package/dist/daemon/engine.d.ts

@@ -0,0 +1,1703 @@
+import { Journal, type LeaseRow } from '../core/journal.js';
+import { LoadBudget, type Committed } from './budget.js';
+import { type UpkeepStep } from '../core/upkeep.js';
+import { ProxyHub } from './proxy.js';
+import { killGroupVerified } from './supervisor.js';
+import { type BindDiagnostics } from '../core/diagnostics.js';
+import type { Hygiene, LeaseKind } from '../core/types.js';
+/** Streamed bind phases → human progress on stderr (never on the --json stdout). */
+export type Progress = (phase: string) => void;
+/** The answer to `up --data-only` from any client that still sends it (the CLI exits 64 before the daemon). */
+export declare const DATA_ONLY_REMOVED: string;
+export interface UpOptions {
+    /**
+     * Datastores to RELOAD from their template, each with the preset to load
+     * (decision 0034). A datastore not named here keeps whatever it holds.
+     */
+    presets?: unknown;
+    cwd: string;
+    /** Explicit refresh envelope; absent means retain this lease's in-memory inputs. */
+    callerEnv?: unknown;
+    holder?: string;
+    hygiene?: Hygiene;
+    kind?: LeaseKind;
+    ttlMs?: number;
+    /**
+     * Services to START, plus their transitive depends_on closure — ADDED to
+     * what the environment already runs (decision 0034: `up` is additive and
+     * never stops a running service). Empty or omitted is the manifest's default
+     * set, which is every service. (Only the internal reset-data rebind adds
+     * nothing; it does not come through `up`.)
+     */
+    services?: string[];
+    /** Removed by decision 0034; a request that still sets it is refused with DATA_ONLY_REMOVED. */
+    dataOnly?: boolean;
+    /** Run every build, also those whose `when:` inputs are unchanged (decision 0038). */
+    rebuild?: boolean;
+    /**
+     * The CALLER's process, so its lease can be released when it dies.
+     * The CLI exits per invocation, so this must be the long-lived agent's pid —
+     * supplied via --holder-pid or BACKLOT_HOLDER_PID.
+     */
+    holderPid?: number;
+    /** Set by the daemon per-request; emits progress frames back to the client. */
+    onProgress?: Progress;
+    /**
+     * Aborted when the requesting client disconnects (the daemon wires it to
+     * the response's close). A queued `up` whose caller is gone gives up
+     * instead of binding for nobody.
+     */
+    signal?: AbortSignal;
+}
+export declare class Engine {
+    private readonly reapServiceGroup;
+    constructor(reapServiceGroup?: typeof killGroupVerified);
+    readonly journal: Journal;
+    /** The L4 proxy holding every environment's public ports (decision 0033). */
+    readonly proxy: ProxyHub;
+    private supervisors;
+    private lastSweep;
+    private lastRetention;
+    private lastGc;
+    private lastSweepMono;
+    /** waketime (epoch ms) of the last kernel-recorded sleep already pardoned. */
+    private lastPardonedWake;
+    /** FIFO tickets for capacity waiters, so an early waiter is not starved.
+     * PER STACK: capacity is per-stack, so one queue for the whole engine made
+     * a waiter on full stack A block stack B's instantly-satisfiable claim. */
+    private waitTicket;
+    private waiting;
+    private poolChain;
+    private envChains;
+    /**
+     * One lock per WORKTREE (keyed by stack id), held around everything runly
+     * writes into it: upkeep rules, builds, and a pristine bind clearing the
+     * worktree ledger (decision 0032). A worktree has one environment, but
+     * `runly warm` runs there with none — and before the first bind creates it —
+     * so the environment lock alone cannot serialize them. Ordering rule: an
+     * environment lock is always taken BEFORE this one, never after — `warm`
+     * takes the environment lock(s) of its stack first, so no cycle exists.
+     */
+    private treeChains;
+    /** Envs with an operation in flight — the sweeper must not expire/quiesce these. */
+    readonly busy: Set<string>;
+    /** What is in flight on a busy env, so a deferral can name it. */
+    private busyOp;
+    /** Never persisted or returned. Lease IDs prevent reuse from inheriting another caller's inputs. */
+    private leaseInputs;
+    /** Opaque in-memory revisions only; no secret values or hashes in the journal. */
+    private appliedInputs;
+    private appliedInputSpecs;
+    private appliedManifests;
+    /**
+     * Re-publishing the leases' previews after a restart (decision 0045), per
+     * lease id: in flight, or failed with the reason `ctx` reports. In memory:
+     * it describes this daemon life; the lease row keeps what to re-publish.
+     */
+    private previewRestores;
+    /** Settles once every recorded preview was re-published or reported; a restore that outlives a `shutdown` stops what it started. */
+    previewsRestored: Promise<void>;
+    private inputRevision;
+    /** Unsaved proxy activity per env, by port key; flushed throttled and by the sweeper. */
+    private activityDirty;
+    private activityFlushedAt;
+    /** When each running service process was started — a fresh start is activity. */
+    private startedAt;
+    /** Services stopped for idleness (ps shows them as `idle`). */
+    /** The last failed `up` per environment (0.19), for ctx and ps; cleared by a successful one. */
+    private readonly bindFailures;
+    private idleStopped;
+    /**
+     * Services of a LEASED environment that crash-looped and were stopped
+     * (decision 0039), by env + service: `ps` and `ctx` show them as `failed`
+     * with how they ended; a wake skips them; the next `up` starts them again.
+     */
+    private failedServices;
+    /** In-flight wakes, by env + service, so a burst of connections starts a service once. */
+    private waking;
+    /** First time a tether was seen dead; it is believed only after the grace. */
+    private goneSince;
+    /** The manifest each environment's running services were started from (budget accounting). */
+    private envManifests;
+    /** Appliances runly started in this daemon life, by probe address (budget accounting); pruned when one stops. */
+    private startedAppliances;
+    /** When each idle-stopped service stopped: a wake soon after skips the CPU gate (decision 0036). */
+    private idleStoppedAt;
+    /** A sweep is running: the next tick is skipped rather than overlapping it. */
+    private sweeping;
+    /** shutdown() has begun: no sweep, no wake, nothing new. */
+    stopping: boolean;
+    /** The server-wide load budget (decision 0036). */
+    readonly budget: LoadBudget;
+    private poolLocked;
+    private envLocked;
+    private treeLocked;
+    /** Hold several environment locks at once, in a fixed (sorted) order. */
+    private envsLocked;
+    /**
+     * The worktree's upkeep ledger, and a committer that writes back only the
+     * worktree's half of a merged fingerprint map. MUST be used inside
+     * treeLocked: the read-modify-write is what the lock serializes.
+     */
+    private treeLedgerSession;
+    /** Recovery (decision 0009): reap recorded PIDs from a previous daemon life; hot -> warm. */
+    recover(): Promise<void>;
+    /**
+     * Reclaim runly-spawned processes that no live environment accounts for.
+     *
+     * A process is an orphan when it carries this state root's tag but its env
+     * either no longer exists in the journal, or exists in a state that must have
+     * no services running (warm/recycling). Anything belonging to a hot env, or
+     * to an env with an operation in flight, is left strictly alone — a bind
+     * racing the sweep must not have its dev-server shot out from under it.
+     */
+    poolGc(): Promise<{
+        supported: boolean;
+        reclaimed: Array<{
+            pid: number;
+            envId: string;
+            service: string;
+        }>;
+        skipped: number;
+    }>;
+    /**
+     * An environment's PRIVATE state — data dir, logs. There is no tree here:
+     * services run in the caller's worktree (decision 0032).
+     */
+    private envDirs;
+    private createEnv;
+    /**
+     * A public port nobody holds: inside the public block, recorded on no
+     * environment row, not one this daemon listens on, and probed free (which
+     * also skips a port a tunnel or another process binds on any address).
+     */
+    private allocPublicPort;
+    /**
+     * A fresh internal port for one start of env/key (decision 0033), reserved
+     * in the proxy at once. The probe awaits, so another start can be probing
+     * the same port meanwhile: the reservation is re-checked after it and taken
+     * with no await in between. Released when the target goes down (a stop, a
+     * failed start, a settle) or is owned by the target once it is up.
+     */
+    private allocInternalPort;
+    /**
+     * Make the proxy hold every public port of `env` (decision 0033). Idempotent.
+     *
+     * A recorded port is kept whenever it can be: the whole point is that it is
+     * stable. It moves only when it cannot be held — it lies outside the public
+     * block (a journal from runly 0.13, whose ports came from the OS ephemeral
+     * range), or another process took it while no listener held it (the daemon
+     * was down). A move is saved to the journal at once and reported; returns
+     * one line per moved port, empty when nothing moved.
+     */
+    private ensureProxies;
+    /** One atomic claim attempt — MUST run under the pool lock. */
+    private tryClaim;
+    /**
+     * Does the machine-wide ceiling refuse a NEW environment right now? Named
+     * explicitly because a refusal must quote the cap that bound (#47). There
+     * is no per-stack cap (one environment per worktree, decision 0032) and no
+     * data-only cap (decision 0034: a database without an application is a
+     * `runly db` copy, which is not an environment). MUST run under the pool lock.
+     */
+    private capacityBinding;
+    /**
+     * Cold, unleased environments that can be given up to free a MACHINE-WIDE
+     * slot, least-recently-used first.
+     *
+     * Why eviction rather than just not counting them (#46's own suggestion): the
+     * caps gate environment CREATION only — rebinding an existing environment is
+     * never capacity-checked — so the row count is what bounds worst-case
+     * concurrent load. Excluding cold rows from the count would leave nothing to
+     * stop N of them being rebound hot at once. Giving the slot back for real
+     * keeps the ceiling meaningful, and costs the least-recently-used environment
+     * one cold provision the next time it is bound.
+     *
+     * Unleased + not busy + idle past IDLE_TTL qualifies. A recently released
+     * environment is the warm pool doing its job, so it is never taken — if
+     * nothing is that idle the caller gets a refusal naming the cap that actually
+     * bound, which is still strictly better than the lockout.
+     *
+     * Deliberately NOT restricted to `warm`. Idle past IDLE_TTL is precisely what
+     * the sweeper quiesces, but it only looks every BACKLOT_SWEEP_MS (15s by
+     * default) — so an environment released and abandoned a moment ago is still
+     * `hot` while already being condemned. Requiring `warm` meant that for a whole
+     * sweep interval the caller was refused with "waiting will not help", when the
+     * next sweep would in fact have made this environment evictable. Taking a
+     * condemned `hot` environment is the same trade one step further, and
+     * recycleOne stops its services through the ordinary teardown.
+     */
+    private evictionCandidates;
+    /**
+     * Free a machine-wide slot by giving up the least-recently-used cold
+     * environment. Returns the id evicted, or null if nothing qualified.
+     *
+     * MUST NOT hold the pool lock: recycleOne claims under it (the chain is not
+     * re-entrant), and the teardown that follows deletes a tree, which the pool
+     * lock must never wait on. claimForTeardown re-reads and refuses anything
+     * leased or busy, so a candidate chosen here and leased in the gap is declined
+     * rather than taken — never take an environment somebody else is holding (#40).
+     */
+    private evictForMachineCapacity;
+    /**
+     * Is some environment about to become claimable on its own?
+     *
+     * `busy` is the one that matters here and was missed: the idle quiesce runs
+     * under the environment lock, which marks it busy, and decision 0021 keeps its
+     * mid-quiesce state as plain `hot` on purpose. So the sweeper reclaiming heat
+     * from the only candidate made it briefly unevictable — and the machine-wide
+     * refusal, which tells the caller that waiting cannot help, fired on a
+     * condition that clears in milliseconds. It reproduced on the macOS runner,
+     * where teardown is slower (services get SIGTERM, then a verified SIGKILL).
+     *
+     * The other three are transient for the reasons the per-stack branch already
+     * gives: the sweeper reaps them and frees capacity.
+     */
+    private transientlyUnclaimable;
+    /**
+     * Why this environment could not be given up, per environment.
+     *
+     * It used to say "too recent to evict" for every unleased row, which is the
+     * defect #47 was about in miniature: a message that names one cause for four
+     * different situations sends the reader after the wrong one. (It cost an hour
+     * here, diagnosing a CI failure whose real cause was `busy`.)
+     */
+    private notEvictableBecause;
+    /**
+     * Is the pool full of environments whose leases outlast our whole wait?
+     *
+     * If so, queueing cannot possibly succeed, and reporting "waited 60s" blames a
+     * timing problem that does not exist. MUST run under the pool lock.
+     */
+    private structuralCapacityBlock;
+    /**
+     * Why this worktree's own environment cannot be claimed, if that is what is
+     * in the way (decision 0032: one environment per worktree, so a second
+     * holder waits for it instead of getting another).
+     *
+     * - `undefined`: the worktree has no environment, or it sits unleased and
+     *   usable — whatever refused the claim is a capacity ceiling, not the
+     *   worktree.
+     * - `null`: it is in the way, but will clear by itself within the wait
+     *   (a lease that lapses in time, a recycle or reap in progress).
+     * - a string: it is leased past the wait window — naming who holds it.
+     */
+    private worktreeHold;
+    /**
+     * One refusal text for both throw sites, quoting real counts and the cap that
+     * actually bound.
+     *
+     * The old messages printed `(${POOL_MAX()}/${POOL_MAX()})` — the cap twice,
+     * not a count — so a stack with ZERO environments was told "pool at capacity
+     * (6/6)" and pointed at the wrong knob (#47).
+     */
+    private capacityRefusal;
+    /** Queue at capacity WITHOUT holding the pool lock while sleeping. */
+    private acquireEnv;
+    private acquireQueued;
+    /**
+     * The values `{{…}}` resolves to. Everything is PUBLIC (decision 0033): the
+     * ports and URLs users, builds, exec and other services see are the proxy's.
+     * The one exception is a service's own command line and env, given
+     * `own = { key, port }`: there `{{ports.<own key>}}` is the INTERNAL port the
+     * service must listen on. `{{public_ports.<key>}}` is always the public one,
+     * for a service that has to advertise its own address.
+     */
+    private templateCtx;
+    private supervisor;
+    /**
+     * The services a bind must bring up: the named ones plus the transitive
+     * `depends_on` closure of each. An unknown name is a manifest work-error,
+     * reported like the other service lookups. A depends_on cycle is tolerated
+     * here (the visit is closure-guarded) and caught by the start loop's own
+     * cycle check.
+     */
+    private resolveServiceClosure;
+    /**
+     * The services `env`'s lease wants up (decision 0034): `up` adds to this set
+     * and `down` takes away. Undefined on the row means every declared service,
+     * so a service added to the manifest later is included.
+     */
+    private desiredServices;
+    /** How a wanted set is recorded: undefined for every declared service, else the list (possibly empty). */
+    private recordedShape;
+    /**
+     * The services that use datastore `ds`, read from the manifest: a service
+     * uses it when its `run:`, `build:` or `env:` templates `{{datastores.<ds>.…}}`
+     * — that is how a service is handed a connection string. `null` when no
+     * service references it at all: then runly cannot tell who reads it (a
+     * connection string in a config file, a hard-coded path), and the caller
+     * must restart every running service to be safe (decision 0034).
+     */
+    private datastoreUsers;
+    /** The datastores an environment of `stack` provisions: all but the `copies_only` ones (decision 0039). */
+    private envDatastores;
+    /** `up --preset` and `reset-data --preset` name only datastores an environment has (decision 0039). */
+    private refuseCopiesOnlyPresets;
+    /**
+     * Give back the namespaces of datastores an environment no longer
+     * provisions — one made before its datastore became `copies_only` (decision
+     * 0039) — by the drop recorded for each. A drop that fails stays on the row
+     * for teardown to retry.
+     */
+    private retireEnvDatastores;
+    /**
+     * Create, keep or reload each datastore in `plan` — all of them at once
+     * (0.19): each bakes and restores under its own datastore lock, so three
+     * datastores cost the slowest one, not their sum. Every completed restore is
+     * journalled at once, so a failure still reports the others truthfully, and
+     * the call settles only when every datastore has (the first error wins). A
+     * datastore not forced and already present is KEPT — whatever it holds, even
+     * a preset the catalog no longer offers (decision 0034: no preset means keep
+     * the data, never a silent reset to the default).
+     */
+    private prepareDatastores;
+    /**
+     * What an additive `up` builds and may restart: every service it leaves
+     * running for a plain `up`; for `up <service…>` only the named services,
+     * their depends_on closure and what it (re)starts because it is not running
+     * (0.19). A full rebind still stops and starts everything — its reasons
+     * (an upkeep rule ran, the manifest changed, …) concern every service.
+     */
+    private bindScope;
+    private bindAndStart;
+    private bindAndStartInner;
+    /** The public ports of `services` hold new connections until their service is ready again. */
+    private markStarting;
+    /**
+     * The order the builds of `names` run in: depends_on waves. A build runs
+     * after the builds of what its service depends on (transitively), and the
+     * builds of one wave run at once — independent services no longer wait for
+     * each other. `build: {serial: true}` runs alone; `builds: serial` on the
+     * stack runs every build alone, in manifest order (the behaviour before
+     * 0.16.1). The load budget holds the costliest wave's sum (needFor).
+     *
+     * Builds that write one shared output or take one tool lock belong in
+     * `serial`. Two Angular projects are fine in parallel: the CLI's persistent
+     * cache is keyed per project (`.angular/cache/<version>/<project>`).
+     */
+    private buildWaves;
+    /**
+     * Run `fn` for each service of `waves`, wave after wave, the members of one
+     * wave at once. A failure fails the call once its whole wave has settled —
+     * never with a sibling build still running behind the caller's back.
+     */
+    private inWaves;
+    /** Build `names` (those that declare a build) in waves. MUST run under treeLocked. */
+    private runBuilds;
+    /**
+     * Run one service's build in the worktree. MUST run under treeLocked. Its
+     * output goes to `<service>.build.log` in the environment's log directory
+     * (decision 0038), replaced by each build; `logDir` is undefined only for a
+     * `warm` with no environment.
+     */
+    private runServiceBuild;
+    /**
+     * Whether a service's build must run now (decision 0038), and the key a
+     * successful run is recorded under. A `when:` build runs only when its
+     * inputs changed since its last successful build in this worktree; a
+     * string build always runs on a bind, and on a wake only when it never
+     * succeeded here (a wake resumes what ran; `up` applies changes).
+     */
+    private buildDecision;
+    private decideBuild;
+    /** Build one service if its build is due; record a success. MUST run under treeLocked. */
+    private buildService;
+    /** Would this service's build run now? (Recorded in `decided` for the build that follows.) */
+    private buildWillRun;
+    /**
+     * A stat print of a service's declared outputs, as the build ledger keeps
+     * it: undefined when it declares none, '' when none exist on disk.
+     */
+    private outputsPrint;
+    /** The upkeep rules' output of this bind, in `upkeep.build.log` (decision 0038), begun by the first rule that runs. */
+    private upkeepLog;
+    /**
+     * Ensure the stack's appliances (decision 0018), remembering the ones runly
+     * started for the budget. A started one is counted as running from now on,
+     * so its share leaves the caller's reservation.
+     */
+    private ensureAppliances;
+    /**
+     * Forget appliances that are no longer up (stopped by hand, crashed, a
+     * reboot): their cost stayed committed for the rest of the daemon's life.
+     * Re-probed every sweep — a TCP connect per appliance runly started.
+     */
+    private pruneStartedAppliances;
+    /** Declared (or default) run resources of everything runly runs now, across every environment. */
+    private committedRunning;
+    /**
+     * What starting `starts` and building `builds` would cost (decision 0036),
+     * item by item: run resources per start, build resources per build that
+     * will actually run, and run resources per appliance that is not up.
+     */
+    private needFor;
+    /**
+     * Start `only` (a subset of `active`) in dependency order, readiness-gated,
+     * fatal-log fast-fail. The other members of `active` are already running,
+     * so they count as started for depends_on — and so does a dependency the
+     * lease took `down` on purpose (it is not wanted; the dependent reaches its
+     * stable public port). On a failure a bind stops everything (`stop-all`); a
+     * wake stops only what it started (`stop-these`). In a LEASED environment a
+     * bind's service that fails to boot on its own account (a work-error: it
+     * exited, hit a fatal log marker, daemonized) is instead stopped and marked
+     * failed like a runtime crash loop (decision 0039, 0.18.1); its dependents
+     * are not started, everything else is. Returns those dependents.
+     */
+    private startServices;
+    /**
+     * Who the caller is when it names no holder: its WORKTREE — the directory
+     * holding the manifest, found by searching upward — whichever subdirectory
+     * the verb runs from. `up` at the root and `ctx --env` from `src/app` are
+     * the same caller. A live lease an older runly keyed to a subdirectory is
+     * still honoured from that subdirectory until it ends.
+     */
+    private callerHolder;
+    up(opts: UpOptions): Promise<{
+        previewNotice: string | undefined;
+        bindDiagnostics: BindDiagnostics;
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        /**
+         * `holderPid`: the process the lease is tethered to (decision 0035) —
+         * while it lives the lease does not expire, so `expiresAt` is only the
+         * renewal horizon. null for a lease that ends at `expiresAt`.
+         */
+        lease: {
+            id: string;
+            kind: "session";
+            hygiene: Hygiene;
+            expiresAt: number;
+            holderPid: number | null;
+        } | null;
+        urls: Record<string, string>;
+        /** The environment's PUBLIC ports by manifest key (`runly ctx --env` → RUNLY_PORT_<KEY>). */
+        ports: {
+            [x: string]: number;
+        };
+        /**
+         * The proxy in front of each public port, by port key (decision 0033):
+         * state, client→server bytes and the last client byte's time. runly's
+         * own readiness probes bypass it and are never counted.
+         */
+        proxy: Record<string, import("./proxy.js").ProxyStats>;
+        previewUrls: Record<string, string>;
+        /**
+         * A preview the daemon re-publishes after a restart (decision 0045):
+         * `restoring`, or `failed` with the error; null when there is none.
+         */
+        previewRestore: {
+            error?: string | undefined;
+            service: string;
+            url: string;
+            state: "failed" | "restoring";
+        } | null;
+        /**
+         * Every declared service and where it stands (decision 0034): `running`,
+         * `stopped` (wanted, but not running — a quiesce or a daemon restart; the
+         * next `up` starts it) or `down` (not wanted: never started, or taken
+         * down with `runly down`). `urls` lists the wanted ones.
+         */
+        services: Record<string, "down" | "failed" | "running" | "stopped">;
+        /** Services that crash-looped and were stopped (decision 0039), with their last exit; the next `up` retries them. */
+        failures: Record<string, {
+            reason: string;
+            exitCode: number | null;
+            signal: string | null;
+            at: number;
+            detail: string;
+            hint: string;
+        }>;
+        /** The last `up` failed and none succeeded since (0.19): what failed; null otherwise. */
+        lastUpFailed: {
+            at: number | null;
+            class: string | null;
+            message: string;
+            source: string | null;
+            hint: string;
+        } | null;
+        /**
+         * `logins` stays the PRIMARY login even for a stack that declares a list, so
+         * a consumer reading `ctx.logins.user` is unaffected by the manifest growing
+         * more of them; `allLogins` carries the full set. Both are null/omitted when
+         * the stack declares none.
+         */
+        logins: import("../core/manifest.js").Login | null;
+        allLogins: import("../core/manifest.js").Login[];
+        /**
+         * The manifest's INTERNAL hook, templated and run inside the leased
+         * environment — not something to run by hand. It still carries its
+         * `{{role}}` placeholder, and run from a worktree it signs with the wrong
+         * key, so a token minted that way comes back 401 and reads as a
+         * permissions problem. `tokenVia` is the supported path.
+         */
+        tokenCommand: string | null;
+        tokenVia: string | null;
+        /**
+         * Every datastore exists for the environment's whole life (decision
+         * 0034). `preset` is what it holds now — the last preset restored into
+         * it — or null before its first restore. `runly ctx --env` exports it as
+         * RUNLY_DATASTORE_<NAME>_PRESET.
+         */
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+                preset: string | null;
+            };
+        };
+        events: import("./supervisor.js").ServiceEvent[];
+    }>;
+    /**
+     * The environment a lease points to. leaseForHolder JOINs envs, so the row
+     * existed when the lease was resolved — but a concurrent forced teardown can
+     * delete it before this read (deleteEnv is one transaction now, so a torn
+     * write can no longer leave a lease naming a deleted row; journals from
+     * before that change still can, and the sweeper prunes those). Every verb
+     * that asserted `getEnv(lease.envId)!` used to crash with an unclassified
+     * TypeError instead of telling the caller what to do about it.
+     */
+    private envForLease;
+    ctx(cwd: string, holder?: string, envId?: string): {
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        /**
+         * `holderPid`: the process the lease is tethered to (decision 0035) —
+         * while it lives the lease does not expire, so `expiresAt` is only the
+         * renewal horizon. null for a lease that ends at `expiresAt`.
+         */
+        lease: {
+            id: string;
+            kind: "session";
+            hygiene: Hygiene;
+            expiresAt: number;
+            holderPid: number | null;
+        } | null;
+        urls: Record<string, string>;
+        /** The environment's PUBLIC ports by manifest key (`runly ctx --env` → RUNLY_PORT_<KEY>). */
+        ports: {
+            [x: string]: number;
+        };
+        /**
+         * The proxy in front of each public port, by port key (decision 0033):
+         * state, client→server bytes and the last client byte's time. runly's
+         * own readiness probes bypass it and are never counted.
+         */
+        proxy: Record<string, import("./proxy.js").ProxyStats>;
+        previewUrls: Record<string, string>;
+        /**
+         * A preview the daemon re-publishes after a restart (decision 0045):
+         * `restoring`, or `failed` with the error; null when there is none.
+         */
+        previewRestore: {
+            error?: string | undefined;
+            service: string;
+            url: string;
+            state: "failed" | "restoring";
+        } | null;
+        /**
+         * Every declared service and where it stands (decision 0034): `running`,
+         * `stopped` (wanted, but not running — a quiesce or a daemon restart; the
+         * next `up` starts it) or `down` (not wanted: never started, or taken
+         * down with `runly down`). `urls` lists the wanted ones.
+         */
+        services: Record<string, "down" | "failed" | "running" | "stopped">;
+        /** Services that crash-looped and were stopped (decision 0039), with their last exit; the next `up` retries them. */
+        failures: Record<string, {
+            reason: string;
+            exitCode: number | null;
+            signal: string | null;
+            at: number;
+            detail: string;
+            hint: string;
+        }>;
+        /** The last `up` failed and none succeeded since (0.19): what failed; null otherwise. */
+        lastUpFailed: {
+            at: number | null;
+            class: string | null;
+            message: string;
+            source: string | null;
+            hint: string;
+        } | null;
+        /**
+         * `logins` stays the PRIMARY login even for a stack that declares a list, so
+         * a consumer reading `ctx.logins.user` is unaffected by the manifest growing
+         * more of them; `allLogins` carries the full set. Both are null/omitted when
+         * the stack declares none.
+         */
+        logins: import("../core/manifest.js").Login | null;
+        allLogins: import("../core/manifest.js").Login[];
+        /**
+         * The manifest's INTERNAL hook, templated and run inside the leased
+         * environment — not something to run by hand. It still carries its
+         * `{{role}}` placeholder, and run from a worktree it signs with the wrong
+         * key, so a token minted that way comes back 401 and reads as a
+         * permissions problem. `tokenVia` is the supported path.
+         */
+        tokenCommand: string | null;
+        tokenVia: string | null;
+        /**
+         * Every datastore exists for the environment's whole life (decision
+         * 0034). `preset` is what it holds now — the last preset restored into
+         * it — or null before its first restore. `runly ctx --env` exports it as
+         * RUNLY_DATASTORE_<NAME>_PRESET.
+         */
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+                preset: string | null;
+            };
+        };
+        events: import("./supervisor.js").ServiceEvent[];
+    };
+    /**
+     * Where each declared service stands: running, failed (wanted, crash-looped
+     * and stopped — decision 0039), stopped (wanted, not running) or down (not
+     * wanted).
+     */
+    private serviceStates;
+    /**
+     * The last `up` of `env`, when it failed and none has succeeded since
+     * (0.19): what failed, and that `up` redoes it — neither a connection nor a
+     * verb starts its services meanwhile. After a daemon restart only the fact
+     * survives (the journal's fail streak), not the message.
+     */
+    private bindFailureOf;
+    /** The failed services of `env` (decision 0039): how each last ended, and the log to read. */
+    private serviceFailures;
+    /**
+     * `runly warm`: run THIS worktree's due upkeep rules and its services'
+     * `build:` steps, with no lease and no services (decision 0032). The intended
+     * caller is an idle pool slot that was just moved to a new commit
+     * (`git checkout <sha> && runly warm`): the installs are done and the build
+     * tools' own incremental state is current, so the next agent's bind finds
+     * the upkeep fresh and its builds near no-ops.
+     *
+     * Upkeep rules go through the same worktree ledger a bind reads, so a rule
+     * warm ran is a rule the next bind skips. Builds are not recorded anywhere:
+     * warm runs every one, and the next bind runs them again — cheaply, because
+     * the build tool finds its output current. It holds the environment lock of
+     * this worktree (if it has one: a check must not run while its output
+     * changes underneath it) and then the worktree lock — the same order every
+     * bind uses, so it can wait but never deadlock.
+     *
+     * What it cannot do without an environment it reports as skipped: a build
+     * line that templates an environment's ports or datastores has no values to
+     * run with, and `@` built-ins act on an environment's data.
+     */
+    warm(cwd: string, onProgress?: Progress): Promise<{
+        ok: boolean;
+        stack: string;
+        root: string;
+        steps: (({
+            kind: "upkeep";
+        } & UpkeepStep) | {
+            kind: "build";
+            service: string;
+            status: "ran" | "skipped" | "failed";
+            durationMs: number;
+            reason?: string;
+        })[];
+        failure: null;
+        durationMs: number;
+    }>;
+    resetData(cwd: string, holder?: string, onProgress?: Progress, presets?: unknown): Promise<{
+        previewNotice: string | undefined;
+        bindDiagnostics: BindDiagnostics;
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        /**
+         * `holderPid`: the process the lease is tethered to (decision 0035) —
+         * while it lives the lease does not expire, so `expiresAt` is only the
+         * renewal horizon. null for a lease that ends at `expiresAt`.
+         */
+        lease: {
+            id: string;
+            kind: "session";
+            hygiene: Hygiene;
+            expiresAt: number;
+            holderPid: number | null;
+        } | null;
+        urls: Record<string, string>;
+        /** The environment's PUBLIC ports by manifest key (`runly ctx --env` → RUNLY_PORT_<KEY>). */
+        ports: {
+            [x: string]: number;
+        };
+        /**
+         * The proxy in front of each public port, by port key (decision 0033):
+         * state, client→server bytes and the last client byte's time. runly's
+         * own readiness probes bypass it and are never counted.
+         */
+        proxy: Record<string, import("./proxy.js").ProxyStats>;
+        previewUrls: Record<string, string>;
+        /**
+         * A preview the daemon re-publishes after a restart (decision 0045):
+         * `restoring`, or `failed` with the error; null when there is none.
+         */
+        previewRestore: {
+            error?: string | undefined;
+            service: string;
+            url: string;
+            state: "failed" | "restoring";
+        } | null;
+        /**
+         * Every declared service and where it stands (decision 0034): `running`,
+         * `stopped` (wanted, but not running — a quiesce or a daemon restart; the
+         * next `up` starts it) or `down` (not wanted: never started, or taken
+         * down with `runly down`). `urls` lists the wanted ones.
+         */
+        services: Record<string, "down" | "failed" | "running" | "stopped">;
+        /** Services that crash-looped and were stopped (decision 0039), with their last exit; the next `up` retries them. */
+        failures: Record<string, {
+            reason: string;
+            exitCode: number | null;
+            signal: string | null;
+            at: number;
+            detail: string;
+            hint: string;
+        }>;
+        /** The last `up` failed and none succeeded since (0.19): what failed; null otherwise. */
+        lastUpFailed: {
+            at: number | null;
+            class: string | null;
+            message: string;
+            source: string | null;
+            hint: string;
+        } | null;
+        /**
+         * `logins` stays the PRIMARY login even for a stack that declares a list, so
+         * a consumer reading `ctx.logins.user` is unaffected by the manifest growing
+         * more of them; `allLogins` carries the full set. Both are null/omitted when
+         * the stack declares none.
+         */
+        logins: import("../core/manifest.js").Login | null;
+        allLogins: import("../core/manifest.js").Login[];
+        /**
+         * The manifest's INTERNAL hook, templated and run inside the leased
+         * environment — not something to run by hand. It still carries its
+         * `{{role}}` placeholder, and run from a worktree it signs with the wrong
+         * key, so a token minted that way comes back 401 and reads as a
+         * permissions problem. `tokenVia` is the supported path.
+         */
+        tokenCommand: string | null;
+        tokenVia: string | null;
+        /**
+         * Every datastore exists for the environment's whole life (decision
+         * 0034). `preset` is what it holds now — the last preset restored into
+         * it — or null before its first restore. `runly ctx --env` exports it as
+         * RUNLY_DATASTORE_<NAME>_PRESET.
+         */
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+                preset: string | null;
+            };
+        };
+        events: import("./supervisor.js").ServiceEvent[];
+    }>;
+    /**
+     * Re-read an environment INSIDE its lock and refuse work on one that is being
+     * torn down.
+     *
+     * Teardown claims the row under the pool lock and then runs slowly outside the
+     * env lock, so a request that resolved its lease before the claim can arrive
+     * here afterwards and operate on a tree that is about to be deleted (or
+     * already is). bindAndStart already re-checks; exec and token
+     * phase did not.
+     */
+    /**
+     * Record that an environment was USED, without extending its lease.
+     *
+     * Activity is what keeps services awake (decision 0035), so only verbs that
+     * USE the environment call this (decision 0039): `up` and `reset-data` (a
+     * bind sets the clock itself), `exec`, `token`, `preview` and `down`. The
+     * read-only verbs — `ctx`, `ps`, `plan`, `logs`, `status`, `db ls`,
+     * `doctor` — do not: an agent polling them is not using a service, and
+     * counting them kept idle services running for as long as anyone looked.
+     */
+    private touch;
+    /** `resumable`: the caller starts idle-stopped services itself (resumeForVerb) instead of being refused. */
+    private assertUsable;
+    /**
+     * What `runly exec` runs with (decision 0040): the environment's variables,
+     * with idle-stopped services (and, after a daemon restart, every wanted
+     * service) started first and the activity clock touched. The CLI spawns the
+     * command itself — inherited stdio, the caller's own environment, the real
+     * exit code — so nothing here holds the environment's lock while it runs.
+     */
+    execEnv(cwd: string, holder?: string): Promise<{
+        envId: string;
+        root: string;
+        vars: {
+            [x: string]: string;
+        };
+    }>;
+    /** A running `runly exec` is activity (decision 0039): the CLI calls this while the command runs. */
+    execTouch(envId: string): {
+        touched: boolean;
+    };
+    /** Resolve auth.token with {{role}} and run it in the worktree the environment runs in. */
+    token(cwd: string, role: string, holder?: string): Promise<{
+        token: string;
+        role: string;
+    }>;
+    /**
+     * Where this worktree's environment keeps the logs of `services` (decision
+     * 0038) — all of them when none are named. The CLI reads, filters and
+     * follows the files itself; the daemon only resolves which ones. With
+     * `build`, the build output of each service's last build, and the upkeep
+     * output of the last `up` that ran a rule.
+     */
+    logsSpec(cwd: string, services: string[], build: boolean, holder?: string): {
+        envId: string;
+        dir: string;
+        build: boolean;
+        files: {
+            service: string;
+            file: string;
+        }[];
+    };
+    /** The pre-0.16 single-service read, kept for RPC clients: the last `lines` lines, without stamps. */
+    logs(cwd: string, service: string, lines: number, holder?: string): {
+        service: string;
+        lines: string;
+    };
+    /**
+     * Hand the environment back. A no-op answer must say WHY.
+     *
+     * A lease is keyed by holder NAME, which defaults to the worktree path — so
+     * releasing from a different directory than the one that bound silently
+     * matches nothing. `{released: false}` on its own gave an agent no way to tell
+     * that apart from "already released", and the reported behaviour was simply to
+     * give up and let the environment linger until its TTL. Name the mismatch, and
+     * list who does hold this stack's leases.
+     */
+    release(cwd: string, holder?: string): Promise<{
+        released: boolean;
+        holder: string;
+        reason: string;
+        otherHolders: string[];
+        envId?: undefined;
+    } | {
+        released: boolean;
+        envId: string;
+        holder?: undefined;
+        reason?: undefined;
+        otherHolders?: undefined;
+    }>;
+    private previewPublisherName;
+    private assertPreviewAllowed;
+    /**
+     * Tagged members of a verified leased preview process group. A publisher's
+     * wrapper can fork its tunnel child; excluding only the leader lets a scan
+     * select the child and kill the whole leased group. All scan consumers share
+     * this classification, using the same state-root-scoped process snapshot.
+     *
+     * Ownership requires the recorded leader identity AND matching env tags.
+     * A stale/reused leader PID, an unreadable identity, or a generic preview:
+     * service label cannot exempt another process. Descendants that leave the
+     * group (setsid) need a separate ownership mechanism and are not protected.
+     */
+    private leasedPreviewPids;
+    /**
+     * Stop and clear any lease-scoped preview tunnel recorded on this lease.
+     *
+     * Teardown may NEVER be blocked by a manifest edit: `preview.publisher` is
+     * re-read from disk on every call, so a name that resolved at start can be a
+     * typo by the time the sweeper gets here — and an unknown name throws a
+     * work-error. Thrown from the sweeper's lease loop that aborted every tick,
+     * so TTL expiry, dead-holder release and eviction stopped daemon-wide. The
+     * teardown path therefore falls back to the default publisher instead.
+     *
+     * Returns false when the tunnel could NOT be confirmed dead. The record is
+     * kept in that case (reapPids' contract): a forgotten preview pid is a
+     * public, unauthenticated URL nobody can ever name again.
+     */
+    private stopPreviewForLease;
+    /**
+     * What an operator can actually do about a tunnel that outlived its kill.
+     *
+     * Pointing at `pool gc` was only ever true on Linux — it is a tag scan, and
+     * `procScanSupported()` is Linux-only — which is precisely the platform where
+     * the record is NOT recoverable. Name the pid and the public URL instead, so
+     * the remedy survives the lease row that is usually about to be deleted.
+     */
+    private unreapedPreview;
+    /**
+     * Release a lease and reap its preview tunnel first.
+     *
+     * Re-read between the stop and the delete. `release` and the sweeper hold no
+     * env lock, and the stop blocks in `killGroupVerified` for up to ~4s — long
+     * enough for a concurrent `preview` to take the env lock, publish, and write
+     * its pid onto this very row. Deleting the row on the strength of the old
+     * snapshot then orphaned the NEW tunnel: no lease names it, `pool gc` skips
+     * nothing it can see, and `preview stop` has nothing left to stop. Taking the
+     * env lock here instead would nest it inside the pool lock (tryClaim calls
+     * this) and stall every claim machine-wide for the length of a bind.
+     */
+    private endLease;
+    /**
+     * Everything about an environment that decides whether publishing `service`
+     * is legal, and the local port to publish. Returns that port.
+     *
+     * One function because it has to run TWICE — once before queueing for the env
+     * lock, and again inside it against a re-read row. Every field it reads is one
+     * a concurrent bind rewrites.
+     */
+    private previewTarget;
+    /**
+     * Publish every recorded preview again after a restart (decision 0045): same
+     * publisher, the settings that pin its address, aimed at the same public
+     * port — which the proxy holds again, so the first request wakes the
+     * service as usual. A failure is an event and `ctx.previewRestore`, never
+     * an error of anyone's verb.
+     */
+    private restorePreviews;
+    private restorePreview;
+    /** The lease's preview is over on purpose: a restart must not bring it back (decision 0045). */
+    private forgetPreview;
+    previewStart(cwd: string, service: string, holder?: string, ttlMs?: number, httpsPort?: number): Promise<{
+        service: string;
+        url: string;
+    }>;
+    previewStop(cwd: string, holder?: string): Promise<{
+        stopped: boolean;
+        service?: string;
+    }>;
+    /** Live-probed appliance overview for the stack at cwd. */
+    applianceLs(cwd: string): Promise<{
+        stack: string;
+        appliances: Record<string, {
+            probe: string;
+            up: boolean;
+            startable: boolean;
+            stoppable: boolean;
+        }>;
+    }>;
+    /** Ensure one appliance (or all of them) — the same path a bind takes. */
+    applianceStart(cwd: string, name?: string): Promise<{
+        results: Record<string, string>;
+    }>;
+    /** Explicit stop — the only path that ever stops an appliance. */
+    applianceStop(cwd: string, name: string): Promise<{
+        stopped: string;
+    }>;
+    /**
+     * `runly down [service…]` (decision 0034): stop just these services — or,
+     * with no names, every service — and keep the lease, the data and the public
+     * ports. The proxy keeps listening; connections to a downed service are
+     * refused until an `up` brings it back. Dependents of a downed service are
+     * NOT stopped ("just those"); they are named in the answer, because they now
+     * talk to a port with nothing behind it.
+     */
+    down(opts: {
+        cwd: string;
+        holder?: string;
+        services: string[];
+        onProgress?: Progress;
+    }): Promise<{
+        stopped: string[];
+        down: string[];
+        dependentsStillRunning: string[];
+        previewNotice: string | undefined;
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        /**
+         * `holderPid`: the process the lease is tethered to (decision 0035) —
+         * while it lives the lease does not expire, so `expiresAt` is only the
+         * renewal horizon. null for a lease that ends at `expiresAt`.
+         */
+        lease: {
+            id: string;
+            kind: "session";
+            hygiene: Hygiene;
+            expiresAt: number;
+            holderPid: number | null;
+        } | null;
+        urls: Record<string, string>;
+        /** The environment's PUBLIC ports by manifest key (`runly ctx --env` → RUNLY_PORT_<KEY>). */
+        ports: {
+            [x: string]: number;
+        };
+        /**
+         * The proxy in front of each public port, by port key (decision 0033):
+         * state, client→server bytes and the last client byte's time. runly's
+         * own readiness probes bypass it and are never counted.
+         */
+        proxy: Record<string, import("./proxy.js").ProxyStats>;
+        previewUrls: Record<string, string>;
+        /**
+         * A preview the daemon re-publishes after a restart (decision 0045):
+         * `restoring`, or `failed` with the error; null when there is none.
+         */
+        previewRestore: {
+            error?: string | undefined;
+            service: string;
+            url: string;
+            state: "failed" | "restoring";
+        } | null;
+        /**
+         * Every declared service and where it stands (decision 0034): `running`,
+         * `stopped` (wanted, but not running — a quiesce or a daemon restart; the
+         * next `up` starts it) or `down` (not wanted: never started, or taken
+         * down with `runly down`). `urls` lists the wanted ones.
+         */
+        services: Record<string, "down" | "failed" | "running" | "stopped">;
+        /** Services that crash-looped and were stopped (decision 0039), with their last exit; the next `up` retries them. */
+        failures: Record<string, {
+            reason: string;
+            exitCode: number | null;
+            signal: string | null;
+            at: number;
+            detail: string;
+            hint: string;
+        }>;
+        /** The last `up` failed and none succeeded since (0.19): what failed; null otherwise. */
+        lastUpFailed: {
+            at: number | null;
+            class: string | null;
+            message: string;
+            source: string | null;
+            hint: string;
+        } | null;
+        /**
+         * `logins` stays the PRIMARY login even for a stack that declares a list, so
+         * a consumer reading `ctx.logins.user` is unaffected by the manifest growing
+         * more of them; `allLogins` carries the full set. Both are null/omitted when
+         * the stack declares none.
+         */
+        logins: import("../core/manifest.js").Login | null;
+        allLogins: import("../core/manifest.js").Login[];
+        /**
+         * The manifest's INTERNAL hook, templated and run inside the leased
+         * environment — not something to run by hand. It still carries its
+         * `{{role}}` placeholder, and run from a worktree it signs with the wrong
+         * key, so a token minted that way comes back 401 and reads as a
+         * permissions problem. `tokenVia` is the supported path.
+         */
+        tokenCommand: string | null;
+        tokenVia: string | null;
+        /**
+         * Every datastore exists for the environment's whole life (decision
+         * 0034). `preset` is what it holds now — the last preset restored into
+         * it — or null before its first restore. `runly ctx --env` exports it as
+         * RUNLY_DATASTORE_<NAME>_PRESET.
+         */
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+                preset: string | null;
+            };
+        };
+        events: import("./supervisor.js").ServiceEvent[];
+    }>;
+    /** In-flight creations and drops of database copies; the reaper never touches these. */
+    private dbBusy;
+    /** What `db new` / `db ls` / `ps` show for one copy. */
+    private dbCopyView;
+    /**
+     * Is a recorded holder process gone? One rule for leases and database copies
+     * alike (decision 0034: copies are reaped exactly like environments), so a
+     * grace period added here applies to both.
+     */
+    private holderGone;
+    /**
+     * `runly db new <datastore>` (decision 0034): a fresh copy of the datastore,
+     * restored from the SAME template the environments use (baked first if it is
+     * missing), outside any environment — no lease, no ports, no services. Many
+     * may exist at once. The row is journalled BEFORE the restore, as
+     * `creating`, so a daemon that dies mid-restore leaves a record the next one
+     * reaps.
+     */
+    dbNew(opts: {
+        cwd: string;
+        datastore: string;
+        preset?: string;
+        holder?: string;
+        holderPid?: number;
+        onProgress?: Progress;
+    }): Promise<{
+        name: string;
+        datastore: string;
+        preset: string;
+        url: string;
+        ns: string;
+        state: "ready" | "creating" | "dropping";
+        worktree: string;
+        holder: string;
+        holderPid: number | null;
+        /** null = no agent tether was given: the copy lives until its worktree goes or it is dropped. */
+        holderAlive: boolean | null;
+        createdAt: number;
+    }>;
+    /**
+     * `runly db with` records the command it runs against a copy (decision
+     * 0039), so a drop can take that command down first when its CLI died.
+     */
+    dbAttach(name: string, child: {
+        pid: number;
+        start?: number;
+        pgid?: number;
+    }): {
+        attached: string;
+    };
+    /**
+     * Stop whatever still runs against copy `row` (decision 0039): the command
+     * `runly db with` recorded — its process group when it has its own, else
+     * the verified pid — and, on Linux, every process carrying the copy's tag.
+     * Only a pid whose start time still matches is signalled. Returns how many
+     * processes were stopped.
+     */
+    private stopCopyUsers;
+    /** Is `path` a copy's own directory under the state root (never anything else)? */
+    private isPrivateDbDir;
+    /**
+     * Drop one copy with what its row recorded — the command (run in the
+     * worktree, or the state root once that is gone) or its private directory.
+     * Needs neither the manifest nor the worktree. A failed drop keeps the row
+     * (`dropping`) with a backoff, so the reaper retries instead of forgetting a
+     * database nothing else can name. Callers hold `dbBusy` for the name.
+     */
+    private dropDbCopy;
+    /** `runly db drop <name>`: drop one copy now, whoever made it. */
+    dbDrop(name: string): Promise<{
+        dropped: string;
+    }>;
+    /** `runly db ls`: this worktree's copies, or every copy with `all`. */
+    dbLs(cwd: string, all: boolean): {
+        scope: string;
+        copies: {
+            name: string;
+            datastore: string;
+            preset: string;
+            url: string;
+            ns: string;
+            state: "ready" | "creating" | "dropping";
+            worktree: string;
+            holder: string;
+            holderPid: number | null;
+            /** null = no agent tether was given: the copy lives until its worktree goes or it is dropped. */
+            holderAlive: boolean | null;
+            createdAt: number;
+        }[];
+    };
+    /** The caller's worktree root, for the per-worktree views (`ps`, `db ls`). */
+    private callerWorktree;
+    /** Why a copy must go now, or null (decision 0034: reaped exactly like environments; no TTL). */
+    private dbCopyOrphanReason;
+    /** Drop every copy whose holder or worktree is gone. Runs in every sweep and after recovery. */
+    private reapDbCopies;
+    /** Resident memory per (env, service), summed over its tagged processes. Linux only; empty elsewhere. */
+    private rssByService;
+    /**
+     * `runly ps` (decision 0034): one view of what runs for the caller — the
+     * services of this worktree's environment and its database copies — or,
+     * with `all`, for the whole server.
+     */
+    ps(cwd: string, all: boolean): {
+        scope: string;
+        services: Record<string, unknown>[];
+        databases: {
+            name: string;
+            datastore: string;
+            preset: string;
+            url: string;
+            ns: string;
+            state: "ready" | "creating" | "dropping";
+            worktree: string;
+            holder: string;
+            holderPid: number | null;
+            /** null = no agent tether was given: the copy lives until its worktree goes or it is dropped. */
+            holderAlive: boolean | null;
+            createdAt: number;
+        }[];
+        /** Environments whose last `up` failed (0.19), with what failed. */
+        failedUps: Record<string, unknown>[];
+        /** The server-wide load budget (decision 0036). */
+        budget: {
+            enabled: boolean;
+            memoryBytes: number;
+            cpu: number;
+            committedMemoryBytes: number;
+            committedCpu: number;
+            waiting: number;
+        };
+    };
+    /**
+     * `runly plan [service…]` (decision 0036): what an `up` with these
+     * services would build and start now, what that costs (declared, or the
+     * default, said so), what the box and the budget have free, and whether it
+     * would start now or wait — without doing any of it.
+     */
+    plan(cwd: string, services: string[], rebuild: boolean, holder?: string): Promise<{
+        stack: string;
+        envId: string | null;
+        items: {
+            kind: "start" | "appliance" | "build";
+            name: string;
+            memoryBytes: number;
+            cpu: number;
+            declared: boolean;
+            skipped: string | null;
+        }[];
+        need: {
+            memoryBytes: number;
+            cpu: number;
+            start: {
+                memoryBytes: number;
+                cpu: number;
+            };
+            build: {
+                memoryBytes: number;
+                cpu: number;
+            };
+        };
+        machine: import("./budget.js").Machine;
+        budget: {
+            enabled: boolean;
+            memoryBytes: number;
+            cpu: number;
+            reserveBytes: number;
+            loadPerCore: number;
+            waitMs: number;
+        };
+        committed: Committed;
+        queue: number;
+        startsNow: boolean;
+        verdict: string;
+        defaultsAssumed: string[];
+    }>;
+    /**
+     * `runly destroy` (decision 0035): everything runly holds for this worktree
+     * goes now — its environment (services, data, preview, ports, lease) and its
+     * database copies. What a worktree pool calls when it takes a worktree back;
+     * the sweeper does the same by itself when the worktree is removed or its
+     * agent's tether dies. The baked templates and the build records stay
+     * (decision 0039; a build's `outputs:` are checked before it is skipped).
+     * Of the upkeep ledger only the rules that declare `outputs:` stay: the pool
+     * usually resets the worktree next (`git clean -fdx`), which removes what
+     * the other rules produced, and nothing else could tell.
+     */
+    destroy(cwd: string): Promise<{
+        worktree: string;
+        environments: string[];
+        copies: string[];
+        copiesNotDropped: string[];
+        upkeepForgotten: number;
+    }>;
+    /**
+     * `runly pool doctor [--fix]` (decision 0037): what this state root owns
+     * that nothing references any more. Dry run by default; `--fix` removes it.
+     * Only runly's own: files under the state root in runly's naming,
+     * processes carrying this state root's tag, listeners of this daemon, and
+     * server-side namespaces a datastore's `list:` hook reports that carry
+     * runly's naming AND a stack id this state root has a record of.
+     */
+    poolDoctor(cwd: string, fix: boolean): Promise<{
+        fix: boolean;
+        clean: boolean;
+        findings: {
+            kind: string;
+            what: string;
+            detail: string;
+            fixed?: boolean;
+            error?: string;
+        }[];
+    }>;
+    status(): {
+        pid: number;
+        /**
+         * Who restarts this daemon when it crashes (decision 0039): `systemd` or
+         * `launchd` after `runly daemon install` (the unit sets
+         * RUNLY_SUPERVISOR), `autospawn` (the next CLI command) otherwise. Not
+         * INVOCATION_ID: a daemon autospawned from anything under ANY systemd
+         * service inherits that.
+         */
+        supervisor: string;
+        envs: {
+            id: string;
+            stack: string;
+            state: import("../core/types.js").EnvState;
+            ports: Record<string, number>;
+            bindCount: number;
+            /** Proxy state and traffic per public port (decision 0033). */
+            proxy: Record<string, import("./proxy.js").ProxyStats>;
+            /** Where its services run: the caller's worktree (decision 0032). */
+            worktree: string;
+            lease: LeaseRow | null;
+            /** null = every service (the default set); otherwise the services the lease wants up — [] after `runly down` (decision 0034). */
+            activeServices: string[] | null;
+            idleMs: number;
+            /** null = the holder never identified itself, so liveness is unknowable. */
+            holderAlive: boolean | null;
+            /** Why this environment is still holding its services, in one word. */
+            heat: string;
+            /**
+             * Will the next bind take this environment as-is?
+             *
+             * `heat: 'cold'` means quiesced — services stopped, everything else
+             * intact — which is a HEALTHY free pool entry, not a stuck one. Read as
+             * "dead", it sent an operator to `pool recycle` to unstick a pool that
+             * was already fine, and that recycle took other people's live leases
+             * with it. So state the conclusion instead of leaving it to be inferred.
+             */
+            available: boolean;
+            /** Plain language for the two fields above, so no one has to infer it. */
+            summary: string;
+        }[];
+        poolMaxTotal: number;
+        ports: {
+            public: import("../core/ports.js").PortBlock;
+            internal: import("../core/ports.js").PortBlock;
+            tunnel: import("../core/ports.js").PortBlock;
+            ephemeral: import("../core/ports.js").PortBlock;
+            conflicts: string[];
+        };
+        /** The server-wide load budget (decision 0036). */
+        budget: {
+            committedMemoryBytes: number;
+            committedCpu: number;
+            committed: {
+                what: string;
+                memoryBytes: number;
+                cpu: number;
+            }[];
+            waiting: number;
+            enabled: boolean;
+            memoryBytes: number;
+            cpu: number;
+            reserveBytes: number;
+            cpuPressure: number;
+            loadPerCore: number;
+            waitMs: number;
+            maxQueue: number;
+            defaultRun: {
+                memoryBytes: number;
+                cpu: number;
+            };
+            defaultBuild: {
+                memoryBytes: number;
+                cpu: number;
+            };
+        };
+        /** Client bytes every proxied connection holds for a replay right now; capped by BACKLOT_PROXY_REPLAY_CAP_BYTES (0.19, default 64 MiB). */
+        proxyReplayCarriedBytes: number;
+        events: import("../core/events.js").DaemonEvent[];
+    };
+    /** Who a restart would make rebind: every live lease, named. */
+    leaseHolders(): Array<{
+        envId: string;
+        holder: string;
+        kind: string;
+    }>;
+    /**
+     * What a `runly update` restart would cost, without doing it.
+     *
+     * Reported rather than inferred by the CLI because the two facts that decide
+     * whether a restart is safe — which environments are BUSY, and who holds a
+     * lease — only exist in the daemon's memory and journal.
+     */
+    updatePlan(cliVersion?: string): {
+        daemon: string;
+        daemonBuild: string;
+        cli: string | null;
+        daemonPid: number;
+        journalSchema: number;
+        skew: import("../core/version.js").VersionSkew | null;
+        busy: string[];
+        leases: {
+            envId: string;
+            holder: string;
+            kind: string;
+        }[];
+    };
+    /**
+     * Refuse a restart that would destroy work, and allow the one that costs only
+     * a rebind.
+     *
+     * BUSY is the refusal. An `exec` runs detached so the command itself
+     * survives the daemon, but the CALLER is blocked on this socket waiting for
+     * its result — restarting hands it a dead connection and no result. Every other reclaim path already treats busy as inviolable
+     * (claimForTeardown, both sweeper branches, pool gc, and shutdown's own reap
+     * since 0.8.0), so this one does too.
+     *
+     * A LIVE LEASE is deliberately NOT a refusal. A restart stops services, keeps
+     * the lease, and the holder's next verb rebinds — which is exactly what the
+     * idle quiesce already does to leased environments without anyone's consent,
+     * and what assertUsable already tells the holder to do ("run 'runly up' to
+     * rebind"). Refusing here would mean an update on any busy shared box always
+     * needs --force, and a flag you always pass is a flag that stops meaning
+     * anything: that habituation is what made issue #40 destructive. Holders are
+     * named in the plan instead.
+     *
+     * A DOWNGRADE is refused separately. Restarting from an older CLI replaces a
+     * newer daemon with older code, which is the direction that strands state —
+     * the journal stamp exists because of exactly that (JOURNAL_SCHEMA_VERSION).
+     */
+    assertRestartable(opts: {
+        force: boolean;
+        cliVersion?: string;
+    }): void;
+    /**
+     * doctor: actively check for the failure shapes the review surfaced —
+     * orphaned ports, journal/reality pid divergence, envs stuck recycling, and a
+     * CLI talking to a daemon that is not the installed build.
+     */
+    doctor(cliVersion?: string): Promise<{
+        ok: boolean;
+        issues: {
+            level: string;
+            envId?: string;
+            issue: string;
+        }[];
+        version: string;
+        journalSchema: number;
+        events: import("../core/events.js").DaemonEvent[];
+    }>;
+    /**
+     * Atomically claim an env for teardown UNDER THE POOL LOCK: re-read it, and
+     * (unless force) refuse if it's leased or busy, then flip it to the
+     * 'recycling' guard state so tryClaim/sweep skip it. Returns the row to tear
+     * down, or null if it slipped away. The slow teardown then runs OUTSIDE the
+     * lock, but no claim can touch a 'recycling' env.
+     */
+    private claimForTeardown;
+    /**
+     * Stop and reap this environment's services mid-bind, and journal the result
+     * at once. The row is what capacity accounting reads: an application charge
+     * retained for a conversion stands on `hot` or recorded pids, so leaving
+     * either in the journal after the processes are gone kept a slot reserved for
+     * nothing if the rest of the bind failed. Survivors stay recorded — and keep
+     * the charge — because a pid nobody can confirm dead may still hold a port.
+     * Re-reads the live row so a concurrent degrade is preserved and a recycled
+     * row is never written back.
+     */
+    /**
+     * Stop just the services an `up` is about to restart because their build
+     * output changed (decision 0032); the others keep running. Same reap
+     * contract as stopForBind — recorded pids, then a tag scan — but the scan
+     * is limited to THESE services' tags: the env's other services carry the
+     * same env tag and are still serving.
+     */
+    private stopServicesForRestart;
+    private stopForBind;
+    /**
+     * After a supervisor stopAll(), kill any process that survived or escaped the
+     * group signal so the port is truly free before the port-check below.
+     *
+     * Two failure modes:
+     *   (a) Recorded pid survived a previous kill (quiesce/teardown race): reapPids
+     *       retries with fresh SIGTERM→SIGKILL on all platforms.
+     *   (b) A service called setsid() / spawned a detached grandchild that inherited
+     *       the BACKLOT tag but moved to a new process group, escaping the -pgid
+     *       SIGKILL: scanTagged (Linux only) finds it by the tag in its environment
+     *       and kills the new group.
+     *
+     * Without this, a warm env whose quiesce left survivors hands out a port that
+     * is still bound — the bind then fails with "occupied by a foreign process"
+     * instead of reclaiming the escapee.
+     *
+     * Returns the entries NOT confirmed dead (reapPids contract): callers must
+     * keep those in the journal — a forgotten pid is an orphan nobody can ever
+     * reclaim, and only Linux has the tag scan to fall back on.
+     */
+    private reapEnvProcesses;
+    private reapDiscoveredProcesses;
+    /** Enforce the kill switch under the env lock before preset validation can fail. */
+    private enforceHolderPreviewForbidden;
+    /**
+     * Tear down a live preview the moment the manifest forbids one.
+     *
+     * Unconditional and early, unlike the rest of the reconcile: this is the
+     * security kill switch README and ADR 0027 present as taking effect, and it
+     * would be worthless if a stack stayed published whenever the bind that read
+     * the flag went on to fail.
+     */
+    private enforcePreviewForbidden;
+    /**
+     * Reconcile a live preview against the environment this bind just produced.
+     *
+     * The tunnel outlives service restarts, so everything here is about what is
+     * now BEHIND the unchanged public URL. Three outcomes invalidate it outright
+     * and tear it down — the manifest started forbidding preview, the previewed
+     * service is no longer wanted (`runly down`, decision 0034), or it moved to a different local
+     * port (a renamed port key; existing keys are never reassigned, decision
+     * 0004). A data reset does not: the tunnel keeps serving, which is precisely
+     * why it has to be said out loud.
+     *
+     * Runs at the bind's EPILOGUE, once the shape it judges against is committed.
+     * From the top of the bind it was reading a REQUESTED slice that the epilogue
+     * had not written yet, so a bind that then failed its ready probe left the
+     * tunnel torn down against a slice change that never happened — and dropped
+     * the report with the thrown error. `preview.forbidden` is the exception and
+     * is enforced early by `enforcePreviewForbidden`: it depends on the manifest,
+     * not on the bind.
+     *
+     * Never throws. The `down` that stopped the service or the bind that wiped the data is a
+     * legitimate operation and failing it would strand the caller in a loop (and
+     * bump failStreak into a pristine escalation); the classified message is the
+     * report, and it rides back on the bind's own result.
+     *
+     * `active` must be the DURABLE shape this environment is bound to, never the
+     * supervisor's live pid map: a service in restart backoff is missing from
+     * that map for a second and would be read as "left the slice", killing a
+     * tunnel the restart makes correct again. `portsReallocated` is false on the
+     * hot-reload refresh path — only a real bind fills `env.ports` for a renamed port
+     * key, so before one runs the service is still listening where the tunnel
+     * points and a mismatch means nothing yet.
+     */
+    private reconcilePreviewForBind;
+    /**
+     * Last-resort reap of anything still LIVING IN this env's private directory,
+     * by cwd — at teardown, when that directory is about to be deleted.
+     *
+     * Since decision 0032 services run in the caller's WORKTREE, not here, so
+     * this no longer finds a service that scrubbed its tag: cwd in a worktree is
+     * NOT an ownership signal (the agent's own shells and builds sit there), and
+     * scanning it would kill a stranger's process — the one outcome this whole
+     * module is written to avoid. The tag scan and recorded groups are what
+     * remain for services; this covers anything left in the env directory
+     * itself (a process started under the old projection, for one).
+     */
+    private reapEnvTree;
+    /** Slow teardown of an already-claimed ('recycling') env. */
+    private teardownClaimed;
+    /**
+     * Drop one namespace the way its row recorded it (decision 0037): run the
+     * templated drop command, or delete a file inside the state root. Throws
+     * when the drop did not confirm.
+     */
+    private runDropRecipe;
+    /**
+     * Is `env.root` safe to delete? It must sit strictly inside the state root's
+     * envs/ directory, and must not be (or contain) the worktree the
+     * environment runs in — a corrupted row must never turn teardown into
+     * `rm -rf` of someone's work.
+     */
+    private isPrivateEnvDir;
+    private recycleOne;
+    /**
+     * The clean-slate button, scoped.
+     *
+     * `envId` is an explicit statement of intent — THIS one, not the others — and
+     * it used to be dropped on the floor, so aiming at one cold environment
+     * recycled the whole pool and tore down siblings' live work. A named target
+     * therefore never widens: an unknown id is a usage error, and a leased target
+     * REFUSES rather than being silently skipped, because "nothing happened and
+     * nothing said why" is what sends a caller reaching for force.
+     *
+     * `force` (--force, historically --all) is the only thing that ever reclaims a
+     * leased environment; `busy` is never interrupted, not even by force.
+     */
+    poolRecycle(opts: {
+        envId?: string;
+        force: boolean;
+    }): Promise<{
+        recycled: string[];
+        skipped: {
+            envId: string;
+            reason: string;
+        }[];
+    }>;
+    /** This worktree's degraded, idle environment(s), reaped so a claim can recreate one. */
+    private reapDegradedOwn;
+    /**
+     * One environment per worktree (decision 0032) holds for every environment
+     * this daemon creates. A journal from an older runly can still hold several
+     * for one stack; the unleased, idle ones beyond the one to keep are recycled
+     * here, so the pool converges. A surplus environment that is still leased is
+     * left to its holder until the lease ends.
+     */
+    private drainSurplusEnvs;
+    /** Reap the provably-dead (degraded) envs now, instead of waiting for the sweep. */
+    poolReconcile(): Promise<{
+        reaped: string[];
+    }>;
+    /** The proxy saw a client byte: the clock moves in memory, and reaches the journal throttled. */
+    private noteActivity;
+    /** Persist unsaved activity clocks (all, from the sweeper; one env, throttled, from the hook). */
+    private flushActivity;
+    /** When anyone last used this environment: a runly verb or a client byte on any of its ports. */
+    private envActivityAt;
+    /**
+     * One running service's idle clock: the environment's last runly verb, the
+     * last client byte through the service's own public port (any port's, for
+     * a service with none), and its own start.
+     */
+    private serviceClock;
+    /**
+     * How long a running service of `env` may sit idle: its `idle:` (or the
+     * default), capped for an UNLEASED environment — nobody can wake that one by
+     * traffic — at BACKLOT_IDLE_TTL_MS (the pre-0.16 quiesce). `ps` shows the same.
+     */
+    private serviceIdleLimit;
+    /** Stop the running services of `env` whose idle clock ran out. */
+    private stopIdleServices;
+    /**
+     * Is a tether gone (decision 0035)? A dead pid is believed only once it has
+     * stayed dead for the grace (BACKLOT_TETHER_GRACE_MS, 1 minute); the first
+     * sighting starts the clock, in memory — a daemon restart starts it again.
+     */
+    private tetherGone;
+    /**
+     * The proxy's wake hook (decision 0035): a connection reached the public
+     * port of a service that is not running. Starts it when this environment
+     * holds a live lease and the lease wants that service (a `down`ed service
+     * stays down); the proxy holds the connection meanwhile. Synchronous and
+     * cheap: the start runs in the background.
+     */
+    private requestWake;
+    /**
+     * Start one wanted service — and the wanted, stopped members of its
+     * depends_on closure — on demand. `up`'s start path for a single service:
+     * appliances ensured, datastores kept, the load budget asked (bounded by
+     * how long the proxy holds a connection), no rebuild unless needed (a
+     * `when:` build whose inputs changed, or one that never succeeded here).
+     */
+    private wakeService;
+    /**
+     * Start `closure` — stopped services the lease wants — the way a wake does.
+     * MUST run under the environment's lock. A wake never restores data: a
+     * datastore that exists is kept as it is, so the trigger listing behind the
+     * template keys is computed only for one that is missing.
+     */
+    private startStoppedLocked;
+    /**
+     * `exec` and `token` run against the environment as the lease left it. A
+     * service the idle clock stopped (decision 0035) is started first — under
+     * the lock these verbs hold, where a connection-triggered wake would only
+     * queue behind them until the proxy's hold ran out. So is what a daemon
+     * restart stopped (0.19). A failed bind is refused: `up` redoes it.
+     */
+    private resumeForVerb;
+    /**
+     * A service the supervisor restarts after a crash (decision 0035): its
+     * port HOLDS connections from the crash until the new process accepts on
+     * its (unchanged) internal port, instead of refusing them.
+     */
+    private serviceCrashed;
+    private serviceRelaunched;
+    private serviceGaveUp;
+    /**
+     * A service of a LEASED environment crash-looped past its restart budget
+     * (decision 0039). It is stopped and reported as failed — `ps` and `ctx`
+     * show `failed` with its last exit, `runly logs <svc>` says why — while the
+     * environment, its data, its other services and its logs stay. Nothing
+     * restarts it on its own (a wake skips it); the next `up` does.
+     */
+    private serviceFailed;
+    /** Is `name`, or a service it depends on (transitively), failed (decision 0039)? */
+    private blockedByFailure;
+    /** How a failed service ended, or undefined (decision 0039). */
+    private failureOf;
+    sweep(): Promise<void>;
+    private sweepOnce;
+    shutdown(): Promise<void>;
+}