@kici-dev/agent 0.4.0 → 0.5.0

package/dist/execution/download.d.ts

@@ -4,6 +4,12 @@
  * Extracted from workflow-loader.ts to avoid duplication across
  * dep-restore.ts and workflow-loader.ts.
  */
+/**
+ * Retries a pre-signed upload makes after its first attempt, matching the
+ * dep-tarball download's ceiling (`MAX_RETRIES` in `dep-restore.ts`) so both
+ * halves of the agent's object-storage traffic give up at the same point.
+ */
+export declare const UPLOAD_MAX_RETRIES = 2;
 /**
  * Download content from an HTTP/HTTPS URL.
  *
@@ -15,15 +21,34 @@
  */
 export declare function downloadUrl(url: string): Promise<Buffer>;
 /**
- * Upload a buffer to a pre-signed S3 URL via HTTP PUT.
+ * Upload a buffer to a pre-signed S3 URL via HTTP PUT, retrying a transient
+ * failure.
  *
  * Used for direct-to-S3 uploads of bundles and dep tarballs. Localhost /
  * 127.0.0.1 URLs are rewritten via `resolveOrchestratorUrl` so the
  * filesystem cache backend's signed URLs work from container agents that
  * can't reach the orchestrator's host loopback directly.
  *
+ * **Why retrying is safe here.** A pre-signed PUT writes one whole object at a
+ * single key: there is no multipart session, no append, and no
+ * server-generated identity, so a repeat attempt writes the same bytes to the
+ * same key and the last write wins. S3 also only makes an object visible once
+ * the body has been received in full, so an attempt that died mid-body left
+ * nothing behind. A retry therefore cannot double-write or produce a torn
+ * object — which is why every AWS SDK retries PUTs by default.
+ *
+ * Only a failure that can plausibly differ next time is repeated — see
+ * {@link isRetryableUploadFailure}.
+ *
  * @param url - The pre-signed URL to upload to
  * @param data - The buffer to upload
+ * @param opts.baseDelayMs - Backoff before the first retry (doubles thereafter)
+ * @param opts.timeoutMs - Per-attempt socket-inactivity timeout (see
+ *   {@link UPLOAD_TIMEOUT_MS}); an override exists so a test can drive the
+ *   stall path without waiting out the production budget.
  */
-export declare function uploadToPresignedUrl(url: string, data: Buffer): Promise<void>;
+export declare function uploadToPresignedUrl(url: string, data: Buffer, opts?: {
+    baseDelayMs?: number;
+    timeoutMs?: number;
+}): Promise<void>;
 //# sourceMappingURL=download.d.ts.map

package/dist/execution/generator-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The single builder for a `DynamicJobFn`'s context.
+ *
+ * A generator is evaluated twice — once pre-dispatch to produce the job list,
+ * and once inside the sandbox to recover the step closures a `LockJob` cannot
+ * carry. `extractStepsFromDynamicJob` throws when the target job is missing on
+ * re-evaluation, so a generator whose two calls see different contexts is
+ * unsound by construction. Every call site builds its context here so the two
+ * cannot drift apart.
+ */
+import type { DynamicJobContext, RepoInfo } from '@kici-dev/sdk';
+/**
+ * The source / workflow repo pair a global workflow's generator sees.
+ *
+ * `sourceRepo.path` is an absolute path into THIS evaluation's work directory:
+ * it is NOT stable across the two evaluations (a different `workDir`, possibly
+ * a different machine). Its *contents* are stable; the path is not. So read
+ * through the path — never embed it in a generated job name, a job output, or
+ * anything else the two evaluations are compared on.
+ *
+ * `RepoInfo.ref` and `.sha` are optional: an evaluation that has no checkout
+ * metadata still supplies the pair. Never assume either is present.
+ */
+export interface GeneratorRepoPair {
+    sourceRepo: RepoInfo;
+    workflowRepo: RepoInfo;
+}
+/** Input for {@link buildGeneratorContext}. */
+export interface GeneratorContextInput {
+    workflowName: string;
+    /**
+     * The raw wire event. Untyped JSON that, per the unified event protocol,
+     * always carries the normalized event envelope.
+     */
+    event: Record<string, unknown>;
+    env: Record<string, string | undefined>;
+    /** Present for a global workflow; omitted entirely otherwise. */
+    repos?: GeneratorRepoPair;
+    /** Frozen upstream outputs for a result-aware generator. */
+    needs?: NonNullable<DynamicJobContext['ctx']['needs']>;
+    $: DynamicJobContext['$'];
+    log: DynamicJobContext['log'];
+    kici: DynamicJobContext['kici'];
+}
+/**
+ * Build the context handed to a `DynamicJobFn`.
+ *
+ * Optional members are spread conditionally rather than assigned `undefined`,
+ * so an absent `needs` / repo pair leaves no key behind — a present-but-
+ * undefined key reads as "declared" to a generator and serializes differently
+ * between the two evaluations.
+ */
+export declare function buildGeneratorContext(input: GeneratorContextInput): DynamicJobContext;
+//# sourceMappingURL=generator-context.d.ts.map

package/dist/execution/global-eval-runner.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The pre-run global eval round.
+ *
+ * One round runs per (event × workflow repo), on an agent that already holds
+ * both trees on disk. For each candidate global workflow it runs the workflow's
+ * `filter` — deciding whether the workflow applies to the source repo at all —
+ * and, for a survivor, its `DynamicJobFn`s, so the orchestrator can dispatch
+ * generated jobs it could not otherwise see. The round precedes every run row:
+ * a `filter` returning `false` means no run is created.
+ *
+ * Shape is modelled on `init-runner.ts` — load the module, resolve the target,
+ * evaluate under `withTimeout`, return a structured result. As there, author
+ * code runs in the agent's ordinary module loader: no `vm`, no `new Function`,
+ * no dynamic `eval`.
+ *
+ * Two properties are load-bearing and easy to lose:
+ *
+ * - **One bad candidate never sinks the round.** A candidate whose filter or
+ *   generator throws, or that blows its budget, comes back
+ *   `{ run: false, indeterminate: true, reason }` while its siblings carry real
+ *   verdicts. Several unrelated org-wide workflows share a round; a single
+ *   broken filter suppressing all of them would be a silent outage.
+ * - **Candidates are STARTED sequentially.** They share one checkout and one
+ *   working directory, so a parallel `$` would race on cwd. This is a strict
+ *   guarantee on the happy path and **best-effort past a timeout**: `withTimeout`
+ *   races rather than cancels, so a candidate that blew its own budget is still
+ *   running when the next one starts. Nothing can preempt user code mid-`await`,
+ *   so the round bounds the damage rather than eliminating it — the loop stops
+ *   at the round deadline (and on the caller's abort signal), which caps the
+ *   overlap at one orphaned candidate instead of the whole remaining queue.
+ */
+import type { RepoInfo, DynamicJobContext, Logger } from '@kici-dev/sdk';
+import { type $ as Shell } from 'zx';
+import type { ChangedFilesStatus, GlobalEvalRoundResult } from '@kici-dev/engine';
+/** One workflow the round must decide on, as the lock file describes it. */
+export interface GlobalEvalCandidate {
+    workflowName: string;
+    /** Repo-relative path of the workflow module inside the workflow checkout. */
+    sourceFile: string;
+    /** From `LockWorkflow.hasFilter` — skip the filter call entirely when false. */
+    hasFilter: boolean;
+}
+/** Arguments for {@link runGlobalEvalRound}. */
+export interface GlobalEvalRoundArgs {
+    /** Absolute path of the workflow-repo checkout (modules are loaded from here). */
+    workflowDir: string;
+    /** Absolute path of the source-repo checkout. */
+    sourceDir: string;
+    repos: {
+        sourceRepo: RepoInfo;
+        workflowRepo: RepoInfo;
+    };
+    candidates: GlobalEvalCandidate[];
+    /** The raw wire event, carrying the normalized event envelope. */
+    event: Record<string, unknown>;
+    changedFiles: string[];
+    /**
+     * Availability of `changedFiles`. Required, not defaulted: it feeds the
+     * throwing accessor on `FilterContext`, and defaulting it to `'fetched'`
+     * would let a diff-less event read as an empty diff and silently suppress
+     * every path-gated workflow in the round.
+     */
+    changedFilesStatus: ChangedFilesStatus;
+    /** Wall-clock budget for the whole round. */
+    roundTimeoutMs: number;
+    /** Wall-clock budget for one candidate (its filter plus its generators). */
+    candidateTimeoutMs: number;
+    /**
+     * Caller's cancellation signal. The round stops starting new candidates once
+     * it fires; the one already in flight cannot be preempted (see the module
+     * doc comment) but its verdict is discarded.
+     */
+    signal?: AbortSignal;
+    /** zx shell handed to filters and generators. Defaults to the ambient `$`. */
+    $?: typeof Shell;
+    /** Logger handed to generators. Defaults to a no-op. */
+    log?: Logger;
+    /** KiCI API handed to generators. Defaults to one that rejects every call. */
+    kici?: DynamicJobContext['kici'];
+    /**
+     * Module loader seam. Defaults to `loadWorkflowSource` against `workflowDir`;
+     * a caller that already holds the modules (or a unit test) supplies its own.
+     */
+    loadModule?: (sourceFile: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * Run one global eval round and return every candidate's verdict, in candidate
+ * order. Never throws: a round that exceeds `roundTimeoutMs` reports whatever
+ * it established and marks the rest indeterminate.
+ */
+export declare function runGlobalEvalRound(args: GlobalEvalRoundArgs): Promise<GlobalEvalRoundResult>;
+//# sourceMappingURL=global-eval-runner.d.ts.map

package/dist/execution/global-workflow-env.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The single writer of the seven `KICI_*` ambient env keys a global workflow's
+ * user code sees.
+ *
+ * It lives here rather than in `sandbox/workflow-runner.ts` because that module
+ * calls `main()` at import time — it is the sandbox process entry point — so the
+ * agent's own process cannot import it. The pre-dispatch global eval round runs
+ * in the agent process and must set exactly the same keys the sandbox does.
+ *
+ * Why exactly the same keys: `extractAndNormalizeSteps` hands a `DynamicJobFn`
+ * `process.env` as its `env`, and a generator is evaluated twice — once
+ * pre-dispatch, once inside the sandbox to recover the step closures a `LockJob`
+ * cannot carry. A generator that reads `process.env.KICI_SOURCE_REPO_PATH` and
+ * gets a value on one call and `undefined` on the other has seen two different
+ * worlds, which `extractStepsFromDynamicJob` turns into a hard determinism
+ * failure. `buildGeneratorContext` keeps the two contexts' *shape* identical; it
+ * cannot keep the ambient env identical, which is what this does.
+ */
+import type { RepoInfo } from '@kici-dev/sdk';
+/** The source / workflow repo pair a global-workflow evaluation runs against. */
+export interface GlobalWorkflowRepos {
+    sourceRepo: RepoInfo;
+    workflowRepo: RepoInfo;
+}
+/**
+ * Derive an `owner/repo` identifier from a clone URL, stripping the trailing
+ * `.git` and any `http(s)://host/` prefix.
+ */
+export declare function repoIdentifierFromUrl(repoUrl: string): string;
+/** Every env key {@link applyGlobalWorkflowEnv} writes, in one place. */
+export declare const GLOBAL_WORKFLOW_ENV_KEYS: readonly ['KICI_IS_GLOBAL_WORKFLOW', 'KICI_WORKFLOW_REPO_PATH', 'KICI_SOURCE_REPO_PATH', 'KICI_SOURCE_REPO', 'KICI_SOURCE_BRANCH', 'KICI_SOURCE_SHA', 'KICI_WORKFLOW_REPO'];
+/**
+ * Inject the seven global-workflow env keys and return a restorer that puts
+ * `process.env` back exactly as it was — each key reset to its prior value, or
+ * deleted if it had none.
+ *
+ * **The restorer is mandatory for any caller in a long-lived process.** The
+ * sandbox may ignore it: it runs one job per forked child, which exits. The
+ * pre-dispatch global eval round may NOT: it runs in the agent process, which
+ * serves many dispatches from one `JobRunner`. Leaving the keys set there is
+ * this module's own hazard running backwards — a later NON-global
+ * `DynamicJobFn` evaluation builds its generator context with
+ * `env: process.env` still carrying `KICI_IS_GLOBAL_WORKFLOW=true` and a
+ * `KICI_SOURCE_REPO_PATH` pointing at a deleted work directory, while that
+ * job's own sandbox re-evaluation sees neither (`buildSanitizedEnv` scrubs the
+ * whole `KICI_*` namespace on the trusted profile, and the default profile is
+ * allowlist-only). That is the same two-worlds determinism failure, injected
+ * into an unrelated job.
+ *
+ * `RepoInfo.ref` / `.sha` are optional, so an evaluation with no checkout
+ * metadata writes an empty string rather than leaving the key unset — matching
+ * how `KICI_WORKFLOW_REPO` already handles a missing identifier. Assigning
+ * `undefined` to a `process.env` key would stringify to `"undefined"`, which is
+ * worse than either.
+ */
+export declare function applyGlobalWorkflowEnv(repos: GlobalWorkflowRepos): () => void;
+//# sourceMappingURL=global-workflow-env.d.ts.map

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

@@ -1,5 +1,6 @@
-import type { Workflow } from '@kici-dev/sdk';
-import { type MatrixValues } from '@kici-dev/engine';
+import type { $ as Shell } from 'zx';
+import type { Workflow, RepoInfo } from '@kici-dev/sdk';
+import { type ChangedFilesStatus, type MatrixValues } from '@kici-dev/engine';
 /**
  * Result of evaluating dynamic fields on a job.
  * Only fields that were flagged as dynamic and successfully resolved are set.
@@ -14,7 +15,56 @@ export interface InitResult {
      * The orchestrator re-materializes these into N execution jobs at dispatch.
      */
     matrixValues?: MatrixValues[];
+    /**
+     * Verdict of the workflow-level `filter`, set only when the init job was asked
+     * to evaluate one (`flags.hasFilter`). `false` means the workflow does not
+     * apply and its job must not be dispatched.
+     *
+     * Optional on purpose: an agent that predates the filter never sets it, so the
+     * orchestrator reads absence as "no verdict was reported", never as "suppress".
+     */
+    filterPassed?: boolean;
+}
+/**
+ * Everything a workflow-level `filter` needs beyond the workflow module and the
+ * event. Supplied by the caller because none of it is derivable here: the source
+ * tree lives wherever the init job materialized it, and the diff is ground truth
+ * from that same clone.
+ */
+export interface FilterEvalInput {
+    /** The repo whose event triggered this evaluation. */
+    sourceRepo: RepoInfo;
+    /** The repo that registered the workflow — identical to `sourceRepo` here. */
+    workflowRepo: RepoInfo;
+    changedFiles: string[];
+    changedFilesStatus: ChangedFilesStatus;
+    env?: Record<string, string | undefined>;
+    /** zx shell handed to the filter. Defaults to the ambient `$`. */
+    $?: typeof Shell;
 }
+/**
+ * Run a workflow's `filter` and report whether the workflow applies.
+ *
+ * Shared by both agent-side evaluation sites for a same-repo workflow: the init
+ * job that gates each static job's dispatch, and the dynamic-eval job that gates
+ * whether a generator runs at all. Both must reach the same verdict from the same
+ * inputs, so neither builds the context itself.
+ *
+ * The context is built through `createFilterContext` rather than as an object
+ * literal: the factory installs `changedFiles` as a throwing getter, so a filter
+ * that reads the diff on an event that has none fails loudly instead of seeing an
+ * empty list. A `false` verdict dispatches none of the workflow's own jobs, so a
+ * silently-empty diff would suppress it on a mistake. On this same-repo path the
+ * verdict is at least recoverable — the run row exists, carrying the `__init__*`
+ * jobs, and this evaluation's own step log records the verdict; it is the
+ * organization-wide path, which runs elsewhere, that leaves nothing behind.
+ *
+ * A throwing filter propagates: the evaluating job fails, which surfaces as a
+ * failed run. "Could not decide" is never treated as "do not run" — that would
+ * be a false green, the same reasoning `buildJobRuleCompletion` applies to a rule
+ * whose `check()` threw.
+ */
+export declare function evaluateWorkflowFilter(workflow: Workflow, event: Record<string, unknown>, input: FilterEvalInput | undefined, timeoutMs: number): Promise<boolean>;
 /**
  * Evaluate dynamic fields (context, env, concurrencyGroup) on a job.
  *
@@ -26,16 +76,23 @@ export interface InitResult {
  * -: If a dynamic function returns undefined/null, the field is left undefined.
  * -: Each dynamic function call is wrapped in a timeout (default 60s).
  *
+ * A workflow-level `filter` is evaluated FIRST when `flags.hasFilter` is set. A
+ * `false` verdict returns immediately: no job of that workflow will be
+ * dispatched, so evaluating this one's dynamic fields would run customer code
+ * whose result nothing can consume.
+ *
  * @param workflow - The extracted Workflow object
  * @param jobName - Name of the job whose dynamic fields to evaluate
  * @param event - Normalized event envelope — same shape every dynamic-function call site receives.
  * @param flags - Which fields are dynamic and need evaluation
  * @param timeoutMs - Timeout per dynamic function call (default 60_000ms)
+ * @param filterInput - Source tree + diff the workflow's `filter` reads. Required when `flags.hasFilter`.
  */
 export declare function evaluateDynamicFields(workflow: Workflow, jobName: string, event: Record<string, unknown>, flags: {
     dynamicContext: boolean;
     dynamicEnv: boolean;
     dynamicConcurrencyGroup: boolean;
     dynamicMatrix?: boolean;
-}, timeoutMs?: number): Promise<InitResult>;
+    hasFilter?: boolean;
+}, timeoutMs?: number, filterInput?: FilterEvalInput): Promise<InitResult>;
 //# sourceMappingURL=init-runner.d.ts.map

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

@@ -1,7 +1,69 @@
 import type { AgentToOrchestratorMessage, JobDispatch } from '@kici-dev/engine';
+import type { LogStream } from '@kici-dev/engine';
 import type { AppConfig } from '../config.js';
+import { type FilterEvalInput } from './init-runner.js';
 import { buildNeedsContext } from '@kici-dev/sdk';
+import type { $ as Shell } from 'zx';
 import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, ArtifactRequestIpc, ArtifactResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
+/**
+ * Materialize the source tree a non-global workflow's `filter` reads through
+ * `ctx.sourceRepo.path`.
+ *
+ * An init or dynamic-eval job normally restores only `.kici/` from the cached
+ * source tarball — enough to import the workflow module, but a directory with no
+ * repo in it. A filter that reads a file or shells out against that path would
+ * get a confidently wrong answer, and `changedFiles` could not be computed at
+ * all, so a filter-bearing job clones the source repo into a sibling directory.
+ *
+ * When no tarball was attached the job already cloned the whole repo into
+ * `workDir`, and that clone is reused rather than duplicated — including the
+ * local working-tree case, where there is no repo url and `workDir` IS the tree.
+ *
+ * A tarball with no repo url is the one combination that cannot be honoured:
+ * `workDir` holds `.kici/` alone and there is nothing to clone from. Returning it
+ * would hand the filter a directory in which every path test answers "absent" —
+ * the exact silent lie this function exists to prevent — so it throws instead.
+ */
+export declare function ensureFilterSourceDir(dispatch: JobDispatch, workDir: string): Promise<string>;
+/**
+ * Build the context a non-global workflow's `filter` is evaluated against.
+ *
+ * `sourceRepo` and `workflowRepo` are the same repo — that is what "non-global"
+ * means — so both carry the same identifier, path, ref, and sha. The zx shell is
+ * rooted at the source tree and streams into the evaluating step's log, matching
+ * what the global eval round hands its own filters.
+ *
+ * They are two distinct objects all the same. Being the same repo is a fact
+ * about their VALUES, not a licence to hand the author one object under two
+ * names: a filter that mutated `ctx.sourceRepo` would silently see
+ * `ctx.workflowRepo` change with it, which happens on no other path.
+ */
+export declare function buildInitFilterInput(dispatch: JobDispatch, event: Record<string, unknown>, workDir: string, emit: (line: string, stream: LogStream) => void): Promise<FilterEvalInput>;
+/**
+ * Build the per-invocation zx `$` a global eval round hands to filters and
+ * generators, so a `await $\`…\`` inside one is visible in the eval step's log.
+ *
+ * **`env` is the LIVE `process.env` reference, never a spread.** A spread is a
+ * snapshot taken when the shell is built, which is before the round applies the
+ * seven `KICI_*` keys — so a filter that shells out (`$\`printenv
+ * KICI_SOURCE_REPO_PATH\``, or any subprocess inheriting env) would see nothing
+ * here while the sandbox re-evaluation's ambient `$` resolves `process.env`
+ * after `setupGlobalWorkflowEnv` has run and does see them. That is the same
+ * two-worlds determinism failure the cwd choice below exists to prevent, one
+ * layer down. Passing the live reference reproduces the ambient `$`'s own
+ * behaviour, which is what the sandbox uses.
+ *
+ * `verbose: true` + `makeStreamingZxLog` honors a per-call `quiet: true`, so a
+ * decrypted secret never leaks into the log.
+ *
+ * `emit` is a callback rather than the `LogStreamer` itself so the caller can
+ * route it through its own closed-guard: `LogStreamer.destroy()` sets no closed
+ * flag and `addLine` buffers unconditionally, so a subprocess line arriving
+ * after the step was reported would otherwise emit a `log.chunk` for a terminal
+ * step. That is the likeliest path for it — an orphaned candidate is usually
+ * orphaned *because* it is waiting on a subprocess.
+ */
+export declare function buildEvalShell(cwd: string, emit: (line: string, stream: LogStream) => void): Promise<typeof Shell>;
 /**
  * Dependencies injected into JobRunner.
  */
@@ -276,6 +338,18 @@ export declare class JobRunner {
      * uncommitted changes).
      */
     private cloneAndApplyOverlay;
+    /**
+     * Materialize the init job's workflow source into `workDir`. A test run ships
+     * its full working tree as an encrypted overlay tarball (`fullRepo`) rather
+     * than a git repo, so skip the clone and let the overlay populate the
+     * workspace — the same handling the normal execution-job path uses. Otherwise
+     * restore from the cached tarball if present, else clone. In every case, apply
+     * an attached overlay tarball afterward (test runs with uncommitted changes;
+     * for a fullRepo run this is what actually populates the workspace, so the
+     * init job resolves a dynamic context against the real source tree instead of
+     * an empty directory).
+     */
+    private materializeInitJobSource;
     /**
      * Phase 2 of build: install dependencies locally if needed for the build,
      * and (when the orchestrator has flagged the dep cache as stale) pack
@@ -288,6 +362,30 @@ export declare class JobRunner {
      * it to the source cache.
      */
     private packAndUploadSource;
+    /**
+     * Clone both repos for a global eval round and materialize the workflow
+     * repo's dependencies, mirroring the sandbox's own dual-clone: the workflow
+     * repo under `<workDir>/workflow`, the source repo under `<workDir>/source`.
+     *
+     * `.kici/` lives in the WORKFLOW repo for a global workflow, so deps and the
+     * scratch-dir git exclude both apply to that checkout, never the source one.
+     */
+    private checkoutForGlobalEvalRound;
+    /**
+     * Handle a pre-run global eval round.
+     *
+     * The round runs once per (event × workflow repo) BEFORE any run row exists:
+     * it checks out the workflow repo and the source repo, then runs each
+     * candidate global workflow's `filter` and — for a survivor — its
+     * `DynamicJobFn`s, so the orchestrator learns which workflows apply to this
+     * source repo and which jobs each one generates.
+     *
+     * A candidate that fails is reported indeterminate inside the result, not as
+     * a job failure: the round carries several unrelated org-wide workflows, and
+     * one broken filter must not suppress the rest. The job itself fails only
+     * when the checkout or the round machinery breaks.
+     */
+    private handleGlobalEvalRound;
     /**
      * Handle an init-only job.
      *

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,6 +101,15 @@ 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;
     /**

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

@@ -16,11 +16,13 @@
 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 { Step, StepInput, StepContext, RepoInfo, EventPayload } from '@kici-dev/sdk';
 import type { NeedsContext, FanoutPosition, EventDefinition } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap, TrackedStepSecrets } from '@kici-dev/sdk';
 import type { RunnerToAgentMessage, JobExecutionRequest } 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';
 /**
  * Build `ctx.needs` for a job's steps from the dispatch envelope. Reconstructs
@@ -103,6 +105,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 +188,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[];
 }>;