@evident-ai/runner-synchroniser 0.1.0 → 0.1.1-dev.7568241

package/README.md

@@ -15,8 +15,10 @@ the boot script gates on. It also renders the `litestream.yml` that covers the s
 database, so both halves read their bucket, prefix and paths from one config module
 instead of two.
 
-It is a CLI, not a library: the runner's `entrypoint.sh` invokes it as a single
-self-contained bundle (`node cli.js <command>`).
+It is a CLI, not a library, invoked by two consumers that differ in how they get the
+binary: the Fargate runner image installs the published package and invokes it by name
+(`runner-synchroniser <command>`); the MicroVM still builds it from source and runs the
+bundle directly (`node cli.js <command>`).
 
 ## Install
 
@@ -30,11 +32,25 @@ npx @evident-ai/runner-synchroniser@dev env
 `dist/cli.js` is a single self-contained ESM bundle with **no runtime dependencies** —
 the AWS SDK is bundled at build time, so installing it pulls nothing else in.
 
-> Publishing is being rolled out (#612). The `dev` tag is published on every merge to
-> `main` that touches this package; the first publish is a human bootstrap (#694), and
-> the `latest`-on-release path is not wired up yet. Nothing in this repo installs the
-> package: the runner image and the MicroVM still build the bundle from source, and will
-> keep doing so until that flip lands.
+### Versioning
+
+The package's version **tracks the product release version**, exactly like
+`@evident-ai/cli`. `latest` is published on a product release, at the release
+version. `dev` is published on every merge to `main` that touches this package or
+the root `package.json`, at `<root major>.<minor>.<patch+1>-dev.<sha>`, so `dev`
+stays strictly ahead of `latest`.
+
+The version committed in this package's `package.json` is **vestigial** — CI
+overwrites it before every publish. This is why `latest` jumped straight from
+`0.1.0` to `3.x.y`: the `0.1.x` line predates the policy, not a missing
+major-version story, and because npm publishes are immutable that jump is
+permanent.
+
+The two consumers still differ in how they get the binary: the Fargate runner
+image installs the published package
+(`ARG RUNNER_SYNCHRONISER_VERSION=dev`, resolved to a concrete version by the
+deploy workflow); the MicroVM still builds it from source and reads no npm
+version at all.
 
 ## Commands
 
@@ -47,9 +63,9 @@ the AWS SDK is bundled at build time, so installing it pulls nothing else in.
 | `model-auth-ready`             | —                                       | `0` = ready, `10` = not ready; other = tool broken       |
 | `self-stop`                    | —                                       | `0` = stopped, `20` = keep the task; other = tool broken |
 
-`self-stop` scales this agent's own ECS service to `desiredCount=0` on a clean idle
-exit, reading `CLUSTER`, `SERVICE` and (optionally) `EVIDENT_SELFSTOP_ROLE_ARN` from the
-environment. It exits `0` **only** on a confirmed `desiredCount` of 0.
+`self-stop` scales this agent's own ECS service to `desiredCount=0` on a clean idle exit
+(see Configuration for `CLUSTER`/`SERVICE`/`EVIDENT_SELFSTOP_ROLE_ARN`). It exits `0`
+**only** on a confirmed `desiredCount` of 0.
 
 Everything the operator needs to read goes to **stderr**, prefixed `[auth-persistence]`,
 so a caller can safely capture stdout. The prefix now covers more than credentials — the
@@ -96,23 +112,28 @@ real violation also rejects correct rewrites.
 
 ## Configuration
 
-All configuration is environment variables, resolved once in `src/config.ts`.
+Configuration is environment variables; `src/config.ts` resolves the shared paths, keys
+and settings below once for every command. The three variables marked † are read
+directly by `self-stop` instead — they configure that one command, not a shared path or
+key, so they never appear in `env`'s output or `litestream.yml`.
+
+| Variable                                  | Meaning                                                                   | When absent                                                                        |
+| ------------------------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `HOME`                                    | Every credential and database path is derived from it.                   | Throws; logged `FATAL:`, exits `1`. Affects every command.                        |
+| `LITESTREAM_BUCKET` / `LITESTREAM_PREFIX` | Object-store bucket and key prefix.                                       | Persistence off (needs **both**): `restore`/`sync-once` no-op, `env` warns.       |
+| `AWS_REGION`                              | Region for the AWS clients (S3, and the ECS/STS calls `self-stop` makes). | Left to the SDK's own resolution.                                                 |
+| `CREDS_SYNC_INTERVAL`                     | Seconds between sync ticks, reported by `env` for the caller's loop.     | Falls back to `60`; also on unparseable or non-positive values.                   |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`    | Presence alone counts as configured model auth (see `model-auth-ready`). | No API-key fallback; `model-auth-ready` then depends solely on the credential files. |
+| `CLUSTER` † / `SERVICE` †                 | ECS cluster/service `self-stop` scales to `desiredCount=0`.              | Warns "cannot self-stop" and exits `20` (keep the task). Ignored by every other command. |
+| `EVIDENT_SELFSTOP_ROLE_ARN` †             | Role `self-stop` assumes for its ECS calls.                              | Optional: falls back to the task role's own credentials. A failed/incomplete assume-role → `20`. |
 
-| Variable                               | Meaning                                                                                      |
-| -------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `HOME`                                 | **Required.** Every credential and database path is derived from it; unset is a fatal error. |
-| `LITESTREAM_BUCKET`                    | Object-store bucket.                                                                         |
-| `LITESTREAM_PREFIX`                    | Key prefix within the bucket.                                                                |
-| `AWS_REGION`                           | Region for the S3 client. Unset leaves it to the SDK's own resolution.                       |
-| `CREDS_SYNC_INTERVAL`                  | Seconds between sync ticks, reported by `env` for the caller's loop. Defaults to `60`.       |
-| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | Presence alone counts as configured model auth (see `model-auth-ready`).                     |
+`packages/runner-image/README.md` documents these same three from the deployment side —
+keep them in sync.
 
-**Persistence is enabled only when both `LITESTREAM_BUCKET` and `LITESTREAM_PREFIX` are
-set.** With either missing, `restore` and `sync-once` become no-ops and `env` warns
-loudly that credentials will be lost when the task is replaced — half a location can
-never produce a malformed key.
+Requiring **both** `LITESTREAM_BUCKET` and `LITESTREAM_PREFIX` (never just one) means
+half a location can never produce a malformed key.
 
-The paths and keys that follow from that:
+The paths and keys that follow from the bucket/prefix:
 
 | Store       | Local path                                | Object key                          |
 | ----------- | ----------------------------------------- | ----------------------------------- |
@@ -171,10 +192,11 @@ pnpm lint
 
 From the repository root, prefix with `pnpm --filter @evident-ai/runner-synchroniser`.
 
-The bundle must stay a **single file**: the runner image copies exactly one artifact out
-of its builder stage, so code splitting would ship a `cli.js` importing chunks that are
-not there. `tsup.config.ts` disables splitting and bundles the AWS SDK, and the
-Dockerfile asserts the output is one file.
+The bundle must stay a **single file**: both consumers need a self-contained
+`dist/cli.js` with no sibling chunks — the npm `files: ["dist"]` install ships
+whatever `dist` contains, and the MicroVM runs `dist/cli.js` directly with no
+`node_modules` alongside it. `tsup.config.ts` disables splitting and bundles the
+AWS SDK so neither consumer needs anything else.
 
 The restore/sync/CLI tests need neither AWS nor a real filesystem — rather than shimming
 a fake `aws` binary onto `PATH`, they inject two ports: `InMemoryObjectStore` (in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-synchroniser",
-  "version": "0.1.0",
+  "version": "0.1.1-dev.7568241",
   "description": "Restores and syncs the Evident runner's OpenCode credential stores (and litestream config) to an object store, so a runner survives task replacement with almost no state loss.",
   "type": "module",
   "main": "./dist/cli.js",