@kici-dev/orchestrator 0.8.0 → 0.9.0

package/dist/__test-helpers__/test-db.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Teardown helper for tests that create their own PostgreSQL database.
+ */
+import type pg from 'pg';
+/**
+ * Terminate whatever backends still hold `dbName`, after first waiting for
+ * the connections the test itself closed to finish closing.
+ *
+ * `pool.end()` — and Kysely's `destroy()`, which calls it — resolves as soon
+ * as every client has SENT its Terminate message, not when its socket has
+ * closed. A `pg_terminate_backend` issued inside that window delivers a FATAL
+ * `57P01` to a client that is mid-shutdown and no longer carries an error
+ * listener, and that surfaces as an uncaught exception that fails the whole
+ * test file after every test in it passed. So this polls `pg_stat_activity`
+ * until the database has no backend left (bounded by `timeoutMs`), and
+ * terminates only what is still there — a connection the test never closed.
+ */
+export declare function terminateTestDbBackends(admin: pg.Pool, dbName: string, opts?: {
+    timeoutMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=test-db.d.ts.map

package/dist/app.d.ts

@@ -146,9 +146,9 @@ export interface AppDependencies {
      */
     ingestOverflowReplayer?: IngestOverflowReplayer;
     /**
-     * Fulfil deferred attestations on demand (mints in this process, which owns
-     * the Platform WS). Backs `POST /api/v1/admin/attestations/retry`. Wired only
-     * in coordinator mode where the retrier exists.
+     * Fulfil deferred attestations on demand (mints in this process with the
+     * orchestrator's own signer). Backs `POST /api/v1/admin/attestations/retry`.
+     * Wired only in coordinator mode where the retrier exists.
      */
     retryAttestations?: (opts: {
         runId?: string;
@@ -183,8 +183,9 @@ export interface AppDependencies {
     /**
      * In-process dev-signed identity signer for the offline local dev plane.
      * Present ONLY in independent mode with KICI_INDEPENDENT_IDENTITY=1. When set
-     * (and NOT Platform-connected), the local mint path for `OIDC_TOKEN_REQUEST_METHOD`
-     * is registered so `ctx.kici.oidc.token()` mints a `kici-local` dev token.
+     * (and no orchestrator-owned signer is configured), the local mint path for
+     * `OIDC_TOKEN_REQUEST_METHOD` is registered so `ctx.kici.oidc.token()` mints
+     * a `kici-local` dev token.
      */
     localOidcSigner?: LocalSigner;
     /**

package/dist/artifacts/artifact-store.d.ts

@@ -168,12 +168,12 @@ export declare class ArtifactStore {
      * is the immutability backstop for a racing duplicate that slipped past the
      * pre-mint check.
      *
-     * Neither agent-supplied value is trusted: the storage key is re-derived from
-     * the server-resolved `runId` + `name`, and the recorded size is the real byte
-     * size of the stored object read back from the storage backend. Agents run
-     * untrusted customer workflow code, so an echoed key could otherwise point a
-     * row at another tenant's object, and a declared size could under-account the
-     * per-org quota (a presigned PUT does not bind content length).
+     * The agent asserts neither the key nor the size: the storage key is derived
+     * from the server-resolved `runId` + `name`, and the recorded size is the real
+     * byte size of the stored object read back from the storage backend. Agents
+     * run untrusted customer workflow code, so an echoed key could otherwise point
+     * a row at another tenant's object, and a declared size could under-account
+     * the per-org quota (a presigned PUT does not bind content length).
      *
      * The name is re-validated here, not only at `beginUpload`: a commit is its
      * own inbound message, so an agent can send one for a name it never got a
@@ -192,11 +192,7 @@ export declare class ArtifactStore {
         runId: string;
         jobId: string;
         name: string;
-        /** Agent-declared size. Advisory — the stored object is stat'd instead. */
-        sizeBytes: number;
         sha256: string;
-        /** Agent-echoed key. Ignored — the key is re-derived server-side. */
-        storageKey: string;
     }): Promise<void>;
     /** Load a single artifact row (any TTL state) for a run + name. */
     private loadRow;

package/dist/cache/legacy-prefixes.d.ts

@@ -0,0 +1,19 @@
+/** The cache prefixes a retired layout can live under. */
+export declare const LEGACY_PREFIXES: readonly ['cache/', 'source/', 'deps/'];
+export type LegacyPrefix = (typeof LEGACY_PREFIXES)[number];
+/**
+ * True only for a key in a retired layout that its shape alone identifies;
+ * false for every key the current writers produce.
+ *
+ * A `deps/` key is never legacy by shape (see the module comment) — use
+ * `legacyDepTarballKeys` over a listing for that prefix.
+ */
+export declare function isLegacyKey(key: string): boolean;
+/**
+ * The `deps/` tarballs in a listing that belong to the retired layout: each is
+ * paired with a `.hash` object under the same platform segment and stem.
+ */
+export declare function legacyDepTarballKeys(keys: readonly string[]): string[];
+/** Every legacy key in a listing, grouped by the prefix it lives under. */
+export declare function classifyLegacyKeys(keys: readonly string[]): Map<LegacyPrefix, string[]>;
+//# sourceMappingURL=legacy-prefixes.d.ts.map

package/dist/cache/pending-precursor-db-watcher.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The shared-database channel for pending precursor jobs.
+ *
+ * The dispatch queue is cluster-wide, so a build / init / dynamic-eval job this
+ * coordinator dispatched may be claimed by an agent connected to a sibling
+ * coordinator. That agent reports to the sibling; the sibling persists the
+ * terminal `job.status` — status plus `execution_jobs.precursor_result` — and
+ * relays nothing, because between coordinators the shared row IS the report.
+ * The trackers on this coordinator would otherwise wait out their own timeout
+ * on a job the fleet already finished.
+ *
+ * While any tracker awaits a job, this watcher polls the rows for exactly that
+ * set and hands each terminal one to `settlePendingPrecursor` — the same
+ * function the local agent socket goes through, so the two channels cannot
+ * disagree on what "finished" means. A job the socket already settled is no
+ * longer tracked and is not queried again; a row that is not yet terminal
+ * settles nothing and is re-read on the next tick.
+ *
+ * Only builds, inits and dynamic evals ride this channel. A pre-run global
+ * eval round is not a run and writes no `execution_jobs` row, so it has no
+ * shared row to read; its own wait ceiling still bounds it.
+ */
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { PendingBuildTracker } from './pending-builds.js';
+import type { PendingDynamicTracker } from './pending-dynamics.js';
+import type { PendingInitTracker } from './pending-inits.js';
+/**
+ * How often the tracked rows are re-read while anything is pending.
+ *
+ * The interval is the latency a cross-coordinator build adds before the
+ * awaiting pipeline dispatches its real jobs, so it is short; the query is one
+ * primary-key lookup per tracked job and runs only while a tracker is
+ * non-empty, so an idle coordinator pays nothing.
+ */
+export declare const DEFAULT_PRECURSOR_DB_POLL_MS = 2000;
+export interface PendingPrecursorDbWatcherDeps {
+    db: Kysely<Database>;
+    pendingBuilds?: Pick<PendingBuildTracker, 'has' | 'resolve' | 'reject' | 'trackedJobIds'>;
+    pendingInits?: Pick<PendingInitTracker, 'has' | 'resolve' | 'reject' | 'trackedJobIds'>;
+    pendingDynamics?: Pick<PendingDynamicTracker, 'has' | 'resolve' | 'reject' | 'trackedJobIds'>;
+    /**
+     * Keeps this coordinator's in-memory job status in step with the row it
+     * settled from. The agent frame that would have done so went to the sibling,
+     * and without it the run's completion check on this coordinator reads the
+     * job as still pending forever.
+     */
+    executionTracker?: {
+        updateInMemoryJob(runId: string, jobId: string, status: string): void;
+    };
+    /** Poll interval. Defaults to {@link DEFAULT_PRECURSOR_DB_POLL_MS}. */
+    intervalMs?: number;
+}
+export declare class PendingPrecursorDbWatcher {
+    private readonly deps;
+    private readonly intervalMs;
+    private timer;
+    private tickInFlight;
+    /**
+     * Terminal rows that carried nothing the settle function could act on —
+     * a `success` with no precursor marker, which a coordinator that predates
+     * `precursor_result` writes. Logged once per job, not once per tick; the
+     * waiter's own timeout still bounds it.
+     */
+    private readonly warnedNoPayload;
+    constructor(deps: PendingPrecursorDbWatcherDeps);
+    start(): void;
+    stop(): void;
+    /** The job ids any tracker currently awaits, de-duplicated. */
+    private trackedJobIds;
+    /**
+     * One pass: read the terminal rows for every tracked job and settle them.
+     * Returns how many entries settled. Never throws — a read fault costs one
+     * tick, and the next one re-reads the same set. Single-flight, so a slow
+     * read cannot stack ticks.
+     */
+    tick(): Promise<number>;
+}
+//# sourceMappingURL=pending-precursor-db-watcher.d.ts.map

package/dist/cache/pending-tracker.d.ts

@@ -61,5 +61,15 @@ export declare class PendingTracker<T> {
      * Number of pending entries (for metrics / debugging).
      */
     get size(): number;
+    /**
+     * The job ids currently awaited, for the shared-database channel.
+     *
+     * The local agent socket is one of two channels that settle an entry. A job
+     * this coordinator dispatched may be claimed from the shared queue by an
+     * agent connected to a sibling coordinator, whose terminal frame never
+     * reaches this process — the sibling writes it to `execution_jobs` instead.
+     * `PendingPrecursorDbWatcher` polls those rows for exactly this set.
+     */
+    trackedJobIds(): string[];
 }
 //# sourceMappingURL=pending-tracker.d.ts.map

package/dist/cache/precursor-result.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Settling a pending precursor job — build, init, dynamic eval, global eval
+ * round — from a terminal `job.status`, whichever channel delivered it.
+ *
+ * Two channels feed the pending trackers:
+ *
+ * - **The local agent socket.** The agent that ran the job reports to the
+ *   coordinator it is connected to, and `app.ts` hands the frame here.
+ * - **The shared database.** The dispatch queue is cluster-wide, so a job this
+ *   coordinator dispatched may be claimed by an agent connected to a sibling
+ *   coordinator. That sibling's frame never reaches this process; the sibling
+ *   persists it to `execution_jobs` instead, and `PendingPrecursorDbWatcher`
+ *   reads the row back and hands it here in the same shape.
+ *
+ * One function settles both so the two channels cannot drift on what counts as
+ * "the build finished" or "the init returned its result".
+ */
+import type { LockJob } from '@kici-dev/engine';
+import type { PendingBuildTracker } from './pending-builds.js';
+import type { PendingDynamicTracker } from './pending-dynamics.js';
+import { type PendingGlobalEvalTracker } from './pending-global-evals.js';
+import type { InitResult, PendingInitTracker } from './pending-inits.js';
+/**
+ * The part of a precursor job's terminal `job.status.data` that the awaiting
+ * coordinator needs, persisted to `execution_jobs.precursor_result` so a
+ * sibling coordinator can read it back.
+ *
+ * Only the markers and their payloads are kept. The build marker is a flag —
+ * the build's artifacts live in the shared source and dependency caches, keyed
+ * by content hash, so the waiter re-reads them from there. The init and
+ * dynamic-eval markers carry their results, because nothing else does.
+ */
+export interface PrecursorResult {
+    buildComplete?: true;
+    initComplete?: true;
+    initResult?: InitResult;
+    dynamicComplete?: true;
+    dynamicJobs?: LockJob[];
+}
+/**
+ * Pull the precursor payload out of a terminal `job.status.data`, or `null`
+ * when the frame carries no precursor marker (an ordinary job).
+ */
+export declare function extractPrecursorResult(data: Record<string, unknown> | undefined): PrecursorResult | null;
+/** The settle-side surface of a tracker: membership plus the two ways to settle. */
+type Settleable<T> = Pick<T, Extract<keyof T, 'has' | 'resolve' | 'reject'>>;
+export interface PendingPrecursorTrackers {
+    pendingBuilds?: Settleable<PendingBuildTracker>;
+    pendingInits?: Settleable<PendingInitTracker>;
+    pendingDynamics?: Settleable<PendingDynamicTracker>;
+    pendingGlobalEvals?: Settleable<PendingGlobalEvalTracker>;
+}
+export interface PrecursorJobStatus {
+    jobId: string;
+    state: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Resolve or reject whichever tracker awaits `jobId`, from a terminal status.
+ *
+ * Returns true when an entry settled. A status for a job nobody awaits, or a
+ * non-terminal status, settles nothing and returns false — the caller may log
+ * that, but must not treat it as an error: the local channel sees every job's
+ * frames, precursor or not.
+ */
+export declare function settlePendingPrecursor(trackers: PendingPrecursorTrackers, { jobId, state, data }: PrecursorJobStatus): boolean;
+export {};
+//# sourceMappingURL=precursor-result.d.ts.map

package/dist/cache/source-cache.d.ts

@@ -31,7 +31,8 @@
  * 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 and aged out by the normal cache TTL.
+ * Old objects are orphaned. The cache TTL is enforced lazily on access, so
+ * nothing here removes them; `kici-admin cache purge-legacy` does.
  */
 import type { CacheStorage } from '../storage/types.js';
 /**

package/dist/cache/user-cache.d.ts

@@ -24,6 +24,26 @@ export interface UserCacheOrgLimits {
 }
 /** Resolves the per-org cache limits for an org id (e.g. an `org_settings` read). */
 export type UserCacheOrgLimitsReader = (orgId: string) => Promise<UserCacheOrgLimits>;
+/**
+ * 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.
+ */
+export declare const TEMP_UPLOAD_STEM = ".tmp-";
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function sanitizeSegment(s: string): string;
 /** Identifies the org + repo + write scope a cache operation targets. */
 export interface UserCacheRef {
     org: string;
@@ -45,6 +65,14 @@ export interface UserCacheBeginSaveResult {
     uploadUrl?: string;
     tempKey?: string;
 }
+/**
+ * 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.
+ */
+export declare function userCacheEntryKey(ref: UserCacheRef, key: string): string;
 export declare class UserCache {
     private readonly storage;
     /** Cluster-wide default quota (the `KICI_USER_CACHE_QUOTA_BYTES` value). */
@@ -69,63 +97,6 @@ export declare class UserCache {
      * restore/save because the settings lookup hiccupped.
      */
     private resolveLimits;
-    /**
-     * 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.
-     */
-    private seg;
-    /** Org-level prefix: the per-tenant isolation boundary and quota scope. */
-    private orgPrefix;
-    /** Org + repo prefix shared by every scope of a repo. */
-    private repoPrefix;
-    /** Namespace prefix for the WRITE scope of a ref (shared OR per-run isolated). */
-    private writePrefix;
-    /** Namespace prefixes the ref may READ, in priority order. Isolated reads its own run scope, then shared. */
-    private readPrefixes;
-    /**
-     * 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.
-     */
-    private finalKey;
-    /**
-     * The pre-discriminator object key.
-     *
-     * @deprecated Read-only compatibility path for entries written before the key
-     * carried a discriminator. Nothing writes this format; it is removed at the
-     * next major, by which point every such entry has aged out of the cache TTL.
-     */
-    private legacyFinalKey;
-    /**
-     * Restore an entry still stored in the pre-discriminator key format.
-     *
-     * Two gates, and BOTH are load-bearing — dropping either re-creates the
-     * wrong-cache-hit this change fixes:
-     *
-     * 1. `unambiguousLegacyKey` statically rules out any key that could have
-     *    collided with a case variant in the old format.
-     * 2. The listed name must match byte-exactly. A case-insensitive backend
-     *    resolves `getUrl('build')` to an object created as `Build`, but its
-     *    *listing* reports the real created name — so comparing against the
-     *    listing is what detects that the object is not really ours.
-     *
-     * @deprecated Removed at the next major; see `legacyFinalKey`.
-     */
-    private restoreLegacyExact;
     /** Restore: try the exact key across read prefixes, then restoreKeys prefix scan (newest wins). */
     restore(ref: UserCacheRef & {
         key: string;
@@ -147,7 +118,15 @@ export declare class UserCache {
         tempKey?: string;
     }): Promise<void>;
     private readHash;
-    /** Evict least-recently-used entries for the org until total tarball size <= the per-org quota. */
+    /**
+     * 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.
+     */
     private enforceQuota;
 }
 //# sourceMappingURL=user-cache.d.ts.map

package/dist/cli/api-client.d.ts

@@ -147,13 +147,10 @@ export declare class AdminApiClient {
         timeoutSeconds?: number;
     }, outPath: string): Promise<void>;
     /**
-     * List secret scopes for an org.
-     *
-     * @param allBackends - Aggregate every registered backend and return scopes
-     *   in qualified `<backend>:<path>` form. Default (false) returns the bare,
-     *   pg-only listing; that default flips at v1.0.0.
+     * List an org's secret scopes across every registered backend, each in
+     * qualified `<backend>:<path>` form.
      */
-    listScopes(orgId: string, allBackends?: boolean): Promise<{
+    listScopes(orgId: string): Promise<{
         scopes: string[];
     }>;
     listKeys(orgId: string, scope: string): Promise<{

package/dist/cli/commands/cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cache maintenance commands for kici-admin (orchestrator side).
+ *
+ *   cache purge-legacy [--yes] [--org <id>]   Remove objects under the retired cache layouts
+ *
+ * The CLI talks **directly** to the configured cache storage backend — the same
+ * `KICI_STORAGE_*` configuration the orchestrator runs with — and never through
+ * the orchestrator HTTP admin API: the objects it removes are ones no running
+ * process reads, so there is nothing for the process to mediate. No database
+ * and no running orchestrator are needed.
+ */
+import type { Command } from 'commander';
+import type { CacheStorage } from '../../storage/types.js';
+import { type LegacyPrefix } from '../../cache/legacy-prefixes.js';
+/** Build the cache storage client from the orchestrator config (S3 or filesystem). */
+export declare function resolveCacheStorage(): CacheStorage;
+export interface PurgeLegacyOptions {
+    storage: CacheStorage;
+    /** Delete the matched objects. Off = dry run: list and count only. */
+    apply: boolean;
+    /** Narrow the sweep to one org's user-cache prefix (`cache/<org>/`). */
+    org?: string;
+}
+export interface PurgeLegacyPrefixSummary {
+    count: number;
+    bytes: number;
+}
+export interface PurgeLegacySummary {
+    applied: boolean;
+    perPrefix: Map<LegacyPrefix, PurgeLegacyPrefixSummary>;
+    totalCount: number;
+    totalBytes: number;
+}
+/**
+ * Find every object under the retired cache layouts and, with `apply`, delete
+ * it. Sizes come from a stat of each candidate — the listing carries none —
+ * and a candidate that vanishes between the listing and the stat counts as
+ * zero bytes rather than failing the sweep.
+ *
+ * `org` limits the scan to that org's `cache/<org>/` prefix. The retired source
+ * and dependency layouts carry no org segment, so an org-scoped sweep leaves
+ * them untouched.
+ */
+export declare function purgeLegacyCache(opts: PurgeLegacyOptions): Promise<PurgeLegacySummary>;
+/** Seams the tests replace: where the storage comes from and where output goes. */
+export interface CacheCommandDeps {
+    resolveStorage: () => CacheStorage;
+    out: (line: string) => void;
+}
+export declare function registerCacheCommands(program: Command, deps?: CacheCommandDeps): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cli/commands/cluster-settings.d.ts

@@ -71,17 +71,6 @@ export declare function buildClusterPatch(opts: Record<string, string | undefine
  * Returns the lines rather than printing them so the check is unit-testable.
  */
 export declare function unpairedEvalTimeoutWarnings(patch: PatchBody): string[];
-/**
- * Warn for every deprecated knob the patch sets.
- *
- * The set still goes through — the column and the route field are a released
- * operator surface and keep accepting writes — so the warning says what the
- * stored value now does, which is nothing.
- *
- * Returns the lines rather than printing them so the check is unit-testable,
- * matching {@link unpairedEvalTimeoutWarnings}.
- */
-export declare function deprecatedKnobWarnings(patch: PatchBody): string[];
 /** Build the reset PATCH body: all knobs → null, or just the flagged ones. */
 export declare function buildClusterReset(opts: Record<string, boolean | undefined>): PatchBody;
 /**

package/dist/cli/commands/trust-policy.d.ts

@@ -29,25 +29,17 @@ import type { AdminApiClient } from '../api-client.js';
 /**
  * The policy shape the admin route returns.
  *
- * The four policy fields are OPTIONAL because a **v0.5.0 independent**
- * orchestrator omits them: there, and only there, no policy row and no attached
- * Platform meant no policy was resolved at all, and it reported
- * `enforcement: 'legacy'` with the fields absent. A v0.5.0 Platform-attached
- * orchestrator with no row still sent the fail-closed values. This build's route
- * always sends them in every mode, so the `unknown` fallbacks below — and the
- * `no policy stored` provenance wording — render only against that older
- * independent orchestrator.
- *
- * The route also sends a deprecated `enforcement` field. Nothing here reads it —
- * on this build it is always `policy` — so it is absent from this shape;
- * `--format json` stringifies the parsed policy object, so the field still
- * reaches the operator verbatim.
+ * The policy fields are OPTIONAL because a **v0.5.0 independent** orchestrator
+ * omits them: there, and only there, no policy row and no attached Platform
+ * meant no policy was resolved at all. A v0.5.0 Platform-attached orchestrator
+ * with no row still sent the fail-closed values. This build's route always sends
+ * them in every mode, so the `unknown` fallbacks below — and the `no policy
+ * stored` provenance wording — render only against that older independent
+ * orchestrator.
  */
 export interface TrustPolicyView {
     customerId: string;
     forkPolicy?: string;
-    unknownContributorPolicy?: string;
-    workflowChangePolicy?: string;
     approvalExpiryHours?: number;
     /**
      * The authoritative hold window. Absent from any orchestrator that predates
@@ -59,15 +51,7 @@ export interface TrustPolicyView {
     effectiveDefault?: boolean;
     platformManaged?: boolean;
 }
-/**
- * Render the policy as an aligned table, or as JSON when asked.
- *
- * The two deprecated arms are deliberately absent from the table: no dispatch
- * decision reads either one, so a row claiming `Unknown contributor policy:
- * hold` would assert an enforcement that is not happening. They are still
- * stored and still echoed back, and `--format json` prints the policy object the
- * route returned, so the values remain reachable for anyone who needs them.
- */
+/** Render the policy as an aligned table, or as JSON when asked. */
 export declare function formatPolicy(policy: TrustPolicyView, format: string): string;
 /**
  * Warn that the fork switch in force silently drops pull requests.
@@ -78,10 +62,8 @@ export declare function formatPolicy(policy: TrustPolicyView, format: string): s
  * touched to a policy they never set, so the reader of `trust-policy show`
  * is told outright — with where to look for each individual drop.
  *
- * `reject` is deprecated and resolves through the same arm, so it warns too.
- *
  * Returns the lines rather than printing them so the check is unit-testable,
- * matching `policyDeprecationWarnings` above.
+ * matching `policyExpiryWarnings` below.
  */
 export declare function forkDropWarnings(policy: TrustPolicyView): string[];
 /**
@@ -112,21 +94,9 @@ export declare function buildPolicyPatch(opts: Record<string, string | undefined
  * one that is not applied is named rather than dropped in silence.
  *
  * Returns the lines rather than printing them so the check is unit-testable,
- * matching `policyDeprecationWarnings` below.
+ * matching `forkDropWarnings` above.
  */
 export declare function policyExpiryWarnings(patch: Record<string, string | number>): string[];
-/**
- * Warn about deprecated flags and deprecated values in an already-built patch.
- *
- * Every one of these still PATCHes through unchanged — the orchestrator stores
- * what it is given, and an older Platform or CLI keeps seeing the value it
- * expects. The warning says what the value does now, which for all three is
- * nothing the fork switch reads.
- *
- * Returns the lines rather than printing them so the check is unit-testable,
- * matching `unpairedEvalTimeoutWarnings` in `cluster-settings.ts`.
- */
-export declare function policyDeprecationWarnings(patch: Record<string, string | number>): string[];
 /** One identity link as the directory route reports it. */
 interface DirectoryIdentityLink {
     userId: string;
@@ -184,8 +154,8 @@ export declare function formatDirectoryAge(updatedAt: string, now: number): stri
  * The connected wording is a `Note:` and the disconnected one a `Warning:`,
  * because the two ask for different things: one states a property of the design
  * the reader should know, the other names a condition they should act on. The
- * `Warning:` producers above — `forkDropWarnings`, `policyExpiryWarnings` and
- * `policyDeprecationWarnings` — are all of the second kind.
+ * `Warning:` producers above — `forkDropWarnings` and `policyExpiryWarnings` —
+ * are both of the second kind.
  *
  * Returns the lines rather than printing them so the check is unit-testable,
  * matching `forkDropWarnings` above.

package/dist/cli/service/privilege.d.ts

@@ -1,15 +1,19 @@
 /**
  * Resolve the system-vs-user privilege level for a service lifecycle command.
  *
- * Five CLI verbs (install / start / stop / restart / uninstall) need to agree
- * on whether they're operating against the user-level service
- * (~/Library/LaunchAgents, `systemctl --user`) or the system-level one
- * (/Library/LaunchDaemons, `systemctl`). Default behavior (no flag) is to
- * auto-detect based on UID — non-root → user-level, root → system-level.
+ * The service lifecycle verbs (install, start, stop, restart, uninstall,
+ * status, logs) and `db` need to agree on whether they're operating against
+ * the user-level service (~/Library/LaunchAgents, `systemctl --user`) or the
+ * system-level one (/Library/LaunchDaemons, `systemctl`). Default behavior
+ * (no flag) is to auto-detect based on UID — non-root → user-level, root →
+ * system-level.
  *
  * Explicit `--system` / `--user-level` flags override the auto-detect.
  * They're mutually exclusive: passing both throws. Passing `--system`
- * without root throws with an actionable "re-run under sudo" message.
+ * without root throws with a `sudo` command the operator can paste: it names
+ * the node binary and CLI script the refused process was actually running,
+ * because `sudo` resets PATH to its `secure_path` and cannot find a node that
+ * a version manager (nvm, mise, fnm, volta) put on the operator's PATH.
  */
 export interface PrivilegeOpts {
     /** Force system-level install/lifecycle. Requires root. */
@@ -17,5 +21,22 @@ export interface PrivilegeOpts {
     /** Force user-level install/lifecycle. */
     userLevel?: boolean;
 }
+/** The slice of `process` the re-run hint is built from, injectable for tests. */
+export interface RerunContext {
+    /** `process.execPath` — the node binary actually running. */
+    execPath: string;
+    /** `process.argv` — `[node, script, ...args]`. */
+    argv: readonly string[];
+    /** `process.platform`. */
+    platform: NodeJS.Platform;
+}
+/**
+ * The lines appended to the `--system` refusal: a command that re-runs the
+ * refused invocation as root, built from the running process rather than from
+ * a literal `kici-admin`, which `sudo` cannot find when node comes from a
+ * version manager. On Windows there is no `sudo`; the hint names an elevated
+ * shell instead.
+ */
+export declare function systemRerunHint(ctx: RerunContext): string;
 export declare function resolveUserLevel(opts: PrivilegeOpts): boolean;
 //# sourceMappingURL=privilege.d.ts.map