@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/index.js

@@ -22,17 +22,13 @@ import { exec } from "node:child_process";
 //#endregion
 //#region src/storage/s3.ts
 /**
-* S3-backed cache storage.
+* S3-backed cache storage; AWS SDK v3 modules load only when S3 storage is configured.
 *
-* Stores cached items in S3 with custom metadata headers for TTL tracking.
-* Uses AWS SDK v3 modular imports -- only loaded when S3 storage is configured.
-*
-* Metadata storage:
+* TTL metadata headers:
 *   x-amz-meta-created-at      -- ISO timestamp of creation
 *   x-amz-meta-last-accessed-at -- ISO timestamp of last access
 *
 * TTL is enforced lazily: expired items are deleted on access.
-* Pre-signed URLs are generated for getUrl() with 15-minute expiry.
 */
 const logger$5 = createLogger({ prefix: "s3-cache" });
 /** Pre-signed download URL expiry in seconds (15 minutes) */
@@ -41,17 +37,14 @@ const PRESIGNED_URL_EXPIRY_SECONDS = 900;
 const UPLOAD_URL_EXPIRY_SECONDS = 1800;
 var S3CacheStorage = class {
 	client;
-	/** Separate client for pre-signed URL generation (uses externalEndpoint if configured). */
+	/** Pre-signing client: externalEndpoint when configured. */
 	presignClient;
 	/** Client for the developer upload URL: uploadEndpoint, else the presign client. */
 	uploadPresignClient;
 	bucket;
 	prefix;
 	ttlMs;
-	/**
-	* False once the backend answered a conditional self-copy with
-	* `501 NotImplemented`. From then on `updateMeta` copies unconditionally.
-	*/
+	/** False once the backend answered a conditional self-copy with `501 NotImplemented`. */
 	conditionalCopySupported = true;
 	constructor(options) {
 		this.bucket = options.bucket;
@@ -68,7 +61,6 @@ var S3CacheStorage = class {
 			endpoint: options.uploadEndpoint
 		}) : this.presignClient;
 	}
-	/** Build the full S3 object key from a cache key. */
 	objectKey(key) {
 		return `${this.prefix}${key}`;
 	}
@@ -78,17 +70,11 @@ var S3CacheStorage = class {
 		const lastAccessed = new Date(meta.lastAccessedAt).getTime();
 		return Date.now() - lastAccessed > ttl;
 	}
-	/**
-	* Read metadata from an S3 object's custom headers.
-	* Returns null if the object doesn't exist (NoSuchKey/NotFound).
-	*/
+	/** Null when the object does not exist (NoSuchKey/NotFound). */
 	async readMeta(key) {
 		return (await this.readHead(key))?.meta ?? null;
 	}
-	/**
-	* Read an object's TTL metadata together with the ETag of the version it
-	* belongs to. Returns null if the object doesn't exist (NoSuchKey/NotFound).
-	*/
+	/** TTL metadata plus the ETag of its version; null when the object does not exist. */
 	async readHead(key) {
 		try {
 			const head = await this.client.send(new HeadObjectCommand({
@@ -111,25 +97,16 @@ var S3CacheStorage = class {
 		}
 	}
 	/**
-	* Update metadata on an S3 object by copying it to itself.
-	* This is the standard S3 pattern for updating metadata without re-uploading data.
-	*
-	* The copy is conditional on `etag`, the version whose metadata the caller
-	* read. A self-copy is a whole-object write: without the condition, one that
-	* races a `put()` of the same key can land after it and write the older body
-	* back. Cache pointers are rewritten in place while builds publish them, so a
-	* touch-on-read racing a publish reverted the pointer to a tarball that no
-	* longer exists. `CopySourceIfMatch` pins the bytes copied to that version and
-	* `IfMatch` refuses the write unless the key still holds it.
+	* Updates metadata by self-copy, conditional on `etag` (the version the caller read). A
+	* self-copy is a whole-object write: unconditioned, one racing a `put()` of the key can write
+	* the older body back, reverting a cache pointer to a deleted tarball. `CopySourceIfMatch`
+	* pins the copied bytes; `IfMatch` refuses the write unless the key still holds that version.
 	*
-	* Returns false when the object was replaced since the read (`412`), or is
-	* being replaced right now (`409 ConditionalRequestConflict`): the newer
-	* write stamps metadata of its own, so there is nothing left to refresh.
+	* Returns false when the object was replaced since the read (`412`) or is being replaced
+	* (`409 ConditionalRequestConflict`): the newer write stamps its own metadata.
 	*
-	* An S3-compatible backend that does not implement conditional copies
-	* answers `501 NotImplemented`. The copy then runs again without the
-	* condition, and later copies skip it, as on a backend that ignores the
-	* headers.
+	* A backend without conditional copies answers `501 NotImplemented`; the copy reruns
+	* unconditionally, and later copies skip the condition.
 	*/
 	async updateMeta(key, meta, etag) {
 		const condition = this.conditionalCopySupported ? etag : void 0;
@@ -164,15 +141,15 @@ var S3CacheStorage = class {
 			}
 		}));
 	}
-	/** Check if an error is a failed conditional request (PreconditionFailed, 412). */
+	/** A failed conditional request (PreconditionFailed, 412). */
 	isPreconditionFailedError(err) {
 		return this.hasErrorShape(err, "PreconditionFailed", 412);
 	}
-	/** Check if an error is a conditional write that raced another write (ConditionalRequestConflict, 409). */
+	/** A conditional write that raced another write (ConditionalRequestConflict, 409). */
 	isConditionalConflictError(err) {
 		return this.hasErrorShape(err, "ConditionalRequestConflict", 409);
 	}
-	/** Check if an error is a request the backend does not implement (NotImplemented, 501). */
+	/** A request the backend does not implement (NotImplemented, 501). */
 	isNotImplementedError(err) {
 		return this.hasErrorShape(err, "NotImplemented", 501);
 	}
@@ -181,7 +158,7 @@ var S3CacheStorage = class {
 		if (err.name === name) return true;
 		return err.$metadata?.httpStatusCode === status;
 	}
-	/** Check if an error is a "not found" error (NoSuchKey, NotFound, 404). */
+	/** NoSuchKey, NotFound or 404. */
 	isNotFoundError(err) {
 		if (typeof err !== "object" || err === null) return false;
 		const name = err.name;
@@ -359,30 +336,21 @@ var S3CacheStorage = class {
 //#endregion
 //#region src/storage/sign-url.ts
 /**
-* HMAC-signed URL tokens for the filesystem cache backend.
-*
-* Pre-signed S3 URLs are not available for filesystem storage, so the
-* filesystem backend mints HMAC-SHA256 tokens that the orchestrator's HTTP
-* blob route verifies before serving / writing a file. Token shape:
+* HMAC-SHA256 URL tokens for the filesystem cache backend (which has no pre-signed S3 URLs);
+* the blob route verifies them before serving / writing a file. Token shape:
 *
 *   `${expiresUnixMs}.${hexSig}`
 *
-* Signature input: `${method}:${key}:${expiresUnixMs}` with HMAC-SHA256 keyed
-* by a per-orchestrator-process secret (random 32-byte hex at boot, persists
-* for the lifetime of the process). Tokens become invalid on orchestrator
-* restart — fine for the filesystem backend's single-host / test-sandbox use
-* case.
+* Signs `${method}:${key}:${expiresUnixMs}` with a per-process secret (random 32 bytes at
+* boot), so tokens die on orchestrator restart — fine for single-host / test-sandbox use.
 */
-/** Default URL lifetime: 1 hour (matches S3 backend's PUT-URL lifetime). */
+/** Default URL lifetime: 1 hour. */
 const DEFAULT_SIGN_URL_TTL_MS = 36e5;
 function computeSig(secret, method, key, expiresMs) {
 	const hmac = createHmac("sha256", secret);
 	hmac.update(`${method}:${key}:${expiresMs}`);
 	return hmac.digest("hex");
 }
-/**
-* Mint a signed token for the given (method, key, expiry) triple.
-*/
 function signToken(secret, method, key, ttlMs = DEFAULT_SIGN_URL_TTL_MS) {
 	const expiresMs = Date.now() + ttlMs;
 	return {
@@ -393,19 +361,15 @@ function signToken(secret, method, key, ttlMs = DEFAULT_SIGN_URL_TTL_MS) {
 //#endregion
 //#region src/storage/filesystem.ts
 /**
-* Filesystem-backed cache storage.
-*
-* Mirrors the `CacheStorage` interface that `S3CacheStorage` provides, but
-* stores blobs as files under a configured base directory. Pre-signed URLs
-* are replaced by HMAC-signed `http://<orchUrl>/api/v1/cache/blob/...` URLs
-* — see `sign-url.ts` for the token mechanics and `app.ts` for the route.
+* Filesystem-backed `CacheStorage`, the counterpart of `S3CacheStorage`, for
+* single-host deployments and test sandboxes. Production should still use S3.
 *
-* Intended for single-host deployments and test sandboxes where standing up
-* an S3-compatible service is overkill. Production should still use S3.
+* Pre-signed URLs become HMAC-signed `http://<orchUrl>/api/v1/cache/blob/...`
+* URLs (token mechanics: `sign-url.ts`; route: `app.ts`).
 *
-* Metadata is co-located as a sibling JSON file (`<key>.meta.json`) so the
-* data file is byte-identical to what the agent receives over HTTP. TTL is
-* enforced lazily on access — same model as the S3 backend.
+* Metadata sits in a sibling `<key>.meta.json`, so the data file is
+* byte-identical to what the agent receives over HTTP. TTL is enforced lazily
+* on access, as in the S3 backend.
 */
 const DEFAULT_ROUTE_PREFIX = "/api/v1/cache/blob/";
 var FilesystemCacheStorage = class {
@@ -422,9 +386,9 @@ var FilesystemCacheStorage = class {
 		this.routePrefix = (options.routePrefix ?? DEFAULT_ROUTE_PREFIX).replace(/\/?$/, "/");
 	}
 	/**
-	* Map a cache key to its on-disk path. Keys may contain `/`, which becomes a
-	* directory separator. Reject keys containing `..` segments or NUL bytes to
-	* prevent path traversal — the same defence the route layer enforces too.
+	* Map a cache key to its on-disk path (`/` becomes a directory separator).
+	* Rejects `..` segments and NUL bytes against path traversal, as the route
+	* layer also does.
 	*/
 	resolvePath(key) {
 		if (key.includes("\0") || key.split("/").some((seg) => seg === ".." || seg === "")) throw new Error(`Invalid cache key: ${JSON.stringify(key)}`);
@@ -534,19 +498,14 @@ var FilesystemCacheStorage = class {
 		});
 	}
 	/**
-	* List cache keys under a prefix.
-	*
-	* The prefix is a **key prefix**, not necessarily a directory — `UserCache`'s
-	* `restoreKeys` fallback lists on `${prefix}${seg(restoreKey)}`, a partial
-	* object name. Two shapes, and both must work the way the S3 backend does:
+	* List cache keys under a **key prefix**, which need not be a directory:
+	* `UserCache`'s `restoreKeys` fallback lists on `${prefix}${seg(restoreKey)}`,
+	* a partial object name. Both shapes must behave as on S3:
 	*
 	* - trailing `/` — a directory. Walk it directly; this is the hot path.
-	* - no trailing `/` — a partial name. Walk the parent directory and filter by
-	*   the prefix, since the prefix itself may name a file (or nothing at all).
-	*
-	* Reading the prefix as a directory in the second case is what made the
-	* `restoreKeys` fallback silently never hit here (`ENOENT` → `[]`) or throw
-	* (`ENOTDIR`, when a real object carried that exact name).
+	* - no trailing `/` — a partial name. Walk the parent and filter by the
+	*   prefix, which may name a file or nothing at all. Reading it as a
+	*   directory made `restoreKeys` never hit (`ENOENT`) or throw (`ENOTDIR`).
 	*/
 	async list(subPrefix) {
 		const isDirPrefix = subPrefix.endsWith("/");
@@ -587,10 +546,9 @@ var FilesystemCacheStorage = class {
 		});
 	}
 	/**
-	* Recursively collect data files under `dir`, returning each as a cache key
-	* relative to `basePath` paired with its mtime. Metadata sidecars
-	* (`*.meta.json`) and the atomic-write temp files (`*.tmp-*`) are skipped so
-	* `list()` only surfaces real cache objects.
+	* Recursively collect data files under `dir` as `basePath`-relative keys with
+	* their mtime, skipping `*.meta.json` sidecars and `*.tmp-*` atomic-write
+	* temp files so `list()` surfaces only real cache objects.
 	*/
 	async walkDataFiles(dir, keyPrefix) {
 		const out = [];
@@ -627,9 +585,8 @@ function isNotFoundFsError(err) {
 	return code === "ENOENT" || code === "ENOTDIR";
 }
 /**
-* Write a file atomically: write to a temp sibling, fsync, rename. Avoids
-* partial reads if the orchestrator crashes mid-write. The temp suffix is
-* randomised so concurrent writers don't collide on the same temp name.
+* Write atomically (temp sibling, fsync, rename) so a crash mid-write leaves no
+* partial file. The random temp suffix keeps concurrent writers apart.
 */
 async function writeFileAtomic(path, data) {
 	const tmp = `${path}.tmp-${randomBytes(6).toString("hex")}`;
@@ -644,9 +601,6 @@ async function writeFileAtomic(path, data) {
 }
 //#endregion
 //#region src/storage/index.ts
-/**
-* Create a cache storage backend from configuration.
-*/
 function createCacheStorage(config) {
 	if (config.type === "s3") return new S3CacheStorage({
 		bucket: config.bucket,
@@ -669,61 +623,44 @@ function createCacheStorage(config) {
 //#endregion
 //#region src/cache/source-cache.ts
 /**
-* Source-tarball cache layer wrapping CacheStorage.
-*
-* Stores customer-workflow source tarballs — the `.kici/` directory minus
-* `node_modules/`, packed by the agent's build job via `source-packer.ts` —
-* under the tarball's OWN content hash, with a small pointer resolving an org's
-* workflow `contentHash` to that hash. Tarballs are platform-independent: raw
-* TypeScript source is identical across architectures. Refreshes TTL on reads
-* (touch-on-read) so actively used sources stay in cache longer.
+* Source-tarball cache over CacheStorage: the `.kici/` directory minus
+* `node_modules/` (packed by the agent's build job via `source-packer.ts`),
+* stored under the tarball's OWN content hash, with a pointer resolving an
+* org's workflow `contentHash` to it. Tarballs are platform-independent (raw
+* TypeScript source). Reads touch the TTL so active sources stay cached.
 *
 * Keys: `source/v2/{orgId}/{sourceTarDigest}.tar.gz` (immutable) and
-* `source/v2/{orgId}/{contentHash}.hash` (the pointer) — the shape `dep-cache.ts`
-* already uses, for the same reasons — content addressing and org scoping.
-*
-* **Content addressing** makes a mismatched pair unrepresentable. At
-* `source/{contentHash}.tar.gz` the object's key was derived from something
-* other than its bytes, so nothing a reader fetched could be verified against
-* anything, and the agent restored whatever the signed URL returned.
+* `source/v2/{orgId}/{contentHash}.hash` (the pointer) — the `dep-cache.ts`
+* shape, for the same reasons:
 *
-* **Org scoping** makes the key a tenant's key. `contentHash` alone is a
-* property of a `.kici/` tree, so two repositories scaffolded from the same
-* `kici init` template — or a fork and its upstream — produced one object, and
-* whichever built first won for the life of that object. On an orchestrator
-* serving more than one org that is a cross-tenant read of `.kici/` contents.
-* The org is the tenant boundary and the segment the user cache already scopes
-* by; inside one org, sharing a key now means the two trees are byte-identical,
-* so a monorepo or a same-org fork keeps its warm cache and pays nothing.
+* - **Content addressing** makes a mismatched pair unrepresentable: a key not
+*   derived from the bytes lets nothing a reader fetches be verified.
+* - **Org scoping** makes the key a tenant's key. `contentHash` alone is a
+*   property of a `.kici/` tree, so two repositories from the same `kici init`
+*   template, or a fork and its upstream, would share one object — a
+*   cross-tenant read on a multi-org orchestrator. The org is the tenant
+*   boundary the user cache scopes by too; within one org a shared key means
+*   byte-identical trees, so a monorepo or same-org fork keeps its warm cache.
 *
-* Legacy `source/{contentHash}.tar.gz` objects are **not read**. Only a
-* `compileSchemaVersion: 5` lock can name one, and that `contentHash` covers
-* the workflow entry file alone rather than the tree the tarball holds — the
-* defect this layout closes — so serving it would serve the bug. For a v6 lock
-* the fallback is unreachable anyway, since the schema bump moves every hash.
-* Old objects are orphaned. The cache TTL is enforced lazily on access, so
-* nothing here removes them.
+* Retired `source/{contentHash}.tar.gz` objects are **not read**: only a
+* `compileSchemaVersion: 5` lock names one, and its `contentHash` covers the
+* entry file alone rather than the packed tree, so serving it would serve the
+* bug. A v6 lock cannot reach it (the bump moves every hash). The lazy TTL never
+* removes them (docs/operator/orchestrator/storage-layout.md § "Retired layouts").
 */
 const logger$4 = createLogger({ prefix: "source-cache" });
 /**
-* Cache key for a source tarball, addressed by the tarball's OWN content hash:
-* `source/v2/{orgId}/{sourceTarDigest}.tar.gz`.
-*
-* Naming the object by its own hash means every pair a reader can observe is
-* self-consistent, and the bytes at a given key can never change after a URL is
-* signed for it.
+* Named by its own hash, so every pair a reader observes is self-consistent and
+* the bytes at a key never change after a URL is signed for it.
 */
 function sourceTarballKey(orgId, sourceTarDigest) {
 	return `source/v2/${orgId}/${sourceTarDigest}.tar.gz`;
 }
 /**
-* Cache key for the pointer that resolves a workflow `contentHash` to the
-* content hash of the tarball built from it: `source/v2/{orgId}/{contentHash}.hash`.
-*
-* This is the one mutable object in the scheme. A concurrent write replaces a
-* pointer wholesale — there is no half-written window — so the worst a racing
-* pair of builders can do is leave whichever pointer landed last, and both
-* tarballs stay valid and fetchable.
+* The pointer from a workflow `contentHash` to its tarball's hash: the one
+* mutable object. A write replaces it wholesale (no half-written window), so
+* racing builders at worst leave the last-landed pointer, and both tarballs
+* stay valid and fetchable.
 */
 function sourcePointerKey(orgId, contentHash) {
 	return `source/v2/${orgId}/${contentHash}.hash`;
@@ -733,16 +670,13 @@ var SourceCache = class SourceCache {
 	constructor(options) {
 		this.storage = options.storage;
 	}
-	/** The single place the pointer indirection is read. */
+	/** Resolves the pointer indirection (`getUrlAndDigest` reads it inline to touch it). */
 	async resolvePointer(orgId, contentHash) {
 		return (await this.storage.get(sourcePointerKey(orgId, contentHash)))?.toString("utf-8").trim() || null;
 	}
 	/**
-	* Whether a source tarball for this org's `contentHash` exists.
-	*
-	* Both halves must be present: a pointer whose tarball has aged out is a
-	* miss, not a hit, or the caller skips a rebuild and dispatches a URL that
-	* 404s on the agent.
+	* Both halves must exist: a pointer whose tarball aged out is a miss, or the
+	* caller skips a rebuild and dispatches a URL that 404s on the agent.
 	*/
 	async has(orgId, contentHash) {
 		const digest = await this.resolvePointer(orgId, contentHash);
@@ -769,13 +703,9 @@ var SourceCache = class SourceCache {
 		return data;
 	}
 	/**
-	* A pre-signed download URL and the tarball's own digest.
-	*
-	* The pointer is resolved FIRST: it names the content hash, which is also the
-	* tarball's key, so the url and the digest returned here are read from a
-	* single source of truth and cannot disagree. Returns null on a miss —
-	* including a pointer with no tarball behind it, which is unverifiable and so
-	* is deliberately not served.
+	* A pre-signed download URL and the tarball's own digest. The pointer is
+	* resolved FIRST and names both, so url and digest cannot disagree. Null on a
+	* miss, including a pointer with no tarball (unverifiable, so not served).
 	*/
 	async getUrlAndDigest(orgId, contentHash) {
 		const pointerKey = sourcePointerKey(orgId, contentHash);
@@ -802,19 +732,15 @@ var SourceCache = class SourceCache {
 		return (await this.getUrlAndDigest(orgId, contentHash))?.url ?? null;
 	}
 	/**
-	* A pre-signed upload URL for direct agent-to-storage upload.
-	*
-	* Takes the tarball's OWN digest, not the workflow `contentHash`: the agent
-	* computes it before asking for a URL, and the object is named by it.
+	* A pre-signed agent-to-storage upload URL, keyed by the tarball's OWN digest
+	* (which the agent computes first), not the workflow `contentHash`.
 	*/
 	async getUploadUrl(orgId, sourceTarDigest) {
 		return this.storage.getUploadUrl(sourceTarballKey(orgId, sourceTarDigest));
 	}
 	/**
-	* Publish the pointer that makes an uploaded tarball discoverable by
-	* `contentHash`. Called only after the agent confirms its upload completed —
-	* publishing before the bytes land would let a reader follow the pointer to a
-	* missing object.
+	* Publish the pointer to an uploaded tarball. Called only after the agent
+	* confirms the upload, or a reader could follow it to a missing object.
 	*/
 	async publishPointer(orgId, contentHash, sourceTarDigest) {
 		await this.storage.put(sourcePointerKey(orgId, contentHash), sourceTarDigest);
@@ -835,7 +761,6 @@ var SourceCache = class SourceCache {
 	static computeDigest(data) {
 		return sha256(data);
 	}
-	/** Remove a source tarball and its pointer. */
 	async remove(orgId, contentHash) {
 		const digest = await this.resolvePointer(orgId, contentHash);
 		await this.storage.delete(sourcePointerKey(orgId, contentHash));
@@ -847,12 +772,9 @@ var SourceCache = class SourceCache {
 //#endregion
 //#region src/cache/dep-cache.ts
 /**
-* Dependency-specific cache layer wrapping CacheStorage.
-*
-* Stores dependency tarballs under their own content hash, with a small pointer
-* resolving lockfileHash + platform + arch to that hash. Shared CacheStorage
-* backend with SourceCache (same S3 bucket). Refreshes TTL on reads
-* (touch-on-read).
+* Dependency cache over CacheStorage (the same S3 bucket as SourceCache).
+* Tarballs live under their own content hash, with a small pointer resolving
+* lockfileHash + platform + arch to it. Reads refresh TTL (touch-on-read).
 *
 * Keys: `deps/{platform}-{arch}/{depsHash}.tar.gz` (immutable) and
 * `deps/{platform}-{arch}/{lockfileHash}.hash` (the pointer).
@@ -864,17 +786,14 @@ const DEFAULT_MAX_TARBALL_BYTES = 524288e3;
 const DEFAULT_CACHE_TTL_DAYS = 30;
 const MS_PER_DAY = 864e5;
 /**
-* Cache key for a dependency tarball, addressed by the tarball's OWN content
-* hash: `deps/{platform}-{arch}/{depsHash}.tar.gz`.
+* Cache key for a dependency tarball, addressed by its OWN content hash:
+* `deps/{platform}-{arch}/{depsHash}.tar.gz`.
 *
-* Content-addressing is what makes a mismatched pair unrepresentable. When the
-* tarball lived at a lockfile-derived name, it and its companion `.hash` were
-* two independently-written objects under keys that any two builds sharing a
-* lockfile + platform + arch also share — so concurrent builders could leave the
-* `.tar.gz` from one and the `.hash` from the other, and the reader failed
-* verification durably. Naming the object by its own hash means every pair a
-* reader can observe is self-consistent, and the bytes at a given key can never
-* change after a URL is signed for it.
+* Content-addressing makes a mismatched pair unrepresentable. Under a
+* lockfile-derived name, concurrent builders sharing lockfile + platform + arch
+* could leave one's `.tar.gz` and the other's `.hash`, and the reader failed
+* verification durably. Named by its own hash, every observable pair is
+* self-consistent and a key's bytes never change after a URL is signed for it.
 */
 function depTarballKey(depsHash, platform, arch) {
 	return `deps/${platform}-${arch}/${depsHash}.tar.gz`;
@@ -884,17 +803,14 @@ function depTarballKey(depsHash, platform, arch) {
 * tarball built from it: `deps/{platform}-{arch}/{lockfileHash}.hash`, or
 * `…/{lockfileHash}-{siblingsDigest}.hash` when the lock carries one.
 *
-* `siblingsDigest` is part of the key because the deps tarball carries in-repo
-* `workspace:` sibling directories WITH their built output, and editing a
-* sibling's source moves no package-manager lock file — so a `lockfileHash`-only
-* key restored the sibling's stale build over the fresh clone on every run. A
-* lock with no in-repo sibling carries no digest and keys exactly as before, so
-* existing pointers stay live.
+* `siblingsDigest` is keyed because the tarball carries in-repo `workspace:`
+* siblings WITH their built output, and editing a sibling moves no lock file —
+* a `lockfileHash`-only key restored a stale sibling build over the fresh clone.
+* A lock with no in-repo sibling carries no digest, so existing pointers stay live.
 *
-* This is the one mutable object in the scheme. A concurrent write replaces a
-* pointer wholesale — there is no window in which it is half-written — so the
-* worst a racing pair of builders can do is leave whichever pointer landed last,
-* and both tarballs remain valid and fetchable.
+* The one mutable object in the scheme. A write replaces the pointer wholesale
+* (never half-written), so racing builders at worst leave whichever landed
+* last, and both tarballs stay valid and fetchable.
 */
 function depPointerKey(lockfileHash, platform, arch, siblingsDigest) {
 	return `deps/${platform}-${arch}/${siblingsDigest ? `${lockfileHash}-${siblingsDigest}` : lockfileHash}.hash`;
@@ -911,28 +827,21 @@ var DepCache = class DepCache {
 		this.clusterSettings = options.clusterSettings;
 	}
 	/**
-	* Resolve the live dependency-cache entry TTL as a per-operation override
-	* (ms) from `cluster_settings.cache_ttl_days`, falling back to the cluster
-	* default. `undefined` when no reader is wired, so the storage backend uses
-	* its own configured TTL. Passed to read/expiry operations so an operator's
-	* `cache_ttl_days` change takes effect on the next lookup.
+	* Per-operation TTL override (ms) from `cluster_settings.cache_ttl_days`, so
+	* an operator's change takes effect on the next lookup. `undefined` when no
+	* reader is wired, so the backend uses its own configured TTL.
 	*/
 	async resolveTtlMsOverride() {
 		if (!this.clusterSettings) return void 0;
 		return await this.clusterSettings.getNumber("cache_ttl_days", this.cacheTtlDaysFallback) * MS_PER_DAY;
 	}
-	/**
-	* Resolve a lockfile to the content hash of the tarball built from it, or
-	* null when no pointer exists. The single place the indirection is read.
-	*/
+	/** Lockfile → tarball content hash, or null when no pointer exists. */
 	async resolvePointer(lockfileHash, platform, arch, ttlMsOverride, siblingsDigest) {
 		return (await this.storage.get(depPointerKey(lockfileHash, platform, arch, siblingsDigest), ttlMsOverride))?.toString("utf-8").trim() || null;
 	}
 	/**
-	* Check if a dep tarball exists in cache.
-	*
-	* Both halves must be present: a pointer whose tarball has aged out is a miss,
-	* not a hit, or the caller skips a rebuild and dispatches a URL that 404s.
+	* Both halves must be present: a pointer whose tarball aged out is a miss, or
+	* the caller skips a rebuild and dispatches a URL that 404s.
 	*/
 	async has(lockfileHash, platform, arch, siblingsDigest) {
 		const ttlMsOverride = await this.resolveTtlMsOverride();
@@ -951,18 +860,13 @@ var DepCache = class DepCache {
 		});
 		return exists;
 	}
-	/**
-	* Get a pre-signed download URL for the dep tarball (for agent delivery).
-	* Refreshes TTL on hit.
-	*/
+	/** Pre-signed download URL for agent delivery. Refreshes TTL on hit. */
 	async getUrl(lockfileHash, platform, arch, siblingsDigest) {
 		return (await this.getUrlAndHash(lockfileHash, platform, arch, siblingsDigest))?.url ?? null;
 	}
 	/**
-	* Get a pre-signed download URL and the tarball content hash.
-	*
-	* Returns null on cache miss — including an entry with no pointer, which is
-	* unverifiable and so is deliberately not served.
+	* Pre-signed download URL plus tarball content hash; null on a miss,
+	* including an entry with no pointer (unverifiable, so never served).
 	*/
 	async getUrlAndHash(lockfileHash, platform, arch, siblingsDigest) {
 		const ttlMsOverride = await this.resolveTtlMsOverride();
@@ -996,17 +900,13 @@ var DepCache = class DepCache {
 			hash
 		};
 	}
-	/**
-	* Get a pre-signed upload URL for direct agent-to-S3 upload.
-	*/
+	/** Pre-signed URL for direct agent-to-S3 upload. */
 	async getUploadUrl(depsHash, platform, arch) {
 		return this.storage.getUploadUrl(depTarballKey(depsHash, platform, arch));
 	}
 	/**
-	* Publish the pointer that makes an uploaded tarball discoverable by lockfile.
-	*
-	* Called only after the agent confirms its upload completed. Publishing before
-	* the bytes land would let a reader follow the pointer to a missing object.
+	* Make an uploaded tarball discoverable by lockfile. Called only after the
+	* agent confirms its upload, or a reader could follow the pointer to nothing.
 	*/
 	async publishPointer(lockfileHash, platform, arch, depsHash, siblingsDigest) {
 		await this.storage.put(depPointerKey(lockfileHash, platform, arch, siblingsDigest), depsHash);
@@ -1015,10 +915,7 @@ var DepCache = class DepCache {
 			arch
 		});
 	}
-	/**
-	* Store a dep tarball in cache.
-	* Throws if tarball exceeds max size (per user decision).
-	*/
+	/** Throws when the tarball exceeds the max size. */
 	async store(lockfileHash, platform, arch, tarballData) {
 		const maxTarballBytes = this.clusterSettings ? await this.clusterSettings.getNumber("cache_max_tarball_bytes", this.maxTarballBytes) : this.maxTarballBytes;
 		if (tarballData.length > maxTarballBytes) throw new Error(`Dep tarball exceeds max size: ${tarballData.length} bytes > ${maxTarballBytes} bytes limit`);
@@ -1033,8 +930,8 @@ var DepCache = class DepCache {
 		});
 	}
 	/**
-	* Compute SHA-256 hash of a tarball buffer.
-	* Used by build agents to compute the hash for depsHash protocol field.
+	* Compute SHA-256 hash of a tarball buffer: the `depsHash` that `store()`
+	* keys and logs the tarball under.
 	*/
 	static computeHash(data) {
 		return sha256(data);
@@ -1054,10 +951,9 @@ var DepCache = class DepCache {
 /**
 * A collision-resistant discriminator for a user-supplied object-key segment.
 *
-* Hashes the **exact** name, before any sanitization. Sanitizing is many-to-one
-* — `seg()` maps both `/` and `_` to `_`, so `a/b` and `a_b` collapse to one
-* segment — and a case-insensitive backend folds `build` onto `Build`. Hashing
-* the pre-sanitization name is what keeps each of those pairs two objects.
+* Hashes the **exact** pre-sanitization name: `seg()` maps both `/` and `_` to
+* `_` (`a/b` and `a_b` collapse), and a case-insensitive backend folds `build`
+* onto `Build`, so only the hash keeps each pair two objects.
 */
 function keyDiscriminator(exact) {
 	return createHash("sha256").update(exact, "utf8").digest("hex").slice(0, 32);
@@ -1068,47 +964,40 @@ function keyDiscriminator(exact) {
 * User-facing cache layer wrapping CacheStorage.
 *
 * Namespacing: `cache/<orgId>/<repoId>/<refScope>/<key>-<discriminator>.tar.gz`.
-* The discriminator is a hash of the exact cache key, so two keys differing
-* only by case stay two objects even on a case-insensitive store. `refScope`
-* is `shared` for trusted refs (org-shared, default-branch cache)
-* or `iso/<runId>` for untrusted refs (per-run isolated scope). Restores from
-* an untrusted ref read the shared scope as a fallback but writes can NEVER
-* land in the shared scope — the GitHub Actions cache-isolation model. Keyed
-* strictly per org so no tenant can read another tenant's cache.
+* The discriminator is a hash of the exact cache key, so keys differing only by
+* case stay two objects on a case-insensitive store. `refScope` is `shared` for
+* trusted refs (org-shared, default-branch cache) or `iso/<runId>` for
+* untrusted refs. An untrusted ref reads the shared scope as a fallback but can
+* NEVER write it — the GitHub Actions cache-isolation model. Keyed strictly per
+* org so no tenant can read another tenant's cache.
 *
-* Saves are immutable (first save under an exact key wins) and atomic
-* (upload to a `.tmp-<uuid>` key, then server-side copy to the final key and
-* delete the temp), so a crashed save never leaves a corrupt final entry.
+* Saves are immutable (first save under an exact key wins) and atomic (upload
+* to `.tmp-<uuid>`, server-side copy to the final key, delete the temp), so a
+* crashed save never leaves a corrupt final entry.
 *
-* Eviction: per-org byte quota plus the TTL the backing CacheStorage already
-* enforces lazily on access. On a save that pushes the org over quota,
-* least-recently-used entries (oldest `lastAccessedAt`, read from the storage
-* backend's metadata) are evicted until under quota; each eviction is logged.
-* The companion `.hash` / `.size` sidecar objects carry the integrity
-* hash and size accounting outside the tarball's own (presigned, metadata-less)
-* upload.
+* Eviction: per-org byte quota plus the TTL the backing CacheStorage enforces
+* lazily on access. A save that pushes the org over quota evicts LRU entries
+* (oldest `lastAccessedAt` from backend metadata) until under quota, logging
+* each. The `.hash` / `.size` sidecars carry the integrity hash and size
+* accounting outside the presigned, metadata-less tarball upload.
 */
 const logger$2 = createLogger({ prefix: "user-cache" });
 /**
-* Cluster-wide default quota: 5 GiB. Serves as the fallback when an org has no
-* per-org override in `org_settings.user_cache_quota_bytes`. The cluster-wide
-* value is itself operator-configurable via KICI_USER_CACHE_QUOTA_BYTES.
+* Cluster-wide default quota: 5 GiB, used when an org has no
+* `org_settings.user_cache_quota_bytes` override. Operator-configurable via
+* KICI_USER_CACHE_QUOTA_BYTES.
 */
 const DEFAULT_USER_CACHE_QUOTA_BYTES = 5368709120;
 /**
-* Cluster-wide default entry TTL: 7 days. Fallback when an org has no per-org
-* override in `org_settings.user_cache_ttl_ms`. The cluster-wide value is
-* operator-configurable via KICI_USER_CACHE_TTL_MS.
+* Cluster-wide default entry TTL: 7 days, used when an org has no
+* `org_settings.user_cache_ttl_ms` override. Operator-configurable via
+* KICI_USER_CACHE_TTL_MS.
 */
 const DEFAULT_USER_CACHE_TTL_MS = 6048e5;
 /** Tarball suffix for committed cache entries. */
 const TAR_SUFFIX = ".tar.gz";
-/**
-* Stem prefix of an in-flight upload, `.tmp-<uuid>.tar.gz`: the presigned PUT
-* target a save lands on before commit copies it to its final key.
-*/
+/** Stem of an in-flight upload, `.tmp-<uuid>.tar.gz`, before commit copies it to its final key. */
 const TEMP_UPLOAD_STEM = ".tmp-";
-/** Whether a listed object is an in-flight upload rather than a cache entry. */
 function isTempUpload(key) {
 	return key.slice(key.lastIndexOf("/") + 1).startsWith(TEMP_UPLOAD_STEM);
 }
@@ -1116,36 +1005,28 @@ function isTempUpload(key) {
 const KEY_DISCRIMINATOR_TAIL = new RegExp(`^(.*)-([0-9a-f]{32})$`);
 /**
 * Whether a listed object is a committed entry, `<stem>-<discriminator>.tar.gz`.
-*
-* This is the filter the `restoreKeys` prefix scan applies to a listing, and it
-* is what keeps two other kinds of object out of a restore: an in-flight
-* `.tmp-<uuid>.tar.gz` upload, which is a partial tarball until commit copies
-* it to its final key, and an object under the retired un-discriminated layout,
-* which nothing writes.
+* The `restoreKeys` prefix scan filters on it, which keeps out an in-flight
+* `.tmp-` upload (a partial tarball until commit) and an object under the
+* retired un-discriminated layout, which nothing writes.
 */
 function isCommittedEntry(key) {
 	return key.endsWith(TAR_SUFFIX) && KEY_DISCRIMINATOR_TAIL.test(key.slice(0, -7));
 }
 /**
-* Recover the reported cache key from a committed entry's stem.
-*
-* The value on this path is already the sanitized, lossy form, so this only
-* needs to undo the discriminator the key format appends. A stem that itself
-* ends in a discriminator-shaped tail loses it — that affects only the string
-* reported back as `matchedKey`, never which object is served.
+* Recover the reported cache key from a committed entry's (already sanitized,
+* lossy) stem by undoing the appended discriminator. A stem that itself ends in
+* a discriminator-shaped tail loses it — that affects only the reported
+* `matchedKey`, never which object is served.
 */
 function stripKeyDiscriminator(stem) {
 	return KEY_DISCRIMINATOR_TAIL.exec(stem)?.[1] ?? stem;
 }
 /**
 * Sanitize a path segment so a key can never escape its org/repo/scope
-* namespace. Beyond stripping disallowed characters, a segment consisting
-* only of dots (`.`, `..`, …) is replaced wholesale: such a segment is a
-* dot-segment that HTTP/S3 path canonicalization collapses (`a/./b` → `a/b`,
-* `a/../b` → `b`), which both corrupts the namespace and breaks the SigV4
-* signature on a pre-signed PUT/GET. Repo identifiers like `.` (the internal
-* provider's repo id) hit exactly this case, so the all-dots guard keeps the
-* object key canonical and the namespace boundary intact.
+* namespace. An all-dots segment (`.`, `..`, …) is also rewritten: HTTP/S3
+* path canonicalization collapses it (`a/./b` → `a/b`, `a/../b` → `b`), which
+* corrupts the namespace and breaks the SigV4 signature on a pre-signed
+* PUT/GET. The internal provider's repo id `.` hits exactly this case.
 */
 function sanitizeSegment(s) {
 	const cleaned = s.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -1178,36 +1059,27 @@ function readPrefixes(ref) {
 	return [`${base}/shared/`];
 }
 /**
-* Object key for a committed cache entry.
-*
-* The trailing discriminator is a hash of the EXACT cache key, and it is what
-* keeps `build` and `Build` apart on a case-insensitive namespace — the
-* filesystem backend on a macOS or Windows host, where the two would
-* otherwise resolve to one object and a restore could return the other key's
-* tarball.
-*
-* It is deliberately a SUFFIX: `restoreByPrefix` matches `restoreKeys` by
-* string prefix, so appending leaves those semantics untouched. The only
-* parse that has to know about it is the `matchedKey` slice.
+* Object key for a committed cache entry. The trailing discriminator, a hash of
+* the EXACT cache key, keeps `build` and `Build` apart on a case-insensitive
+* namespace (the filesystem backend on macOS or Windows), where a restore could
+* otherwise return the other key's tarball. It is deliberately a SUFFIX:
+* `restoreByPrefix` matches `restoreKeys` by string prefix, so only the
+* `matchedKey` slice has to know about it.
 */
 function finalKey(prefix, key) {
 	return `${prefix}${sanitizeSegment(key)}-${keyDiscriminator(key)}${TAR_SUFFIX}`;
 }
-/**
-* The object key a committed save under `key` lands on for this ref. This is
-* the writer's own path: `beginSave` and `commitSave` address the entry
-* through it.
-*/
+/** The writer's object key for `key` under this ref, used by `beginSave` and `commitSave`. */
 function userCacheEntryKey(ref, key) {
 	return finalKey(writePrefix(ref), key);
 }
 var UserCache = class {
 	storage;
-	/** Cluster-wide default quota (the `KICI_USER_CACHE_QUOTA_BYTES` value). */
+	/** `KICI_USER_CACHE_QUOTA_BYTES`. */
 	defaultQuotaBytes;
-	/** Cluster-wide default TTL (the `KICI_USER_CACHE_TTL_MS` value). */
+	/** `KICI_USER_CACHE_TTL_MS`. */
 	defaultTtlMs;
-	/** Optional per-org override reader; absent = always use the cluster defaults. */
+	/** Absent = always use the cluster defaults. */
 	orgLimitsReader;
 	constructor(opts) {
 		this.storage = opts.storage;
@@ -1216,10 +1088,9 @@ var UserCache = class {
 		this.orgLimitsReader = opts.orgLimitsReader;
 	}
 	/**
-	* Resolve the effective quota + TTL for an org: the per-org override from
-	* `org_settings` when present, otherwise the cluster-wide default. A reader
-	* failure falls back to the defaults (logged) — the cache must never fail a
-	* restore/save because the settings lookup hiccupped.
+	* Per-org override when present, else the cluster default. A reader failure
+	* falls back to the defaults (logged): a settings-lookup hiccup must never
+	* fail a restore/save.
 	*/
 	async resolveLimits(org) {
 		if (!this.orgLimitsReader) return {
@@ -1318,13 +1189,11 @@ var UserCache = class {
 		return (await this.storage.get(`${key}.hash`))?.toString("utf-8") || void 0;
 	}
 	/**
-	* Evict least-recently-used entries for the org until total tarball size <= the per-org quota.
-	*
-	* An in-flight `.tmp-` upload is never a candidate. A presigned PUT carries
-	* no metadata, so it would rank oldest and be reclaimed first — freeing
-	* nothing, since it has no `.size` — and the concurrent commit would then
-	* fail on its copy to the final key. Retired un-discriminated entries stay
-	* in the set: they hold accounted bytes and are evictable like any other.
+	* Evict the org's LRU entries until total tarball size <= the per-org quota.
+	* An in-flight `.tmp-` upload is never a candidate: with no metadata it would
+	* rank oldest and be reclaimed first, freeing nothing (no `.size`) and failing
+	* the concurrent commit's copy. Retired un-discriminated entries stay
+	* candidates: they hold accounted bytes.
 	*/
 	async enforceQuota(ref) {
 		const { quotaBytes } = await this.resolveLimits(ref.org);
@@ -1367,34 +1236,25 @@ var UserCache = class {
 	}
 };
 /**
-* `metadata` key set when a coordinator retires the self-issued credential its
-* previous run left behind. An operator revoke never sets it, which is how a
-* retirement is told apart from a revoke.
+* `metadata` key set when a coordinator retires its previous run's self-issued
+* credential. An operator revoke never sets it, which tells the two apart.
 */
 const RETIRED_BY_INSTANCE_KEY = "retiredByInstance";
 /** Default credential expiry: 90 days. */
 const DEFAULT_EXPIRY_DAYS = 90;
-/**
-* Database CRUD operations for peer credentials.
-* Used by the coordinator to manage credentials for all cluster members.
-*/
+/** The coordinator's DB store of every cluster member's credential. */
 var PeerCredentialStore = class {
 	db;
 	constructor(db) {
 		this.db = db;
 	}
 	/**
-	* Save a new peer credential, revoking any prior active credential for the
-	* same instanceId (the `peer_credentials_active_uniq` partial unique index
-	* permits exactly one active credential per instanceId).
+	* Save a credential, revoking the instanceId's prior active one
+	* (`peer_credentials_active_uniq` permits one active credential per instanceId).
 	*
-	* Returns `{ revokedCount }` — how many previously-active credentials this
-	* save revoked. Because a coordinator's peer-clients share one
-	* identity-scoped credential, a `revokedCount > 0` here means every sibling
-	* peer-client of `instanceId` that was authenticating with the old
-	* credential is now invalidated and will be rejected on its next proof. The
-	* caller logs this so a revoke that cascades sibling rejections is visible in
-	* the orchestrator logs.
+	* `revokedCount > 0` means every sibling peer-client of `instanceId` still on the
+	* old shared credential is rejected on its next proof; the caller logs it so a
+	* cascade of sibling rejections is visible.
 	*/
 	async save(opts) {
 		const expiryDays = opts.expiryDays ?? DEFAULT_EXPIRY_DAYS;
@@ -1421,16 +1281,12 @@ var PeerCredentialStore = class {
 			throw err;
 		}
 	}
-	/**
-	* Find a non-revoked, non-expired credential by its hash.
-	*/
+	/** Non-revoked, non-expired credential by hash. */
 	async findByCredentialHash(hash) {
 		const row = await this.db.selectFrom("peer_credentials").selectAll().where("credential_hash", "=", hash).where("revoked_at", "is", null).where("expires_at", ">", /* @__PURE__ */ new Date()).executeTakeFirst();
 		return row ? mapRow(row) : null;
 	}
-	/**
-	* Find a non-revoked, non-expired credential by instance ID.
-	*/
+	/** Newest non-revoked, non-expired credential for the instance. */
 	async findByInstanceId(instanceId) {
 		const row = await this.db.selectFrom("peer_credentials").selectAll().where("instance_id", "=", instanceId).where("revoked_at", "is", null).where("expires_at", ">", /* @__PURE__ */ new Date()).orderBy("created_at", "desc").executeTakeFirst();
 		return row ? mapRow(row) : null;
@@ -1449,10 +1305,9 @@ var PeerCredentialStore = class {
 		return row ? mapRow(row) : null;
 	}
 	/**
-	* Revoke `instanceId`'s unrevoked, self-issued row whose hash is
-	* `credentialHash`, recording who retired it. Every condition sits in the
-	* WHERE clause, so a row that changed meanwhile is left alone.
-	* Returns whether a row was retired.
+	* Revoke `instanceId`'s unrevoked self-issued row with `credentialHash`,
+	* recording who retired it. Every condition is in the WHERE clause, so a row
+	* that changed meanwhile is left alone. Returns whether a row was retired.
 	*/
 	async retireSelfIssued(opts) {
 		const marker = JSON.stringify({ [RETIRED_BY_INSTANCE_KEY]: opts.retiredByInstance });
@@ -1462,39 +1317,25 @@ var PeerCredentialStore = class {
 		}).where("instance_id", "=", opts.instanceId).where("credential_hash", "=", opts.credentialHash).where("revoked_at", "is", null).where(sql`metadata->>'issuance'`, "=", "self").executeTakeFirst();
 		return Number(result?.numUpdatedRows ?? 0n) > 0;
 	}
-	/**
-	* Update the last_seen_at timestamp for a credential.
-	* Optionally records which coordinator validated it.
-	*/
+	/** Bump last_seen_at; optionally record the validating coordinator. */
 	async updateLastSeen(credentialHash, validatedBy) {
 		const updates = { last_seen_at: /* @__PURE__ */ new Date() };
 		if (validatedBy) updates.last_validated_by = validatedBy;
 		await this.db.updateTable("peer_credentials").set(updates).where("credential_hash", "=", credentialHash).execute();
 	}
-	/**
-	* Revoke a peer's credential by instance ID.
-	*/
 	async revoke(instanceId) {
 		await this.db.updateTable("peer_credentials").set({ revoked_at: /* @__PURE__ */ new Date() }).where("instance_id", "=", instanceId).where("revoked_at", "is", null).execute();
 	}
-	/**
-	* Revoke all active credentials.
-	* @returns The number of credentials revoked.
-	*/
+	/** @returns The number of credentials revoked. */
 	async revokeAll() {
 		const result = await this.db.updateTable("peer_credentials").set({ revoked_at: /* @__PURE__ */ new Date() }).where("revoked_at", "is", null).executeTakeFirst();
 		return Number(result?.numUpdatedRows ?? 0);
 	}
-	/**
-	* List all active (non-revoked, non-expired) credentials.
-	*/
+	/** Non-revoked, non-expired credentials, oldest first. */
 	async listActive() {
 		return (await this.db.selectFrom("peer_credentials").selectAll().where("revoked_at", "is", null).where("expires_at", ">", /* @__PURE__ */ new Date()).orderBy("created_at", "asc").execute()).map(mapRow);
 	}
 };
-/**
-* Map a database row to a PeerCredential interface.
-*/
 function mapRow(row) {
 	return {
 		id: row.id,
@@ -1511,15 +1352,7 @@ function mapRow(row) {
 		metadata: row.metadata ?? {}
 	};
 }
-/**
-* Write credential data to a JSON file with restrictive permissions.
-*
-* Creates the parent directory (e.g., ~/.kici/) with 0700 if it doesn't exist.
-* The credential file is written with 0600 permissions (owner read/write only).
-*
-* @param filePath - Absolute path to the credential file
-* @param data - Credential data to persist
-*/
+/** Write the credential file 0600, creating its parent directory 0700 if missing. */
 async function writeCredentialFile(filePath, data) {
 	const dir = dirname(filePath);
 	await mkdir(dir, {
@@ -1530,12 +1363,7 @@ async function writeCredentialFile(filePath, data) {
 	await writeFile(filePath, json, { mode: 384 });
 	await chmod(filePath, 384);
 }
-/**
-* Read credential data from a JSON file.
-*
-* @param filePath - Absolute path to the credential file
-* @returns Parsed credential data, or null if the file doesn't exist
-*/
+/** @returns The parsed credential file, or null if it does not exist. */
 async function readCredentialFile(filePath) {
 	try {
 		const content = await readFile(filePath, "utf-8");
@@ -1546,13 +1374,9 @@ async function readCredentialFile(filePath) {
 	}
 }
 /**
-* Construct a PeerCredentialStore bound to a Postgres URL, returning the
-* store plus a disposer that closes the underlying pool. Lets tests
-* exercise the real Kysely-backed store without importing pg/kysely.
-*
-* Intended for tests of the store's own CRUD methods — production
-* code constructs the store with an already-allocated Kysely instance
-* shared with the orchestrator.
+* A store bound to a Postgres URL plus a pool disposer, so tests exercise the real
+* store without importing pg/kysely. Test-only: production passes the
+* orchestrator's shared Kysely instance.
 */
 async function createPeerCredentialStoreFromUrl(databaseUrl, opts) {
 	const pool = new pg.Pool({
@@ -1609,22 +1433,19 @@ createLogger({ prefix: "coordinator-credential" });
 /**
 * Per-orchestrator coordinator that owns the shared peer credential file.
 *
-* A single orchestrator runs N peer-clients (one per cluster peer) that all
-* share one identity-scoped credential file. Left uncoordinated, a reconnect
-* storm makes each sibling independently token-join (each join revokes the
-* prior credential, invalidating the others) and delete the shared file on any
-* rejection — a credential revocation cascade. This coordinator serializes all
-* file access through one in-process mutex so only one peer-client token-joins
-* per storm, and it never deletes a credential file a sibling has refreshed.
+* An orchestrator's peer-clients (one per peer) share one identity-scoped
+* credential file. Uncoordinated, a reconnect storm makes each sibling token-join
+* (each join revokes the prior credential, invalidating the others) and delete the
+* shared file on any rejection — a revocation cascade. One in-process mutex
+* serializes all file access, so one peer-client token-joins per storm, and a file
+* a sibling has refreshed is never deleted.
 *
-* A coordinator without a join token also wires a `selfIssue` callback. When a
-* decision finds no credential and no token, the callback issues the
-* coordinator its own credential, once per storm, under the same mutex.
+* A coordinator without a join token wires `selfIssue`: with no credential and no
+* token, it issues its own credential, once per storm, under the same mutex.
 *
-* A coordinator also wires `corroborateRejection`. Any dialled endpoint can
-* send a rejection, so before it deletes the file the coordinator asks its own
-* cluster database: a credential the database holds as valid, or a database it
-* cannot read, keeps the file.
+* A coordinator also wires `corroborateRejection`. Any dialled endpoint can send a
+* rejection, so before deleting the file it asks its own cluster database: a
+* credential the database holds as valid, or an unreadable database, keeps the file.
 */
 const logger = createLogger({ prefix: "peer-auth-coordinator" });
 /** How long a waiting peer-client awaits an in-flight sibling token-join. */
@@ -1860,10 +1681,7 @@ var JoinTokenManager = class {
 	constructor(deps) {
 		this.deps = deps;
 	}
-	/**
-	* Create a new join token.
-	* Returns the full token string (only available at creation time).
-	*/
+	/** Returns the full token string, available only at creation time. */
 	async createToken(opts) {
 		const expiryMs = opts.expiryMs ?? DEFAULT_EXPIRY_MS;
 		const expiry = Date.now() + Math.floor(expiryMs);
@@ -1896,12 +1714,11 @@ var JoinTokenManager = class {
 	* Peer token mode: claim the row the presented token's secret hashes to. Role and
 	* routing come from the row (`claimByHash`), never from the token's routing part.
 	*
-	* Self-healing reuse: a join token is re-consumable by the same joining peer
-	* (`peerInstanceId`) until its `expires_at`. A peer that lost its credential
-	* re-presents the still-valid join token already in its env, and the coordinator
-	* issues a fresh credential without an operator action. Reuse is bounded by both
-	* `expires_at` and the consuming instanceId, so it never widens a leaked token's
-	* usefulness beyond the instance that first consumed it.
+	* Self-healing reuse: the same joining peer (`peerInstanceId`) can re-consume
+	* the token until `expires_at`, so a peer that lost its credential re-presents
+	* the token in its env and gets a fresh credential without an operator action.
+	* Bounding reuse by `expires_at` and the consuming instanceId keeps a leaked
+	* token useless beyond the instance that first consumed it.
 	*/
 	async validateAndConsumeToken(token, consumedBy, peerInstanceId) {
 		return this.claimByHash(tokenHashOf(parseToken(token).secretHex), consumedBy, peerInstanceId);
@@ -1982,10 +1799,8 @@ var JoinTokenManager = class {
 	}
 };
 /**
-* Build a JoinTokenManager backed by its own connection pool to the given
-* orchestrator database URL. Mirrors `createPeerCredentialStoreFromUrl`;
-* used by tests that need to exercise token validation/reuse against a real
-* cluster DB.
+* A JoinTokenManager with its own connection pool, for tests against a real
+* cluster DB. Mirrors `createPeerCredentialStoreFromUrl`.
 */
 function createJoinTokenManagerFromUrl(databaseUrl, opts) {
 	const pool = new pg.Pool({
@@ -2000,9 +1815,6 @@ function createJoinTokenManagerFromUrl(databaseUrl, opts) {
 		}
 	};
 }
-/**
-* Parse a join token string into routing info and secret hex.
-*/
 function parseToken(token) {
 	const parts = token.split(".");
 	if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX) throw new Error(`Invalid join token format. Expected: ${TOKEN_PREFIX}.<routing>.<secret>`);
@@ -2529,32 +2341,18 @@ function createTrustPolicyStoreFromUrl(databaseUrl, opts) {
 }
 //#endregion
 //#region src/cli/api-client.ts
+/** kici-admin's HTTP client for the orchestrator admin API (Bearer token auth). */
 /**
-* HTTP client wrapper for the kici-admin CLI.
-*
-* Communicates with the orchestrator admin API via Bearer token authentication.
-* All methods are thin wrappers around fetch() that handle JSON serialization,
-* error formatting, and URL construction.
-*/
-/**
-* `fetch` rejects with a bare `TypeError: fetch failed` when it cannot reach the
-* host — it names neither the address dialled nor the knob that sets it. Printed
-* through the CLI's `Error: ${message}` handler that becomes `Error: fetch
-* failed`, which reads like a fault in the subcommand rather than a misaddressed
-* client, and sends the operator debugging the wrong thing.
-*
-* The trap is sharpened by two details of this CLI. The base URL comes from
-* `KICI_ADMIN_URL`, not the `KICI_ORCHESTRATOR_URL` an operator is likelier to
-* have exported; and subcommands accepting `--database-url` fall back to direct
-* DB access, so on a host with `KICI_DATABASE_URL` set they keep working while
-* the HTTP-only ones fail — making it look like specific subcommands are broken.
-*
-* So: name the address, name the variable, and name the near-miss.
+* A bare `TypeError: fetch failed` names neither the address nor the knob that
+* sets it, so it reads as a broken subcommand rather than a misaddressed client.
+* The base URL comes from `KICI_ADMIN_URL`, not `KICI_ORCHESTRATOR_URL`, and
+* subcommands with `--database-url` fall back to direct DB access, so with
+* `KICI_DATABASE_URL` set only the HTTP-only ones fail. The error therefore names
+* the address, the variable and the near-miss.
 */
 /**
-* Best-effort one-line detail from a rejected `fetch`. Returns '' when nothing
-* useful is available, so the caller can omit the parenthetical rather than
-* print an empty one.
+* Best-effort one-line detail from a rejected `fetch`; '' when none, so the
+* caller omits the parenthetical.
 */
 function firstCauseMessage(err) {
 	if (!(err instanceof Error)) return "";
@@ -2568,21 +2366,16 @@ function firstCauseMessage(err) {
 	return "";
 }
 /**
-* True when a rejected `fetch` failed at the transport layer, as opposed to
-* failing while the request was still being built.
-*
-* `fetch` uses a `TypeError` for both, so they are easy to conflate — but only
-* a transport failure means the orchestrator was actually dialled. Measured
-* against Node 24's undici:
+* True when a rejected `fetch` failed at the transport layer, not while the
+* request was being built. Both are a `TypeError`, but only a transport failure
+* means the orchestrator was dialled. Measured against Node 24's undici:
 *
 *   closed port    → TypeError('fetch failed')                       cause: Error(ECONNREFUSED)
 *   invalid header → TypeError('Headers.append: … invalid header …') cause: undefined
 *   invalid URL    → TypeError('Failed to parse URL from …')         cause: Error(ERR_INVALID_URL)
 *
-* The discriminator is therefore the message, NOT the presence of a `cause`:
-* the invalid-URL case carries one. undici uses exactly `fetch failed` for a
-* transport failure and a descriptive message for everything it rejects before
-* opening a connection.
+* So the discriminator is the message, NOT a `cause` (the invalid-URL case has
+* one): undici says exactly `fetch failed` only for a transport failure.
 */
 function isTransportFailure(err) {
 	return err instanceof TypeError && err.message === "fetch failed";
@@ -2620,9 +2413,6 @@ var AdminApiClient = class {
 		this.baseUrl = baseUrl;
 		this.token = token;
 	}
-	/**
-	* Make an authenticated HTTP request to the admin API.
-	*/
 	async request(method, path, body) {
 		const res = await fetchAdminApi(`${this.baseUrl}${path}`, {
 			method,
@@ -2645,39 +2435,21 @@ var AdminApiClient = class {
 		if (res.status === 204) return;
 		return await res.json();
 	}
-	/**
-	* Public GET request returning parsed JSON.
-	*/
 	async get(path) {
 		return this.request("GET", path);
 	}
-	/**
-	* Public POST request returning parsed JSON.
-	*/
 	async post(path, body) {
 		return this.request("POST", path, body);
 	}
-	/**
-	* Public PATCH request returning parsed JSON.
-	*/
 	async patch(path, body) {
 		return this.request("PATCH", path, body);
 	}
-	/**
-	* Public PUT request returning parsed JSON.
-	*/
 	async put(path, body) {
 		return this.request("PUT", path, body);
 	}
-	/**
-	* Public DELETE request returning parsed JSON.
-	*/
 	async delete(path) {
 		return this.request("DELETE", path);
 	}
-	/**
-	* Public GET request returning raw response text.
-	*/
 	async getText(path) {
 		const res = await fetchAdminApi(`${this.baseUrl}${path}`, {
 			method: "GET",
@@ -2841,13 +2613,9 @@ var AdminApiClient = class {
 		return this.request("GET", `/api/v1/agent-tokens${qs}`);
 	}
 	/**
-	* Revoke an agent token.
-	*
-	* The orchestrator both flips `agent_tokens.revoked_at` AND
-	* synchronously closes every in-flight agent WS authenticated by
-	* this token. The returned `kicked` count is the number
-	* of WS connections that were closed on the wire — surface it to
-	* the operator so they know the revocation actually propagated.
+	* Revoke an agent token: the orchestrator sets `agent_tokens.revoked_at` AND
+	* synchronously closes every agent WS authenticated by it. `kicked` counts
+	* the closed connections; show it so the operator sees the revocation propagated.
 	*/
 	async revokeAgentToken(id) {
 		return this.request("DELETE", `/api/v1/agent-tokens/${encodeURIComponent(id)}`);
@@ -2905,7 +2673,6 @@ var AdminApiClient = class {
 	async drainStatus() {
 		return this.request("GET", "/api/v1/admin/orchestrator/drain");
 	}
-	/** Forget a departed peer on this coordinator and every connected sibling. */
 	/**
 	* Forget a departed peer on this coordinator and every connected sibling. A
 	* refusal that only needs the backstop acknowledgement comes back as a body
@@ -3016,10 +2783,9 @@ var AdminApiClient = class {
 		return this.request("POST", "/api/v1/admin/backends/sync");
 	}
 	/**
-	* List execution runs. `status` accepts either a single status or a
-	* comma-separated list (e.g. `success,failed`). `since` is an ISO-8601
-	* timestamp; only runs with `created_at` strictly later than this value
-	* are returned.
+	* List runs. `status` takes one status or a comma-separated list (e.g.
+	* `success,failed`). `since` is an ISO-8601 timestamp; only runs with
+	* `created_at` strictly later are returned.
 	*/
 	async listRuns(opts) {
 		const qs = toQuery({
@@ -3425,14 +3191,10 @@ function startManifestLoopback(opts) {
 //#endregion
 //#region src/cli/open-browser.ts
 /**
-* Open a URL in the operator's default browser, best-effort. Used by the GitHub
-* App manifest setup flow to launch the create / install pages. Failure is
-* non-fatal — the caller always prints the URL too, so a headless host (or a
-* blocked launcher) just falls back to copy-paste.
-*
-* `KICI_BROWSER_CMD` overrides the launcher: `none` suppresses it entirely
-* (automated tests / headless capture), any other value is run with `{url}` substituted —
-* mirroring the `kici login` convention.
+* Best-effort: the caller always prints the URL too, so a headless host falls
+* back to copy-paste. `KICI_BROWSER_CMD` overrides the launcher as in
+* `kici login`: `none` suppresses it (tests, headless capture), any other
+* value runs with `{url}` substituted.
 */
 function openBrowserBestEffort(url) {
 	const override = process.env.KICI_BROWSER_CMD;
@@ -3466,15 +3228,13 @@ const WebhookUrlNote = z.enum([
 //#endregion
 //#region src/cli/webhook-url-notes.ts
 /**
-* The text the CLI prints when the orchestrator returns no webhook URL. Shared
-* by `kici-admin source add` and the manifest setup flow, so each
-* `WebhookUrlNote` reads the same in both.
+* Text for a missing webhook URL, shared by `kici-admin source add` and the
+* manifest setup flow.
 */
 const DASHBOARD_HINT = "Find the webhook URL in the dashboard under Sources.";
 /**
-* Short reason shown in `(unavailable — <reason>)` when no webhook URL could be
-* resolved. Takes a plain string too, because an orchestrator of another
-* version can send a note this CLI does not know.
+* The reason in `(unavailable — <reason>)`. Takes a plain string: another
+* orchestrator version can send a note this CLI does not know.
 */
 function webhookNoteReason(note) {
 	switch (note) {
@@ -3506,16 +3266,14 @@ function webhookNoteHint(note) {
 //#endregion
 //#region src/cli/commands/source-manifest.ts
 /**
-* `kici-admin source add github --manifest` — the one-click GitHub App setup
-* flow. Drives GitHub's App Manifest flow end-to-end: builds a pre-configured
-* manifest (KiCI's exact permissions/events/webhook URL), hands it to GitHub via
-* an auto-submitting form, catches the returned short-lived setup code over a
-* localhost loopback (or copy-paste in --no-browser mode), exchanges it for the
-* App's id + private key + webhook secret, then reuses the existing source
-* storage + Platform-registration path.
+* `kici-admin source add github --manifest`: GitHub's App Manifest flow end to
+* end. The pre-configured manifest goes to GitHub through an auto-submitting
+* form; the short-lived setup code comes back over a localhost loopback (or is
+* pasted with --no-browser) and is exchanged for the App's id, private key and
+* webhook secret, which take the normal source storage and registration path.
 *
-* The private-key-bearing conversion happens entirely here on the orchestrator
-* host — it never transits the Platform (sovereignty invariant).
+* The private-key-bearing conversion runs only on the orchestrator host and
+* never transits the Platform (sovereignty invariant).
 */
 /** Static marketing-site page the CLI points at in headless paste-code mode. */
 const STATIC_CALLBACK_URL = "https://kici.dev/gh-manifest-callback";