@theford/runly 0.0.0-stage → 0.20.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# runly
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@theford/runly)](https://www.npmjs.com/package/@theford/runly) [![ci](https://github.com/ChristianKohlberg/backlot/actions/workflows/ci.yml/badge.svg)](https://github.com/ChristianKohlberg/backlot/actions/workflows/ci.yml) [![release](https://img.shields.io/github/v/release/ChristianKohlberg/backlot)](https://github.com/ChristianKohlberg/backlot/releases)
+
+runly puts a running, seeded, authenticated instance of your web application in
+front of a coding agent or a human. It runs your repo's own commands in the
+worktree you call it from, one environment per worktree, described by one
+`runly.yml`.
+
+## Install
+
+```bash
+npm i -g @theford/runly        # requires Node ≥ 22.13 and git
+runly update          # after every upgrade: restarts the running daemon onto the installed build
+```
+
+The daemon starts on first use (a unix socket in `~/.local/state/backlot`;
+`BACKLOT_STATE_DIR` moves it). The `backlot` command and `backlot.yml` are
+accepted aliases, and every setting is a `BACKLOT_*` environment variable
+([list](docs/architecture.md#configuration)).
+
+For Claude Code, install the bundled skill:
+
+```
+/plugin marketplace add ChristianKohlberg/backlot
+/plugin install runly
+```
+
+## Quickstart
+
+```bash
+git clone https://github.com/ChristianKohlberg/backlot && cd backlot
+npm ci && npm run build && npm link
+cd examples/hello-multi
+
+runly up web                 # upkeep, builds, data; start web and its depends_on (api); prints the context
+runly up                     # add every other service; up never stops one
+runly ps                     # services and database copies of this worktree
+eval "$(runly ctx --env)" && node smoke.test.mjs   # your tests, fed exported RUNLY_* variables
+runly up --preset main=empty # reload one datastore; the others keep their data
+runly db with main -- sh -c 'echo "$RUNLY_DB_URL"'   # a fresh database copy for one command, dropped after
+runly logs api -f --until 'listening' --timeout 60   # wait for the current process's line (124 on timeout)
+runly down web               # stop one service; lease, data and port stay
+runly destroy                # tear down everything this worktree holds
+```
+
+After an edit, run `runly up` again: it runs the due upkeep and the builds and
+restarts only the services whose build output changed. Idle services stop after
+10 minutes and start again on the next request. How an environment lives and
+ends is in [the guide](docs/overview.md#an-environments-life).
+
+## Manifest reference
+
+`runly.yml` at the repo root ([JSON Schema](schema/runly.schema.json)). Commands
+run under `sh` in the worktree; write POSIX sh.
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Stack name (`a-z0-9-`). Required. |
+| `services.<svc>.run` | The supervised command. Required. |
+| `services.<svc>.build` | Command run before the service starts, on every `up`. `{ run, when: [globs], serial }`: `when` skips it while the matched files are unchanged since the last successful build and its `outputs:` are still what that build left; `serial: true` runs it alone. |
+| `services.<svc>.outputs` | Globs the build produces; a running service restarts only when they changed. `{ paths, compare: stat \| content }`. None declared = restart after every build. |
+| `services.<svc>.port` | Symbolic port name. Omit for a portless worker. |
+| `services.<svc>.env` | Environment variables; values may use templates (below). |
+| `services.<svc>.env_from` | Caller variables to pass in: `NAME: required \| optional`. Not `BACKLOT_*`. |
+| `services.<svc>.cwd` | Working directory, relative to the repo root. |
+| `services.<svc>.ready` | Readiness: `http` (path answering 200), `log` (regex), or `cmd` (exit 0); `timeout` seconds (120). |
+| `services.<svc>.fatal_logs` | Regex that fails the start at once when it appears in the log. |
+| `services.<svc>.depends_on` | Services that must be ready first. |
+| `services.<svc>.idle` | Idle time before the service is stopped (`90s`, `30m`, `2h`, seconds, or `never`). Default 10 minutes. |
+| `services.<svc>.resources` | Cost for the load budget: `{ memory, cpu, build: { memory, cpu } }`. Default 512M / 0.5 cpu running, 1G / 1 cpu building. |
+| `datastores.<ds>.driver` | `sqlite`, `postgres`, `mssql`, `mysql` or `redis`. Required. |
+| `datastores.<ds>.create` | Creates and seeds a namespace; `{{ns}}`, `{{preset}}`. |
+| `datastores.<ds>.drop` | Drops a namespace; `{{ns}}`. Needed for `runly db` copies of a server datastore. |
+| `datastores.<ds>.template_restore` | Restores a baked template into a namespace; `{{template}}`, `{{ns}}`. Server drivers. |
+| `datastores.<ds>.template` | `true`: bake a template file and restore by copy. sqlite only. |
+| `datastores.<ds>.url` | Connection string handed to services; `{{ns}}`. Required for server drivers. |
+| `datastores.<ds>.probe` | `host:port` checked before anything starts (unreachable = infra-error). |
+| `datastores.<ds>.server` | `external` (the only value): runly never runs a database server. |
+| `datastores.<ds>.presets` | Named seed states. |
+| `datastores.<ds>.default_preset` | The preset a new datastore is created with (else the first preset). A name, or `{ session, run }` read as one value. |
+| `datastores.<ds>.ephemeral` | `true`: no presets or templates; a reset runs `drop:` as a flush (Redis-class). |
+| `datastores.<ds>.share_templates` | `false`: keep this datastore's templates per worktree. Default: a template keyed by an `@rebake-template` rule is baked once and shared by every worktree of the same stack name on this machine; `--pristine` bakes a private one for its worktree. |
+| `datastores.<ds>.copies_only` | `true`: never provisioned for an environment; only the source of `runly db new\|with` copies (template baked on the first copy). No service may template it; `ctx` does not list it. |
+| `datastores.<ds>.list` | Command printing the namespaces on the server, one per line; read only by `runly pool doctor`. |
+| `appliances.<name>` | A shared backing server: `probe` (required), `start` (run once when the probe fails), `stop` (only for `runly appliance stop`), `ready`, `timeout` (60), `resources`. |
+| `upkeep[]` | `{ when: <path or glob>, run: <cmd>, timeout: <s>, outputs: <path or list> }`: runs when the matched files' content changed since it last ran in this worktree, or when a declared `outputs` path is missing (a `git clean` removed it). `runly destroy` forgets the rules that declare no `outputs`, so they run again on the next `up`. `run: "@rebake-template <ds>"` makes the matched files part of that datastore's template key: changed content gets a new template (baked once, then reused) and reloads the store; `--pristine` rebakes. Timeout 300 s. |
+| `builds` | `parallel` (default): builds run in `depends_on` waves, each wave at once. `serial`: one at a time, in manifest order. |
+| `caches` | Build and install output in the worktree (`node_modules`, `**/obj`); never an upkeep trigger. |
+| `sync.include` | Git-ignored files an upkeep `when:` may still match (`.env.local`). |
+| `auth.logins` | One `{ user, password, role, description }` or a list; the first is the primary login. |
+| `auth.token` | Command printing a token on stdout; `{{role}}`. |
+| `preview.publisher` | `cloudflare-quick` (default), `cloudflare-named` or `tailscale`. |
+| `preview.domain`, `preview.prefix` | `cloudflare-named`: the zone, and the hostname suffix (default: the environment id). |
+| `preview.https_port` | `tailscale`: the tailnet HTTPS port (default: derived per environment and service). |
+| `preview.forbidden` | `true`: `runly preview` is refused. |
+
+Templates: `{{ports.<port>}}`, `{{public_ports.<port>}}`, `{{services.<svc>.url}}`,
+`{{datastores.<ds>.url}}`, `{{datastores.<ds>.ns}}`. In a service's own `run:` and
+`env:`, its own `{{ports.<port>}}` is the internal port it must listen on;
+everywhere else ports and URLs are the stable public ones. Top-level `outputs`,
+`checks` (with a warning), `sync.keep`, `watch_run` and `hot_reload` are accepted
+and ignored.
+
+## Command reference
+
+Every verb takes `--json` (stdout is one JSON object). Exit codes: `0` ok, `1`
+work-error (your code), `2` env-error (the environment), `3` infra-error
+(something external), `64` usage.
+
+| Command | What it does |
+| --- | --- |
+| `runly up [svc...]` | Lease this worktree's environment, run due upkeep and builds, start the named services and their `depends_on` (none named = all). Never stops a running service; with services named, the other running ones are not rebuilt or restarted. Prints a short summary (what started or restarted, and why a full rebind happened); `--json` the full context. |
+| `  --preset [ds=]NAME` | Reload that datastore from its template (repeatable); the services that use it restart. Without it, data is kept. |
+| `  --reset-data` / `--pristine` | Restore every datastore / that, plus re-run every upkeep rule and build (never deletes worktree files). |
+| `  --rebuild` | Run every build, ignoring `when:`. |
+| `  --ttl <minutes>` | Lease length (default 30), for an untethered lease: it skips the automatic tether, and is refused next to `--holder-pid`. |
+| `  --env` | Print the `ctx --env` export lines instead of the summary. |
+| `  --holder-pid <pid>` | Tie the environment to a process that outlives the command; torn down a minute after it exits. The summary then says `held by agent <pid>` instead of a deadline. |
+| `runly down [svc...]` | Stop these services (none = all); lease, data and ports stay. |
+| `runly ctx [--env]` | A short summary (service URLs and states, datastores, login, a failed last `up`); `--json` the full context; `--env` prints `export RUNLY_*=…` lines for `eval`. |
+| `runly ps [--all]` | Services (state, ports, pid, idle, memory) and database copies of this worktree, or of the whole box (with a worktree column). A service that crash-looped, or failed its boot during an `up`, shows `failed` with its last exit; an `up` that failed (a build, upkeep, data) is named with its error. The next `up` retries both. |
+| `runly plan [svc...] [--rebuild]` | What an `up` would build and start, what it costs, and whether it starts now or waits for the load budget. |
+| `runly logs [svc...]` | Service logs, interleaved (last 40 lines). `--lines N`, `--since up\|10m`, `--grep <re>` (exit 1 when nothing matches), `--build` (the upkeep output and each service's last build, a section each with its own last N lines; the header says what was cut). |
+| `  -f [--until <re>] [--timeout <s>]` | Follow; `--until` exits 0 on the first matching line of the current process (never an earlier one), `--timeout` exits 124. |
+| `runly db with <ds> [--preset NAME] [--runly-exit N] -- <cmd>` | Run a command against a fresh copy (`RUNLY_DB_URL`; `RUNLY_DB_DATABASE`, the database's name on its server; `RUNLY_DB_COPY`, the handle), drop it after, exit with its code. The command dies with the CLI however the CLI dies. runly's own failures are marked on stderr (`runly db with:`, and a `{"runlyDbWith":…}` line with `--json`) and exit 1/2/3, or `N` with `--runly-exit N`. |
+| `runly db new <ds> [--preset NAME]` | Make a copy and print `name=`, `url=`, `database=`, `preset=`. |
+| `runly db ls [--all]` / `db drop <name>` | List copies / drop one now. |
+| `runly exec <cmd...>` | Run a command in the worktree with your environment plus the `ctx --env` variables (and `BACKLOT_URL_*`, `BACKLOT_PORT_*`, `BACKLOT_DS_*`). Stopped services start first. Your terminal, its exit code; `--json` collects `stdout`, `stderr`, `exitCode`. No deadline unless `BACKLOT_CMD_TIMEOUT_S` is set. |
+| `runly warm` | Run due upkeep and builds now, with no lease and no services. |
+| `runly reset-data [--preset ds=NAME]` | Restore the data of the current lease. |
+| `runly token [--role <r>] [--raw]` | Run `auth.token` (role default `admin`, also in `RUNLY_ROLE`); `--raw` prints the bare token. Stopped services start first. |
+| `runly release` | End the lease; the environment stays for the next `up`. |
+| `runly destroy` | Tear down everything runly holds for this worktree: services, data, copies, ports, lease. Its build records, templates and the upkeep rules that declare `outputs` stay. |
+| `runly preview <svc> [--ttl <minutes>] [--https-port N]` | Publish one service through the preview publisher. Unauthenticated. Lasts as long as the lease; a daemon restart publishes it again (same address where the publisher can pin one). |
+| `runly preview stop` | End the preview (also one a restart could not publish again). |
+| `runly status` / `runly doctor` | Daemon, environments, budget and recent warnings (`--json` everything) / health and drift report. |
+| `runly appliance ls\|start\|stop [name]` | Probe, start or stop shared backing servers. |
+| `runly pool ls\|recycle [<env-id>] [--force]\|reconcile\|gc` | Environments; recycle one (or all); reap degraded ones; reclaim orphaned processes. |
+| `runly pool doctor [--fix]` | List (and with `--fix` remove) what runly left behind. Only runly's own. |
+| `runly update [--check] [--force]` | Restart the daemon onto the installed build. Leases survive. |
+| `runly daemon stop` / `runly --version` | Stop the daemon, waiting up to 60 s (`BACKLOT_DAEMON_STOP_TIMEOUT_MS`) / print the CLI version. |
+| `runly daemon install [--print] [--env NAME]` / `daemon uninstall` | Supervise the daemon with a systemd user unit (Linux) or launchd agent (macOS) that restarts it when it crashes; `--print` shows the unit. The unit carries `PATH`, an allowlist (`DOTNET_*`, `NODE_*`, `JAVA_HOME`, `DOCKER_*`, `LANG`/`LC_*`, proxies, `SSL_CERT_*`), `BACKLOT_*`, the variables the manifest's commands reference and each `--env NAME`, never an `env_from` input; install prints what it captured and left out. |
+
+The verbs that act on a lease or copy take `--holder <name>` to act for a holder
+other than the caller's worktree (the default; any subdirectory of it counts). `up`, `warm` and `reset-data` show progress on a terminal;
+`--progress` forces it, `--quiet` silences it.
+
+## More
+
+- [docs/overview.md](docs/overview.md) — the guide: environment life, ports,
+  testing, data, builds, the load budget, previews, security.
+- [docs/architecture.md](docs/architecture.md) — the design and every setting.
+- [docs/decisions/](docs/decisions/) — why it is the way it is.
+
+## License
+
+Apache-2.0.

package/dist/cli/client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Classify a client-side failure for the exit-code contract (decision 0010).
+ *
+ * Agents branch on the class mechanically, so an unreachable or wedged daemon
+ * must NOT report env-error: that tells the agent to recycle an environment,
+ * which cannot fix a broken daemon. Anything that never became a classified
+ * daemon response is infrastructure.
+ */
+export declare function classifyClientError(err: unknown): 'infra-error' | 'env-error';
+export interface RpcError {
+    class?: string;
+    code?: string;
+    message: string;
+    source?: string;
+    logExcerpt?: string;
+}
+export type RpcResponse = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: RpcError;
+};
+/**
+ * The daemon streams newline-delimited frames: {type:'progress',phase} … then
+ * one {type:'result',ok,…}. `onProgress` (optional) sees each phase; the
+ * promise resolves on the result frame. Consumers that ignore progress (for example,
+ * ping, most verbs) just don't pass it — the frames are consumed and dropped.
+ */
+export declare function rpc(verb: string, args: Record<string, unknown>, onProgress?: (phase: string) => void, deadlineMs?: number): Promise<RpcResponse>;
+/**
+ * What the daemon answering the socket says it is.
+ *
+ * `version` is undefined for a daemon that predates version reporting (<= 0.8.0)
+ * — indistinguishable at the protocol level from "answered without it", which is
+ * why callers must treat undefined as skew rather than as "same version".
+ */
+export interface DaemonInfo {
+    pid?: number;
+    version?: string;
+    journalSchema?: number;
+}
+/** Inspect without spawning; only an absent socket/listener means no daemon. */
+export declare function daemonInfo(): Promise<DaemonInfo | null>;
+/**
+ * How long `daemon stop` waits for the acknowledged shutdown to finish. The
+ * engine serialises a verified group kill per service (SIGTERM grace plus a
+ * post-SIGKILL wait) across every supervisor before it reaps, so a shared box
+ * with many signal-trapping services legitimately needs more than `update`'s
+ * default window.
+ */
+export declare const DAEMON_STOP_TIMEOUT_MS = 60000;
+/** The stop window, overridable (BACKLOT_DAEMON_STOP_TIMEOUT_MS) so a test of the timeout need not sit through a minute. */
+export declare const daemonStopTimeoutMs: () => number;
+/**
+ * Wait for the daemon to be really gone — not answering AND not running.
+ *
+ * `update` needs this between the restart request and the respawn, and
+ * `daemon stop` (with `DAEMON_STOP_TIMEOUT_MS`) before it reports `stopped`,
+ * for two distinct reasons:
+ *
+ * - `shutdown` returns its result frame ~50ms BEFORE the process exits, so
+ *   pinging straight away is answered by the daemon that is about to die,
+ *   ensureDaemon concludes one is already up, and the update silently does
+ *   nothing.
+ * - The socket is removed a moment BEFORE the process exits and releases the
+ *   election lock. A daemon spawned in that window finds the lock held by a
+ *   still-live holder, and electSelf refuses to break a live claim (correctly —
+ *   that check is what stops two daemons binding the same journal), so it
+ *   concedes with exit 0. The client then reads "our child exited cleanly, a
+ *   winner must exist" and waits out a full window for a winner that was never
+ *   started. Waiting on the PID closes it.
+ *
+ * Each ping is cut at the remaining budget, and a ping that had to be cut is
+ * evidence of a daemon, not of its absence: a listener that never answered is
+ * still a listener. Only a probe that found no socket or no listener, with the
+ * recorded pid (when known) also dead, counts as gone.
+ */
+export declare function awaitDaemonGone(oldPid?: number, timeoutMs?: number): Promise<boolean>;
+export declare function ensureDaemon(cwd?: string): Promise<DaemonInfo>;