@kici-dev/compiler 0.1.26 → 0.1.27

package/dist/local-plane/run-follow.js

@@ -0,0 +1,104 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { ExecutionJobStatus, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES } from "@kici-dev/engine";
+import { AdminApiClient } from "@kici-dev/orchestrator";
+//#region src/local-plane/run-follow.ts
+/**
+* Follow an offline routed run against the local plane by polling the
+* orchestrator admin API (no SSE in independent mode). Streams step log lines as
+* they arrive and resolves when the run reaches a terminal state.
+*/
+/** Job states that mean the job did NOT succeed (failed / stale / cancelled / dropped). */
+const FAILED_JOB_STATES = /* @__PURE__ */ new Set([
+	ExecutionJobStatus.enum.failed,
+	ExecutionJobStatus.enum.timed_out_stale,
+	ExecutionJobStatus.enum.cancelled,
+	ExecutionJobStatus.enum.drift_dropped
+]);
+/** Poll a run to completion, streaming step logs. */
+async function followRun(planeUrl, adminToken, runId, opts = {}) {
+	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
+	const pollIntervalMs = opts.pollIntervalMs ?? 750;
+	const idleTimeoutMs = opts.idleTimeoutMs ?? opts.timeoutMs ?? 9e5;
+	const maxTotalMs = opts.maxTotalMs ?? 72e5;
+	const cursors = /* @__PURE__ */ new Map();
+	const stream = !opts.quiet && opts.onLine ? opts.onLine : void 0;
+	const startedAt = Date.now();
+	let lastProgressAt = startedAt;
+	let lastStatus = "";
+	for (;;) {
+		const now = Date.now();
+		if (now - lastProgressAt > idleTimeoutMs) throw new Error(`offline run: follow timed out (no progress for ${idleTimeoutMs}ms) for run ${runId}`);
+		if (now - startedAt > maxTotalMs) throw new Error(`offline run: follow exceeded its max window (${maxTotalMs}ms) for run ${runId}`);
+		const { run } = await client.get(`/api/v1/admin/runs/${runId}`);
+		let progressed = false;
+		if (run.status !== lastStatus) {
+			lastStatus = run.status;
+			progressed = true;
+		}
+		if (stream) {
+			if (await drainLogs(client, runId, cursors, stream) > 0) progressed = true;
+		}
+		if (progressed) lastProgressAt = now;
+		if (TERMINAL_RUN_STATES.has(run.status)) {
+			const jobs = await fetchJobs(client, runId);
+			const allTerminal = jobs.length > 0 && jobs.every((j) => TERMINAL_JOB_STATES.has(j.status));
+			const anyFailed = jobs.some((j) => FAILED_JOB_STATES.has(j.status));
+			if (allTerminal && !(run.status === "success" && anyFailed)) {
+				if (stream) await drainLogs(client, runId, cursors, stream);
+				return {
+					runId,
+					status: run.status,
+					jobs
+				};
+			}
+		}
+		await sleep(pollIntervalMs);
+	}
+}
+/** Fetch the run's jobs mapped to the summary shape. */
+async function fetchJobs(client, runId) {
+	const { jobs } = await client.get(`/api/v1/admin/runs/${runId}/jobs`);
+	return jobs.map((j) => ({
+		name: j.jobName,
+		status: j.status,
+		durationMs: j.durationMs ?? void 0
+	}));
+}
+/**
+* Stream any new step-log lines. Best-effort: a per-step fetch error never
+* aborts the follow (logs are observability, not the terminal signal).
+*/
+async function drainLogs(client, runId, cursors, onLine) {
+	let emitted = 0;
+	let jobs;
+	try {
+		jobs = (await client.get(`/api/v1/admin/runs/${runId}/jobs?includeSteps=true`)).jobs;
+	} catch {
+		return emitted;
+	}
+	for (const job of jobs) for (const step of job.steps ?? []) {
+		const key = `${job.jobId}:${step.stepIndex}`;
+		try {
+			let cursor = cursors.get(key);
+			for (;;) {
+				const qs = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
+				const page = await client.get(`/api/v1/admin/runs/${runId}/jobs/${job.jobId}/steps/${step.stepIndex}/logs${qs}`);
+				for (const l of page.lines) {
+					onLine(l.value);
+					emitted++;
+				}
+				cursor = page.nextCursor ?? String(page.totalLines);
+				cursors.set(key, cursor);
+				if (!page.nextCursor) break;
+			}
+		} catch {}
+	}
+	return emitted;
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+export { followRun };
+
+//# sourceMappingURL=run-follow.js.map

package/dist/local-plane/scaler-config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Bare-metal scaler configuration for the local dev plane.
+ *
+ * A dispatched job needs an agent to run it. The plane orchestrator boots with
+ * a single bare-metal scaler pointed at a label set matching the default
+ * `runsOn` (`default`), so an offline `kici run --local` dispatch auto-spawns an
+ * ephemeral, one-job-then-exit agent on this machine. The spawned binary is a
+ * small executable wrapper that execs `node <@kici-dev/agent server entry>` —
+ * mirroring the shape proven by the `local-file-source` E2E, and avoiding a
+ * dependency on the (non-executable) shipped `kici-agent` script.
+ */
+/** Resolve the built `@kici-dev/agent` server entry the bare-metal scaler runs. */
+export declare function resolveAgentBinary(): string;
+/**
+ * Write the executable wrapper the bare-metal scaler spawns. The scaler invokes
+ * `spawn(binaryPath, [])` directly, so the target must be an executable file;
+ * the shipped agent entry is a plain Node module without an exec bit, so this
+ * wrapper bridges the gap. Returns the wrapper path.
+ */
+export declare function writeAgentWrapper(): string;
+/**
+ * The non-reserved routing label a `kici run --local --trusted` run appends to
+ * every job's `runsOn` so the dispatch lands on the plane's trusted label set.
+ * `self-hosted` (not a `kici:`-prefixed reserved label) is also the `runsOn` the
+ * CI deploy/CDN workflows already declare, so those route to the trusted profile
+ * on this plane by construction.
+ */
+export declare const TRUSTED_ROUTING_LABEL = "self-hosted";
+/**
+ * The non-reserved routing label a `kici run --local --trusted --in-place` run
+ * appends (alongside `self-hosted`) so the dispatch lands on the plane's trusted
+ * **in-place** label set — the agent runs the operator's real working tree
+ * directly (no clone). This is the profile KiCI's own routed `deploy:stg` uses.
+ */
+export declare const IN_PLACE_ROUTING_LABEL = "in-place";
+/**
+ * Write the plane's bare-metal scaler YAML and return its path. One scaler with
+ * two coexisting label sets spawning the agent wrapper against the plane
+ * orchestrator's localhost WS endpoint:
+ *
+ * - `default` — the sandboxed / credential-isolated profile a normal
+ *   `kici run --local` dispatch (jobs with `runsOn: ['default']` or none) lands
+ *   on. Smallest-set-wins routing keeps default runs here.
+ * - `default` + `self-hosted` — the TRUSTED fleet profile (`KICI_TRUSTED_ENV=true`,
+ *   bwrap off) a `kici run --local --trusted` run (or a `runsOn: self-hosted`
+ *   workflow) lands on: steps run with the ambient host env passed through,
+ *   minus the agent's own KiCI identity secrets.
+ * - `default` + `self-hosted` + `in-place` — the TRUSTED **in-place** profile
+ *   (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted --in-place` run
+ *   lands on: same trusted env, but the agent uses the operator's real working
+ *   tree directly (no clone) — the profile KiCI's own routed `deploy:stg` uses.
+ */
+export declare function writeScalerConfig(orchestratorPort: number): string;
+//# sourceMappingURL=scaler-config.d.ts.map

package/dist/local-plane/scaler-config.js

@@ -0,0 +1,114 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { planePaths } from "./paths.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import { stringify } from "yaml";
+//#region src/local-plane/scaler-config.ts
+/**
+* Bare-metal scaler configuration for the local dev plane.
+*
+* A dispatched job needs an agent to run it. The plane orchestrator boots with
+* a single bare-metal scaler pointed at a label set matching the default
+* `runsOn` (`default`), so an offline `kici run --local` dispatch auto-spawns an
+* ephemeral, one-job-then-exit agent on this machine. The spawned binary is a
+* small executable wrapper that execs `node <@kici-dev/agent server entry>` —
+* mirroring the shape proven by the `local-file-source` E2E, and avoiding a
+* dependency on the (non-executable) shipped `kici-agent` script.
+*/
+/** Resolve the built `@kici-dev/agent` server entry the bare-metal scaler runs. */
+function resolveAgentBinary() {
+	return createRequire(import.meta.url).resolve("@kici-dev/agent/server");
+}
+/**
+* Write the executable wrapper the bare-metal scaler spawns. The scaler invokes
+* `spawn(binaryPath, [])` directly, so the target must be an executable file;
+* the shipped agent entry is a plain Node module without an exec bit, so this
+* wrapper bridges the gap. Returns the wrapper path.
+*/
+function writeAgentWrapper() {
+	const { agentWrapperFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	const server = resolveAgentBinary();
+	fs.writeFileSync(agentWrapperFile, `#!/usr/bin/env bash\nexec node ${JSON.stringify(server)} "$@"\n`);
+	fs.chmodSync(agentWrapperFile, 493);
+	return agentWrapperFile;
+}
+/**
+* The non-reserved routing label a `kici run --local --trusted` run appends to
+* every job's `runsOn` so the dispatch lands on the plane's trusted label set.
+* `self-hosted` (not a `kici:`-prefixed reserved label) is also the `runsOn` the
+* CI deploy/CDN workflows already declare, so those route to the trusted profile
+* on this plane by construction.
+*/
+const TRUSTED_ROUTING_LABEL = "self-hosted";
+/**
+* The non-reserved routing label a `kici run --local --trusted --in-place` run
+* appends (alongside `self-hosted`) so the dispatch lands on the plane's trusted
+* **in-place** label set — the agent runs the operator's real working tree
+* directly (no clone). This is the profile KiCI's own routed `deploy:stg` uses.
+*/
+const IN_PLACE_ROUTING_LABEL = "in-place";
+/**
+* Write the plane's bare-metal scaler YAML and return its path. One scaler with
+* two coexisting label sets spawning the agent wrapper against the plane
+* orchestrator's localhost WS endpoint:
+*
+* - `default` — the sandboxed / credential-isolated profile a normal
+*   `kici run --local` dispatch (jobs with `runsOn: ['default']` or none) lands
+*   on. Smallest-set-wins routing keeps default runs here.
+* - `default` + `self-hosted` — the TRUSTED fleet profile (`KICI_TRUSTED_ENV=true`,
+*   bwrap off) a `kici run --local --trusted` run (or a `runsOn: self-hosted`
+*   workflow) lands on: steps run with the ambient host env passed through,
+*   minus the agent's own KiCI identity secrets.
+* - `default` + `self-hosted` + `in-place` — the TRUSTED **in-place** profile
+*   (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted --in-place` run
+*   lands on: same trusted env, but the agent uses the operator's real working
+*   tree directly (no clone) — the profile KiCI's own routed `deploy:stg` uses.
+*/
+function writeScalerConfig(orchestratorPort) {
+	const { scalerConfigFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	const binaryPath = writeAgentWrapper();
+	const yaml = stringify({
+		version: 1,
+		scalers: [{
+			name: "kici-local-bare-metal",
+			type: "bare-metal",
+			maxAgents: 10,
+			orchestratorUrl: `ws://127.0.0.1:${orchestratorPort}/ws`,
+			labelSets: [
+				{
+					labels: ["default"],
+					binaryPath
+				},
+				{
+					labels: ["default", TRUSTED_ROUTING_LABEL],
+					binaryPath,
+					env: {
+						KICI_TRUSTED_ENV: "true",
+						KICI_SANDBOX: "false"
+					}
+				},
+				{
+					labels: [
+						"default",
+						TRUSTED_ROUTING_LABEL,
+						IN_PLACE_ROUTING_LABEL
+					],
+					binaryPath,
+					env: {
+						KICI_TRUSTED_ENV: "true",
+						KICI_SANDBOX: "false",
+						KICI_IN_PLACE: "true"
+					}
+				}
+			]
+		}]
+	});
+	fs.writeFileSync(scalerConfigFile, yaml);
+	return scalerConfigFile;
+}
+//#endregion
+export { IN_PLACE_ROUTING_LABEL, TRUSTED_ROUTING_LABEL, resolveAgentBinary, writeAgentWrapper, writeScalerConfig };
+
+//# sourceMappingURL=scaler-config.js.map

package/dist/local-plane/secret-seed.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Seed a project's local `secrets.yaml` (and `.kici/.secrets` INI) contexts into
+ * the local dev plane's real `scoped_secrets` store, preserving context/scope
+ * structure so the plane's real `SecretResolver` honors scoping at dispatch —
+ * the routed local run resolves scoped secrets through the plane's real
+ * resolver rather than a flat merge.
+ *
+ * Local secret files are READ-ONLY here: values are only READ and transit into
+ * the local plane's Postgres via the admin secret API. Nothing is written back
+ * to a secret file, and nothing leaves this machine (the plane is local).
+ *
+ * Scope model: each `secrets.yaml` top-level key is a context name. The seeder
+ * creates a context of that name, binds it to a scope pattern equal to the
+ * context name, and stores each secret at that scope. So a workflow job bound to
+ * context `production` resolves `production`-scoped secrets through the resolver.
+ */
+/** Minimal AdminApiClient surface the seeder needs (for test injection). */
+export interface SecretSeedClient {
+    createContext(data: {
+        orgId: string;
+        name: string;
+        allowLocalExecution?: boolean;
+    }): Promise<{
+        envId: string;
+        created: boolean;
+    }>;
+    bindContext(data: {
+        orgId: string;
+        name: string;
+        scopePattern: string;
+        hostPattern?: string;
+    }): Promise<unknown>;
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+}
+/** Result of a seed run: the contexts seeded and how many secret keys landed. */
+export interface SeededSecrets {
+    contexts: string[];
+    secretCount: number;
+}
+/**
+ * Collect the per-context secrets from a project's `.kici/` directory,
+ * preserving context structure. Reads `.kici/.secrets` (INI sections) and
+ * `.kici/secrets.yaml` (top-level contexts). The yaml layer wins on key
+ * collisions within a context. Flat (context-less) secrets are ignored here —
+ * a routed job only resolves secrets for the contexts it binds.
+ */
+export declare function loadLocalSecretContexts(kiciDir: string): Promise<Record<string, Record<string, string>>>;
+/**
+ * Seed the local plane's `scoped_secrets` store from a project's `secrets.yaml`
+ * / `.secrets` contexts. Idempotent: `createContext` upserts, `bind` is a no-op
+ * when the scope is already bound, and `setSecret` overwrites in place. Returns
+ * the contexts + secret-key count seeded (never the values).
+ */
+export declare function seedLocalSecrets(planeUrl: string, adminToken: string, opts: {
+    orgId: string;
+    kiciDir: string;
+    client?: SecretSeedClient;
+}): Promise<SeededSecrets>;
+//# sourceMappingURL=secret-seed.d.ts.map

package/dist/local-plane/secret-seed.js

@@ -0,0 +1,112 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { parseSecretsFile } from "../test-runner/secrets-file.js";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { AdminApiClient } from "@kici-dev/orchestrator";
+//#region src/local-plane/secret-seed.ts
+/**
+* Seed a project's local `secrets.yaml` (and `.kici/.secrets` INI) contexts into
+* the local dev plane's real `scoped_secrets` store, preserving context/scope
+* structure so the plane's real `SecretResolver` honors scoping at dispatch —
+* the routed local run resolves scoped secrets through the plane's real
+* resolver rather than a flat merge.
+*
+* Local secret files are READ-ONLY here: values are only READ and transit into
+* the local plane's Postgres via the admin secret API. Nothing is written back
+* to a secret file, and nothing leaves this machine (the plane is local).
+*
+* Scope model: each `secrets.yaml` top-level key is a context name. The seeder
+* creates a context of that name, binds it to a scope pattern equal to the
+* context name, and stores each secret at that scope. So a workflow job bound to
+* context `production` resolves `production`-scoped secrets through the resolver.
+*/
+/**
+* Read a file, returning null when it does not exist.
+*/
+async function readFileOrNull(filePath) {
+	try {
+		return await readFile(filePath, "utf-8");
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* Parse `secrets.yaml`, PRESERVING its top-level context structure (a flat merge
+* would collapse the contexts). Top-level keys are context names; values are
+* key→value maps. Non-scalar leaf values are stringified.
+*/
+function parseSecretsYamlContexts(content) {
+	const parsed = parse(content);
+	if (!parsed || typeof parsed !== "object") return {};
+	const out = {};
+	for (const [contextName, contextSecrets] of Object.entries(parsed)) if (contextSecrets && typeof contextSecrets === "object" && !Array.isArray(contextSecrets)) {
+		const map = {};
+		for (const [key, value] of Object.entries(contextSecrets)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") map[key] = String(value);
+		if (Object.keys(map).length > 0) out[contextName] = map;
+	}
+	return out;
+}
+/**
+* Collect the per-context secrets from a project's `.kici/` directory,
+* preserving context structure. Reads `.kici/.secrets` (INI sections) and
+* `.kici/secrets.yaml` (top-level contexts). The yaml layer wins on key
+* collisions within a context. Flat (context-less) secrets are ignored here —
+* a routed job only resolves secrets for the contexts it binds.
+*/
+async function loadLocalSecretContexts(kiciDir) {
+	const contexts = {};
+	const iniContent = await readFileOrNull(path.join(kiciDir, ".secrets"));
+	if (iniContent !== null) {
+		const parsed = parseSecretsFile(iniContent);
+		for (const [ctx, vals] of Object.entries(parsed.contexts)) contexts[ctx] = {
+			...contexts[ctx] ?? {},
+			...vals
+		};
+	}
+	const yamlContent = await readFileOrNull(path.join(kiciDir, "secrets.yaml"));
+	if (yamlContent !== null) for (const [ctx, vals] of Object.entries(parseSecretsYamlContexts(yamlContent))) contexts[ctx] = {
+		...contexts[ctx] ?? {},
+		...vals
+	};
+	return contexts;
+}
+/**
+* Seed the local plane's `scoped_secrets` store from a project's `secrets.yaml`
+* / `.secrets` contexts. Idempotent: `createContext` upserts, `bind` is a no-op
+* when the scope is already bound, and `setSecret` overwrites in place. Returns
+* the contexts + secret-key count seeded (never the values).
+*/
+async function seedLocalSecrets(planeUrl, adminToken, opts) {
+	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
+	const contexts = await loadLocalSecretContexts(opts.kiciDir);
+	const seeded = [];
+	let secretCount = 0;
+	for (const [contextName, secrets] of Object.entries(contexts)) {
+		await client.createContext({
+			orgId: opts.orgId,
+			name: contextName,
+			allowLocalExecution: true
+		});
+		await client.bindContext({
+			orgId: opts.orgId,
+			name: contextName,
+			scopePattern: contextName,
+			hostPattern: "**"
+		});
+		for (const [key, value] of Object.entries(secrets)) {
+			await client.setSecret(opts.orgId, contextName, key, value);
+			secretCount++;
+		}
+		seeded.push(contextName);
+	}
+	return {
+		contexts: seeded,
+		secretCount
+	};
+}
+//#endregion
+export { loadLocalSecretContexts, seedLocalSecrets };
+
+//# sourceMappingURL=secret-seed.js.map

package/dist/local-plane/source-provider.d.ts

@@ -0,0 +1,43 @@
+/**
+ * LocalSourceProvider — resolve the workdir a `kici run --local` dispatch
+ * registers as a `file://` source for the plane.
+ *
+ * The plane orchestrator's local provider fetches the lock from
+ * `<repoBasePath>/.kici/kici.lock.json` and the ephemeral agent clones
+ * `file://<repoBasePath>` at a committed sha. So the resolved workdir must be a
+ * git repo whose HEAD carries the workflow + lock the run should execute.
+ *
+ * Two profiles:
+ * - **default (isolated):** an isolated tmp clone at HEAD with the local overlay
+ *   (dirty + untracked files) applied and committed onto a `kici-local` branch,
+ *   so the clone-by-sha the agent performs sees uncommitted work without
+ *   touching the developer's tree.
+ * - **`--in-place`:** the repo root directly (ambient state, the profile the CI
+ *   deploy jobs use). Cleanup is a no-op.
+ */
+/** The `kici-local` branch the isolated profile commits its overlay onto. */
+export declare const LOCAL_RUN_BRANCH = "kici-local";
+/** A resolved workdir plus the git coordinates the plane trigger needs. */
+export interface ResolvedWorkdir {
+    /** Absolute path registered as the local source `repoBasePath`. */
+    dir: string;
+    /** Git ref the synthetic push carries (`refs/heads/<branch>`). */
+    ref: string;
+    /** Committed HEAD sha the agent clones + checks out. */
+    sha: string;
+    /** Branch short name (matched by the workflow's push filter). */
+    branch: string;
+    /** Remove the tmp workdir (no-op for `--in-place`). */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Resolve the workdir for an offline routed run.
+ *
+ * @param opts.inPlace - Use the repo root directly instead of an isolated clone.
+ * @param opts.repoRoot - The developer's repo root.
+ */
+export declare function resolveWorkdir(opts: {
+    inPlace: boolean;
+    repoRoot: string;
+}): Promise<ResolvedWorkdir>;
+//# sourceMappingURL=source-provider.d.ts.map

package/dist/local-plane/source-provider.js

@@ -0,0 +1,165 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { selectOverlayFiles } from "../remote/uploader.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { execFileSync, execSync } from "node:child_process";
+import os from "node:os";
+import { randomBytes } from "node:crypto";
+//#region src/local-plane/source-provider.ts
+/**
+* LocalSourceProvider — resolve the workdir a `kici run --local` dispatch
+* registers as a `file://` source for the plane.
+*
+* The plane orchestrator's local provider fetches the lock from
+* `<repoBasePath>/.kici/kici.lock.json` and the ephemeral agent clones
+* `file://<repoBasePath>` at a committed sha. So the resolved workdir must be a
+* git repo whose HEAD carries the workflow + lock the run should execute.
+*
+* Two profiles:
+* - **default (isolated):** an isolated tmp clone at HEAD with the local overlay
+*   (dirty + untracked files) applied and committed onto a `kici-local` branch,
+*   so the clone-by-sha the agent performs sees uncommitted work without
+*   touching the developer's tree.
+* - **`--in-place`:** the repo root directly (ambient state, the profile the CI
+*   deploy jobs use). Cleanup is a no-op.
+*/
+/** The `kici-local` branch the isolated profile commits its overlay onto. */
+const LOCAL_RUN_BRANCH = "kici-local";
+/** Max number of overlay files copied concurrently. */
+const COPY_BATCH_SIZE = 32;
+/**
+* Resolve the workdir for an offline routed run.
+*
+* @param opts.inPlace - Use the repo root directly instead of an isolated clone.
+* @param opts.repoRoot - The developer's repo root.
+*/
+async function resolveWorkdir(opts) {
+	requireGitRepo(opts.repoRoot);
+	return opts.inPlace ? resolveInPlace(opts.repoRoot) : resolveIsolated(opts.repoRoot);
+}
+/** In-place: the repo root, triggered at its current branch + HEAD. */
+function resolveInPlace(repoRoot) {
+	const branch = gitOut(repoRoot, [
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	]);
+	const sha = gitOut(repoRoot, ["rev-parse", "HEAD"]);
+	return {
+		dir: repoRoot,
+		ref: `refs/heads/${branch}`,
+		sha,
+		branch,
+		cleanup: async () => {}
+	};
+}
+/**
+* Isolated: a tmp clone at HEAD with the local overlay applied and committed
+* onto the `kici-local` branch, then commits so the agent's clone-by-sha
+* carries the work.
+*/
+async function resolveIsolated(repoRoot) {
+	const base = os.tmpdir();
+	const tmpDir = path.join(base, `kici-local-run-${randomBytes(3).toString("hex")}`);
+	const { sha, existingFiles, deletedFiles } = await selectOverlayFiles(repoRoot);
+	execSync(`git clone --no-hardlinks --quiet ${shellQuote(repoRoot)} ${shellQuote(tmpDir)}`, { stdio: "ignore" });
+	execSync(`git checkout --quiet ${sha}`, {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	await applyOverlay(repoRoot, tmpDir, existingFiles, deletedFiles);
+	execFileSync("git", [
+		"checkout",
+		"-B",
+		LOCAL_RUN_BRANCH
+	], {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	execFileSync("git", ["add", "-A"], {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	if (gitOut(tmpDir, ["status", "--porcelain"])) execFileSync("git", [
+		"-c",
+		"user.email=local@kici.dev",
+		"-c",
+		"user.name=kici local",
+		"commit",
+		"--no-verify",
+		"--no-gpg-sign",
+		"-m",
+		"kici run --local overlay"
+	], {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	const committed = gitOut(tmpDir, ["rev-parse", "HEAD"]);
+	return {
+		dir: tmpDir,
+		ref: `refs/heads/${LOCAL_RUN_BRANCH}`,
+		sha: committed,
+		branch: LOCAL_RUN_BRANCH,
+		cleanup: async () => {
+			await fs.rm(tmpDir, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+}
+/** Copy overlay files onto the clone and remove local deletions. */
+async function applyOverlay(repoRoot, tmpDir, existingFiles, deletedFiles) {
+	for (let i = 0; i < existingFiles.length; i += COPY_BATCH_SIZE) {
+		const batch = existingFiles.slice(i, i + COPY_BATCH_SIZE);
+		await Promise.all(batch.map((file) => copyOverlayFile(repoRoot, tmpDir, file)));
+	}
+	for (let i = 0; i < deletedFiles.length; i += COPY_BATCH_SIZE) {
+		const batch = deletedFiles.slice(i, i + COPY_BATCH_SIZE);
+		await Promise.all(batch.map((file) => fs.rm(path.join(tmpDir, file), { force: true })));
+	}
+}
+/**
+* Copy a single overlay file, preserving its mode. Symlinks are recreated as
+* links (not dereferenced) — the same shape the remote tarball preserves.
+*/
+async function copyOverlayFile(repoRoot, tmpDir, file) {
+	const src = path.join(repoRoot, file);
+	const dest = path.join(tmpDir, file);
+	await fs.mkdir(path.dirname(dest), { recursive: true });
+	const srcStat = await fs.lstat(src);
+	if (srcStat.isSymbolicLink()) {
+		const target = await fs.readlink(src);
+		await fs.rm(dest, { force: true });
+		await fs.symlink(target, dest);
+		return;
+	}
+	await fs.copyFile(src, dest);
+	await fs.chmod(dest, srcStat.mode);
+}
+/** Throw an actionable error if `repoRoot` is not a git work tree. */
+function requireGitRepo(repoRoot) {
+	try {
+		execSync("git rev-parse --is-inside-work-tree", {
+			cwd: repoRoot,
+			stdio: "ignore"
+		});
+	} catch {
+		throw new Error(`kici run --local needs a git repository, but "${repoRoot}" is not inside a git work tree. Initialize a repo (git init) before running.`);
+	}
+}
+/** Run a git command in `cwd` and return trimmed stdout. */
+function gitOut(cwd, args) {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf8"
+	}).trim();
+}
+/** Minimal single-quote shell escaping for paths passed to git via execSync. */
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//#endregion
+export { LOCAL_RUN_BRANCH, resolveWorkdir };
+
+//# sourceMappingURL=source-provider.js.map