@kici-dev/agent 0.1.23 → 0.1.25

package/dist/execution/cache/cache-phase.d.ts

@@ -10,20 +10,37 @@ export interface CachePhaseDeps {
     cache: CacheApi;
     /** Emit a runner→agent IPC message (the masked send). */
     sendIpc: (msg: RunnerToAgentMessage) => void;
-    /** Monotonic pseudo-step index allocator (continues after real steps + hooks). */
-    nextStepIndex: () => number;
+    /**
+     * Allocate the next cache pseudo-step index for `ownerStepIndex` (the real
+     * step the cache op belongs to, or {@link JOB_CACHE_OWNER} for job-level
+     * cache). Each owner draws from a disjoint block above every real-step and
+     * hook index, so two concurrently-running steps' cache pseudo-steps never
+     * collide.
+     */
+    nextStepIndex: (ownerStepIndex: number) => number;
 }
+/** Owner sentinel for job-level (not step-scoped) cache restore/save. */
+export declare const JOB_CACHE_OWNER = -1;
+/**
+ * Build the cache pseudo-step index allocator. Each owner (a real step index, or
+ * {@link JOB_CACHE_OWNER}) gets its own disjoint block of {@link CACHE_INDEX_BLOCK}
+ * indices, all above every real-step and hook index (`stepCount * 3 + 100`). A
+ * step's two-or-more cache pseudo-steps are a pure function of its own owner
+ * index, so concurrent children never collide. Under sequential execution the
+ * emitted indices stay above all real/hook indices exactly as before.
+ */
+export declare function createCacheStepIndexAllocator(stepCount: number): (ownerStepIndex: number) => number;
 /**
  * Restore every spec, surfacing each as a `cache:restore` pseudo-step. Returns
  * a map keyed by spec key recording whether the EXACT key hit (so the save
  * phase can skip a redundant save of an entry that already exists).
  */
-export declare function restoreCacheSpecs(specs: CacheSpec[], deps: CachePhaseDeps): Promise<Map<string, CacheRestoreOutcome>>;
+export declare function restoreCacheSpecs(specs: CacheSpec[], deps: CachePhaseDeps, ownerStepIndex: number): Promise<Map<string, CacheRestoreOutcome>>;
 /**
  * Save every spec whose EXACT key did not already hit on restore (immutable +
  * no redundant save), surfacing each as a `cache:save` pseudo-step. A spec
  * whose restore matched a different key via a `restoreKeys` prefix is still
  * saved under its exact key.
  */
-export declare function saveCacheSpecs(specs: CacheSpec[], restoreResults: Map<string, CacheRestoreOutcome>, deps: CachePhaseDeps): Promise<void>;
+export declare function saveCacheSpecs(specs: CacheSpec[], restoreResults: Map<string, CacheRestoreOutcome>, deps: CachePhaseDeps, ownerStepIndex: number): Promise<void>;
 //# sourceMappingURL=cache-phase.d.ts.map

package/dist/execution/cache/index.d.ts

@@ -5,5 +5,5 @@
  * `ctx.cache` API factory plus its transport interface.
  */
 export { createCacheApi, packCachePaths, extractCacheTarball, downloadAndExtractCache, resolveCachePath, type CacheTransport, type CacheRoots, } from './cache-engine.js';
-export { restoreCacheSpecs, saveCacheSpecs, type CachePhaseDeps, type CacheRestoreOutcome, } from './cache-phase.js';
+export { restoreCacheSpecs, saveCacheSpecs, createCacheStepIndexAllocator, JOB_CACHE_OWNER, type CachePhaseDeps, type CacheRestoreOutcome, } from './cache-phase.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/execution/init-runner.d.ts

@@ -5,7 +5,8 @@ import { type MatrixValues } from '@kici-dev/engine';
  * Only fields that were flagged as dynamic and successfully resolved are set.
  */
 export interface InitResult {
-    environmentName?: string;
+    /** Resolved bound-environment names, in merge order (one per `environments` element). */
+    environmentNames?: string[];
     env?: Record<string, string>;
     concurrencyGroup?: string;
     /**

package/dist/execution/sandbox/capture-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Run `fn` with `stepIndex` as the active console-capture attribution for the
+ * duration of its async execution (including everything it awaits).
+ */
+export declare function runInStepCapture<T>(stepIndex: number, fn: () => Promise<T>): Promise<T>;
+/**
+ * The step index whose run is currently on the async stack, or `-1` when no
+ * capture scope is active (workflow-level / between-steps output).
+ */
+export declare function currentCaptureStepIndex(): number;
+//# sourceMappingURL=capture-context.d.ts.map

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

@@ -24,13 +24,27 @@ interface StepStartMessage {
     stepName: string;
     /** Distinguishes regular steps from hook executions (e.g., 'hook:onCancel', 'hook:cleanup'). Defaults to 'step'. */
     step_type?: string;
+    /**
+     * Initial state for the step. Defaults to `running`. A parallel-group child
+     * queued behind `maxParallel` is announced as `pending` before it acquires a
+     * slot; it later emits a second `step.start` with `running` when it launches.
+     */
+    state?: 'running' | 'pending';
+    /** Step concurrency role; absent means an ordinary sequential step. */
+    concurrencyKind?: string;
+    /** Parallel-group correlation id shared by a group's children (e.g. `g0`). */
+    groupId?: string;
 }
-/** A step has completed (success, failure, or a check-mode skip). */
+/** A step has completed (success, failure, check-mode skip, or fail-fast cancel). */
 interface StepCompleteMessage {
     type: 'step.complete';
     stepIndex: number;
-    status: 'success' | 'failed' | 'skipped';
+    status: 'success' | 'failed' | 'skipped' | 'cancelled';
     durationMs: number;
+    /** Step concurrency role; absent means an ordinary sequential step. */
+    concurrencyKind?: string;
+    /** Parallel-group correlation id shared by a group's children (e.g. `g0`). */
+    groupId?: string;
     error?: {
         message: string;
         exitCode?: number;
@@ -202,12 +216,16 @@ export interface StepApprovalRequestIpc {
     };
 }
 /** Which provenance upload operation to relay. */
-export type ProvenanceRequestOp = 'requestUploadUrl' | 'complete';
+export type ProvenanceRequestOp = 'requestUploadUrl' | 'complete' | 'defer';
 /**
  * Request a provenance bundle upload operation (runner -> agent). The agent
- * relays it over the WS as a `provenance.upload.request` / `.complete` and pipes
- * the response back as a {@link ProvenanceResponseIpc}. Mirrors the
- * {@link CacheRequestIpc} relay pattern.
+ * relays it over the WS as a `provenance.upload.request` / `.complete` /
+ * `.defer` and pipes the response back as a {@link ProvenanceResponseIpc}.
+ * Mirrors the {@link CacheRequestIpc} relay pattern.
+ *
+ * `defer` captures a frozen, DSSE-signed statement for later minting (the
+ * transient mint-failure path): no upload happens; the orchestrator persists
+ * the envelope in its deferred-attestation outbox instead.
  */
 export interface ProvenanceRequestIpc {
     type: 'provenance.request';
@@ -217,10 +235,18 @@ export interface ProvenanceRequestIpc {
     op: ProvenanceRequestOp;
     /** Primary subject digest (lowercase hex) — the storage-key discriminator. */
     subjectDigest: string;
-    /** Caller-supplied artifact name. `complete` only. */
+    /** Caller-supplied artifact name. `complete` + `defer` only. */
     subjectName?: string;
-    /** Bundle media type. `complete` only. */
+    /** Bundle media type. `complete` + `defer` only. */
     mediaType?: string;
+    /** Requested token audience. `defer` only. */
+    audience?: string;
+    /** SHA-256 of the frozen DSSE statement payload. `defer` only. */
+    statementHash?: string;
+    /** Frozen, DSSE-signed statement envelope. `defer` only. */
+    dsseEnvelope?: unknown;
+    /** Ephemeral public key JWK the envelope was signed with. `defer` only. */
+    publicKey?: unknown;
 }
 export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | ProvenanceRequestIpc | StepApprovalRequestIpc;
 /** Instruct the workflow runner to execute a job. */
@@ -452,9 +478,18 @@ export interface JobExecutionRequest {
     event?: Record<string, unknown>;
     /** Git provider that originated the triggering event (e.g. 'github', 'forgejo'). */
     provider?: string;
+    /**
+     * Platform provenance issuer, threaded from the orchestrator for a deferred
+     * attestation's frozen `builder.id`. Best-effort: absent when the orchestrator
+     * has no issuer wired (e.g. never authenticated to the Platform), in which
+     * case the frozen statement records an unknown issuer honestly. Not
+     * verification load-bearing — a deferred bundle's later token binds to the
+     * frozen statement by hash, and the authoritative org id lives in that token.
+     */
+    provenanceIssuer?: string;
     /** Whether to checkout the repo (default: true). */
     checkout?: boolean;
-    /** Whether this job is part of a test run triggered by `kici test`. */
+    /** Whether this job is part of a developer-initiated run triggered by `kici run`. */
     isTestRun?: boolean;
     /**
      * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`).

package/dist/execution/sandbox/parallel-scheduler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Concurrency-aware scheduler for `parallel()` step groups.
+ *
+ * A parallel group's children each run as their own observable step (own logs,
+ * status, timing, retry, cache, hooks — all task-scoped by the Phase 0 per-task
+ * isolation) through the same `runStepIteration` machinery the sequential loop
+ * uses. Children launch behind a `maxParallel` window (queued children report
+ * `pending`); the group joins at a barrier. On the first non-`continueOnError`
+ * child failure when `failFast`, every in-flight sibling's per-task abort
+ * controller is fired so its step race rejects and it is reported `cancelled`
+ * (which is NOT a failure).
+ */
+import { type StepLoopOptions, type StepNode } from './step-loop.js';
+import type { SandboxStepResult } from './types.js';
+type ParallelNode = Extract<StepNode, {
+    kind: 'parallel';
+}>;
+/** Outcome of running one parallel group. */
+export interface ParallelGroupOutcome {
+    /** True when at least one non-`continueOnError` child failed. */
+    failed: boolean;
+    /** Name of the first failing child (drives the job failure reason). */
+    failedStepName?: string;
+    /** Per-child results, in child array order. */
+    results: SandboxStepResult[];
+}
+/**
+ * Run a parallel group: launch children with a bounded-concurrency window, join
+ * at a barrier, and fail-fast-cancel in-flight siblings on the first hard
+ * failure.
+ */
+export declare function runParallelGroup(node: ParallelNode, opts: StepLoopOptions): Promise<ParallelGroupOutcome>;
+export {};
+//# sourceMappingURL=parallel-scheduler.d.ts.map

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

@@ -10,6 +10,36 @@ import { CheckMode } from '@kici-dev/engine';
 import type { RunnerToAgentMessage } from './ipc-protocol.js';
 import type { SandboxStepResult } from './types.js';
 import { type CachePhaseDeps } from '../cache/index.js';
+/**
+ * Thrown inside the step race when a step's own per-task abort controller fires
+ * (parallel fail-fast cancels an in-flight sibling). Distinguished from a
+ * timeout/job-deadline reject so the loop reports the step as `cancelled`
+ * (which is NOT a failure) rather than `failed`.
+ */
+export declare class StepCancelledError extends Error {
+    readonly name = "StepCancelledError";
+    constructor(stepName: string);
+}
+/**
+ * A node in the concurrency-aware step walk. A `sequential` node is one ordinary
+ * step; a `parallel` node is a `parallel()` group whose children each carry their
+ * own flat `stepIndex` (the group wrapper consumes no index).
+ */
+export type StepNode = {
+    kind: 'sequential';
+    step: Step;
+    stepIndex: number;
+} | {
+    kind: 'parallel';
+    groupId: string;
+    name: string;
+    failFast: boolean;
+    maxParallel?: number;
+    children: {
+        step: Step;
+        stepIndex: number;
+    }[];
+};
 /** Job-level hooks passed to the step loop. */
 export interface JobHooks {
     beforeStep?: HookInput;
@@ -21,7 +51,32 @@ export interface JobHooks {
 }
 /** Options for the step execution loop. */
 export interface StepLoopOptions {
+    /**
+     * Flat list of every executable step (sequential steps + parallel-group
+     * children inlined in flat-stepIndex order). `steps.length` is the flat step
+     * count used to derive hook pseudo-indices. The structural walk order (which
+     * entries are grouped) is carried separately by `stepNodes`.
+     */
     steps: Step[];
+    /**
+     * Structural walk order: sequential steps and parallel groups in array order.
+     * When present, the loop walks these nodes (dispatching parallel groups to the
+     * concurrency-aware scheduler); when absent, it walks `steps` sequentially with
+     * the array index as the stepIndex (unit-harness back-compat).
+     */
+    stepNodes?: StepNode[];
+    /**
+     * Abort the per-task controller for `stepIndex` (parallel fail-fast). Wired to
+     * the workflow-runner's `stepAbortControllers` map so an aborted sibling's
+     * `ctx.signal` fires and its step race rejects with {@link StepCancelledError}.
+     */
+    abortStep?: (stepIndex: number) => void;
+    /**
+     * Returns the per-task abort signal for `stepIndex` (the same controller
+     * `abortStep` triggers). The step race watches it so a fail-fast abort
+     * interrupts an in-flight step even if its body ignores `ctx.signal`.
+     */
+    getStepAbortSignal?: (stepIndex: number) => AbortSignal | undefined;
     /**
      * Run mode for idempotent steps. `apply` (default) converges; `check` /
      * `check-fail-on-drift` preview drift and never invoke a checked step's apply.
@@ -29,6 +84,12 @@ export interface StepLoopOptions {
     checkMode?: CheckMode;
     /** Factory that creates a StepContext for a given step index and name. */
     createStepContext: (stepIndex: number, stepName: string) => StepContext;
+    /**
+     * Run `fn` inside the step's console-capture scope so any console output it
+     * (or its hooks) produces attributes to `stepIndex`. Defaults to calling `fn`
+     * directly when absent (unit harnesses without capture wiring).
+     */
+    runWithStepCapture?: <T>(stepIndex: number, fn: () => Promise<T>) => Promise<T>;
     sendIpc: (msg: RunnerToAgentMessage) => void;
     defaultTimeoutMs: number;
     outputsMap: OutputsMap;
@@ -63,36 +124,38 @@ export interface StepLoopOptions {
     /** Job start time (epoch ms) for outcome metadata duration. */
     startTime?: number;
     /**
-     * Returns the secret key names accessed by the most recently created step context.
-     * Called after each step completes to include in step.complete IPC messages.
+     * Returns the secret key names accessed by the step context created for
+     * `stepIndex`. Called after each step completes to include in step.complete
+     * IPC messages.
      */
-    getSecretsAccessLog?: () => string[];
+    getSecretsAccessLog?: (stepIndex: number) => string[];
     /**
-     * Tear down per-step state created by the most recent `createStepContext`
-     * call. Invoked from the step-loop's `finally` after the step completes
+     * Tear down per-step state created by the `createStepContext` call for
+     * `stepIndex`. Invoked from the step-loop's `finally` after the step completes
      * (success, failure, rule-skip, or timeout) so resources like the
      * `ctx.secrets.mountFile` tmpdir get removed even on the failure paths.
      * Never throws -- errors are logged by the wired implementation.
      */
-    disposeStepResources?: () => Promise<void>;
+    disposeStepResources?: (stepIndex: number) => Promise<void>;
     /**
-     * Returns the IPC `step.secret_mount` records collected by the most
-     * recently created step context. Emitted on step completion so the
-     * orchestrator can persist the audit trail alongside `secretsAccessed`.
+     * Returns the IPC `step.secret_mount` records collected by the step context
+     * created for `stepIndex`. Emitted on step completion so the orchestrator can
+     * persist the audit trail alongside `secretsAccessed`.
      */
-    getSecretMountRecords?: () => StepSecretMountRecord[];
+    getSecretMountRecords?: (stepIndex: number) => StepSecretMountRecord[];
     /**
      * Before a step's run function executes, point KICI_ENV / KICI_PATH at fresh
-     * temp files for this step. Invoked once per executed step (NOT for rule-skipped
+     * temp files for this step (keyed by `stepIndex` so concurrent steps never
+     * share a delta file). Invoked once per executed step (NOT for rule-skipped
      * steps). The workflow-runner owns the file lifecycle.
      */
-    beforeStepEnvFiles?: () => Promise<void>;
+    beforeStepEnvFiles?: (stepIndex: number) => Promise<void>;
     /**
-     * After a step's run function completes (success OR failure), read the
-     * KICI_ENV / KICI_PATH files, apply the delta via applyEnvDelta, and truncate
-     * them for the next step. Never throws -- errors are logged by the wired impl.
+     * After a step's run function completes (success OR failure), read this
+     * step's KICI_ENV / KICI_PATH files, apply the delta via applyEnvDelta, and
+     * release them. Never throws -- errors are logged by the wired impl.
      */
-    afterStepApplyEnvFiles?: () => Promise<void>;
+    afterStepApplyEnvFiles?: (stepIndex: number) => Promise<void>;
     /**
      * Block an `approval` step (`when: 'always'`) pending an orchestrator-side
      * approval hold. The runner sends the normalized requirement and awaits the
@@ -145,6 +208,18 @@ interface StepLoopResult {
     stepResults: SandboxStepResult[];
     failureReason?: string;
 }
+/**
+ * Per-step iteration outcome returned by `runStepIteration`.
+ */
+export interface StepIterationOutcome {
+    /** The result to append to the running stepResults list. */
+    result: SandboxStepResult;
+    /** When true, the loop must break (failed step without continueOnError). */
+    shouldBreak: boolean;
+    /** Set when the step failed; carried into completion-hook outcome metadata. */
+    failedStepName?: string;
+}
+export declare function runStepIteration(step: Step, stepIndex: number, opts: StepLoopOptions): Promise<StepIterationOutcome>;
 /**
  * Execute the step loop with hook integration and step-level rule evaluation.
  *

package/dist/execution/sandbox/step-task-registry.d.ts

@@ -0,0 +1,26 @@
+import type { StepSecretMountRecord, TrackedStepSecrets } from '@kici-dev/sdk';
+/** Per-step secrets handle + its teardown closure, keyed by step index. */
+export interface StepTaskSlot {
+    secrets: TrackedStepSecrets;
+    dispose: () => Promise<void>;
+}
+/**
+ * Per-task replacement for the runner's former `currentStepSecrets` /
+ * `currentStepDispose` single-slots.
+ *
+ * The runner used to remember only the *most recent* step's secrets handle and
+ * dispose closure; the access-log / mount-record / dispose reader callbacks read
+ * that single slot. Under sequential execution that is correct (one step at a
+ * time), but two concurrently-running steps would clobber each other's
+ * secrets-audit trail. Keying every slot by the step's index keeps each step's
+ * audit trail and teardown isolated — sequential behavior is identical, Phase 1
+ * concurrency is correct.
+ */
+export declare class StepTaskRegistry {
+    #private;
+    set(stepIndex: number, slot: StepTaskSlot): void;
+    getAccessLog(stepIndex: number): string[];
+    getMountRecords(stepIndex: number): StepSecretMountRecord[];
+    dispose(stepIndex: number): Promise<void>;
+}
+//# sourceMappingURL=step-task-registry.d.ts.map

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

@@ -150,8 +150,8 @@ export interface SandboxStepResult {
     name: string;
     /** Zero-based index of the step within the job. */
     stepIndex: number;
-    /** Step execution status. */
-    status: 'success' | 'failed' | 'skipped';
+    /** Step execution status. `cancelled` = a parallel sibling fail-fast cancel. */
+    status: 'success' | 'failed' | 'skipped' | 'cancelled';
     /** Step duration in milliseconds. */
     durationMs: number;
     /** Error details when status is 'failed'. */

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

@@ -35,7 +35,7 @@ export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[]
  * NOT serialized across the process boundary. This means zx $ runs natively
  * inside this process with full shell access.
  */
-export declare function createSandboxStepContext(workDir: string, stepIndex: number, stepName: string, request: JobExecutionRequest, maskedSendFn: (msg: RunnerToAgentMessage) => void, outputsMap: OutputsMap, refMap: StepRefMap, operatorSecretKeys: Set<string>, secretOutputs: Map<string, string>, jobOutputsMap: OutputsMap, secrets: TrackedStepSecrets, masker: LogMasker): StepContext;
+export declare function createSandboxStepContext(workDir: string, stepIndex: number, stepName: string, request: JobExecutionRequest, maskedSendFn: (msg: RunnerToAgentMessage) => void, outputsMap: OutputsMap, refMap: StepRefMap, operatorSecretKeys: Set<string>, secretOutputs: Map<string, string>, jobOutputsMap: OutputsMap, secrets: TrackedStepSecrets, masker: LogMasker, signal: AbortSignal): StepContext;
 /**
  * Derive the fan-out position (`ctx.fanout`) from a dispatch request. Returns
  * `undefined` for a non-fan-out job (no `fanoutTotal`), so `ctx.fanout` is only
@@ -44,4 +44,25 @@ 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 step loop's KICI_ENV/KICI_PATH callbacks with a per-step delta-file
+ * pair (keyed by step index). `beforeStepEnvFiles(stepIndex)` lazily creates the
+ * step's pair and points the runner's process.env at it (each step's zx $
+ * snapshots process.env at context creation, which happens AFTER this
+ * before-hook, so the shell sees them; the pre-fork env allowlist does not
+ * re-filter runtime-set vars). `afterStepApplyEnvFiles(stepIndex)` applies that
+ * step's delta and releases the pair.
+ *
+ * Env-isolation contract: under sequential execution this is identical to a
+ * single shared pair truncated between steps — each step still sees only its own
+ * delta. The pair is now per-step so two concurrently-running steps cannot
+ * corrupt each other's delta file. `process.env.KICI_ENV` / `process.env.KICI_PATH`
+ * remain process-global, so Phase 1 forbids `setEnv` / `addPath` / `$KICI_ENV`
+ * writes inside `parallel()` children (compile-time validation); Phase 0 only
+ * makes the file pair per-task.
+ */
+export declare function buildStepEnvFileHooks(operatorSecretKeys: Set<string>, maskedSend: (msg: RunnerToAgentMessage) => void): {
+    beforeStepEnvFiles: (stepIndex: number) => Promise<void>;
+    afterStepApplyEnvFiles: (stepIndex: number) => Promise<void>;
+};
 //# sourceMappingURL=workflow-runner.d.ts.map

package/dist/index.js

@@ -20,7 +20,14 @@ import https from "node:https";
 import http from "node:http";
 import "node:url";
 var __defProp = Object.defineProperty;
-var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
 var __exportAll = (all, no_symbols) => {
 	let target = {};
 	for (var name in all) __defProp(target, name, {
@@ -30,7 +37,6 @@ var __exportAll = (all, no_symbols) => {
 	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
-import.meta.url;
 //#endregion
 //#region src/config.ts
 /** Execution mode for the agent's sandbox backend. Mirrors the runtime enum. */

package/dist/provenance/attest.d.ts

@@ -1,13 +1,31 @@
 import { type KiciBundle } from '@kici-dev/engine/provenance/bundle';
 import type { OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
-import { type ProvenanceSubject } from './statement-builder.js';
+import { type LocalBuildContext, type ProvenanceSubject } from './statement-builder.js';
+/** The frozen, DSSE-signed attestation the agent reports for later fulfilment. */
+export interface DeferredAttestationReport {
+    subjectName: string;
+    subjectDigest: string;
+    audience: string;
+    mediaType: string;
+    statementHash: string;
+    dsseEnvelope: KiciBundle['dsseEnvelope'];
+    publicKey: Record<string, unknown>;
+}
 export interface AttestDeps {
-    /** P1.4 relay: returns a KiCI ID token bound to the current job. */
+    /** P1.4 relay: returns a minted KiCI ID token or a transient `deferred` signal. */
     getIdToken: (opts: {
         audience: string;
     }) => Promise<OidcTokenResult>;
     /** Upload the serialized bundle; returns the storage key it was written to. */
     persist: (bundle: KiciBundle, subjectDigest: string) => Promise<string>;
+    /**
+     * Report a frozen, DSSE-signed statement for later minting (the transient
+     * mint-failure path). Required only when the relay may defer; the live path
+     * never calls it.
+     */
+    reportDeferred?: (report: DeferredAttestationReport) => Promise<void>;
+    /** Agent-local job facts used to freeze a statement when the mint defers. */
+    localContext?: LocalBuildContext;
     builderVersions: {
         'kici-agent': string;
         'kici-orchestrator': string;
@@ -19,11 +37,16 @@ export interface AttestInput {
     subject: ProvenanceSubject;
     audience?: string;
 }
-export interface AttestResult {
+/** A minted-and-uploaded attestation, or a deferred one captured for later. */
+export type AttestResult = {
     storageKey: string;
     bundle: KiciBundle;
     subjectDigest: string;
-}
+} | {
+    deferred: true;
+    statementHash: string;
+    subjectDigest: string;
+};
 export declare function attestProvenance(deps: AttestDeps, input: AttestInput): Promise<AttestResult>;
 /**
  * Pick the primary digest (`sha256` preferred) as the storage-key discriminator.

package/dist/provenance/statement-builder.d.ts

@@ -5,6 +5,7 @@
  * statement's identity equals the token's identity by construction.
  */
 import { type KiciProvenanceStatement } from '@kici-dev/engine/provenance/schema';
+import type { SourceOrigin } from '@kici-dev/engine';
 /** The KiCI identity-token claims the builder reads (Platform server-truth). */
 export interface ProvenanceTokenClaims {
     iss: string;
@@ -15,6 +16,12 @@ export interface ProvenanceTokenClaims {
     kici_run_id: string;
     kici_job_id: string;
     orchestrator_id?: string | null;
+    /** Authoritative origin: the customer's public org id (Platform-asserted). */
+    org_id?: string;
+    /** Source-origin brand: triggered vs run-remote (local working-tree overlay). */
+    source_origin?: SourceOrigin;
+    /** Informational source provider (github / gitlab / bitbucket / local). */
+    provider?: string | null;
 }
 /** Caller-supplied artifact subject: a name plus a lowercase-hex digest map. */
 export interface ProvenanceSubject {
@@ -33,6 +40,49 @@ export interface BuildStatementInput {
     /** ISO-8601 timestamp with offset. */
     finishedOn: string;
 }
+/**
+ * Agent-local job context used to freeze a provenance statement for a deferred
+ * attestation. When the Platform mint fails transiently there is no identity
+ * token to read claims from, so the statement is built from facts the agent
+ * already holds about the job it just ran. Only the identity token is deferred;
+ * these attested facts are sealed (DSSE-signed) at build time.
+ */
+export interface LocalBuildContext {
+    repository: string;
+    ref: string;
+    sha: string | null;
+    workflowRef: string;
+    runId: string;
+    jobId: string;
+    orgId?: string;
+    sourceOrigin?: SourceOrigin;
+    /**
+     * Platform provenance issuer for the `builder.id`. The agent does not always
+     * know it at build time (the orchestrator may be disconnected — that is why
+     * the mint deferred), so it is best-effort; an empty string yields a
+     * `/orchestrator/unknown` builder id. This field is not verification
+     * load-bearing for a deferred bundle: the later token binds to the frozen
+     * statement by hash, not by field-for-field cross-check.
+     */
+    issuer: string;
+}
+/**
+ * Build a frozen SLSA v1.0 provenance statement from agent-local job context,
+ * for a deferred attestation (no minted identity token yet). Marks
+ * `attestationOrigin: 'deferred'` in the internal parameters. The caller
+ * DSSE-signs the returned statement immediately and computes its statement hash
+ * — the binding the later OIDC mint commits to (truth-contract property 2).
+ */
+export declare function buildLocalProvenanceStatement(input: {
+    context: LocalBuildContext;
+    subject: ProvenanceSubject;
+    builderVersions: {
+        'kici-agent': string;
+        'kici-orchestrator': string;
+    };
+    startedOn: string;
+    finishedOn: string;
+}): KiciProvenanceStatement;
 /** Build a KiCI SLSA v1.0 provenance statement (validates against the P1.1 schema). */
 export declare function buildProvenanceStatement(input: BuildStatementInput): KiciProvenanceStatement;
 //# sourceMappingURL=statement-builder.d.ts.map