@kici-dev/shared 0.1.14 → 0.1.16

package/README.md

@@ -1 +1,13 @@
-TBD
+# @kici-dev/shared
+
+Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic. Re-exports `@kici-dev/core`.
+
+This is an internal support library — other `@kici-dev` packages depend on it; it is not meant to be installed directly.
+
+Part of [KiCI](https://kici.dev) — CI/CD workflows as TypeScript code: author them with full language power, dry-run them locally, and run them on your own infrastructure.
+
+## Links
+
+- Documentation: <https://docs.kici.dev/architecture/overview/>
+- Source: <https://github.com/kici-dev/kici-public/tree/main/packages/shared>
+- License: Apache-2.0

package/dist/db-admin.d.ts

@@ -187,6 +187,7 @@ export interface SeedEnvironmentOpts {
     waitTimerSeconds?: number | null;
     holdExpirySeconds?: number | null;
     minimumTrust?: string | null;
+    globPattern?: string | null;
 }
 export interface SeedEnvironmentResult {
     envId: string;
@@ -198,6 +199,24 @@ export interface SeedEnvironmentResult {
  * are JSON-serialised server-side; pass them as plain arrays or objects.
  */
 export declare function seedEnvironmentDirect(databaseUrl: string, opts: SeedEnvironmentOpts): Promise<SeedEnvironmentResult>;
+export interface DeleteEnvironmentOpts {
+    orgId: string;
+    name: string;
+}
+/**
+ * Delete an environment keyed by (org_id, name). Returns whether a row was
+ * removed. The `environment_bindings`, `environment_variables`, and
+ * `environment_source_overrides` children all carry
+ * `FOREIGN KEY (environment_id) REFERENCES environments(id) ON DELETE CASCADE`,
+ * so a single DELETE on `environments` cascades to those children. The
+ * `held_runs` FK uses `ON DELETE SET NULL`, so terminal held-run history
+ * survives the delete with a null environment reference. Pending held runs
+ * still reference the environment, so this helper pre-checks their count and
+ * throws before issuing the DELETE — approve or reject them first.
+ */
+export declare function deleteEnvironmentDirect(databaseUrl: string, opts: DeleteEnvironmentOpts): Promise<{
+    deleted: boolean;
+}>;
 export interface SeedEnvironmentBindingOpts {
     orgId: string;
     envName: string;
@@ -219,6 +238,7 @@ export interface SetEnvironmentPolicyOpts {
     holdExpirySeconds?: number | null;
     minimumTrust?: string | null;
     enabled?: boolean;
+    allowLocalExecution?: boolean;
 }
 /**
  * UPDATE only the policy fields that were explicitly provided. Columns that
@@ -1462,5 +1482,14 @@ export declare function clearPeerCredentialsRevokedAtByIdsDirect(databaseUrl: st
 export declare function countActivePeerCredentialsByInstanceDirect(databaseUrl: string, opts: {
     instanceId: string;
 }): Promise<number>;
+/**
+ * Terminate every idle backend of the connecting user except our own
+ * connection. Mirrors what a Postgres leader demotion does to idle pooled
+ * connections — used by resilience tests to verify the pg pool error
+ * handlers absorb the termination without a process restart.
+ *
+ * Returns the number of backends terminated.
+ */
+export declare function terminateIdleDbBackendsDirect(databaseUrl: string): Promise<number>;
 export {};
 //# sourceMappingURL=db-admin.d.ts.map

package/dist/db-admin.js

@@ -351,7 +351,8 @@ const ENV_POLICY_COLUMNS = new Set([
 	"wait_timer_seconds",
 	"hold_expiry_seconds",
 	"minimum_trust",
-	"enabled"
+	"enabled",
+	"allow_local_execution"
 ]);
 /**
 * Upsert an environment row keyed by (org_id, name). Returns the env id and
@@ -370,9 +371,9 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
 		const reviewersJson = opts.requiredReviewers === void 0 ? null : JSON.stringify(opts.requiredReviewers);
 		const row = (await pool.query(`INSERT INTO environments
           (org_id, name, type, enabled, branch_restrictions, required_reviewers,
-           wait_timer_seconds, hold_expiry_seconds, minimum_trust)
+           wait_timer_seconds, hold_expiry_seconds, minimum_trust, glob_pattern)
         VALUES ($1, $2, COALESCE($3, 'fixed'), COALESCE($4, true), $5::jsonb, $6::jsonb,
-                $7, COALESCE($8, 86400), $9)
+                $7, COALESCE($8, 86400), $9, $10)
         ON CONFLICT (org_id, name) DO UPDATE SET
           type = COALESCE(EXCLUDED.type, environments.type),
           enabled = EXCLUDED.enabled,
@@ -381,6 +382,7 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
           wait_timer_seconds = EXCLUDED.wait_timer_seconds,
           hold_expiry_seconds = EXCLUDED.hold_expiry_seconds,
           minimum_trust = EXCLUDED.minimum_trust,
+          glob_pattern = COALESCE(EXCLUDED.glob_pattern, environments.glob_pattern),
           updated_at = now()
         RETURNING id, (xmax = 0) AS inserted`, [
 			opts.orgId,
@@ -391,7 +393,8 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
 			reviewersJson,
 			opts.waitTimerSeconds ?? null,
 			opts.holdExpirySeconds ?? null,
-			opts.minimumTrust ?? null
+			opts.minimumTrust ?? null,
+			opts.globPattern ?? null
 		])).rows[0];
 		if (!row) throw new Error(`environment: upsert returned no row for ${opts.name}`);
 		return {
@@ -403,6 +406,33 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
 	}
 }
 /**
+* Delete an environment keyed by (org_id, name). Returns whether a row was
+* removed. The `environment_bindings`, `environment_variables`, and
+* `environment_source_overrides` children all carry
+* `FOREIGN KEY (environment_id) REFERENCES environments(id) ON DELETE CASCADE`,
+* so a single DELETE on `environments` cascades to those children. The
+* `held_runs` FK uses `ON DELETE SET NULL`, so terminal held-run history
+* survives the delete with a null environment reference. Pending held runs
+* still reference the environment, so this helper pre-checks their count and
+* throws before issuing the DELETE — approve or reject them first.
+*/
+async function deleteEnvironmentDirect(databaseUrl, opts) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		const pending = await pool.query(`SELECT count(*)::text AS count FROM held_runs hr
+         JOIN environments e ON e.id = hr.environment_id
+        WHERE e.org_id = $1 AND e.name = $2 AND hr.status = 'pending'`, [opts.orgId, opts.name]);
+		const pendingCount = Number(pending.rows[0]?.count ?? 0);
+		if (pendingCount > 0) throw new Error(`environment has ${pendingCount} pending held run(s) — approve or reject them first`);
+		return { deleted: (await pool.query(`DELETE FROM environments WHERE org_id = $1 AND name = $2 RETURNING id`, [opts.orgId, opts.name])).rows.length > 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
 * Upsert an `environment_bindings` row connecting `envName` to `scopePattern`.
 * Throws if the environment does not exist.
 */
@@ -449,6 +479,7 @@ async function setEnvironmentPolicyDirect(databaseUrl, opts) {
 	if (opts.holdExpirySeconds !== void 0) addSet("hold_expiry_seconds", opts.holdExpirySeconds);
 	if (opts.minimumTrust !== void 0) addSet("minimum_trust", opts.minimumTrust);
 	if (opts.enabled !== void 0) addSet("enabled", opts.enabled);
+	if (opts.allowLocalExecution !== void 0) addSet("allow_local_execution", opts.allowLocalExecution);
 	if (setClauses.length === 0) throw new Error("environment: setEnvironmentPolicy requires at least one policy field");
 	const pool = new pg.Pool({
 		connectionString: databaseUrl,
@@ -2555,7 +2586,27 @@ async function countActivePeerCredentialsByInstanceDirect(databaseUrl, opts) {
 		await pool.end();
 	}
 }
+/**
+* Terminate every idle backend of the connecting user except our own
+* connection. Mirrors what a Postgres leader demotion does to idle pooled
+* connections — used by resilience tests to verify the pg pool error
+* handlers absorb the termination without a process restart.
+*
+* Returns the number of backends terminated.
+*/
+async function terminateIdleDbBackendsDirect(databaseUrl) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT pg_terminate_backend(pid)
+       FROM pg_stat_activity
+       WHERE pid <> pg_backend_pid()
+         AND usename = current_user
+         AND state = 'idle'`)).rowCount ?? 0;
+	} finally {
+		await pool.end();
+	}
+}
 //#endregion
-export { MIGRATION_HASH_TABLE, PROVIDER_HASH_KEY, REGISTERABLE_TRIGGER_TYPES, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDbRole, createEnvironmentTemplateDirect, createJoinTokenDirect, createReadOnlyDbUser, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getRegistryVersionDirect, getWebhookSourceByRoutingKeyDirect, getWorkflowRegistrationByIdDirect, insertCronLastFiredNowDirect, insertCrossRepoTrustStrictDirect, insertKiciEventRawDirect, insertPeerCredentialExpiredDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, isSchemaCurrent, isSchemaCurrentFromFilesDirect, latestExecutionRunByStatusDirect, listActiveGenericWebhookSourcesDirect, listActivePeerCredentialsExcludingDirect, listCrossRepoTrustBySourceRoutingKeyDirect, listEnvironmentsDirect, listExecutionJobsDirect, listExecutionRunsDirect, listKiciEventsDirect, listQueueDirect, listRegistrationsByRoutingKeyDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, platformConnectionExistsDirect, pollKiciEventsDirect, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, resetRaftStateDirect, resolvePlatformWebhookSourceRoutingKeyDirect, restoreSoftDeletedGenericWebhookSourceDirect, seedApiKeyInlineDirect, seedCiSecurityFixturesDirect, seedCrossRepoTrustDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, seedGenericWebhookSourceDirect, seedSourcePrivateKeyDirect, seedSyntheticGithubSourceDirect, seedUniversalGitSourceDirect, seedWebhookSecretDirect, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, showEnvironmentDirect, showExecutionRunDirect, showKiciEventDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, storeMigrationContentHashInTableDirect, tableExistsDirect, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect };
+export { MIGRATION_HASH_TABLE, PROVIDER_HASH_KEY, REGISTERABLE_TRIGGER_TYPES, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDbRole, createEnvironmentTemplateDirect, createJoinTokenDirect, createReadOnlyDbUser, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteEnvironmentDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getRegistryVersionDirect, getWebhookSourceByRoutingKeyDirect, getWorkflowRegistrationByIdDirect, insertCronLastFiredNowDirect, insertCrossRepoTrustStrictDirect, insertKiciEventRawDirect, insertPeerCredentialExpiredDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, isSchemaCurrent, isSchemaCurrentFromFilesDirect, latestExecutionRunByStatusDirect, listActiveGenericWebhookSourcesDirect, listActivePeerCredentialsExcludingDirect, listCrossRepoTrustBySourceRoutingKeyDirect, listEnvironmentsDirect, listExecutionJobsDirect, listExecutionRunsDirect, listKiciEventsDirect, listQueueDirect, listRegistrationsByRoutingKeyDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, platformConnectionExistsDirect, pollKiciEventsDirect, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, resetRaftStateDirect, resolvePlatformWebhookSourceRoutingKeyDirect, restoreSoftDeletedGenericWebhookSourceDirect, seedApiKeyInlineDirect, seedCiSecurityFixturesDirect, seedCrossRepoTrustDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, seedGenericWebhookSourceDirect, seedSourcePrivateKeyDirect, seedSyntheticGithubSourceDirect, seedUniversalGitSourceDirect, seedWebhookSecretDirect, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, showEnvironmentDirect, showExecutionRunDirect, showKiciEventDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, storeMigrationContentHashInTableDirect, tableExistsDirect, terminateIdleDbBackendsDirect, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect };
 
 //# sourceMappingURL=db-admin.js.map

package/dist/db.d.ts

@@ -1,9 +1,28 @@
 import pg from 'pg';
 import { Kysely } from 'kysely';
+/** Where a pg connection error surfaced. */
+export type PgPoolErrorSource = 'idle-pool' | 'client';
+export interface CreatePoolOptions {
+    /** Extra pg.Pool config merged over the connection string (e.g. max, connectionTimeoutMillis). */
+    config?: Omit<pg.PoolConfig, 'connectionString'>;
+    /**
+     * Optional hook invoked after the built-in log line on every absorbed
+     * connection error (e.g. to increment a metrics counter). Additive — it
+     * never replaces the log.
+     */
+    onError?: (err: Error, source: PgPoolErrorSource) => void;
+}
 /**
  * Create PostgreSQL connection pool.
+ *
+ * Always attaches error handlers for both idle pooled clients (the pool's
+ * own 'error' event) and checked-out clients (per-client 'error' via the
+ * 'connect' hook). Without them, a terminated backend — e.g. a Postgres
+ * leader switchover — escalates to an uncaughtException and a full process
+ * restart. The broken connection is logged and discarded; pg replaces it on
+ * the next acquire. In-flight query failures still reject to their callers.
  */
-export declare function createPool(databaseUrl: string): pg.Pool;
+export declare function createPool(databaseUrl: string, options?: CreatePoolOptions): pg.Pool;
 /**
  * Create Kysely database instance (PostgreSQL only).
  *

package/dist/db.js

@@ -1,12 +1,44 @@
 import "./chunk-gOLHoazu.js";
 import pg from "pg";
 import { Kysely, PostgresDialect } from "kysely";
+import { createLogger } from "@kici-dev/core";
 //#region src/db.ts
+let poolLogger;
+function getPoolLogger() {
+	poolLogger ??= createLogger({ prefix: "pg-pool" });
+	return poolLogger;
+}
 /**
 * Create PostgreSQL connection pool.
+*
+* Always attaches error handlers for both idle pooled clients (the pool's
+* own 'error' event) and checked-out clients (per-client 'error' via the
+* 'connect' hook). Without them, a terminated backend — e.g. a Postgres
+* leader switchover — escalates to an uncaughtException and a full process
+* restart. The broken connection is logged and discarded; pg replaces it on
+* the next acquire. In-flight query failures still reject to their callers.
 */
-function createPool(databaseUrl) {
-	return new pg.Pool({ connectionString: databaseUrl });
+function createPool(databaseUrl, options) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		...options?.config
+	});
+	const seen = /* @__PURE__ */ new WeakSet();
+	const handle = (err, source) => {
+		if (seen.has(err)) return;
+		seen.add(err);
+		getPoolLogger().warn("Discarded broken pg connection", {
+			source,
+			error: err.message,
+			stack: err.stack
+		});
+		options?.onError?.(err, source);
+	};
+	pool.on("error", (err) => handle(err, "idle-pool"));
+	pool.on("connect", (client) => {
+		client.on("error", (err) => handle(err, "client"));
+	});
+	return pool;
 }
 /**
 * Create Kysely database instance (PostgreSQL only).

package/dist/db.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=db.test.d.ts.map

package/dist/diagnostics/bundle-archive.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared debug-bundle archive primitives.
+ *
+ * Allowlist config redaction and windowed log-file archiving, used by the
+ * orchestrator's in-process bundle writer, the kici-admin CLI's local bundle,
+ * and the agent's fleet mini-bundle assembler. Keeping one copy means a node
+ * cannot drift from the redaction posture of its peers.
+ */
+import type archiver from 'archiver';
+/** Maximum total log bytes to include in bundle (50MB). */
+export declare const MAX_LOG_BYTES: number;
+/**
+ * Redact config values using allowlist approach.
+ * Only known-safe fields are preserved; everything else becomes "****".
+ */
+export declare function redactConfig(obj: unknown, parentKey?: string): unknown;
+/**
+ * Add log files from logDir to the archive, respecting MAX_LOG_BYTES cap
+ * and the logWindow time filter. Matches any `*.log` file in the directory,
+ * so the per-instance filename pattern produced by
+ * `buildLogFilename()` is picked up without additional configuration.
+ *
+ * Exported for reuse by the `kici-admin debug-bundle` CLI command, which
+ * runs outside the orchestrator process but still needs to include the
+ * same log files in its locally-assembled bundle.
+ */
+export declare function addLogsToArchive(archive: archiver.Archiver, logDir: string, logWindowHours: number): Promise<void>;
+//# sourceMappingURL=bundle-archive.d.ts.map

package/dist/diagnostics/bundle-archive.js

@@ -0,0 +1,141 @@
+import "../chunk-gOLHoazu.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+//#region src/diagnostics/bundle-archive.ts
+/**
+* Shared debug-bundle archive primitives.
+*
+* Allowlist config redaction and windowed log-file archiving, used by the
+* orchestrator's in-process bundle writer, the kici-admin CLI's local bundle,
+* and the agent's fleet mini-bundle assembler. Keeping one copy means a node
+* cannot drift from the redaction posture of its peers.
+*/
+/** Maximum total log bytes to include in bundle (50MB). */
+const MAX_LOG_BYTES = 50 * 1024 * 1024;
+/**
+* Config field names that are safe to include unredacted.
+* Everything else gets replaced with "****".
+*/
+const SAFE_CONFIG_KEYS = new Set([
+	"mode",
+	"host",
+	"port",
+	"logLevel",
+	"region",
+	"environment",
+	"name",
+	"label",
+	"labels",
+	"enabled",
+	"disabled",
+	"timeout",
+	"interval",
+	"maxRetries",
+	"retries",
+	"workers",
+	"concurrency",
+	"maxConcurrency",
+	"batchSize",
+	"bufferSize",
+	"warmPool",
+	"cooldown",
+	"type",
+	"provider",
+	"scaler",
+	"driver",
+	"backend",
+	"protocol",
+	"scheme",
+	"path",
+	"basePath",
+	"metricsPath",
+	"healthPath",
+	"logFormat",
+	"logFile",
+	"logDir",
+	"dataDir",
+	"version",
+	"debug",
+	"verbose",
+	"quiet",
+	"tls",
+	"cors",
+	"rateLimiting",
+	"maxConnections",
+	"poolSize",
+	"minPool",
+	"maxPool",
+	"idleTimeout",
+	"connectTimeout",
+	"requestTimeout",
+	"shutdownTimeout",
+	"gracefulShutdown"
+]);
+/**
+* Redact config values using allowlist approach.
+* Only known-safe fields are preserved; everything else becomes "****".
+*/
+function redactConfig(obj, parentKey) {
+	if (obj === null || obj === void 0) return obj;
+	if (Array.isArray(obj)) return obj.map((item) => redactConfig(item, parentKey));
+	if (typeof obj === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) result[key] = redactConfig(value, key);
+		return result;
+	}
+	if (typeof obj === "string" && parentKey && !SAFE_CONFIG_KEYS.has(parentKey)) return "****";
+	if (typeof obj === "number" || typeof obj === "boolean") return obj;
+	if (typeof obj === "string" && parentKey && SAFE_CONFIG_KEYS.has(parentKey)) return obj;
+	if (typeof obj === "string") return "****";
+	return obj;
+}
+/**
+* Add log files from logDir to the archive, respecting MAX_LOG_BYTES cap
+* and the logWindow time filter. Matches any `*.log` file in the directory,
+* so the per-instance filename pattern produced by
+* `buildLogFilename()` is picked up without additional configuration.
+*
+* Exported for reuse by the `kici-admin debug-bundle` CLI command, which
+* runs outside the orchestrator process but still needs to include the
+* same log files in its locally-assembled bundle.
+*/
+async function addLogsToArchive(archive, logDir, logWindowHours) {
+	const cutoff = Date.now() - logWindowHours * 60 * 60 * 1e3;
+	const entries = fs.readdirSync(logDir).filter((f) => {
+		if (!f.endsWith(".log")) return false;
+		return fs.statSync(path.join(logDir, f)).mtimeMs >= cutoff;
+	});
+	entries.sort((a, b) => {
+		const aStat = fs.statSync(path.join(logDir, a));
+		return fs.statSync(path.join(logDir, b)).mtimeMs - aStat.mtimeMs;
+	});
+	let totalBytes = 0;
+	let totalLines = 0;
+	let errors = 0;
+	let warnings = 0;
+	for (const entry of entries) {
+		const filePath = path.join(logDir, entry);
+		const stat = fs.statSync(filePath);
+		if (totalBytes + stat.size > 52428800) break;
+		const content = fs.readFileSync(filePath, "utf-8");
+		archive.append(content, { name: `logs/${entry}` });
+		totalBytes += stat.size;
+		const lines = content.split("\n");
+		totalLines += lines.length;
+		for (const line of lines) {
+			if (/\berror\b/i.test(line)) errors++;
+			if (/\bwarn(ing)?\b/i.test(line)) warnings++;
+		}
+	}
+	const summary = {
+		totalLines,
+		errors,
+		warnings,
+		totalBytes
+	};
+	archive.append(JSON.stringify(summary, null, 2), { name: "logs/summary.json" });
+}
+//#endregion
+export { MAX_LOG_BYTES, addLogsToArchive, redactConfig };
+
+//# sourceMappingURL=bundle-archive.js.map

package/dist/diagnostics/bundle-archive.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bundle-archive.test.d.ts.map

package/dist/diagnostics/bundle-chunks.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Channel-agnostic chunked transfer for fleet bundle ZIPs.
+ *
+ * The WS frame cap (WS_MAX_PAYLOAD_BYTES = 25 MiB) forbids shipping a whole
+ * bundle in one frame, so a bundle Buffer is split into ordered base64 frames
+ * (~85 KiB raw each, matching the webhook-relay frame size) and reassembled by
+ * the receiver. Used on both the orchestrator-agent and peer channels.
+ */
+/** Raw bytes per chunk before base64 (matches webhook-relay's ~85 KiB frames). */
+export declare const FLEET_CHUNK_BYTES: number;
+export interface BundleChunkFrame {
+    seq: number;
+    dataB64: string;
+    isLast: boolean;
+}
+/** Split a Buffer into ordered base64 frames. An empty buffer yields one final frame. */
+export declare function chunkBuffer(buf: Buffer, chunkBytes?: number): BundleChunkFrame[];
+/**
+ * Correlation core for any "send a request, await a chunked response" channel.
+ *
+ * Key-agnostic so both the orchestrator-agent channel (keyed by requestId) and
+ * the peer channel (keyed by messageId) share one implementation. Pending
+ * requests reject on timeout, on an error frame, or on disconnect. No
+ * orchestrator-initiated request/response primitive existed before fleet
+ * collection; this is it.
+ */
+export declare class ChunkRequestWaiter {
+    private pending;
+    /** Register a pending request `id` that rejects after `timeoutMs`. */
+    add(id: string, timeoutMs: number): Promise<Buffer>;
+    /** Accumulate a chunk; resolves the pending request on the final frame. */
+    onChunk(id: string, seq: number, dataB64: string, isLast: boolean): void;
+    /** Reject the pending request `id` with `message`. */
+    onError(id: string, message: string): void;
+    /** Reject every pending request — used when the underlying connection drops. */
+    rejectAll(reason: string): void;
+}
+/** Reassembles ordered frames into a Buffer. Throws on gaps/reordering. */
+export declare class BundleChunkAssembler {
+    private parts;
+    private next;
+    private done;
+    /** Returns the assembled Buffer on the final frame, otherwise undefined. */
+    accept(seq: number, dataB64: string, isLast: boolean): Buffer | undefined;
+}
+//# sourceMappingURL=bundle-chunks.d.ts.map

package/dist/diagnostics/bundle-chunks.js

@@ -0,0 +1,111 @@
+import "../chunk-gOLHoazu.js";
+//#region src/diagnostics/bundle-chunks.ts
+/**
+* Channel-agnostic chunked transfer for fleet bundle ZIPs.
+*
+* The WS frame cap (WS_MAX_PAYLOAD_BYTES = 25 MiB) forbids shipping a whole
+* bundle in one frame, so a bundle Buffer is split into ordered base64 frames
+* (~85 KiB raw each, matching the webhook-relay frame size) and reassembled by
+* the receiver. Used on both the orchestrator-agent and peer channels.
+*/
+/** Raw bytes per chunk before base64 (matches webhook-relay's ~85 KiB frames). */
+const FLEET_CHUNK_BYTES = 85 * 1024;
+/** Split a Buffer into ordered base64 frames. An empty buffer yields one final frame. */
+function chunkBuffer(buf, chunkBytes = FLEET_CHUNK_BYTES) {
+	const frames = [];
+	if (buf.length === 0) return [{
+		seq: 0,
+		dataB64: "",
+		isLast: true
+	}];
+	for (let offset = 0, seq = 0; offset < buf.length; offset += chunkBytes, seq++) {
+		const slice = buf.subarray(offset, Math.min(offset + chunkBytes, buf.length));
+		frames.push({
+			seq,
+			dataB64: slice.toString("base64"),
+			isLast: offset + chunkBytes >= buf.length
+		});
+	}
+	return frames;
+}
+/**
+* Correlation core for any "send a request, await a chunked response" channel.
+*
+* Key-agnostic so both the orchestrator-agent channel (keyed by requestId) and
+* the peer channel (keyed by messageId) share one implementation. Pending
+* requests reject on timeout, on an error frame, or on disconnect. No
+* orchestrator-initiated request/response primitive existed before fleet
+* collection; this is it.
+*/
+var ChunkRequestWaiter = class {
+	pending = /* @__PURE__ */ new Map();
+	/** Register a pending request `id` that rejects after `timeoutMs`. */
+	add(id, timeoutMs) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`chunk request ${id} timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+			this.pending.set(id, {
+				asm: new BundleChunkAssembler(),
+				resolve,
+				reject,
+				timer
+			});
+		});
+	}
+	/** Accumulate a chunk; resolves the pending request on the final frame. */
+	onChunk(id, seq, dataB64, isLast) {
+		const p = this.pending.get(id);
+		if (!p) return;
+		try {
+			const done = p.asm.accept(seq, dataB64, isLast);
+			if (done) {
+				clearTimeout(p.timer);
+				this.pending.delete(id);
+				p.resolve(done);
+			}
+		} catch (err) {
+			clearTimeout(p.timer);
+			this.pending.delete(id);
+			p.reject(err instanceof Error ? err : new Error(String(err)));
+		}
+	}
+	/** Reject the pending request `id` with `message`. */
+	onError(id, message) {
+		const p = this.pending.get(id);
+		if (!p) return;
+		clearTimeout(p.timer);
+		this.pending.delete(id);
+		p.reject(new Error(message));
+	}
+	/** Reject every pending request — used when the underlying connection drops. */
+	rejectAll(reason) {
+		for (const [, p] of this.pending) {
+			clearTimeout(p.timer);
+			p.reject(new Error(reason));
+		}
+		this.pending.clear();
+	}
+};
+/** Reassembles ordered frames into a Buffer. Throws on gaps/reordering. */
+var BundleChunkAssembler = class {
+	parts = [];
+	next = 0;
+	done = false;
+	/** Returns the assembled Buffer on the final frame, otherwise undefined. */
+	accept(seq, dataB64, isLast) {
+		if (this.done) throw new Error("bundle chunk received after final frame");
+		if (seq !== this.next) throw new Error(`out-of-order bundle chunk: expected ${this.next}, got ${seq}`);
+		this.next++;
+		this.parts.push(Buffer.from(dataB64, "base64"));
+		if (isLast) {
+			this.done = true;
+			return Buffer.concat(this.parts);
+		}
+	}
+};
+//#endregion
+export { BundleChunkAssembler, ChunkRequestWaiter, FLEET_CHUNK_BYTES, chunkBuffer };
+
+//# sourceMappingURL=bundle-chunks.js.map

package/dist/diagnostics/bundle-chunks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bundle-chunks.test.d.ts.map

package/dist/graceful-shutdown.d.ts

@@ -50,9 +50,21 @@ export interface ShutdownHandle {
 /**
  * Wire up SIGTERM / SIGINT (and optionally uncaughtException /
  * unhandledRejection) handlers that execute the provided teardown
- * steps sequentially, then `process.exit(0)`.
+ * steps sequentially, then exit.
+ *
+ * Exit codes: signal-triggered and programmatic shutdowns exit 0;
+ * shutdowns triggered by uncaughtException / unhandledRejection exit 1 so
+ * `Restart=on-failure`-style supervisor policies and exit-code alerting
+ * see the fatal cause. Escalation is sticky — a fatal trigger arriving
+ * while a clean shutdown is already in progress still raises the final
+ * exit code to 1.
  *
  * A force-exit timer ensures the process terminates even if a step hangs.
+ * The force-exit honors the same sticky exit code as a clean completion: a
+ * slow SIGTERM/SIGINT stop that merely overran the grace period still exits 0,
+ * so systemd records an intentional stop rather than marking the unit `failed`
+ * (which would break `systemctl restart` recovery). Only a fatal trigger
+ * (uncaughtException / unhandledRejection) raises the force-exit code to 1.
  */
 export declare function setupGracefulShutdown(options: GracefulShutdownOptions): ShutdownHandle;
 //# sourceMappingURL=graceful-shutdown.d.ts.map