@kici-dev/agent 0.4.0 → 0.6.0

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

@@ -5,7 +5,7 @@
  * Extracted for testability: the workflow-runner's main() handles IPC, clone, deps,
  * module loading, and calls this loop for step execution with hooks.
  */
-import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord, FanoutPosition } from '@kici-dev/sdk';
+import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord, FanoutPosition, RepoInfo } from '@kici-dev/sdk';
 import { CheckMode } from '@kici-dev/engine';
 import type { RunnerToAgentMessage } from './ipc-protocol.js';
 import type { SandboxStepResult } from './types.js';
@@ -101,8 +101,24 @@ export interface StepLoopOptions {
     dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>;
     /** Fan-out position for the rule context (`ctx.fanout`); undefined on a non-fan-out job. */
     fanout?: FanoutPosition;
+    /**
+     * The repo whose event triggered this run, for the step rule context
+     * (`ctx.sourceRepo`). Present for a global workflow, absent otherwise — a
+     * step rule reads the source tree through `.path` the same way a job rule
+     * and a generator do.
+     */
+    sourceRepo?: RepoInfo;
+    /** The repo that registered the workflow, for the step rule context (`ctx.workflowRepo`). */
+    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

@@ -16,12 +16,24 @@
 import { $ } from 'zx';
 import { type TempScope } from '@kici-dev/core/tmp';
 import { ExecutionJobStatus } from '@kici-dev/engine';
-import type { Step, StepInput, StepContext } from '@kici-dev/sdk';
-import type { NeedsContext, FanoutPosition, EventDefinition } from '@kici-dev/sdk';
+import type { Step, StepInput, StepContext, RepoInfo, EventPayload } 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;
@@ -30,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
@@ -69,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
@@ -103,6 +125,42 @@ export declare function createSandboxStepContext(workDir: string, stepIndex: num
 export declare function deriveFanout(request: JobExecutionRequest): FanoutPosition | undefined;
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
 export declare function rawPayloadFromEvent(event: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * Build the argument the user's `concurrency.group(...)` function receives.
+ *
+ * The only inputs an author can scope a group by. `branch` alone does not
+ * separate one repository from another — an organization-wide workflow runs on
+ * events from many repositories, and their default branches share a name — so
+ * `event.sourceRepo` is what makes a per-source-repository group expressible.
+ * That is why the orchestrator writes the whole normalized envelope into every
+ * global job config: an empty `event` here silently collapses every repository
+ * into one group, and with `cancelInProgress` (the default) one repository's
+ * push then cancels another's in-flight run.
+ *
+ * Boundary cast: the wire `request.event` is untyped JSON that, per the unified
+ * event protocol, always carries the normalized event envelope.
+ */
+export declare function buildConcurrencyGroupContext(request: JobExecutionRequest): {
+    branch: string;
+    event: EventPayload;
+};
+/**
+ * Phase 5 — Inject env vars and build the `RepoInfo` pair that the generator,
+ * the job rules, and step contexts receive when the job is a global workflow.
+ * No-op for normal jobs.
+ *
+ * Runs at the head of phase 5, before anything that may read the source tree:
+ * the generator's re-evaluation (phase 5) and the job rules (phase 7) both take
+ * the returned pair, and both must see what the pre-dispatch evaluation saw.
+ *
+ * `sourceRepo.path` is this sandbox's own absolute path — the same repo lives at
+ * a different path in the evaluation that produced the job list. Read through
+ * it; never compare it or embed it in a job name.
+ */
+export declare function setupGlobalWorkflowEnv(request: JobExecutionRequest, isGlobal: boolean, workflowDir: string, sourceDir: string): {
+    workflowRepo: RepoInfo;
+    sourceRepo: RepoInfo;
+} | undefined;
 /**
  * Mutable state threaded through {@link coerceStep} for one job normalization
  * pass: the shared `step-N` counter, the bare-function → name ref map, and the
@@ -150,6 +208,19 @@ export declare function resolveChangedFilesForRules(request: JobExecutionRequest
 export declare function buildJobRuleCompletion(ruleResult: RuleEvaluationResult, normalizedSteps: Step[]): (RunnerToAgentMessage & {
     type: 'job.complete';
 }) | null;
+/**
+ * Build the inputs the step loop turns into every step rule's `RuleContext`.
+ *
+ * Shares its source with `maybeSkipJobOnRules` so a step rule and a job rule
+ * see the same world: the same event, env, dispatch inputs, fan-out position,
+ * and — for a global workflow — the same source / workflow repo pair. A step
+ * rule that received the pair as `undefined` while the job rule beside it
+ * received the real thing would read the same `RuleContext` type two ways.
+ *
+ * The pair is spread conditionally: a present-but-undefined `sourceRepo` reads
+ * as "declared" to a rule that guards on the key rather than the value.
+ */
+export declare function buildStepLoopRuleInputs(request: JobExecutionRequest, repos: GeneratorRepoPair | undefined): Pick<StepLoopOptions, 'event' | 'env' | 'dispatchInputs' | 'fanout' | 'sourceRepo' | 'workflowRepo'>;
 /**
  * Build the step loop's KICI_ENV/KICI_PATH callbacks with a per-step delta-file
  * pair (keyed by step index). `beforeStepEnvFiles(stepIndex)` lazily creates the

package/dist/execution/workflow-loader.d.ts

@@ -7,6 +7,7 @@
  * Node's normal ESM lookup against `.kici/node_modules/`.
  */
 import type { Workflow, StepInput, DynamicJobFn, OutputsMap, StepRefMap } from '@kici-dev/sdk';
+import { type GeneratorRepoPair } from './generator-context.js';
 /**
  * SDK output-map setters resolved from a specific `@kici-dev/sdk` instance.
  * The agent uses these to wire the workflow module's OWN SDK copy (a different
@@ -99,7 +100,13 @@ export declare function extractStepsFromDynamicJob(workflow: Workflow, dynamicIn
 /** Frozen upstream snapshot for a result-aware generator (rebuilds ctx.needs). */
 upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot, 
 /** Declared upstream needs that shape ctx.needs. */
-declaredNeeds?: readonly unknown[]): Promise<{
+declaredNeeds?: readonly unknown[], 
+/**
+ * The source / workflow repo pair for a global workflow. Must match what the
+ * first evaluation saw, or a generator that reads the source tree produces a
+ * different job list here and the determinism check below fails the job.
+ */
+repos?: GeneratorRepoPair): Promise<{
     steps: readonly StepInput[];
     droppedJobs: string[];
 }>;

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