@kici-dev/agent 0.5.0 → 0.6.0

package/dist/execution/sandbox/fork-runner.d.ts

@@ -9,6 +9,21 @@ import { type ChildProcess } from 'node:child_process';
 import type { JobDispatch } from '@kici-dev/engine';
 import type { JobExecutionOptions, JobExecutionResult } from './types.js';
 import type { JobExecutionRequest } from './ipc-protocol.js';
+/**
+ * Best-effort SIGKILL/SIGTERM of an entire process group led by `pid`.
+ * `process.kill(-pid, signal)` targets the group whose leader is `pid` (the
+ * child was spawned `detached`, so its pid is its group id). Returns 1 when the
+ * group was signalled, 0 when it was already gone (ESRCH) or the pid is invalid.
+ * We cannot cheaply count members, so the caller treats a non-zero return as
+ * "reap attempted".
+ */
+export declare function killProcessGroup(pid: number | undefined, signal: NodeJS.Signals): number;
+/**
+ * SIGTERM the job's process group, wait a short grace, then SIGKILL. No-op
+ * (returns 0) when the child was not spawned detached or has no pid. Returns the
+ * count of reap attempts that signalled a live group (0, 1, or 2).
+ */
+export declare function reapGroup(pid: number | undefined, detached: boolean, killFn?: (p: number | undefined, s: NodeJS.Signals) => number, sleepMs?: number): Promise<number>;
 /** Options for creating a fork-based runner. */
 interface ForkRunnerOptions {
     /** Absolute path to the compiled workflow-runner.js. */
@@ -39,6 +54,18 @@ interface ForkRunnerOptions {
      * Defaults to 30_000 (30 seconds).
      */
     maxGracePeriodMs?: number;
+    /**
+     * Spawn the runner child `detached` so it leads its own process group. Set by
+     * the bare-metal backend when orphan cleanup is on and bwrap is off, so the
+     * between-jobs phase can reap a backgrounded daemon that reparented to init.
+     * Ignored under bwrap (its PID namespace already contains the tree).
+     */
+    detachProcessGroup?: boolean;
+    /**
+     * Between-jobs out-of-band cleanup re-run: the runner reuses the preserved
+     * workdir and runs only the job's declared cleanup / onFailure hooks.
+     */
+    cleanupOnly?: boolean;
 }
 /** State of a running fork-based child process. */
 export interface ForkRunnerHandle {
@@ -59,13 +86,40 @@ export interface ForkRunnerHandle {
      *                      Capped by the agent's maxGracePeriodMs.
      */
     cancel: (force: boolean, gracePeriodMs?: number) => void;
+    /**
+     * Whether this runner leads its own detached process group (bare-metal,
+     * non-bwrap, orphan cleanup on). Drives whether `reap()` does anything.
+     */
+    detached: boolean;
+    /**
+     * True once the runner emitted `completion-hooks-done` (its onSuccess /
+     * onFailure / cleanup hooks ran). Stays false when the child exits before
+     * signalling, which is the between-jobs phase's cue to re-run declared
+     * cleanup out-of-band.
+     */
+    completionHooksRan: boolean;
+    /**
+     * True once the runner reported (via `hooks-declared`) that the job declares
+     * an `onFailure` / `cleanup` hook. Recorded early so it survives a later hard
+     * kill; gates whether the out-of-band cleanup re-run is attempted.
+     */
+    declaresCleanup: boolean;
+    /**
+     * SIGTERM → grace → SIGKILL the runner's process group, reaping any daemon it
+     * backgrounded. No-op (resolves 0) when the runner is not detached; returns
+     * the number of reap attempts that signalled a live group.
+     */
+    reap: () => Promise<number>;
 }
 /**
  * Build a JobExecutionRequest from a JobDispatch.
  *
  * Maps orchestrator dispatch fields to the subset needed by the workflow runner.
  */
-export declare function buildRequest(dispatch: JobDispatch, workDir: string): JobExecutionRequest;
+export declare function buildRequest(dispatch: JobDispatch, workDir: string, extra?: {
+    cleanupOnly?: boolean;
+    credentialHelperPath?: string;
+}): JobExecutionRequest;
 /**
  * Build bubblewrap (bwrap) arguments for namespace isolation.
  *

package/dist/execution/sandbox/image-preflight.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fail a container job on an unusable image BEFORE the job starts.
+ *
+ * KiCI injects its own runtime (a pinned official glibc-2.17 Node) into the
+ * customer's image, so the image needs only a glibc and a shell. When it has
+ * neither, the container runtime's own error is close to useless — a musl image
+ * reports
+ *
+ *   exec container process (missing dynamic library?) `/opt/kici/node/bin/node`:
+ *   No such file or directory
+ *
+ * which names a file that plainly exists and says nothing about musl. The
+ * preflight turns that into a sentence an author can act on, and it fires
+ * before any step runs rather than partway through a job.
+ *
+ * glibc-only is the deliberate scope of this version; a musl runtime variant is
+ * a documented follow-up.
+ */
+import type Docker from 'dockerode';
+/** What an image's rootfs says about whether we can run our runtime in it. */
+export type ImageLibc = 'glibc' | 'musl' | 'static' | 'no-shell';
+/** Every path the preflight stats in the image. */
+export declare const PROBE_PATHS: readonly string[];
+/**
+ * Classify an image from the subset of {@link PROBE_PATHS} that exist in it.
+ *
+ * Pure, so the decision table is testable without a container runtime.
+ */
+export declare function classifyImageLibc(presentPaths: readonly string[]): ImageLibc;
+/**
+ * Throw unless `image` can host the injected runtime.
+ *
+ * Stats the probe paths through a created-but-never-started container, so a
+ * shell-less or musl image is diagnosed without executing anything in it —
+ * running a probe command would fail for the very reason we are testing for.
+ */
+export declare function assertImageRunnable(docker: Docker, image: string): Promise<void>;
+//# sourceMappingURL=image-preflight.d.ts.map

package/dist/execution/sandbox/ipc-protocol.d.ts

@@ -119,6 +119,26 @@ interface JobCompleteMessage {
     /** Names of sibling jobs dropped by DynamicJobFn re-evaluation drift. */
     droppedJobs?: string[];
 }
+/**
+ * Emitted once, right after the runner extracts the job's hooks, so the
+ * supervisor knows whether the job declares `onFailure` / `cleanup` even if the
+ * runner is later hard-killed before those hooks run. The between-jobs phase
+ * uses it to decide whether an out-of-band cleanup re-run is warranted.
+ */
+export interface HooksDeclaredMessage {
+    type: 'hooks-declared';
+    /** True when the job declares an `onFailure` or `cleanup` completion hook. */
+    declaresCleanup: boolean;
+}
+/**
+ * The runner's job-completion hooks (onSuccess / onFailure / cleanup) have run.
+ * Emitted once, whether or not a hook failed. Its absence when the child exits
+ * tells the supervisor the runner was killed before its declared cleanup ran,
+ * so the between-jobs phase re-runs that cleanup out-of-band.
+ */
+export interface CompletionHooksDoneMessage {
+    type: 'completion-hooks-done';
+}
 /** Request to emit a custom event from a workflow step (runner -> agent). */
 export interface EventEmitRequest {
     type: 'event.emit';
@@ -186,6 +206,31 @@ export interface CacheRequestIpc {
     /** Tarball size in bytes (drives quota accounting). `completeSave` only. */
     sizeBytes?: number;
 }
+/** Git write-grant operations (runner -> agent). */
+export type GitGrantOp = 'elevate' | 'revoke';
+/**
+ * Open or close a write window for one repository (runner -> agent).
+ *
+ * `withWrite` sends `elevate` before running its callback and `revoke` in a
+ * `finally`. The grant lives in the AGENT's grant table — the credential helper
+ * git spawns is a separate process and consults the agent, not the runner —
+ * which is why this is an agent-directed IPC call rather than an orchestrator
+ * one. Mirrors the {@link CacheRequestIpc} relay pattern.
+ */
+export interface GitGrantRequestIpc {
+    type: 'git.grant.request';
+    /** UUID for correlating the response. */
+    requestId: string;
+    op: GitGrantOp;
+    /** `owner/repo`. `elevate` only. */
+    repository?: string;
+    /** Permissions to request from the forge. `elevate` only. */
+    permissions?: Record<string, string>;
+    /** Named credential from the job's `gitCredentials` map. `elevate` only. */
+    credentialName?: string;
+    /** Grant id returned by a previous `elevate`. `revoke` only. */
+    grantId?: string;
+}
 /**
  * Request a step-level approval hold (runner -> agent). The sandbox runner
  * blocks the step loop before a `requireApproval` step; the agent relays this
@@ -275,7 +320,7 @@ export interface ArtifactRequestIpc {
     /** Storage key echoed from the grant response. `completeUpload` only. */
     storageKey?: string;
 }
-export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | ProvenanceRequestIpc | ArtifactRequestIpc | StepApprovalRequestIpc;
+export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | HooksDeclaredMessage | CompletionHooksDoneMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | ProvenanceRequestIpc | ArtifactRequestIpc | GitGrantRequestIpc | StepApprovalRequestIpc;
 /** Instruct the workflow runner to execute a job. */
 interface ExecuteMessage {
     type: 'execute';
@@ -349,6 +394,30 @@ export interface CacheResponseIpc {
     /** Error description (present when the relay or orchestrator failed). */
     error?: string;
 }
+/**
+ * Result of a git write-grant operation (agent -> runner).
+ *
+ * `granted` reports what the forge ACTUALLY allowed, never an echo of the
+ * request — a static credential comes back unscoped because an SSH key or PAT
+ * cannot be narrowed. `error` is set when the pre-flight found the grant
+ * narrower than requested, which fails the elevation before any git runs.
+ */
+export interface GitGrantResponseIpc {
+    type: 'git.grant.response';
+    /** Matches the original request's requestId. */
+    requestId: string;
+    /** Grant id to pass to a later `revoke`. `elevate` only, on success. */
+    grantId?: string;
+    /** What the credential can actually do. `elevate` only, on success. */
+    granted?: {
+        scoped: false;
+    } | {
+        scoped: true;
+        permissions: Record<string, string>;
+    };
+    /** Error description (present when elevation or revocation failed). */
+    error?: string;
+}
 /**
  * Resolution of a step-level approval hold (agent -> runner). Relayed from the
  * orchestrator's `step.approval-resolved` WS message. On `approved` the runner
@@ -423,7 +492,7 @@ export interface ArtifactResponseIpc {
     /** Error description (present when the relay or orchestrator failed). */
     error?: string;
 }
-export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc | CacheResponseIpc | ProvenanceResponseIpc | ArtifactResponseIpc | StepApprovalResolvedIpc;
+export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc | CacheResponseIpc | ProvenanceResponseIpc | ArtifactResponseIpc | StepApprovalResolvedIpc | GitGrantResponseIpc;
 /**
  * All data the workflow runner needs to execute a job inside the sandbox.
  *
@@ -470,6 +539,15 @@ export interface JobExecutionRequest {
     workflowAuth?: GitAuthDispatch;
     /** URL to a pre-packed `.kici/` source tarball (skip clone if present). */
     sourceTarUrl?: string;
+    /**
+     * Absolute path to the agent's git credential helper, when one is available.
+     *
+     * The runner configures it on every clone it makes, so each later git network
+     * operation asks the agent for a freshly minted credential rather than
+     * relying on one captured at clone time. Absent for a container job, whose
+     * git has no route to the agent's socket — see the dual-mode container work.
+     */
+    credentialHelperPath?: string;
     /** SHA-256 hash of the source tarball bytes for integrity verification. */
     sourceTarHash?: string;
     /** URL to pre-built dependency tarball (skip install if present). */
@@ -568,6 +646,15 @@ export interface JobExecutionRequest {
      * Defaults to `apply` when unset.
      */
     checkMode?: CheckMode;
+    /**
+     * Between-jobs out-of-band cleanup re-run. When true, the runner reuses the
+     * preserved workdir (no clone, no deps, no concurrency / rule / step
+     * evaluation) and runs ONLY the job's `onFailure` + `cleanup` hooks with a
+     * synthesized failed outcome — the durable re-run for a job whose runner was
+     * hard-killed before its in-band completion hooks ran. Bare-metal / in-place
+     * only; the supervisor never sets it for a normally-finished job.
+     */
+    cleanupOnly?: boolean;
     /** When true, skip git clone -- use overlay tarball as complete workspace. */
     fullRepo?: boolean;
     /** URL to download the encrypted overlay tarball (test runs with uncommitted changes). */
@@ -612,6 +699,13 @@ export interface JobExecutionRequest {
     upstreamJobStatuses?: Record<string, import('@kici-dev/engine').ExecutionJobStatus>;
     /** This job's declared upstream needs (normalized lock edges) used to shape ctx.needs for steps. */
     jobNeeds?: readonly unknown[];
+    /**
+     * Per-invoke-gate results for any upstream invoke gate this job `needs`, keyed
+     * by gate job name. Populated for a standard `run:`/step downstream job so
+     * `ctx.needs['<gate>'].result` is an `InvokeResult[]` rather than the fan-out
+     * group shape its proxy children would otherwise imply.
+     */
+    upstreamInvokeResults?: Record<string, import('@kici-dev/engine').InvokeResult[]>;
     /** Resolved private npm registries for `npm install` auth (token bytes already filled). */
     npmRegistries?: ReadonlyArray<{
         url: string;

package/dist/execution/sandbox/kici-runtime.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The KiCI-provisioned runtime a container job executes with.
+ *
+ * A container job used to require the customer's image to ship Node (to run the
+ * workflow runner) and git (to clone). That coupled every image a customer might
+ * name to KiCI's own toolchain. Instead KiCI provisions its own runtime — a
+ * pinned, official glibc-2.17 Node plus the runner bundle, both already inside
+ * the published `kici-agent` image — and mounts it read-only at `/opt/kici`.
+ * The image then needs only a glibc and a shell.
+ *
+ * This module is a pure descriptor on purpose: the container-runtime calls that
+ * act on it live in the spawn helper, so the launch contract stays unit-testable
+ * without a daemon.
+ */
+/** Architectures the published runtime covers. */
+export type RuntimeArch = 'x64' | 'arm64';
+/** Read-only mount point of the KiCI-provisioned runtime inside a job container. */
+export declare const KICI_RUNTIME_MOUNT = "/opt/kici";
+/** Mount point of the injected Node tree inside a job container. */
+export declare const KICI_RUNTIME_NODE_DIR = "/opt/kici/node";
+/** The injected node executable. Absolute — never resolved from the image's PATH. */
+export declare const KICI_RUNTIME_NODE = "/opt/kici/node/bin/node";
+/** How to materialize the runtime into a job container. */
+export interface RuntimeSource {
+    arch: RuntimeArch;
+    /** Where the runtime lives inside the `kici-agent` image. */
+    sourceImagePath: string;
+    /** Where it is mounted inside the job container. */
+    mountPath: string;
+    /** Always read-only: a job must not be able to rewrite the runtime it runs under. */
+    readOnly: true;
+}
+/**
+ * Launch the runner with the injected node, never the image's own.
+ *
+ * The customer image is not required to ship Node, so a bare `node` would
+ * resolve to nothing (or, worse, to an unrelated build).
+ */
+export declare function runnerLaunchArgv(runnerMountPath: string): string[];
+/**
+ * Describe how to materialize `/opt/kici` for a job container on `arch`.
+ *
+ * Refuses an architecture the published runtime does not cover, rather than
+ * mounting a foreign-architecture binary that surfaces mid-job as a confusing
+ * `exec format error`.
+ */
+export declare function resolveRuntimeSource(arch: RuntimeArch): RuntimeSource;
+//# sourceMappingURL=kici-runtime.d.ts.map

package/dist/execution/sandbox/step-loop.d.ts

@@ -112,6 +112,13 @@ export interface StepLoopOptions {
     workflowRepo?: RepoInfo;
     /** Job-level hooks. */
     jobHooks?: JobHooks;
+    /**
+     * Force the completion-hook sequence down the failed path (run `onFailure`
+     * then `cleanup`, not `onSuccess`) regardless of step outcomes. Set by the
+     * between-jobs out-of-band cleanup re-run, which runs no steps but must drive
+     * the declared cleanup as if the job had failed.
+     */
+    forceInitialFailure?: boolean;
     /**
      * Declarative cache phase dependencies (cache API + IPC + pseudo-step index
      * allocator). When set, each step's own `cache` specs are restored before the

package/dist/execution/sandbox/types.d.ts

@@ -1,5 +1,5 @@
 import type { JobDispatch, LogStream } from '@kici-dev/engine';
-import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage, CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, ArtifactRequestIpc, ArtifactResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './ipc-protocol.js';
+import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage, CacheRequestIpc, GitGrantRequestIpc, GitGrantResponseIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, ArtifactRequestIpc, ArtifactResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './ipc-protocol.js';
 /**
  * Common interface for all execution sandbox backends.
  *
@@ -41,6 +41,28 @@ export interface ExecutionSandbox {
      * - Firecracker: no-op (VM lifecycle managed by scaler)
      */
     teardown(): Promise<void>;
+    /**
+     * SIGTERM → grace → SIGKILL the finished job's process group, reaping any
+     * daemon a step backgrounded. Returns the number of reap attempts that
+     * signalled a live group. Only the bare-metal backend reaps a process group;
+     * others (which reap their whole tree on teardown) omit this.
+     */
+    reap?(): Promise<number>;
+    /**
+     * Whether the runner signalled that its completion hooks ran before it exited.
+     * `false` means the runner was hard-killed before running declared cleanup —
+     * the between-jobs phase's cue to re-run it out-of-band. Absent ⇒ treated as
+     * `true` (no re-run) for backends that reap their whole tree.
+     */
+    readonly completionHooksRan?: boolean;
+    /** Whether the job declares an `onFailure` / `cleanup` hook (bare-metal). */
+    readonly declaresCleanup?: boolean;
+    /**
+     * Re-run the finished job's declared cleanup / onFailure hooks out-of-band,
+     * against the preserved workdir, in a fresh bounded child. Resolves on success
+     * and rejects on failure so the caller can time it out. Bare-metal only.
+     */
+    runCleanupOnly?(workDir: string, signal: AbortSignal): Promise<void>;
 }
 /** Options for preparing the sandbox environment. */
 export interface SandboxSetupOptions {
@@ -59,6 +81,19 @@ export interface SandboxSetupOptions {
      * inside `executeJob`, so it ignores this field.
      */
     extraReadOnlyBinds?: string[];
+    /**
+     * Populate the sandbox workspace from `workDir` instead of letting the runner
+     * clone inside it.
+     *
+     * Set when the AGENT already cloned on the host. The container backend packs
+     * `workDir` and copies it into the container's `/workspace` volume; the
+     * bare-metal backend already runs against `workDir` directly and ignores it.
+     *
+     * Cloning on the host is what lets a container image ship without git — and
+     * it puts clone-time credentials on the host, where the credential helper
+     * already works, instead of needing a route into a hardened container.
+     */
+    workspaceFromHost?: boolean;
 }
 /** Options for executing a job inside the sandbox. */
 export interface JobExecutionOptions {
@@ -101,6 +136,25 @@ export interface JobExecutionOptions {
      * working — the runner falls back to a "not configured" cache response.
      */
     onCacheRequest?: (request: CacheRequestIpc) => Promise<CacheResponseIpc>;
+    /**
+     * Callback for opening or closing a git write grant on behalf of the sandbox.
+     *
+     * The grant lives in the AGENT's grant table because the credential helper
+     * git spawns is a separate process that consults the agent, not the sandbox
+     * runner. Optional so harnesses that don't thread git credentials keep
+     * working — the runner falls back to a "not configured" error response.
+     */
+    onGitGrantRequest?: (request: GitGrantRequestIpc) => Promise<GitGrantResponseIpc>;
+    /**
+     * Absolute path to the agent's git credential helper.
+     *
+     * Threaded into the execution request so the runner configures it on every
+     * clone. Set for the bare-metal (fork) backend, whose runner is a host
+     * process that can reach the agent's socket. Deliberately NOT set by the
+     * container backend: git runs inside the container and has no route to it —
+     * see the dual-mode container work.
+     */
+    credentialHelperPath?: string;
     /**
      * Callback for relaying a provenance bundle upload request from the sandbox to
      * the orchestrator. The sandbox runner sends `provenance.request` IPC; the

package/dist/execution/sandbox/workflow-runner.d.ts

@@ -17,13 +17,23 @@ import { $ } from 'zx';
 import { type TempScope } from '@kici-dev/core/tmp';
 import { ExecutionJobStatus } from '@kici-dev/engine';
 import type { Step, StepInput, StepContext, RepoInfo, EventPayload } from '@kici-dev/sdk';
-import type { NeedsContext, FanoutPosition, EventDefinition } from '@kici-dev/sdk';
+import type { NeedsContext, FanoutPosition, EventDefinition, InvokeResult } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap, TrackedStepSecrets } from '@kici-dev/sdk';
-import type { RunnerToAgentMessage, JobExecutionRequest } from './ipc-protocol.js';
+import type { RunnerToAgentMessage, JobExecutionRequest, GitGrantResponseIpc } from './ipc-protocol.js';
 import { LogMasker } from './log-masker.js';
 import type { StepLoopOptions } from './step-loop.js';
 import type { GeneratorRepoPair } from '../generator-context.js';
 import { type RuleEvaluationResult } from '../rule-evaluator.js';
+/**
+ * Open a write window for one repository, run `fn`, and close it.
+ *
+ * The revoke rides a `finally`, so a throwing callback still closes the
+ * window — and the agent's TTL is the backstop if this process dies outright.
+ */
+export declare function withRepoWrite(repository: string, opts: {
+    permissions?: Record<string, string>;
+    credential?: string;
+}, fn: () => Promise<void>, send: (msg: RunnerToAgentMessage) => void, wait: (requestId: string) => Promise<GitGrantResponseIpc>): Promise<void>;
 /**
  * Build `ctx.needs` for a job's steps from the dispatch envelope. Reconstructs
  * an {@link UpstreamSnapshot} from `upstreamJobOutputs` (flat per single job;
@@ -32,7 +42,7 @@ import { type RuleEvaluationResult } from '../rule-evaluator.js';
  * `{ result, status }` / ordered-array shape via the shared SDK builder. Returns
  * undefined when the job declares no needs.
  */
-export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[] | undefined, upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined, upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined): NeedsContext | undefined;
+export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[] | undefined, upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined, upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined, upstreamInvokeResults?: Record<string, InvokeResult[]>): NeedsContext | undefined;
 /**
  * Build a fresh zx `$` shell bound to the sandbox working directory and the
  * sanitized environment (process.env was set by the parent via env-sanitizer
@@ -71,6 +81,16 @@ export declare function buildSandboxShell(cwd: string, stepIndex: number, masked
  * emit overload); a definition resolves to its `.name`, a string passes through.
  */
 export declare function resolveEmitEventName(nameOrDefinition: string | EventDefinition): string;
+/**
+ * Reject a user `ctx.emit` whose event name uses a reserved prefix: `kici.`
+ * (KiCI-internal system events — the event scaler's scale-up / scale-down) or
+ * `__` (the events the orchestrator mints for itself). A workflow step must
+ * forge neither — a `__` name is dispatched as a TRUSTED ref and skips the
+ * event-storm rate limiter, so emitting one would be a privilege escalation,
+ * not merely a naming collision. Throws a clear error at the emit call; the
+ * orchestrator enforces the same reservation authoritatively.
+ */
+export declare function assertUserEmittableEventName(eventName: string): void;
 /**
  * Sanitize a raw identifier into a valid temp label: lowercase, every
  * non-`[a-z0-9-]` char to `-`, falling back to `'step'` when the result is

package/dist/idle-shutdown.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a scaler-managed agent does about its idle-shutdown timer when
+ * `register.ack` arrives.
+ *
+ * This lives apart from `server.ts` so the rule has exactly one
+ * implementation: the server acts on the verdict, and the tests assert on the
+ * verdict. Importing `server.ts` starts the agent (it ends in a top-level
+ * `guardStartup`), so a function exported from there could only ever be tested
+ * by a copy of itself.
+ */
+/**
+ * - `none` — do nothing: either the agent is not scaler-managed, or it is busy.
+ * - `warm` — pre-spawned to wait for work; disarm any timer and stay up.
+ * - `pending-dispatch` — a bound job is on its way; arm the long safety timeout.
+ * - `idle` — arm the ordinary scaler-idle timer.
+ */
+export type IdleShutdownDecision = 'none' | 'warm' | 'pending-dispatch' | 'idle';
+export declare function decideIdleShutdown(input: {
+    scalerManaged: boolean;
+    activeJobs: number;
+    pendingDispatch?: boolean;
+    warmPool?: boolean;
+}): IdleShutdownDecision;
+//# sourceMappingURL=idle-shutdown.d.ts.map