@kici-dev/agent 0.1.16 → 0.1.18

package/dist/execution/dep-installer.d.ts

@@ -4,12 +4,17 @@
  * When the dep cache is unavailable or a download fails, the agent installs
  * `.kici/` dependencies directly with the repository's package manager.
  *
- * The package manager is detected from the cloned repo (npm / pnpm); the
+ * The package manager is detected from the cloned repo (npm / pnpm / yarn); the
  * presence of `.kici/package.json` signals that deps should be installed. npm
  * is the default and ships with every Node.js install; pnpm is used when the
  * repo is a pnpm workspace so a `.kici/` member can resolve in-repo
- * `workspace:` siblings. yarn is detected but not yet supported and is
- * rejected with an actionable error.
+ * `workspace:` siblings. yarn is supported in both flavors: classic (v1) reads
+ * `.kici/.npmrc` for registry auth and links version-range workspace siblings;
+ * berry (v2+) reads a synthesized `.kici/.yarnrc.yml` for auth, runs with a
+ * forced `nodeLinker: node-modules` (so the resulting tree matches classic/npm
+ * and the runner's plain node resolution holds), and resolves
+ * `workspace:`/`portal:` siblings. Either flavor links the sibling but does not
+ * build it, so the agent builds the in-repo closure after install.
  *
  * Security: the install runs with an isolated per-invocation cache/store
  * directory to prevent cache poisoning across build jobs — a malicious
@@ -49,4 +54,8 @@ export interface InstallDepsOptions {
  * @param opts    - Optional registry / installEnv / repoRoot configuration.
  */
 export declare function installDeps(kiciDir: string, opts?: InstallDepsOptions): Promise<void>;
+/** Pure: argv for `yarn install` with an isolated cache folder. */
+export declare function buildYarnInstallArgs(cacheDir: string, hasPrivateRegistry: boolean): string[];
+/** Pure: argv for a berry `yarn install`. Cache + linker live in .yarnrc.yml. */
+export declare function buildYarnBerryInstallArgs(): string[];
 //# sourceMappingURL=dep-installer.d.ts.map

package/dist/execution/dep-packer.d.ts

@@ -6,13 +6,21 @@
  * **repo-root-relative** (cwd = the clone root) so restore is a single layout
  * regardless of package manager:
  *
- * - npm / yarn: just `.kici/node_modules`.
+ * - npm: just `.kici/node_modules`.
  * - pnpm: `.kici/node_modules` plus the repo-root `node_modules/.pnpm` virtual
  *   store and the in-repo `workspace:` sibling package directories `.kici`
  *   depends on (with their built output). pnpm lays `.kici/node_modules` out as
  *   symlinks into the root store and into sibling dirs that live outside
  *   `.kici/`, so packing `.kici/node_modules` alone would capture dangling
  *   links — the store and siblings must travel together.
+ * - yarn (classic + berry): the resolved node_modules root (standalone `.kici`
+ *   → `.kici/node_modules`; hoisted workspace member → the repo-root
+ *   `node_modules`) plus the in-repo sibling package directories `.kici` depends
+ *   on (with their built output), whose symlinks would dangle otherwise. Berry
+ *   runs with a forced `nodeLinker: node-modules`, so its tree has the same
+ *   node_modules shape as classic and is packed identically (the flavor only
+ *   changes how siblings are referenced — version range vs `workspace:`/`portal:`
+ *   — not the packed layout).
  *
  * Uses tar.gz (Node.js built-in zlib, no external binary) in portable mode to
  * strip user/group info for cross-machine consistency; symlinks are preserved

package/dist/execution/env-init/presets/directives.d.ts

@@ -0,0 +1,20 @@
+import type { GenericInitConfig, Job, MiseInitConfig } from '@kici-dev/sdk';
+/** A normalized init step, ready for agent-side expansion. */
+export type InitDirective = {
+    kind: 'generic';
+    config: GenericInitConfig;
+} | {
+    kind: 'preset';
+    name: 'mise';
+    config: MiseInitConfig;
+} | {
+    kind: 'auto';
+};
+/**
+ * Normalize `Job.init` to an ordered list of directives, without touching the
+ * filesystem. `false`/`undefined` -> []; `'auto'` -> one auto directive;
+ * presets/generic configs -> their directive; arrays map element-wise.
+ * `'auto'` is a scalar only — finding it inside an array throws.
+ */
+export declare function normalizeInitItems(job: Job | undefined): InitDirective[];
+//# sourceMappingURL=directives.d.ts.map

package/dist/execution/env-init/presets/expand.d.ts

@@ -0,0 +1,16 @@
+import type { GenericInitConfig } from '@kici-dev/sdk';
+import type { InitDirective } from './directives.js';
+/** Options for agent-side directive expansion. */
+export interface ExpandOptions {
+    cloneRoot: string;
+    /** Host platform; defaults to process.platform. */
+    platform?: NodeJS.Platform;
+    /** Optional info logger (e.g. to emit a pseudo-step line). */
+    log?: (message: string) => void;
+}
+/**
+ * Expand normalized directives into concrete generic init configs, reading the
+ * clone root for preset cache keys and `'auto'` marker detection.
+ */
+export declare function expandInitDirectives(directives: InitDirective[], opts: ExpandOptions): Promise<GenericInitConfig[]>;
+//# sourceMappingURL=expand.d.ts.map

package/dist/execution/env-init/presets/mise/cache-key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Derive the default mise cache key from the committed mise config under
+ * `cloneRoot`. Concatenates whichever of {@link MISE_CONFIG_FILES} exist (in
+ * fixed order) and hashes them. Returns `mise-noconfig` when none exist.
+ */
+export declare function miseCacheKey(cloneRoot: string): Promise<string>;
+//# sourceMappingURL=cache-key.d.ts.map

package/dist/execution/env-init/presets/mise/expander.d.ts

@@ -0,0 +1,16 @@
+import type { GenericInitConfig, MiseInitConfig } from '@kici-dev/sdk';
+import { type MiseWindowsArch } from './windows-install.js';
+/** Arguments to expand the mise preset into a concrete generic init config. */
+export interface MiseExpandArgs {
+    cloneRoot: string;
+    config: MiseInitConfig;
+    /** Host platform (defaults to process.platform). Injected for tests. */
+    platform?: NodeJS.Platform;
+    /** Windows asset resolver (defaults to the real GitHub lookup). Injected for tests. */
+    resolveWindowsAsset?: (arch: MiseWindowsArch) => Promise<string>;
+}
+/** The mise preset expander: turns MiseInitConfig into an OS-correct GenericInitConfig. */
+export declare const miseExpander: {
+    expand(args: MiseExpandArgs): Promise<GenericInitConfig>;
+};
+//# sourceMappingURL=expander.d.ts.map

package/dist/execution/env-init/presets/mise/templates.d.ts

@@ -0,0 +1,16 @@
+/** OS-specific pieces of a mise init expansion. */
+export interface MiseTemplate {
+    /** The `run` command. */
+    run: string;
+    /** Shell to run it with. */
+    shell: string;
+    /** Cache `paths` for mise's data dir on this OS. */
+    cachePaths: string[];
+}
+/**
+ * Pick the mise template for a host platform (Node `process.platform` value).
+ * The Windows `run` carries an `<ASSET_URL>` placeholder the expander replaces
+ * with the resolved GitHub-release zip URL.
+ */
+export declare function selectMiseTemplate(platform: NodeJS.Platform): MiseTemplate;
+//# sourceMappingURL=templates.d.ts.map

package/dist/execution/env-init/presets/mise/windows-install.d.ts

@@ -0,0 +1,18 @@
+/** mise Windows architecture slug used in release asset names. */
+export type MiseWindowsArch = 'x64' | 'arm64';
+interface GithubRelease {
+    assets: {
+        name: string;
+        browser_download_url: string;
+    }[];
+}
+/** Map a Windows `PROCESSOR_ARCHITECTURE` value to mise's asset arch slug. */
+export declare function miseWindowsArch(processorArch: string | undefined): MiseWindowsArch;
+/**
+ * Resolve the download URL of the latest mise standalone Windows zip for `arch`.
+ * `fetchJson` is injected (defaults to a real fetch) so the resolution is
+ * unit-testable without network.
+ */
+export declare function resolveLatestMiseWindowsAsset(arch: MiseWindowsArch, fetchJson?: (url: string) => Promise<GithubRelease>): Promise<string>;
+export {};
+//# sourceMappingURL=windows-install.d.ts.map

package/dist/execution/env-init/presets/registry.d.ts

@@ -0,0 +1,31 @@
+import type { GenericInitConfig } from '@kici-dev/sdk';
+/**
+ * A preset expander: clone root + typed config -> a concrete generic init config.
+ * Expanders may accept additional optional fields (e.g. an injected `platform`
+ * for tests); the agent path passes only `cloneRoot` + `config`.
+ */
+export interface PresetExpander<C> {
+    expand(args: {
+        cloneRoot: string;
+        config: C;
+        platform?: NodeJS.Platform;
+    }): Promise<GenericInitConfig>;
+}
+/**
+ * The set of typed presets. Nix is added here (one row) once its provider lands.
+ */
+export declare const PRESET_REGISTRY: {
+    mise: {
+        expand(args: import("./mise/expander.js").MiseExpandArgs): Promise<GenericInitConfig>;
+    };
+};
+export type PresetName = keyof typeof PRESET_REGISTRY;
+/**
+ * Ordered auto-detect table: `init: 'auto'` tries each row against the clone
+ * root and accumulates matches in this order. (nix row added with its provider.)
+ */
+export declare const AUTO_DETECT_TABLE: {
+    markers: string[];
+    preset: PresetName;
+}[];
+//# sourceMappingURL=registry.d.ts.map

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

@@ -1,4 +1,5 @@
 import type { Workflow } from '@kici-dev/sdk';
+import { 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.
@@ -7,6 +8,11 @@ export interface InitResult {
     environmentName?: string;
     env?: Record<string, string>;
     concurrencyGroup?: string;
+    /**
+     * Resolved matrix combinations when the job's matrix is a dynamic function.
+     * The orchestrator re-materializes these into N execution jobs at dispatch.
+     */
+    matrixValues?: MatrixValues[];
 }
 /**
  * Evaluate dynamic fields (environment, env, concurrencyGroup) on a job.
@@ -29,5 +35,6 @@ export declare function evaluateDynamicFields(workflow: Workflow, jobName: strin
     dynamicEnvironment: boolean;
     dynamicEnv: boolean;
     dynamicConcurrencyGroup: boolean;
+    dynamicMatrix?: boolean;
 }, timeoutMs?: number): Promise<InitResult>;
 //# sourceMappingURL=init-runner.d.ts.map

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

@@ -1,6 +1,6 @@
 import type { AgentToOrchestratorMessage, JobDispatch } from '@kici-dev/engine';
 import type { AppConfig } from '../config.js';
-import type { CacheRequestIpc, CacheResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
+import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
 /**
  * Dependencies injected into JobRunner.
  */
@@ -91,6 +91,13 @@ export interface JobRunnerDeps {
      * Optional for backward compatibility (callers that don't support the cache).
      */
     requestUserCache?: (jobId: string, request: CacheRequestIpc) => Promise<CacheResponseIpc>;
+    /**
+     * Relay a provenance bundle upload operation to the orchestrator and await the
+     * response. Translates the sandbox `provenance.request` IPC into the matching
+     * `provenance.upload.request` / `.complete` WS message. Optional for backward
+     * compatibility (callers that don't support provenance).
+     */
+    relayProvenance?: (jobId: string, request: ProvenanceRequestIpc) => Promise<ProvenanceResponseIpc>;
     /**
      * Relay a step-level approval request to the orchestrator and await the
      * resolution. Translates the sandbox `approval.request` IPC into a
@@ -133,6 +140,7 @@ export declare class JobRunner {
     private readonly _sendConcurrencyReport;
     private readonly _sendApiRequest?;
     private readonly _requestUserCache?;
+    private readonly _relayProvenance?;
     private readonly _sendStepApproval?;
     /** Tracks running jobs for concurrency and cancellation */
     readonly activeJobs: Map<string, ActiveJob>;

package/dist/execution/sandbox/env-delta.d.ts

@@ -31,6 +31,8 @@ export interface ApplyEnvDeltaOptions {
     target?: NodeJS.ProcessEnv;
     /** Invoked once per rejected key (e.g. to emit a masked log warning). */
     onReject?: (key: string) => void;
+    /** PATH list separator. Defaults to the platform separator (';' on Windows, ':' elsewhere). */
+    pathSeparator?: string;
 }
 /**
  * Apply an environment delta to `target` (defaults to process.env), honoring the

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

@@ -5,7 +5,7 @@
  *   import { BareMetalSandbox, ContainerSandbox, buildSanitizedEnv } from './sandbox/index.js';
  */
 export type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult, SandboxStepResult, } from './types.js';
-export type { RunnerToAgentMessage, AgentToRunnerMessage, EventEmitRequest, EventEmitResponse, CacheRequestIpc, CacheResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc, JobExecutionRequest, } from './ipc-protocol.js';
+export type { RunnerToAgentMessage, AgentToRunnerMessage, EventEmitRequest, EventEmitResponse, CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc, JobExecutionRequest, } from './ipc-protocol.js';
 export { buildSanitizedEnv } from './env-sanitizer.js';
 export { ALLOWED_SYSTEM_VARS, KICI_AGENT_ENV_PREFIX, AGENT_REQUIRED_KICI_VARS, } from '@kici-dev/engine';
 export { BareMetalSandbox } from './bare-metal-sandbox.js';

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

@@ -185,7 +185,28 @@ export interface StepApprovalRequestIpc {
     /** Per-gate timeout override (seconds) from the SDK `requireApproval.timeout`. */
     timeoutSeconds?: number;
 }
-export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | StepApprovalRequestIpc;
+/** Which provenance upload operation to relay. */
+export type ProvenanceRequestOp = 'requestUploadUrl' | 'complete';
+/**
+ * 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.
+ */
+export interface ProvenanceRequestIpc {
+    type: 'provenance.request';
+    /** UUID for correlating the response. */
+    requestId: string;
+    /** Which provenance operation to perform. */
+    op: ProvenanceRequestOp;
+    /** Primary subject digest (lowercase hex) — the storage-key discriminator. */
+    subjectDigest: string;
+    /** Caller-supplied artifact name. `complete` only. */
+    subjectName?: string;
+    /** Bundle media type. `complete` only. */
+    mediaType?: string;
+}
+export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | ProvenanceRequestIpc | StepApprovalRequestIpc;
 /** Instruct the workflow runner to execute a job. */
 interface ExecuteMessage {
     type: 'execute';
@@ -276,7 +297,21 @@ export interface StepApprovalResolvedIpc {
     /** Error description (present when the relay or orchestrator failed). */
     error?: string;
 }
-export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc | CacheResponseIpc | StepApprovalResolvedIpc;
+/**
+ * Response to a {@link ProvenanceRequestIpc} (agent -> runner). `requestUploadUrl`
+ * resolves with `uploadUrl`; `complete` resolves with an empty (no-field)
+ * response. `error` is set when the relay or orchestrator failed.
+ */
+export interface ProvenanceResponseIpc {
+    type: 'provenance.response';
+    /** Matches the original request's requestId. */
+    requestId: string;
+    /** Presigned PUT URL for the bundle. `requestUploadUrl` only. */
+    uploadUrl?: string;
+    /** Error description (present when the relay or orchestrator failed). */
+    error?: string;
+}
+export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc | CacheResponseIpc | ProvenanceResponseIpc | StepApprovalResolvedIpc;
 /**
  * All data the workflow runner needs to execute a job inside the sandbox.
  *
@@ -284,6 +319,17 @@ export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResp
  * The runner uses this to clone, install deps, compile, and execute steps.
  */
 export interface JobExecutionRequest {
+    /**
+     * Run UUID. Threaded into the step context so the OIDC token relay can name
+     * the job/run a request is bound to. Correlation only — the orchestrator
+     * re-derives ownership and the runId from its own dispatch state.
+     */
+    runId: string;
+    /**
+     * Job UUID. Sent with `ctx.kici.oidc.token()` requests so the orchestrator
+     * can verify the agent owns this job before relaying a mint request.
+     */
+    jobId: string;
     /** Working directory inside the sandbox (e.g. /workspace). */
     workDir: string;
     /** Repository URL for git clone. */
@@ -320,10 +366,34 @@ export interface JobExecutionRequest {
     depsHash?: string;
     /** Workflow name to execute. */
     workflowName: string;
-    /** Job name within the workflow. */
+    /**
+     * Job name used to locate the job in the compiled workflow and to populate
+     * `ctx.job.name`. For a matrix child this is the BASE job name (the job is
+     * defined once in source); the combination is exposed only via `ctx.matrix`.
+     */
     jobName: string;
     /** Runs-on label for the job. */
     runsOn: string;
+    /**
+     * Matrix combination values for this child (e.g. `{ variant: 'a' }`), exposed
+     * to steps as `ctx.matrix`. Absent for non-matrix jobs.
+     */
+    matrixValues?: Record<string, unknown>;
+    /**
+     * For a `runsOnAll` host-fanout child: the hostname this child runs on,
+     * exposed to steps as `ctx.host`. Absent for non-host jobs.
+     */
+    host?: string;
+    /**
+     * For a `runsOnAll` host-fanout child: the resolved agent facts, exposed to
+     * steps as `ctx.agent`. Absent for non-host jobs.
+     */
+    agent?: {
+        host: string;
+        labels: string[];
+        platform?: string;
+        arch?: string;
+    };
     /** Secrets to merge into step environment (highest precedence). */
     secrets?: Record<string, string>;
     /** Namespaced secrets by context name for ctx.secrets['context-name'].KEY access. */
@@ -413,6 +483,14 @@ export interface JobExecutionRequest {
         event: Record<string, unknown>;
         /** Expected job names from the original eval (for determinism validation). */
         expectedJobNames?: string[];
+        /**
+         * Frozen upstream-output snapshot for a result-aware generator. When present
+         * the re-eval rebuilds `ctx.needs` from this snapshot (never a live read),
+         * so the generator sees the same upstream data as the original eval.
+         */
+        upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot;
+        /** Declared upstream needs (normalized lock edges) used to shape ctx.needs. */
+        declaredNeeds?: readonly unknown[];
     };
 }
 export {};

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

@@ -1,5 +1,5 @@
 import type { JobDispatch } from '@kici-dev/engine';
-import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage, CacheRequestIpc, CacheResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './ipc-protocol.js';
+import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage, CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './ipc-protocol.js';
 /**
  * Common interface for all execution sandbox backends.
  *
@@ -89,6 +89,14 @@ export interface JobExecutionOptions {
      * working — the runner falls back to a "not configured" cache response.
      */
     onCacheRequest?: (request: CacheRequestIpc) => Promise<CacheResponseIpc>;
+    /**
+     * Callback for relaying a provenance bundle upload request from the sandbox to
+     * the orchestrator. The sandbox runner sends `provenance.request` IPC; the
+     * agent wraps it in the matching `provenance.upload.*` WS message and forwards
+     * to the orchestrator. Optional so harnesses that don't thread provenance keep
+     * working — the runner falls back to a "not configured" error response.
+     */
+    onProvenanceRequest?: (request: ProvenanceRequestIpc) => Promise<ProvenanceResponseIpc>;
     /**
      * Callback for relaying a step-level approval request from the sandbox to the
      * orchestrator. The sandbox runner sends `approval.request` IPC; the agent

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

@@ -13,13 +13,18 @@
  * This file is compiled alongside the agent by rolldown (existing build), but
  * runs as a SEPARATE process spawned by the sandbox backend.
  */
-import type { Job, GenericInitConfig } from '@kici-dev/sdk';
-/** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
-export declare function rawPayloadFromEvent(event: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+import type { StepContext } 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';
 /**
- * Normalize `Job.init` (config | config[] | false | undefined) to an ordered
- * array of init specs. `false` is an explicit opt-out and `undefined` (no
- * config) both resolve to an empty list — the init phase is then a no-op.
+ * Create a StepContext natively inside the workflow runner.
+ *
+ * The context is reconstructed from the environment and IPC request fields --
+ * NOT serialized across the process boundary. This means zx $ runs natively
+ * inside this process with full shell access.
  */
-export declare function resolveInitSpecs(job: Job | undefined): GenericInitConfig[];
+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;
+/** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
+export declare function rawPayloadFromEvent(event: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
 //# sourceMappingURL=workflow-runner.d.ts.map

package/dist/execution/validate-kici-deps.d.ts

@@ -14,11 +14,18 @@
  *   clones the whole repo, so an in-repo sibling is present), and resolves
  *   `file:`/`link:`/`portal:` against a path — allowed when that path stays
  *   inside the cloned repo, rejected when it escapes the clone.
+ * - yarn classic (v1) has no `workspace:` protocol and no `portal:` — it links
+ *   in-repo siblings by version range, not by a local specifier — so both are
+ *   rejected with guidance; `file:`/`link:` are allowed when the path stays
+ *   inside the clone, rejected when it escapes.
+ * - yarn berry (v2+) resolves `workspace:` against the repo-root package.json
+ *   `workspaces` field and `portal:`/`file:`/`link:` against inside-repo paths,
+ *   so those are allowed when present/inside the clone and rejected otherwise.
  *
  * This module performs that classification so unresolvable specifiers fail
  * fast with guidance rather than a cryptic install error.
  */
-import { PackageManager } from '@kici-dev/shared/package-manager';
+import { PackageManager, YarnFlavor } from '@kici-dev/shared/package-manager';
 /** Local-protocol specifier prefixes that resolve against the filesystem. */
 export declare enum LocalDepProtocol {
     Workspace = "workspace:",
@@ -49,7 +56,7 @@ export declare function findLocalProtocolDeps(pkg: PackageJsonShape): LocalProto
  */
 export declare function kiciHasLocalProtocolDeps(kiciDir: string): Promise<boolean>;
 /** Build the actionable error for unresolvable local-protocol dependencies. */
-export declare function formatUnresolvableDepError(offenders: readonly LocalProtocolDep[], packageManager: PackageManager): string;
+export declare function formatUnresolvableDepError(offenders: readonly LocalProtocolDep[], packageManager: PackageManager, yarnFlavor: YarnFlavor): string;
 /**
  * Throw an actionable error when `.kici/package.json` declares a local-protocol
  * dependency the detected package manager cannot resolve from the single cloned
@@ -60,6 +67,7 @@ export declare function assertResolvableDeps(args: {
     kiciDir: string;
     repoRoot: string;
     packageManager: PackageManager;
+    yarnFlavor?: YarnFlavor;
 }): Promise<void>;
 export {};
 //# sourceMappingURL=validate-kici-deps.d.ts.map

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

@@ -64,7 +64,11 @@ export declare function extractSteps(workflow: Workflow, jobName: string): reado
  * A sibling mismatch logs a warning; a missing target job throws a clear
  * determinism error.
  */
-export declare function extractStepsFromDynamicJob(workflow: Workflow, dynamicIndex: number, jobName: string, event: Record<string, unknown>, env: Record<string, string | undefined>, apiTransport?: (method: string, params?: Record<string, unknown>) => Promise<unknown>, expectedJobNames?: string[]): Promise<{
+export declare function extractStepsFromDynamicJob(workflow: Workflow, dynamicIndex: number, jobName: string, event: Record<string, unknown>, env: Record<string, string | undefined>, apiTransport?: (method: string, params?: Record<string, unknown>) => Promise<unknown>, expectedJobNames?: string[], 
+/** 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<{
     steps: readonly StepInput[];
     droppedJobs: string[];
 }>;

package/dist/execution/workspace-siblings.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-repo workspace-sibling discovery for the agent's dependency handling.
+ *
+ * A pnpm or yarn-classic workspace lays out a `.kici/` member's `workspace:`
+ * (pnpm) or version-range (yarn) siblings as symlinks pointing at package
+ * directories that live inside the clone but outside `.kici/` and outside the
+ * `node_modules` store. The dep-cache packer must travel those sibling dirs with
+ * the closure (their symlinks would dangle otherwise), and the yarn install path
+ * must build them (the install links a sibling but does not build it).
+ *
+ * `collectInRepoSiblings` walks a starting `node_modules` (and transitively each
+ * discovered sibling's `node_modules`), returning each in-repo sibling directory
+ * once, repo-root-relative, in breadth-first discovery order. The starting
+ * `node_modules` is a parameter so it serves pnpm + yarn-standalone (seeded at
+ * `.kici/node_modules`) and yarn-workspace-member (seeded at the hoisted root
+ * `node_modules`).
+ */
+/**
+ * The directory yarn lays `.kici`'s dependencies into. A standalone `.kici`
+ * (own lockfile, no parent workspace) gets `.kici/node_modules`; a workspace
+ * member hoists everything to the repo-root `node_modules`, leaving no
+ * `.kici/node_modules`.
+ */
+export declare function resolveYarnNodeModulesRoot(repoRoot: string, kiciDir: string): string;
+/**
+ * Walk `seedNodeModules` (and transitively each in-repo sibling's
+ * `node_modules`) collecting the repo-root-relative directories of workspace
+ * siblings — package dirs that live inside the clone but outside `.kici/` and
+ * outside the repo-root `node_modules/` store. Returns each dir once, in
+ * discovery (BFS) order.
+ */
+export declare function collectInRepoSiblings(workDir: string, kiciDir: string, seedNodeModules?: string): Promise<string[]>;
+//# sourceMappingURL=workspace-siblings.d.ts.map

package/dist/execution/yarnrc-berry-config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Apply yarn-berry registry auth + a forced `nodeLinker: node-modules` to a
+ * workflow's `.kici/.yarnrc.yml` for the lifetime of one `yarn install`, then
+ * restore the file on cleanup. The berry analog of `npm-registry-config.ts`:
+ * berry reads `.yarnrc.yml` (not `.npmrc`), so the auth block uses berry's
+ * `npmRegistryServer` / `npmScopes` / `npmAuthToken` keys with `${VAR}`
+ * env-var interpolation. Token bytes never reach disk — each registry token is
+ * exposed as a job-scoped env var and the on-disk value is the `${VAR}`
+ * reference.
+ *
+ * `nodeLinker: node-modules` makes berry lay down a real `node_modules` tree
+ * (no PnP `.pnp.cjs`), so the agent's packer / restore / sibling-walk /
+ * workflow-loader work unchanged. `enableScripts: false` (when a private
+ * registry is configured) keeps dependency lifecycle scripts from seeing the
+ * synthesized token env vars — the same security model as npm/pnpm/classic
+ * `--ignore-scripts`.
+ *
+ * Reuses the same `ApplyNpmRegistryConfigArgs` / `ApplyNpmRegistryConfigResult`
+ * shapes as the npm overlay so `dep-installer` can pick either by flavor.
+ */
+import type { ApplyNpmRegistryConfigArgs, ApplyNpmRegistryConfigResult } from './npm-registry-config.js';
+export declare function applyYarnrcBerryConfig(args: ApplyNpmRegistryConfigArgs): Promise<ApplyNpmRegistryConfigResult>;
+//# sourceMappingURL=yarnrc-berry-config.d.ts.map