@kici-dev/orchestrator 0.14.2 → 0.16.0

package/dist/index.js

@@ -6,12 +6,13 @@ import { createLogger, createS3Client, sha256, toErrorMessage } from "@kici-dev/
 import * as fs from "node:fs";
 import { mkdtempSync, promises, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { createHash, createHmac, hkdfSync, randomBytes, randomUUID } from "node:crypto";
+import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
 import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { Kysely, PostgresDialect, sql } from "kysely";
 import pg from "pg";
+import { DEFAULT_APPROVAL_EXPIRY_SECONDS, ForkPolicy, HoldScope, HoldType, OrchRole, TriggerSource } from "@kici-dev/engine";
 import { z } from "zod";
-import { DEFAULT_APPROVAL_EXPIRY_HOURS, DEFAULT_APPROVAL_EXPIRY_SECONDS, ForkPolicy, HoldScope, HoldType, TriggerSource, approvalExpiryHoursOf, approvalExpirySecondsOf, persistedHoldTypeSpellings } from "@kici-dev/engine";
+import { ORCHESTRATOR_DEFAULT_PORT } from "@kici-dev/shared/env";
 import { platform, tmpdir } from "node:os";
 import { createInterface } from "node:readline";
 import { Octokit } from "@octokit/rest";
@@ -702,7 +703,7 @@ function createCacheStorage(config) {
 * 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; `kici-admin cache purge-legacy` does.
+* nothing here removes them.
 */
 const logger$4 = createLogger({ prefix: "source-cache" });
 /**
@@ -1105,8 +1106,7 @@ const DEFAULT_USER_CACHE_TTL_MS = 6048e5;
 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. Shared with
-* the retired-layout classifier so both agree on what an upload looks like.
+* target a save lands on 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. */
@@ -1122,7 +1122,7 @@ const KEY_DISCRIMINATOR_TAIL = new RegExp(`^(.*)-([0-9a-f]{32})$`);
 * 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 and which `kici-admin cache purge-legacy` removes.
+* which nothing writes.
 */
 function isCommittedEntry(key) {
 	return key.endsWith(TAR_SUFFIX) && KEY_DISCRIMINATOR_TAIL.test(key.slice(0, -7));
@@ -1147,9 +1147,6 @@ function stripKeyDiscriminator(stem) {
 * 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.
-*
-* Exported so an operator tool that addresses an org's prefix from a raw org id
-* (`kici-admin cache purge-legacy --org`) lands on the segment the writer used.
 */
 function sanitizeSegment(s) {
 	const cleaned = s.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -1199,10 +1196,8 @@ function finalKey(prefix, key) {
 }
 /**
 * 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 — so anything that must recognise a current-layout key (the
-* legacy-layout classifier tests) takes it from here rather than restating
-* the format.
+* the writer's own path: `beginSave` and `commitSave` address the entry
+* through it.
 */
 function userCacheEntryKey(ref, key) {
 	return finalKey(writePrefix(ref), key);
@@ -1451,7 +1446,7 @@ var PeerCredentialStore = class {
 	}
 	/** The most recently revoked credential row for `instanceId`, or null. */
 	async findLatestRevokedByInstanceId(instanceId) {
-		const row = await this.db.selectFrom("peer_credentials").selectAll().where("instance_id", "=", instanceId).where("revoked_at", "is not", null).orderBy("revoked_at", "desc").executeTakeFirst();
+		const row = await this.db.selectFrom("peer_credentials").selectAll().where("instance_id", "=", instanceId).where("revoked_at", "is not", null).orderBy("revoked_at", "desc").orderBy("created_at", "desc").executeTakeFirst();
 		return row ? mapRow(row) : null;
 	}
 	/**
@@ -1626,12 +1621,27 @@ createLogger({ prefix: "coordinator-credential" });
 * 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 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.
 */
 const logger = createLogger({ prefix: "peer-auth-coordinator" });
 /** How long a waiting peer-client awaits an in-flight sibling token-join. */
 const DEFAULT_JOIN_WAIT_TIMEOUT_MS = 1e4;
 /** Max read→await→re-read cycles before a waiter gives up and joins/aborts. */
 const MAX_DECIDE_ITERATIONS = 3;
+/** What `reportRejection` did with the credential file. */
+let RejectionAction = /* @__PURE__ */ function(RejectionAction) {
+	/** A sibling refreshed the file: retry with the fresh credential. */
+	RejectionAction["RetryCredential"] = "retry-credential";
+	/** The file was deleted: the next decision token-joins or self-issues. */
+	RejectionAction["Rejoin"] = "rejoin";
+	/** This cluster's database holds the credential as valid (or is unreadable): the file stays. */
+	RejectionAction["KeepCredential"] = "keep-credential";
+	return RejectionAction;
+}({});
 function deferred() {
 	let resolve;
 	return {
@@ -1647,6 +1657,7 @@ var PeerAuthCoordinator = class {
 	joinToken;
 	joinWaitTimeoutMs;
 	selfIssue;
+	corroborateRejection;
 	/** The issuance in progress; concurrent sibling clients share it. */
 	selfIssueInFlight = null;
 	/** An operator revoked this coordinator's credential: never issue again in this process. */
@@ -1661,6 +1672,7 @@ var PeerAuthCoordinator = class {
 		this.joinToken = opts.joinToken;
 		this.joinWaitTimeoutMs = opts.joinWaitTimeoutMs ?? DEFAULT_JOIN_WAIT_TIMEOUT_MS;
 		this.selfIssue = opts.selfIssue;
+		this.corroborateRejection = opts.corroborateRejection;
 	}
 	/** Run `fn` exclusively against the credential file. */
 	async withLock(fn) {
@@ -1771,6 +1783,17 @@ var PeerAuthCoordinator = class {
 				});
 				return "retry-credential";
 			}
+			if (cred && this.corroborateRejection) {
+				const verdict = await this.corroborateRejection(cred.credential);
+				if (verdict !== "not-held") {
+					logger.warn("A peer rejected a credential this cluster holds as valid; keeping the credential file", {
+						instanceId: this.instanceId,
+						reason,
+						verdict
+					});
+					return "keep-credential";
+				}
+			}
 			try {
 				await unlink(this.credentialFile);
 				logger.warn("Deleted stale credential file after server rejection", {
@@ -1790,24 +1813,49 @@ var PeerAuthCoordinator = class {
 //#endregion
 //#region src/cluster/join-token.ts
 /**
-* Join token manager for zero-knowledge cluster bootstrap.
+* Join tokens: creation, lookup and claim.
 *
 * Token format: kici_join_v1.<base64url(routing_json)>.<random_256bit_hex>
-* - Routing JSON: { orgId, routingKey, expiry } (cleartext for Platform relay routing)
-* - Secret: 32 random bytes as hex (used for key derivation)
-*
-* Key derivation:
-* - encryption_key = HKDF-SHA256(secret, salt="kici-join-encrypt", info="v1", length=32)
-* - validation_hash = SHA-256(secret) (stored in DB for lookup)
+* - Routing JSON: { orgId, routingKey, expiry, role }. A lookup key only: the
+*   row the token was stored as decides the role and routing a claim returns.
+* - Secret: 32 random bytes as hex. The database stores token_hash =
+*   SHA-256(secret), never the secret.
 *
-* Config bundle encryption: AES-256-GCM with random 12-byte IV.
-* Wire format: <12-byte IV><16-byte auth tag><ciphertext>
+* A row is found by its hash (claimByHash, readByHash), or by its routing fields
+* plus a proof the caller checks against each candidate hash
+* (resolveLiveTokenByRouting).
 */
 const joinTokenLogger = createLogger({ prefix: "join-token" });
 const TOKEN_PREFIX = "kici_join_v1";
 const DEFAULT_EXPIRY_MS = 36e5;
 const TOKEN_ALREADY_USED_MESSAGE = "Join token has already been used. Create a new token with: kici-admin peer create-token";
 const TOKEN_EXPIRED_MESSAGE = "Join token has expired. Create a new token with: kici-admin peer create-token";
+const INVALID_JOIN_TOKEN_MESSAGE = "Invalid join token";
+const ResolvedJoinTokenStatus = z.enum([
+	"live",
+	"expired",
+	"unknown"
+]);
+const joinRoutingClaimSchema = z.object({
+	orgId: z.string().min(1),
+	routingKey: z.string().min(1),
+	expiry: z.number().finite()
+}).passthrough();
+/** Read a `routing_info` value (object, or a JSON string) and the `role` column. */
+function routingFromRow(routingInfo, role) {
+	const raw = typeof routingInfo === "string" ? JSON.parse(routingInfo) : routingInfo;
+	const parsed = joinRoutingClaimSchema.parse(raw);
+	const rowRole = OrchRole.parse(role);
+	return {
+		role: rowRole,
+		routing: {
+			orgId: parsed.orgId,
+			routingKey: parsed.routingKey,
+			expiry: parsed.expiry,
+			role: rowRole
+		}
+	};
+}
 var JoinTokenManager = class {
 	deps;
 	constructor(deps) {
@@ -1819,8 +1867,8 @@ var JoinTokenManager = class {
 	*/
 	async createToken(opts) {
 		const expiryMs = opts.expiryMs ?? DEFAULT_EXPIRY_MS;
-		const expiry = Date.now() + expiryMs;
-		const role = opts.role ?? "coordinator";
+		const expiry = Date.now() + Math.floor(expiryMs);
+		const role = opts.role ?? OrchRole.enum.coordinator;
 		const routing = {
 			orgId: opts.orgId,
 			routingKey: opts.routingKey,
@@ -1831,10 +1879,9 @@ var JoinTokenManager = class {
 		const routingB64 = Buffer.from(JSON.stringify(routing)).toString("base64url");
 		const secretHex = secret.toString("hex");
 		const token = `${TOKEN_PREFIX}.${routingB64}.${secretHex}`;
-		const { validationHash } = deriveKeys(secret);
 		await this.deps.db.insertInto("join_tokens").values({
 			id: randomUUID(),
-			token_hash: validationHash,
+			token_hash: tokenHashOf(secretHex),
 			routing_info: JSON.stringify(routing),
 			role,
 			created_by: opts.createdBy,
@@ -1847,66 +1894,92 @@ var JoinTokenManager = class {
 		return token;
 	}
 	/**
-	* Atomically validate and consume a token in one DB round-trip.
-	*
-	* Single UPDATE with `WHERE token_hash = ? AND consumed_at IS NULL AND
-	* expires_at > NOW()` — only one caller can win the claim across a
-	* shared-DB multi-coordinator mesh. The winner gets `{ routing, keys }`;
-	* every other concurrent caller gets `TOKEN_ALREADY_USED_MESSAGE` and is
-	* expected to fall into the idempotent recovery branch in
-	* `peer-handler.ts` (which serialises credential issuance via the
-	* `peer_credentials_active_uniq` partial unique index).
+	* 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.
 	*
-	* On a 0-row claim, a follow-up SELECT disambiguates not-found / expired
-	* / already-used / reusable-by-same-instance so callers can branch on the
-	* specific reason — the recovery path in peer-handler.ts keys on the
-	* "already used" string specifically. The follow-up only fires on the
-	* unhappy path.
-	*
-	* 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 (transient outage / deleted credential file) re-presents the
-	* still-valid join token already in its env; the coordinator accepts the
-	* reuse and issues a fresh credential — no operator action, no cluster
-	* redeploy. 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: 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.
 	*/
 	async validateAndConsumeToken(token, consumedBy, peerInstanceId) {
-		const parsed = parseToken(token);
-		const keys = deriveKeys(Buffer.from(parsed.secretHex, "hex"));
-		const updateResult = await this.deps.db.updateTable("join_tokens").set({
+		return this.claimByHash(tokenHashOf(parseToken(token).secretHex), consumedBy, peerInstanceId);
+	}
+	/**
+	* Find the row whose proof the caller accepts, among rows whose routing matches
+	* the claimed routing. Consumption state is not checked here; `claimByHash` owns it.
+	* At most JOIN_TOKEN_ROUTING_CANDIDATE_CAP rows, newest first, are offered.
+	*/
+	async resolveLiveTokenByRouting(claimed, accepts) {
+		const rows = await this.deps.db.selectFrom("join_tokens").select(["token_hash", "expires_at"]).where(sql`routing_info->>'orgId'`, "=", claimed.orgId).where(sql`routing_info->>'routingKey'`, "=", claimed.routingKey).where(sql`routing_info->>'expiry'`, "=", String(claimed.expiry)).orderBy("created_at", "desc").limit(16).execute();
+		for (const row of rows) {
+			if (!accepts(row.token_hash)) continue;
+			return new Date(row.expires_at).getTime() > Date.now() ? {
+				status: ResolvedJoinTokenStatus.enum.live,
+				tokenHash: row.token_hash
+			} : { status: ResolvedJoinTokenStatus.enum.expired };
+		}
+		return { status: ResolvedJoinTokenStatus.enum.unknown };
+	}
+	/**
+	* Atomically consume the row with this hash, or re-validate it for the instance
+	* that consumed it (self-healing reuse, bounded by expires_at). Routing and role
+	* come from the row.
+	*
+	* One UPDATE ... WHERE consumed_at IS NULL wins the claim across a shared-DB
+	* multi-coordinator mesh; every other concurrent caller gets
+	* TOKEN_ALREADY_USED_MESSAGE, the message peer-handler's idempotent retry keys on.
+	* On a 0-row claim, a follow-up SELECT tells not-found, expired, already-used and
+	* reusable-by-the-same-instance apart.
+	*/
+	async claimByHash(tokenHash, consumedBy, consumerInstanceId) {
+		const claimed = await this.deps.db.updateTable("join_tokens").set({
 			consumed_at: /* @__PURE__ */ new Date(),
 			consumed_by: consumedBy,
-			consumed_by_instance: peerInstanceId
-		}).where("token_hash", "=", keys.validationHash).where("consumed_at", "is", null).where("expires_at", ">", /* @__PURE__ */ new Date()).executeTakeFirst();
-		if (Number(updateResult?.numUpdatedRows ?? 0n) > 0) {
+			consumed_by_instance: consumerInstanceId
+		}).where("token_hash", "=", tokenHash).where("consumed_at", "is", null).where("expires_at", ">", /* @__PURE__ */ new Date()).returning(["routing_info", "role"]).executeTakeFirst();
+		if (claimed) {
 			joinTokenLogger.info("Consumed join token", {
 				consumedBy,
-				peerInstanceId
+				consumerInstanceId,
+				tokenFingerprint: tokenFingerprint(tokenHash)
 			});
 			return {
-				routing: parsed.routing,
-				keys
+				tokenHash,
+				...routingFromRow(claimed.routing_info, claimed.role)
 			};
 		}
-		const row = await this.deps.db.selectFrom("join_tokens").selectAll().where("token_hash", "=", keys.validationHash).executeTakeFirst();
-		if (!row) throw new Error("Invalid join token");
+		const row = await this.deps.db.selectFrom("join_tokens").select([
+			"routing_info",
+			"role",
+			"expires_at",
+			"consumed_at",
+			"consumed_by_instance"
+		]).where("token_hash", "=", tokenHash).executeTakeFirst();
+		if (!row) throw new Error(INVALID_JOIN_TOKEN_MESSAGE);
 		if (new Date(row.expires_at).getTime() <= Date.now()) throw new Error(TOKEN_EXPIRED_MESSAGE);
 		if (row.consumed_at) {
-			if (row.consumed_by_instance === peerInstanceId) {
+			if (row.consumed_by_instance === consumerInstanceId) {
 				joinTokenLogger.info("Re-validated join token for returning instance", {
 					consumedBy,
-					peerInstanceId
+					consumerInstanceId,
+					tokenFingerprint: tokenFingerprint(tokenHash)
 				});
 				return {
-					routing: parsed.routing,
-					keys
+					tokenHash,
+					...routingFromRow(row.routing_info, row.role)
 				};
 			}
 			throw new Error(TOKEN_ALREADY_USED_MESSAGE);
 		}
-		throw new Error("Invalid join token");
+		throw new Error(INVALID_JOIN_TOKEN_MESSAGE);
+	}
+	/** Role and routing of the row with this hash, or null. */
+	async readByHash(tokenHash) {
+		const row = await this.deps.db.selectFrom("join_tokens").select(["routing_info", "role"]).where("token_hash", "=", tokenHash).executeTakeFirst();
+		return row ? routingFromRow(row.routing_info, row.role) : null;
 	}
 };
 /**
@@ -1939,21 +2012,17 @@ function parseToken(token) {
 	if (!routing.orgId || !routing.routingKey || !routing.expiry) throw new Error("Invalid join token routing data");
 	return {
 		routing,
+		routingB64: parts[1],
 		secretHex: parts[2]
 	};
 }
-/**
-* Derive encryption key and validation hash from a token secret.
-* - encryptionKey: HKDF-SHA256 with salt="kici-join-encrypt", info="v1"
-* - validationHash: SHA-256 of secret (stored in DB for lookup)
-*/
-function deriveKeys(secret) {
-	const validationHash = sha256(secret);
-	const derived = hkdfSync("sha256", secret, Buffer.from("kici-join-encrypt"), Buffer.from("v1"), 32);
-	return {
-		encryptionKey: Buffer.from(derived),
-		validationHash
-	};
+/** Hex SHA-256 of a token secret: the value `join_tokens.token_hash` stores. */
+function tokenHashOf(secretHex) {
+	return sha256(Buffer.from(secretHex, "hex"));
+}
+/** A log-safe tag for a token hash. Never log the hash itself: it is the join key root. */
+function tokenFingerprint(tokenHash) {
+	return sha256(`kici-join-log:${tokenHash}`).slice(0, 12);
 }
 /**
 * Reason a run was held in the security queue. Persisted verbatim in
@@ -2250,18 +2319,15 @@ var HeldRunStore = class {
 	* incidental: `expireOverdue` is not scope-filtered, so a released-but-not-yet-
 	* resumed row would otherwise be expired out from under its resume.
 	*
-	* The filter matches every persisted spelling of the timer hold type, so a row
-	* an un-upgraded orchestrator wrote as `wait_timer` still resumes rather than
-	* falling through to the expire-and-fail sweep. It deliberately does NOT
-	* filter on `hold_scope`: a job-scoped timer hold used to be excluded here,
-	* which left it with no release path at all — created, never released,
-	* eventually expired, its job never dispatched.
+	* The filter deliberately does NOT filter on `hold_scope`: a job-scoped timer
+	* hold used to be excluded here, which left it with no release path at all —
+	* created, never released, eventually expired, its job never dispatched.
 	*/
 	async releaseDueWaitHolds() {
 		return (await this.db.updateTable("held_runs").set({
 			status: "released",
 			resolved_at: sql`now()`
-		}).where("status", "=", "pending").where("hold_type", "in", persistedHoldTypeSpellings(HoldType.enum.timer)).where("expires_at", "<", sql`now()`).returningAll().execute()).map((row) => ({
+		}).where("status", "=", "pending").where("hold_type", "=", HoldType.enum.timer).where("expires_at", "<", sql`now()`).returningAll().execute()).map((row) => ({
 			holdId: row.id,
 			runId: row.run_id,
 			jobId: row.job_id,
@@ -2279,7 +2345,7 @@ var HeldRunStore = class {
 	* `listQueuedHoldsForContext` fetches the rows it actually releases.
 	*/
 	async listAllQueuedHolds() {
-		return await this.db.selectFrom("held_runs").innerJoin("execution_runs", "execution_runs.run_id", "held_runs.run_id").select(["held_runs.org_id as orgId", "execution_runs.context as concurrencyGroup"]).where("held_runs.status", "=", "pending").where("held_runs.hold_type", "in", persistedHoldTypeSpellings(HoldType.enum.concurrency)).execute();
+		return await this.db.selectFrom("held_runs").innerJoin("execution_runs", "execution_runs.run_id", "held_runs.run_id").select(["held_runs.org_id as orgId", "execution_runs.context as concurrencyGroup"]).where("held_runs.status", "=", "pending").where("held_runs.hold_type", "=", HoldType.enum.concurrency).execute();
 	}
 	/**
 	* List the pending queued (concurrency) holds for one context's concurrency
@@ -2292,7 +2358,7 @@ var HeldRunStore = class {
 	* starve whoever waited longest.
 	*/
 	async listQueuedHoldsForContext(orgId, concurrencyGroup) {
-		return this.db.selectFrom("held_runs").innerJoin("execution_runs", "execution_runs.run_id", "held_runs.run_id").selectAll("held_runs").where("held_runs.org_id", "=", orgId).where("held_runs.status", "=", "pending").where("held_runs.hold_type", "in", persistedHoldTypeSpellings(HoldType.enum.concurrency)).where("execution_runs.context", "=", concurrencyGroup).where("execution_runs.customer_id", "=", orgId).orderBy("held_runs.created_at", "asc").execute();
+		return this.db.selectFrom("held_runs").innerJoin("execution_runs", "execution_runs.run_id", "held_runs.run_id").selectAll("held_runs").where("held_runs.org_id", "=", orgId).where("held_runs.status", "=", "pending").where("held_runs.hold_type", "=", HoldType.enum.concurrency).where("execution_runs.context", "=", concurrencyGroup).where("execution_runs.customer_id", "=", orgId).orderBy("held_runs.created_at", "asc").execute();
 	}
 	/**
 	* Expire overdue pending runs. Called by the stale detector.
@@ -2332,12 +2398,10 @@ function createHeldRunStoreFromUrl(databaseUrl, opts) {
 const DEFAULT_FORK_POLICY = ForkPolicy.enum.ignore;
 Object.freeze({
 	forkPolicy: DEFAULT_FORK_POLICY,
-	approvalExpiryHours: DEFAULT_APPROVAL_EXPIRY_HOURS,
 	approvalExpirySeconds: DEFAULT_APPROVAL_EXPIRY_SECONDS
 });
 Object.freeze({
 	forkPolicy: ForkPolicy.enum.hold,
-	approvalExpiryHours: DEFAULT_APPROVAL_EXPIRY_HOURS,
 	approvalExpirySeconds: DEFAULT_APPROVAL_EXPIRY_SECONDS
 });
 z.enum([
@@ -2367,34 +2431,9 @@ const TrustPolicySource = z.enum(["platform", "local"]);
 */
 const DEFAULT_TRUST_POLICY = {
 	forkPolicy: DEFAULT_FORK_POLICY,
-	approvalExpiryHours: DEFAULT_APPROVAL_EXPIRY_HOURS,
 	approvalExpirySeconds: DEFAULT_APPROVAL_EXPIRY_SECONDS
 };
 /**
-* Resolve a local patch's approval-expiry window against what is already stored.
-*
-* One value is being set, spelled two ways, so the pair is merged as a unit and
-* always re-derived from the winning seconds value:
-*
-* - a patch naming `approvalExpirySeconds` sets the window, and the hours field
-*   is recomputed from it — a stale hours value left behind would be the coarse
-*   view of a window that is no longer stored;
-* - a patch naming only `approvalExpiryHours` sets the window too, and the
-*   seconds field is recomputed from it — keeping the old seconds value would
-*   let it out-rank the operator's explicit hours and silently discard the
-*   write;
-* - a patch naming both takes the seconds value, because it is the more
-*   specific of the two (`approvalExpirySecondsOf`);
-* - a patch naming neither leaves the stored window untouched.
-*/
-function mergedExpiry(patch, existing) {
-	const seconds = (patch.approvalExpirySeconds != null || patch.approvalExpiryHours != null ? approvalExpirySecondsOf(patch) : null) ?? existing?.approvalExpirySeconds ?? DEFAULT_TRUST_POLICY.approvalExpirySeconds ?? DEFAULT_APPROVAL_EXPIRY_SECONDS;
-	return {
-		approvalExpiryHours: approvalExpiryHoursOf(seconds),
-		approvalExpirySeconds: seconds
-	};
-}
-/**
 * Namespace for the per-org advisory lock taken by `upsertLocal`, so the key
 * cannot collide with another feature's advisory lock in the same database.
 */
@@ -2410,11 +2449,7 @@ var TrustPolicyStore = class {
 		if (!row) return null;
 		return {
 			forkPolicy: row.fork_policy,
-			approvalExpiryHours: Number(row.approval_expiry_hours),
-			approvalExpirySeconds: approvalExpirySecondsOf({
-				approvalExpiryHours: Number(row.approval_expiry_hours),
-				approvalExpirySeconds: row.approval_expiry_seconds == null ? null : Number(row.approval_expiry_seconds)
-			}),
+			approvalExpirySeconds: Number(row.approval_expiry_seconds),
 			source: row.source,
 			updatedAt: row.updated_at
 		};
@@ -2454,7 +2489,7 @@ var TrustPolicyStore = class {
 			const existing = await this.get(orgId, trx);
 			const merged = {
 				forkPolicy: patch.forkPolicy ?? existing?.forkPolicy ?? DEFAULT_TRUST_POLICY.forkPolicy,
-				...mergedExpiry(patch, existing)
+				approvalExpirySeconds: patch.approvalExpirySeconds ?? existing?.approvalExpirySeconds ?? DEFAULT_TRUST_POLICY.approvalExpirySeconds
 			};
 			await this.write(orgId, merged, TrustPolicySource.enum.local, trx);
 			await onWrite?.(trx, merged);
@@ -2462,11 +2497,9 @@ var TrustPolicyStore = class {
 		});
 	}
 	async write(orgId, policy, source, executor = this.db) {
-		const seconds = approvalExpirySecondsOf(policy);
 		const columns = {
 			fork_policy: policy.forkPolicy,
-			approval_expiry_hours: approvalExpiryHoursOf(seconds),
-			approval_expiry_seconds: seconds,
+			approval_expiry_seconds: policy.approvalExpirySeconds,
 			source,
 			updated_at: sql`now()`
 		};
@@ -2555,6 +2588,8 @@ function firstCauseMessage(err) {
 function isTransportFailure(err) {
 	return err instanceof TypeError && err.message === "fetch failed";
 }
+/** The admin API address kici-admin dials when neither --url nor KICI_ADMIN_URL is set. */
+const DEFAULT_ADMIN_URL = `http://localhost:${ORCHESTRATOR_DEFAULT_PORT}`;
 async function fetchAdminApi(url, init, baseUrl) {
 	try {
 		return await fetch(url, init);
@@ -2565,9 +2600,20 @@ async function fetchAdminApi(url, init, baseUrl) {
 		}
 		const detail = firstCauseMessage(err);
 		const cause = detail ? ` (${detail})` : "";
-		throw new Error(`cannot reach the orchestrator admin API at ${baseUrl}${cause}. Set KICI_ADMIN_URL to the orchestrator's HTTP address, or pass --base-url where the subcommand accepts it. Note KICI_ORCHESTRATOR_URL is NOT read by this CLI; if other subcommands appear to work, they are using the --database-url / KICI_DATABASE_URL direct-DB path rather than HTTP.`, { cause: err });
+		const defaultHint = baseUrl === DEFAULT_ADMIN_URL ? ` ${DEFAULT_ADMIN_URL} is kici-admin's built-in default, the orchestrator's default port on this host; an orchestrator on another host, or one whose KICI_PORT sets another port, needs KICI_ADMIN_URL or --url.` : "";
+		throw new Error(`cannot reach the orchestrator admin API at ${baseUrl}${cause}. Set KICI_ADMIN_URL to the orchestrator's HTTP address, or pass --base-url where the subcommand accepts it. Note KICI_ORCHESTRATOR_URL is NOT read by this CLI; if other subcommands appear to work, they are using the --database-url / KICI_DATABASE_URL direct-DB path rather than HTTP.${defaultHint}`, { cause: err });
 	}
 }
+/** Build a `?a=1&b=2` query string, skipping undefined, null and empty-string values. */
+function toQuery(params) {
+	const usp = new URLSearchParams();
+	for (const [k, v] of Object.entries(params)) {
+		if (v === void 0 || v === null || v === "") continue;
+		usp.set(k, String(v));
+	}
+	const qs = usp.toString();
+	return qs ? `?${qs}` : "";
+}
 var AdminApiClient = class {
 	baseUrl;
 	token;
@@ -2767,17 +2813,17 @@ var AdminApiClient = class {
 		return this.request("POST", `/api/v1/admin/generic-sources/${encodeURIComponent(id)}/disable`);
 	}
 	async queryAudit(opts) {
-		const params = new URLSearchParams();
-		if (opts?.contextName) params.set("contextName", opts.contextName);
-		if (opts?.routingKey) params.set("routingKey", opts.routingKey);
-		if (opts?.action) params.set("action", opts.action);
-		if (opts?.from) params.set("from", opts.from);
-		if (opts?.to) params.set("to", opts.to);
-		if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
-		if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
-		if (opts?.includeArchived) params.set("includeArchived", "true");
-		const qs = params.toString();
-		return (await this.request("GET", `/api/v1/admin/audit${qs ? `?${qs}` : ""}`)).entries;
+		const qs = toQuery({
+			contextName: opts?.contextName,
+			routingKey: opts?.routingKey,
+			action: opts?.action,
+			from: opts?.from,
+			to: opts?.to,
+			limit: opts?.limit,
+			offset: opts?.offset,
+			includeArchived: opts?.includeArchived || void 0
+		});
+		return (await this.request("GET", `/api/v1/admin/audit${qs}`)).entries;
 	}
 	async createToken(data) {
 		return this.request("POST", "/api/v1/admin/tokens", data);
@@ -2868,7 +2914,23 @@ var AdminApiClient = class {
 	* other failure throws.
 	*/
 	async forgetPeer(body) {
-		const res = await fetchAdminApi(`${this.baseUrl}/api/v1/admin/peers/forget`, {
+		const { res, json, text } = await this.postForBody("/api/v1/admin/peers/forget", body);
+		if (res.ok) return json;
+		if (res.status === 409 && json.acknowledgementRequired === true) return {
+			instanceId: body.instanceId,
+			results: json.results ?? [],
+			acknowledgementRequired: true,
+			...json.error ? { error: json.error } : {}
+		};
+		throw new Error(`HTTP ${res.status}: ${json.error ?? text}`);
+	}
+	/**
+	* POST `body` and parse the answer whatever its status, for a route that
+	* reports per-instance results on a non-2xx status too. An unparseable body
+	* reads as `{}`.
+	*/
+	async postForBody(path, body) {
+		const res = await fetchAdminApi(`${this.baseUrl}${path}`, {
 			method: "POST",
 			headers: {
 				Authorization: `Bearer ${this.token}`,
@@ -2883,14 +2945,25 @@ var AdminApiClient = class {
 		} catch {
 			parsed = void 0;
 		}
-		const json = parsed ?? {};
-		if (res.ok) return json;
-		if (res.status === 409 && json.acknowledgementRequired === true) return {
-			instanceId: body.instanceId,
-			results: json.results ?? [],
-			acknowledgementRequired: true,
-			...json.error ? { error: json.error } : {}
+		return {
+			res,
+			json: parsed ?? {},
+			text
+		};
+	}
+	/**
+	* Reload the scaler config on this orchestrator and, unless `single`, on every
+	* peer it is connected to. A response where an instance refused its file or
+	* was not reached (422) is returned like a success, so the caller can show
+	* every instance; a 404 means the orchestrator predates the route.
+	*/
+	async scalerReload(body) {
+		const { res, json, text } = await this.postForBody("/api/v1/admin/scaler/reload", body);
+		if ((res.ok || res.status === 422) && Array.isArray(json.results)) return {
+			scope: json.scope ?? (body.single ? "single" : "cluster"),
+			results: json.results
 		};
+		if (res.status === 404) throw new Error("this orchestrator predates kici-admin scaler reload; send SIGHUP to it or upgrade it");
 		throw new Error(`HTTP ${res.status}: ${json.error ?? text}`);
 	}
 	/** List the live Firecracker VMs on this coordinator, or on the `target` peer. */
@@ -2942,15 +3015,15 @@ var AdminApiClient = class {
 	* are returned.
 	*/
 	async listRuns(opts) {
-		const params = new URLSearchParams();
-		if (opts?.status) params.set("status", opts.status);
-		if (opts?.workflowName) params.set("workflowName", opts.workflowName);
-		if (opts?.repo) params.set("repo", opts.repo);
-		if (opts?.since) params.set("since", opts.since);
-		if (opts?.limit) params.set("limit", String(opts.limit));
-		if (opts?.offset) params.set("offset", String(opts.offset));
-		const qs = params.toString();
-		return this.request("GET", `/api/v1/admin/runs${qs ? `?${qs}` : ""}`);
+		const qs = toQuery({
+			status: opts?.status,
+			workflowName: opts?.workflowName,
+			repo: opts?.repo,
+			since: opts?.since,
+			limit: opts?.limit || void 0,
+			offset: opts?.offset || void 0
+		});
+		return this.request("GET", `/api/v1/admin/runs${qs}`);
 	}
 	/**
 	* Count matching runs without returning the row list. Wraps the list
@@ -3003,27 +3076,27 @@ var AdminApiClient = class {
 	* secret_audit_log table.
 	*/
 	async getRunSecretOutputs(runId, opts) {
-		const params = new URLSearchParams();
-		if (opts?.outputKey) params.set("outputKey", opts.outputKey);
-		if (opts?.reveal) params.set("reveal", "true");
-		const qs = params.toString();
-		return this.request("GET", `/api/v1/admin/runs/${encodeURIComponent(runId)}/secret-outputs${qs ? `?${qs}` : ""}`);
+		const qs = toQuery({
+			outputKey: opts?.outputKey,
+			reveal: opts?.reveal || void 0
+		});
+		return this.request("GET", `/api/v1/admin/runs/${encodeURIComponent(runId)}/secret-outputs${qs}`);
 	}
 	async listEventLog(opts) {
-		const params = new URLSearchParams();
-		if (opts?.orgId) params.set("orgId", opts.orgId);
-		if (opts?.routingKey) params.set("routingKey", opts.routingKey);
-		if (opts?.event) params.set("event", opts.event);
-		if (opts?.action) params.set("action", opts.action);
-		if (opts?.status) params.set("status", opts.status);
-		if (opts?.from) params.set("from", opts.from);
-		if (opts?.to) params.set("to", opts.to);
-		if (opts?.deliveryId) params.set("deliveryId", opts.deliveryId);
-		if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
-		if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
-		if (opts?.includeArchived) params.set("includeArchived", "true");
-		const qs = params.toString();
-		return this.request("GET", `/api/v1/admin/event-log${qs ? `?${qs}` : ""}`);
+		const qs = toQuery({
+			orgId: opts?.orgId,
+			routingKey: opts?.routingKey,
+			event: opts?.event,
+			action: opts?.action,
+			status: opts?.status,
+			from: opts?.from,
+			to: opts?.to,
+			deliveryId: opts?.deliveryId,
+			limit: opts?.limit,
+			offset: opts?.offset,
+			includeArchived: opts?.includeArchived || void 0
+		});
+		return this.request("GET", `/api/v1/admin/event-log${qs}`);
 	}
 	async getEventLog(deliveryId, opts) {
 		const params = new URLSearchParams({ orgId: opts.orgId });
@@ -3033,44 +3106,42 @@ var AdminApiClient = class {
 	}
 	/** List internal events, newest first (`GET /api/v1/admin/events`). */
 	async listEvents(opts) {
-		const params = new URLSearchParams();
-		if (opts?.name) params.set("name", opts.name);
-		if (opts?.outcome) params.set("outcome", opts.outcome);
-		if (opts?.since) params.set("since", opts.since);
-		if (opts?.before) params.set("before", opts.before);
-		if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
-		const qs = params.toString();
-		return this.request("GET", `/api/v1/admin/events${qs ? `?${qs}` : ""}`);
+		const qs = toQuery({
+			name: opts?.name,
+			outcome: opts?.outcome,
+			since: opts?.since,
+			before: opts?.before,
+			limit: opts?.limit
+		});
+		return this.request("GET", `/api/v1/admin/events${qs}`);
 	}
 	/** One internal event with its redacted payload and dispatched runs. */
 	async getEvent(id) {
 		return this.request("GET", `/api/v1/admin/events/${encodeURIComponent(id)}`);
 	}
 	async listAccessLog(opts) {
-		const params = new URLSearchParams();
-		if (opts?.orgId) params.set("orgId", opts.orgId);
-		if (opts?.actorType) params.set("actorType", opts.actorType);
-		if (opts?.actorId) params.set("actorId", opts.actorId);
-		if (opts?.action) params.set("action", opts.action);
-		if (opts?.source) params.set("source", opts.source);
-		if (opts?.outcome) params.set("outcome", opts.outcome);
-		if (opts?.targetType) params.set("targetType", opts.targetType);
-		if (opts?.targetId) params.set("targetId", opts.targetId);
-		if (opts?.from) params.set("from", opts.from);
-		if (opts?.to) params.set("to", opts.to);
-		if (opts?.q) params.set("q", opts.q);
-		if (opts?.agentLabel) params.set("agentLabel", opts.agentLabel);
-		if (opts?.agentOnly) params.set("agentOnly", "true");
-		if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
-		if (opts?.cursor) params.set("cursor", opts.cursor);
-		const qs = params.toString();
-		return this.request("GET", `/api/v1/admin/access-log${qs ? `?${qs}` : ""}`);
+		const qs = toQuery({
+			orgId: opts?.orgId,
+			actorType: opts?.actorType,
+			actorId: opts?.actorId,
+			action: opts?.action,
+			source: opts?.source,
+			outcome: opts?.outcome,
+			targetType: opts?.targetType,
+			targetId: opts?.targetId,
+			from: opts?.from,
+			to: opts?.to,
+			q: opts?.q,
+			agentLabel: opts?.agentLabel,
+			agentOnly: opts?.agentOnly || void 0,
+			limit: opts?.limit,
+			cursor: opts?.cursor
+		});
+		return this.request("GET", `/api/v1/admin/access-log${qs}`);
 	}
 	async getAccessLogEntry(id, opts) {
-		const params = new URLSearchParams();
-		if (opts?.orgId) params.set("orgId", opts.orgId);
-		const qs = params.toString();
-		return this.request("GET", `/api/v1/admin/access-log/${encodeURIComponent(id)}${qs ? `?${qs}` : ""}`);
+		const qs = toQuery({ orgId: opts?.orgId });
+		return this.request("GET", `/api/v1/admin/access-log/${encodeURIComponent(id)}${qs}`);
 	}
 	async diagnose() {
 		return this.request("GET", "/admin/diagnose");
@@ -3154,6 +3225,28 @@ function validateWebhookUrl(value) {
 	if (url.protocol !== "https:") throw new Error(`--webhook-url must be an https:// URL (got ${url.protocol}//…)`);
 	return value;
 }
+/**
+* Every permission and event a KiCI GitHub App needs. The manifest requests
+* exactly these, and `kici-admin source refresh` reports an existing App that
+* lacks any of them.
+*/
+const GITHUB_APP_REQUIREMENTS = {
+	permissions: {
+		contents: "read",
+		metadata: "read",
+		pull_requests: "read",
+		checks: "write",
+		members: "read",
+		issues: "read"
+	},
+	events: [
+		"push",
+		"pull_request",
+		"check_run",
+		"check_suite",
+		"issue_comment"
+	]
+};
 function buildGithubAppManifest(input) {
 	return {
 		name: input.name,
@@ -3165,19 +3258,8 @@ function buildGithubAppManifest(input) {
 		redirect_url: input.redirectUrl,
 		...input.setupUrl ? { setup_url: input.setupUrl } : {},
 		public: false,
-		default_permissions: {
-			contents: "read",
-			metadata: "read",
-			pull_requests: "read",
-			checks: "write",
-			members: "read"
-		},
-		default_events: [
-			"push",
-			"pull_request",
-			"check_run",
-			"check_suite"
-		]
+		default_permissions: { ...GITHUB_APP_REQUIREMENTS.permissions },
+		default_events: [...GITHUB_APP_REQUIREMENTS.events]
 	};
 }
 /**
@@ -3356,6 +3438,65 @@ function openBrowserBestEffort(url) {
 	exec(cmd, () => {});
 }
 //#endregion
+//#region src/sources/webhook-url-resolvers.ts
+/**
+* Every webhook-URL decision the orchestrator makes for a GitHub-App source,
+* by operating mode. Pure functions: the entry points (`server.ts`,
+* `standalone.ts`) pass in the mode, the public base, the org and the Platform
+* values, so each rule is unit-tested here once.
+*/
+/** Why a webhook URL could not be resolved. The CLI maps each to a reason and a hint. */
+const WebhookUrlNote = z.enum([
+	"unsupported-provider",
+	"no-public-url",
+	"platform-no-public-url",
+	"platform-unavailable",
+	"platform-url-unknown",
+	"org-not-identified",
+	"resolver-unavailable",
+	"resolve-failed"
+]);
+//#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.
+*/
+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.
+*/
+function webhookNoteReason(note) {
+	switch (note) {
+		case WebhookUrlNote.enum["no-public-url"]: return "KICI_WEBHOOK_PUBLIC_URL is not set on the orchestrator";
+		case WebhookUrlNote.enum["platform-no-public-url"]: return "the Platform has no public webhook URL configured";
+		case WebhookUrlNote.enum["platform-unavailable"]: return "could not reach the Platform";
+		case WebhookUrlNote.enum["platform-url-unknown"]: return "the Platform did not send its GitHub webhook URL";
+		case WebhookUrlNote.enum["org-not-identified"]: return "the orchestrator does not know its Platform org yet";
+		case WebhookUrlNote.enum["unsupported-provider"]: return "this provider has no webhook URL to print";
+		case WebhookUrlNote.enum["resolver-unavailable"]: return "this orchestrator cannot resolve webhook URLs";
+		case WebhookUrlNote.enum["resolve-failed"]: return "resolving the webhook URL failed";
+		default: return "webhook URL could not be determined";
+	}
+}
+/** Actionable next-step hint paired with {@link webhookNoteReason}. */
+function webhookNoteHint(note) {
+	switch (note) {
+		case WebhookUrlNote.enum["no-public-url"]: return "Set KICI_WEBHOOK_PUBLIC_URL to the orchestrator's public base, then re-run; paste the printed URL into your GitHub App or repo webhook.";
+		case WebhookUrlNote.enum["platform-unavailable"]: return "Retry once the orchestrator reconnects, or find the URL in the dashboard under Sources.";
+		case WebhookUrlNote.enum["platform-url-unknown"]: return "Retry when the orchestrator is connected to the Platform, or pass --webhook-url with the URL the App must deliver to.";
+		case WebhookUrlNote.enum["org-not-identified"]: return "Retry when the orchestrator is connected to the Platform, or pass --webhook-url.";
+		case WebhookUrlNote.enum["unsupported-provider"]: return "Configure the webhook from the provider's own settings.";
+		case WebhookUrlNote.enum["resolve-failed"]: return "Retry; if it fails again, find the webhook URL in the dashboard under Sources.";
+		case WebhookUrlNote.enum["platform-no-public-url"]:
+		case WebhookUrlNote.enum["resolver-unavailable"]:
+		default: return DASHBOARD_HINT;
+	}
+}
+//#endregion
 //#region src/cli/commands/source-manifest.ts
 /**
 * `kici-admin source add github --manifest` — the one-click GitHub App setup
@@ -3406,7 +3547,7 @@ const realManifestSetupDeps = {
 /** Resolve the org-scoped webhook URL via the pre-flight route; abort if null. */
 async function resolveWebhookUrl(client) {
 	const pre = await client.get("/api/v1/admin/sources/github-webhook-url");
-	if (!pre.webhookUrl) throw new Error(`Cannot resolve the GitHub webhook URL${pre.webhookNote ? ` (${pre.webhookNote})` : ""}. The manifest flow needs it to configure the App. Ensure the orchestrator is connected to the Platform and has identified its org, then retry.`);
+	if (!pre.webhookUrl) throw new Error(`Cannot resolve the webhook URL for the new GitHub App: ${webhookNoteReason(pre.webhookNote)}. ` + webhookNoteHint(pre.webhookNote));
 	return pre.webhookUrl;
 }
 /**
@@ -3501,6 +3642,6 @@ async function runGithubManifestSetup(opts, client, deps = realManifestSetupDeps
 	}
 }
 //#endregion
-export { AdminApiClient, DEFAULT_TRUST_POLICY, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, DepCache, HeldRunStore, JoinTokenManager, PeerAuthCoordinator, PeerCredentialStore, S3CacheStorage, SecurityHoldReason, SourceCache, TrustPolicySource, TrustPolicyStore, UserCache, createCacheStorage, createHeldRunStoreFromUrl, createJoinTokenManagerFromUrl, createPeerCredentialStoreFromUrl, createTrustPolicyStoreFromUrl, runGithubManifestSetup };
+export { AdminApiClient, DEFAULT_TRUST_POLICY, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, DepCache, HeldRunStore, JoinTokenManager, PeerAuthCoordinator, PeerCredentialStore, RejectionAction, S3CacheStorage, SecurityHoldReason, SourceCache, TrustPolicySource, TrustPolicyStore, UserCache, createCacheStorage, createHeldRunStoreFromUrl, createJoinTokenManagerFromUrl, createPeerCredentialStoreFromUrl, createTrustPolicyStoreFromUrl, runGithubManifestSetup };
 
 //# sourceMappingURL=index.js.map