@kici-dev/compiler 0.1.25 → 0.1.27

package/dist/cli-banner.d.ts

@@ -3,9 +3,12 @@ import type { Command } from 'commander';
  * Whether the version banner should be suppressed for the command about to run.
  *
  * Structured-output (`--json`) and quiet (`--quiet`) invocations must keep stdout
- * free of human-facing chrome so callers can parse stdout directly. Uses
- * `optsWithGlobals()` so the check stays correct if either flag is ever promoted
- * to a global option.
+ * free of human-facing chrome so callers can parse stdout directly. Walks the
+ * command chain checking each command's OWN opts (not `optsWithGlobals()`): a
+ * flag set anywhere in the chain suppresses the banner, and reading own opts
+ * avoids a parent's default value shadowing a subcommand's explicit flag —
+ * `kici run` defines `--quiet` for its routed action, which under
+ * `optsWithGlobals()` would mask `kici run remote --quiet`.
  */
 export declare function shouldSuppressBanner(actionCommand: Command): boolean;
 //# sourceMappingURL=cli-banner.d.ts.map

package/dist/cli-banner.js

@@ -4,13 +4,21 @@ import "./rolldown-runtime-ClRpJifh.js";
 * Whether the version banner should be suppressed for the command about to run.
 *
 * Structured-output (`--json`) and quiet (`--quiet`) invocations must keep stdout
-* free of human-facing chrome so callers can parse stdout directly. Uses
-* `optsWithGlobals()` so the check stays correct if either flag is ever promoted
-* to a global option.
+* free of human-facing chrome so callers can parse stdout directly. Walks the
+* command chain checking each command's OWN opts (not `optsWithGlobals()`): a
+* flag set anywhere in the chain suppresses the banner, and reading own opts
+* avoids a parent's default value shadowing a subcommand's explicit flag —
+* `kici run` defines `--quiet` for its routed action, which under
+* `optsWithGlobals()` would mask `kici run remote --quiet`.
 */
 function shouldSuppressBanner(actionCommand) {
-	const opts = actionCommand.optsWithGlobals();
-	return Boolean(opts.json) || Boolean(opts.quiet);
+	let cmd = actionCommand;
+	while (cmd) {
+		const opts = cmd.opts();
+		if (opts.json === true || opts.quiet === true) return true;
+		cmd = cmd.parent;
+	}
+	return false;
 }
 //#endregion
 export { shouldSuppressBanner };

package/dist/cli.js

@@ -7,7 +7,7 @@ import { realpathSync } from "node:fs";
 import { Argument, Command, Option } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.1.25";
+const version = "0.1.27";
 /**
 * Top-level commands that were removed, mapped to their current equivalent.
 * Consulted when the CLI hits an unknown command so the user gets a precise
@@ -16,7 +16,8 @@ const version = "0.1.25";
 */
 const RETIRED_COMMANDS = {
 	status: "`kici status` is no longer a command. Use `kici runs list` / `kici runs show <run-id>` to inspect runs, or `kici diagnostics` for orchestrator, scaler, and agent health.",
-	cancel: "`kici cancel` is no longer a command. Use `kici runs cancel <run-id>`."
+	cancel: "`kici cancel` is no longer a command. Use `kici runs cancel <run-id>`.",
+	"run local": "`kici run local` is retired. Every run is now a real routed dispatch — use `kici run <event> --local` (e.g. `kici run push --local`), which runs this machine as an ephemeral agent through the local dev plane."
 };
 /**
 * Redirect message for a retired top-level command, or undefined if the name is
@@ -43,6 +44,7 @@ function attemptedCommand(program, argv) {
 function buildProgram() {
 	const program = new Command();
 	program.name("kici").description("KiCI workflow compiler").version(version);
+	program.enablePositionalOptions();
 	program.hook("preAction", (_thisCommand, actionCommand) => {
 		if (shouldSuppressBanner(actionCommand)) return;
 		console.log(pc.gray(`kici v${version}`));
@@ -73,50 +75,26 @@ function buildProgram() {
 		await fixtureCommand(event, options);
 	});
 	const runCommand = program.command("run").description("Execute workflows locally or remotely");
-	runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--input <KEY=VALUE>", "Typed workflow-dispatch input (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--in-place", "Run against the real working directory instead of an isolated tmp checkout", false).option("--keep", "Always retain the isolated tmp checkout (default: keep only on failure)", false).option("--check", "Run in check mode: report drift, change nothing", false).option("--fail-on-drift", "In check mode, exit non-zero if any step reports drift", false).action(async (event, options) => {
-		if (options.pick && options.workflow) {
-			console.error("Error: --pick is mutually exclusive with --workflow.");
-			process.exit(2);
-		}
-		if (!options.pick && !event) {
-			const { printRunLocalUsage } = await import("./commands/index.js");
-			printRunLocalUsage();
-			process.exit(2);
-		}
-		const { runLocalCommand } = await import("./commands/index.js");
-		const { resolveCheckMode } = await import("./commands/check-mode.js");
-		let checkMode;
-		try {
-			checkMode = resolveCheckMode({
-				check: options.check,
-				failOnDrift: options.failOnDrift
-			});
-		} catch (err) {
-			console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+	runCommand.enablePositionalOptions();
+	runCommand.argument("[event]", "Event type for a routed local run (e.g. push, pr:open)").option("--local", "Route the run with this machine as the ephemeral agent", false).option("--offline", "Force the throwaway/independent plane (offline)", false).option("--connected", "Force the connected/hybrid plane (requires attachment)", false).option("--in-place", "Reuse the working tree directly instead of an isolated clone", false).option("--trusted", "Route to the trusted fleet agent profile: steps see the ambient host env (minus the agent identity). Alias: --no-sandbox", false).option("--no-sandbox", "Alias for --trusted (the bwrap sandbox is already off by default)").option("--env <KEY=VALUE>", "Per-run secret (repeatable)", (val, prev) => [...prev, val], []).option("--payload <path>", "Dispatch payload JSON { action?, client_payload? } for a routed dispatch run").option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--quiet", "Suppress the banner + streaming output", false).option("--debug", "Verbose internals", false).action(async (event, options) => {
+		const retired = retiredCommandHint(event ? `run ${event}` : void 0);
+		if (retired) {
+			process.stderr.write(pc.red(`${retired}\n`));
 			process.exit(2);
 		}
-		const success = await runLocalCommand({
+		const { runRoutedCommand } = await import("./commands/index.js");
+		const success = await runRoutedCommand({
 			event,
-			checkMode,
-			pick: options.pick,
-			workflow: options.workflow,
-			job: options.job,
-			branch: options.branch,
-			sha: options.sha,
-			payload: options.payload,
-			concurrency: options.concurrency,
-			keepGoing: options.keepGoing,
-			container: options.container,
+			local: options.local,
+			offline: options.offline,
+			connected: options.connected,
+			inPlace: options.inPlace,
+			trusted: Boolean(options.trusted) || options.sandbox === false,
 			env: options.env,
-			inputs: options.input,
-			quiet: options.quiet,
-			json: options.json,
-			junit: options.junit,
-			files: options.files,
-			debug: options.debug,
+			payload: options.payload,
 			kiciDir: options.kiciDir,
-			inPlace: options.inPlace,
-			keep: options.keep
+			quiet: options.quiet,
+			debug: options.debug
 		});
 		process.exit(success ? 0 : 1);
 	});
@@ -174,7 +152,7 @@ function buildProgram() {
 		const success = await hookInstallCommand({ git: options.git });
 		process.exit(success ? 0 : 1);
 	});
-	program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--platform-endpoint <url>", "Platform relay URL").option("--oidc-issuer <url>", "OIDC issuer URL (defaults to the hosted KiCI IdP unless a flag/env selects another)").option("--routing-key <key>", "Routing key for webhook source identification").addHelpText("after", `
+	program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--platform-endpoint <url>", "Platform relay URL").option("--oidc-issuer <url>", "OIDC issuer URL (defaults to the hosted KiCI IdP unless a flag/env selects another)").option("--routing-key <key>", "Routing key for webhook source identification").option("--no-attach", "Skip the post-login prompt to attach the local dev plane").addHelpText("after", `
 Environment variables:
   KICI_BROWSER_CMD     Custom browser command (use {url} placeholder, or 'none' to suppress)
   KICI_CALLBACK_PORT   Fixed port for OAuth PKCE callback server (default: random)
@@ -188,7 +166,8 @@ Environment variables:
 			device: options.device,
 			platformEndpoint: options.platformEndpoint,
 			oidcIssuer: options.oidcIssuer,
-			routingKey: options.routingKey
+			routingKey: options.routingKey,
+			noAttachPrompt: options.attach === false
 		});
 		process.exit(success ? 0 : 1);
 	});
@@ -224,6 +203,50 @@ Environment variables:
 		const success = await orchestratorsUseCommand(name, { org: options.org });
 		process.exit(success ? 0 : 1);
 	});
+	const localCommand = program.command("local").description("Manage the local dev orchestrator plane");
+	localCommand.command("up").description("Start (or reuse) the local dev plane").option("--offline", "Force the independent (offline) plane (does not clear the attachment record)", false).option("--connected", "Force the connected/hybrid plane (requires an attached, reachable Platform)", false).action(async (options) => {
+		const { localUpCommand } = await import("./commands/index.js");
+		const ok = await localUpCommand({
+			offline: options.offline,
+			connected: options.connected
+		});
+		process.exit(ok ? 0 : 1);
+	});
+	for (const [name, desc, fn] of [
+		[
+			"status",
+			"Show local dev plane status and control commands",
+			"localStatusCommand"
+		],
+		[
+			"down",
+			"Stop the local dev plane",
+			"localDownCommand"
+		],
+		[
+			"logs",
+			"Print the local dev plane orchestrator log path",
+			"localLogsCommand"
+		],
+		[
+			"attach",
+			"Attach the local dev plane to the Platform (hybrid)",
+			"localAttachCommand"
+		],
+		[
+			"detach",
+			"Detach the local dev plane from the Platform (offline)",
+			"localDetachCommand"
+		]
+	]) localCommand.command(name).description(desc).action(async () => {
+		const ok = await (await import("./commands/index.js"))[fn]();
+		process.exit(ok ? 0 : 1);
+	});
+	localCommand.command("trust-root").description("Export the offline dev-signed identity trust root ({ issuer, jwks }) to a file").argument("<file>", "Output path for the { issuer, jwks } trust-root JSON").action(async (file) => {
+		const { localTrustRootCommand } = await import("./commands/index.js");
+		const ok = await localTrustRootCommand(file);
+		process.exit(ok ? 0 : 1);
+	});
 	program.command("secrets").description("Manage secrets").command("list").description("List test-available secret contexts").action(async () => {
 		const { secretsListCommand } = await import("./commands/index.js");
 		const success = await secretsListCommand();

package/dist/commands/check-mode.d.ts

@@ -1,5 +1,5 @@
 import { CheckMode } from '@kici-dev/engine';
-/** The two run-mode flags shared by `kici run local` and `kici run remote`. */
+/** The two check-mode flags accepted by `kici run remote`. */
 export interface CheckModeFlags {
     /** --check: report drift, change nothing. */
     check?: boolean;

package/dist/commands/compile.js

@@ -10,7 +10,7 @@ import "../lockfile/index.js";
 import path from "node:path";
 import { existsSync } from "node:fs";
 import pc from "picocolors";
-import fs from "node:fs/promises";
+import fs$1 from "node:fs/promises";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import { PackageManager, detectPackageManagerSync } from "@kici-dev/core/package-manager";
 import { execSync } from "node:child_process";
@@ -20,7 +20,7 @@ import { execSync } from "node:child_process";
 */
 async function readExistingLockfileHash(lockPath) {
 	try {
-		const content = await fs.readFile(lockPath, "utf-8");
+		const content = await fs$1.readFile(lockPath, "utf-8");
 		return JSON.parse(content).lockfileHash ?? void 0;
 	} catch {
 		return;
@@ -75,7 +75,7 @@ async function compileCommand(options) {
 		if (options.verbose) logger.debug(pc.dim("Validation passed"));
 		const lockJson = serializeLockFile(generateLockFile(workflowsWithSource));
 		if (!options.check) {
-			await fs.writeFile(lockPath, lockJson, "utf-8");
+			await fs$1.writeFile(lockPath, lockJson, "utf-8");
 			if (!options.quiet) logger.info(pc.green("✓") + ` Compiled workflows → .kici/kici.lock.json` + pc.dim(` (${workflowsWithSource.length} workflow${workflowsWithSource.length !== 1 ? "s" : ""})`));
 			try {
 				const { loadGlobalConfig } = await import("../remote/config.js");

package/dist/commands/index.d.ts

@@ -5,7 +5,9 @@ export { fixtureCommand } from './fixture.js';
 export type { FixtureOptions } from './fixture.js';
 export { previewCommand, previewEvent } from './preview.js';
 export type { PreviewOptions, RemoteRunOptions, RemoteRunResult } from './preview.js';
-export { runLocalCommand, runRemoteCommand, printRunLocalUsage } from './run.js';
+export { runRemoteCommand } from './run.js';
+export { runRoutedCommand } from './run-routed.js';
+export type { RunRoutedOptions } from './run-routed.js';
 export { initCommand } from './init.js';
 export type { InitOptions } from './init.js';
 export { hookInstallCommand } from './hook.js';
@@ -35,6 +37,8 @@ export type { DiagnosticsOptions } from './diagnostics.js';
 export { orgListCommand, orgUseCommand, orgCurrentCommand } from './org.js';
 export { orchestratorsListCommand, orchestratorsUseCommand } from './orchestrators.js';
 export type { OrchestratorsOptions } from './orchestrators.js';
+export { localUpCommand, localStatusCommand, localDownCommand, localLogsCommand, localAttachCommand, localDetachCommand, } from './local.js';
+export { localTrustRootCommand } from './local-trust-root.js';
 export { logoutCommand } from './logout.js';
 export { approveCommand } from './approve.js';
 export type { ApproveOptions } from './approve.js';

package/dist/commands/index.js

@@ -1,6 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { compileCommand } from "./compile.js";
 import { approveCommand } from "./approve.js";
+import { compileCommand } from "./compile.js";
 import { diagnosticsCommand } from "./diagnostics.js";
 import { docsCommand, docsLlmCommand } from "./docs.js";
 import { drainWorkerCommand } from "./drain-worker.js";
@@ -9,7 +9,8 @@ import { fixtureCommand } from "./fixture.js";
 import { hookInstallCommand } from "./hook.js";
 import { watchCommand } from "./watch.js";
 import { previewCommand, previewEvent } from "./preview.js";
-import { printRunLocalUsage, runLocalCommand, runRemoteCommand } from "./run.js";
+import { runRemoteCommand } from "./run.js";
+import { runRoutedCommand } from "./run-routed.js";
 import { initCommand } from "./init.js";
 import { loginCommand } from "./login.js";
 import { secretsListCommand } from "./secrets-list.js";
@@ -22,8 +23,10 @@ import { runsCancelCommand } from "./runs/cancel.js";
 import { typesCommand } from "./types.js";
 import { orgCurrentCommand, orgListCommand, orgUseCommand } from "./org.js";
 import { orchestratorsListCommand, orchestratorsUseCommand } from "./orchestrators.js";
+import { localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localUpCommand } from "./local.js";
+import { localTrustRootCommand } from "./local-trust-root.js";
 import { logoutCommand } from "./logout.js";
 import { rejectCommand } from "./reject.js";
 import { workflowsListCommand } from "./workflows.js";
 import { verifyAttestationCommand } from "./verify-attestation.js";
-export { approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, drainWorkerCommand, endpointsCommand, fixtureCommand, hookInstallCommand, initCommand, loginCommand, logoutCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, patCreateCommand, previewCommand, previewEvent, printRunLocalUsage, rejectCommand, runLocalCommand, runRemoteCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };
+export { approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, drainWorkerCommand, endpointsCommand, fixtureCommand, hookInstallCommand, initCommand, localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localTrustRootCommand, localUpCommand, loginCommand, logoutCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, patCreateCommand, previewCommand, previewEvent, rejectCommand, runRemoteCommand, runRoutedCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };

package/dist/commands/init.js

@@ -280,7 +280,7 @@ async function writePrivateRegistryScaffold(kiciDir, args) {
 //
 // The agent renders these into the .kici/.npmrc before running \`npm install\`.
 // The token is resolved from the qualified secret reference at dispatch time
-// (the orchestrator looks it up under the named environment's scoped secrets).
+// (the orchestrator looks it up under the named context's scoped secrets).
 import { workflow, job, step } from '@kici-dev/sdk';
 
 export default workflow('private-registry-example', {

package/dist/commands/local-trust-root.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Write the local dev plane's `{ issuer, jwks }` trust root to `outFile`.
+ * Returns true on success.
+ */
+export declare function localTrustRootCommand(outFile: string): Promise<boolean>;
+//# sourceMappingURL=local-trust-root.d.ts.map

package/dist/commands/local-trust-root.js

@@ -0,0 +1,52 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { devIdentityPublicJwkFile } from "../local-plane/plane-manager.js";
+import fs from "node:fs";
+import pc from "picocolors";
+import { logger } from "@kici-dev/core";
+//#region src/commands/local-trust-root.ts
+/**
+* `kici local trust-root <file>` — export the offline local dev plane's
+* dev-signed identity trust root as a self-contained `{ issuer, jwks }` file.
+*
+* The plane's dev identity mints tokens with issuer `kici-local` (clearly
+* non-prod). To self-test a dev-signed attestation offline, `kici
+* verify-attestation --trust-root <file>` needs the plane's public JWKS + its
+* issuer, supplied out-of-band. This command writes exactly the shape
+* `verify-attestation`'s `--trust-root` file path consumes.
+*
+* The exported issuer is the fixed sentinel `kici-local` — it can NEVER
+* masquerade as the prod issuer (`https://api.kici.dev`), so verifying the same
+* bundle against the default (prod) trust root still rejects structurally.
+*/
+/** The plane's fixed non-prod dev-identity issuer. */
+const KICI_LOCAL_ISSUER = "kici-local";
+/**
+* Write the local dev plane's `{ issuer, jwks }` trust root to `outFile`.
+* Returns true on success.
+*/
+async function localTrustRootCommand(outFile) {
+	if (!outFile) {
+		logger.error(pc.red("Error: an output file path is required (`kici local trust-root <file>`)."));
+		return false;
+	}
+	const pubFile = devIdentityPublicJwkFile();
+	let pubJwk;
+	try {
+		pubJwk = JSON.parse(fs.readFileSync(pubFile, "utf-8"));
+	} catch {
+		logger.error(pc.red("Error: no dev-signed identity found for the local plane. Boot the plane first (`kici local up`) so it generates + publishes its public key."));
+		return false;
+	}
+	const trustRoot = {
+		issuer: KICI_LOCAL_ISSUER,
+		jwks: { keys: [pubJwk] }
+	};
+	fs.writeFileSync(outFile, JSON.stringify(trustRoot, null, 2) + "\n");
+	logger.info(`${pc.green("✓")} Wrote local dev trust root to ${pc.bold(outFile)} ` + pc.dim(`(issuer ${KICI_LOCAL_ISSUER} — NOT prod)`));
+	logger.info(pc.dim(`Verify a dev-signed bundle offline with:\n  kici verify-attestation --bundle <bundle> --trust-root ${outFile}`));
+	return true;
+}
+//#endregion
+export { localTrustRootCommand };
+
+//# sourceMappingURL=local-trust-root.js.map

package/dist/commands/local.d.ts

@@ -0,0 +1,39 @@
+/**
+ * kici local commands
+ *
+ * Manage the warm, per-user local dev orchestrator plane: a real independent
+ * orchestrator plus a local Postgres (embedded, with a podman fallback) that
+ * `kici run --local` dispatches through. `up` boots or reuses the plane,
+ * `status` reports it plus the control commands, `down` stops it, and `logs`
+ * prints the orchestrator log path.
+ */
+/**
+ * Boot (or reuse) the local dev plane, honoring the durable attachment record.
+ *
+ * Routes through the same `resolvePlaneForRun` resolver `kici run --local` uses,
+ * so the two commands share one plane-resolution path and never diverge: an
+ * attached + reachable plane comes up hybrid, an attached-but-unreachable plane
+ * falls back to offline with a loud banner, and a never-attached plane comes up
+ * offline. `--offline` forces the independent boot (without clearing the durable
+ * attachment record — only `detach` does that); `--connected` requires an
+ * attached, reachable Platform.
+ */
+export declare function localUpCommand(flags?: {
+    offline?: boolean;
+    connected?: boolean;
+}): Promise<boolean>;
+/** Show the local dev plane status and its control commands. */
+export declare function localStatusCommand(): Promise<boolean>;
+/** Stop the local dev plane. */
+export declare function localDownCommand(): Promise<boolean>;
+/** Print the local dev plane orchestrator log path. */
+export declare function localLogsCommand(): Promise<boolean>;
+/**
+ * Attach the local dev plane to the hosted Platform so `kici run --local` uses
+ * real Platform-minted OIDC + attestation. Mints an org-scoped orchestrator key
+ * with the logged-in PAT, then (re)boots the plane hybrid.
+ */
+export declare function localAttachCommand(): Promise<boolean>;
+/** Detach the local dev plane from the Platform and reboot it offline (independent). */
+export declare function localDetachCommand(): Promise<boolean>;
+//# sourceMappingURL=local.d.ts.map

package/dist/commands/local.js

@@ -0,0 +1,137 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { loadGlobalConfig } from "../remote/config.js";
+import { attachPlane, detachPlane, planeDown, planeLogPath, planeStatus } from "../local-plane/plane-manager.js";
+import { resolvePlaneForRun } from "../local-plane/resolve-plane.js";
+import pc from "picocolors";
+import { toErrorMessage } from "@kici-dev/core";
+//#region src/commands/local.ts
+/**
+* kici local commands
+*
+* Manage the warm, per-user local dev orchestrator plane: a real independent
+* orchestrator plus a local Postgres (embedded, with a podman fallback) that
+* `kici run --local` dispatches through. `up` boots or reuses the plane,
+* `status` reports it plus the control commands, `down` stops it, and `logs`
+* prints the orchestrator log path.
+*/
+/** Print the control commands a user needs once the plane is running. */
+function printControlHints() {
+	console.log("");
+	console.log(pc.dim("Control commands:"));
+	console.log(`  ${pc.cyan("kici local status")}   Show plane status`);
+	console.log(`  ${pc.cyan("kici local logs")}     Print the orchestrator log path`);
+	console.log(`  ${pc.cyan("kici local down")}     Stop the plane`);
+}
+/**
+* Boot (or reuse) the local dev plane, honoring the durable attachment record.
+*
+* Routes through the same `resolvePlaneForRun` resolver `kici run --local` uses,
+* so the two commands share one plane-resolution path and never diverge: an
+* attached + reachable plane comes up hybrid, an attached-but-unreachable plane
+* falls back to offline with a loud banner, and a never-attached plane comes up
+* offline. `--offline` forces the independent boot (without clearing the durable
+* attachment record — only `detach` does that); `--connected` requires an
+* attached, reachable Platform.
+*/
+async function localUpCommand(flags = {}) {
+	console.log(pc.dim("Starting the local dev plane…"));
+	const resolved = await resolvePlaneForRun({
+		offline: flags.offline ?? false,
+		connected: flags.connected ?? false
+	});
+	if ("error" in resolved) {
+		console.log(pc.red(`✗ ${resolved.error}`));
+		return false;
+	}
+	const { plane } = resolved;
+	const url = plane.url ?? "";
+	const pg = pc.dim(`(postgres: ${plane.pgKind ?? "unknown"})`);
+	if (resolved.kind === "attached") console.log(pc.green("✓") + ` Local dev plane running (hybrid → Platform, org: ${pc.bold(resolved.orgId)}) at ${pc.bold(url)} ` + pg);
+	else {
+		console.log(pc.green("✓") + ` Local dev plane running (independent/offline) at ${pc.bold(url)} ` + pg);
+		if (resolved.kind === "fallback") console.log(pc.yellow(`  ⚠ Attached, but booted offline: ${resolved.reason}`));
+	}
+	printControlHints();
+	return true;
+}
+/** Show the local dev plane status and its control commands. */
+async function localStatusCommand() {
+	const status = await planeStatus();
+	if (!status.running) {
+		console.log(pc.yellow("Local dev plane is not running."));
+		console.log(`Start it with ${pc.cyan("kici local up")}.`);
+		return true;
+	}
+	console.log(pc.green("✓") + ` Local dev plane running at ${pc.bold(status.url ?? "")}`);
+	console.log(pc.dim(`  port:     ${status.port}`));
+	console.log(pc.dim(`  pid:      ${status.pid ?? "unknown"}`));
+	console.log(pc.dim(`  postgres: ${status.pgKind ?? "unknown"}`));
+	if (status.mode === "hybrid" && status.attachment) console.log(pc.dim(`  attached: hybrid → Platform (org: ${status.attachment.orgId})`));
+	else console.log(pc.dim("  attached: no (independent/offline)"));
+	printControlHints();
+	return true;
+}
+/** Stop the local dev plane. */
+async function localDownCommand() {
+	console.log(pc.dim("Stopping the local dev plane…"));
+	await planeDown();
+	console.log(pc.green("✓") + " Local dev plane stopped.");
+	return true;
+}
+/** Print the local dev plane orchestrator log path. */
+async function localLogsCommand() {
+	console.log(planeLogPath());
+	return true;
+}
+/**
+* Attach the local dev plane to the hosted Platform so `kici run --local` uses
+* real Platform-minted OIDC + attestation. Mints an org-scoped orchestrator key
+* with the logged-in PAT, then (re)boots the plane hybrid.
+*/
+async function localAttachCommand() {
+	const config = await loadGlobalConfig();
+	if (!config.pat) {
+		console.error(pc.red("Not authenticated. Run `kici login` first."));
+		return false;
+	}
+	if (!config.platformEndpoint) {
+		console.error(pc.red("No Platform endpoint configured. Run `kici login` first."));
+		return false;
+	}
+	const orgId = config.activeOrgId;
+	if (!orgId) {
+		console.error(pc.red("No active organization. Select one with `kici org use <org>` before attaching."));
+		return false;
+	}
+	try {
+		console.log(pc.dim("Attaching the local dev plane to the Platform…"));
+		const status = await attachPlane({
+			apiBase: config.platformEndpoint,
+			pat: config.pat,
+			orgId
+		});
+		console.log(pc.green("✓") + ` Local dev plane attached (hybrid) at ${pc.bold(status.url ?? "")} ` + pc.dim(`(org: ${orgId})`));
+		console.log(pc.dim("`kici run --local` now uses real Platform OIDC + attestation. Detach: ") + pc.cyan("kici local detach"));
+		return true;
+	} catch (err) {
+		console.error(pc.red(`Attach failed: ${toErrorMessage(err)}`));
+		return false;
+	}
+}
+/** Detach the local dev plane from the Platform and reboot it offline (independent). */
+async function localDetachCommand() {
+	const config = await loadGlobalConfig();
+	try {
+		console.log(pc.dim("Detaching the local dev plane…"));
+		await detachPlane({ pat: config.pat });
+		console.log(pc.green("✓") + " Local dev plane detached (independent/offline).");
+		return true;
+	} catch (err) {
+		console.error(pc.red(`Detach failed: ${toErrorMessage(err)}`));
+		return false;
+	}
+}
+//#endregion
+export { localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localUpCommand };
+
+//# sourceMappingURL=local.js.map

package/dist/commands/login.d.ts

@@ -9,6 +9,8 @@ export interface LoginOptions {
     routingKey?: string;
     /** Force device authorization flow regardless of environment */
     device?: boolean;
+    /** Skip the post-login "attach the local dev plane?" prompt (scripted logins). */
+    noAttachPrompt?: boolean;
 }
 /**
  * Authenticate with KiCI.

package/dist/commands/login.js

@@ -2,6 +2,7 @@ import "../rolldown-runtime-ClRpJifh.js";
 import { getConfigPath, loadGlobalConfig, mergeGlobalConfig, saveGlobalConfig } from "../remote/config.js";
 import { deviceFlow, exchangeTokenForPat, pkceFlow } from "../remote/oauth.js";
 import "../remote/prod-defaults.js";
+import { attachPlane, planeStatus } from "../local-plane/plane-manager.js";
 import { isHeadless } from "../auth/headless-detect.js";
 import pc from "picocolors";
 import { toErrorMessage } from "@kici-dev/core";
@@ -92,9 +93,48 @@ async function oauthLogin(options) {
 	console.log(pc.gray(`  PAT expires: ${expiryDate}`));
 	console.log(pc.gray(`  Config saved to ${configPath}`));
 	checkPatExpiry(patResult.expiresAt);
+	await maybePromptAttach(options, {
+		apiBase: platformUrl,
+		pat: patResult.token,
+		orgId: next.activeOrgId
+	});
 	return true;
 }
 /**
+* After a successful login, prompt an interactive user to attach their local
+* dev plane to the Platform. Skipped entirely for non-TTY / piped input, when
+* `--no-attach` is set, when no org is selected (nothing to attach against), or
+* when a plane is already attached. Any failure here is non-fatal — login has
+* already succeeded.
+*/
+async function maybePromptAttach(options, ctx) {
+	try {
+		if (options.noAttachPrompt) return;
+		if (!process.stdin.isTTY) return;
+		if (!ctx.orgId) {
+			console.log(pc.gray("\n  Tip: select an org (`kici org use <org>`) then `kici local attach` to use real Platform identity for `kici run --local`."));
+			return;
+		}
+		if ((await planeStatus()).mode === "hybrid") return;
+		console.log("\n  You don't have your local dev plane attached to the Platform.\n  Attach it so `kici run --local` uses real Platform secrets & identity?");
+		const answer = (await promptInput("  Attach now? [Y/n] ")).toLowerCase();
+		if (answer === "n" || answer === "no") {
+			console.log(pc.gray("  Left offline. Re-attach later with `kici local attach`."));
+			return;
+		}
+		console.log(pc.cyan("\n  Attaching the local dev plane…"));
+		const status = await attachPlane({
+			apiBase: ctx.apiBase,
+			pat: ctx.pat,
+			orgId: ctx.orgId
+		});
+		console.log(pc.green(`  ✓ Attached (hybrid) at ${status.url ?? ""} — \`kici run --local\` is now connected.`));
+	} catch (err) {
+		console.log(pc.yellow(`  Could not attach the local dev plane: ${toErrorMessage(err)}`));
+		console.log(pc.gray("  Login succeeded; attach later with `kici local attach`."));
+	}
+}
+/**
 * Authenticate with KiCI.
 *
 * - With `--token`, saves the API key directly (legacy flow)

package/dist/commands/logout.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { getConfigPath, loadGlobalConfig, saveGlobalConfig } from "../remote/config.js";
+import { detachPlane, planeStatus } from "../local-plane/plane-manager.js";
 import pc from "picocolors";
 //#region src/commands/logout.ts
 /**
@@ -37,6 +38,12 @@ async function logoutCommand() {
 	} catch {
 		console.log(pc.yellow("Warning: could not revoke PAT on server (will expire automatically)."));
 	}
+	try {
+		if ((await planeStatus()).mode === "hybrid") {
+			await detachPlane({ pat: config.pat });
+			console.log(pc.gray("Local dev plane detached (back to offline)."));
+		}
+	} catch {}
 	const cleanConfig = { ...config };
 	delete cleanConfig.pat;
 	delete cleanConfig.patId;

package/dist/commands/preview.js

@@ -35,7 +35,7 @@ async function previewCommand(event, options) {
 			logger.info(pc.gray("  kici preview schedule"));
 			logger.info(pc.gray("  kici preview lifecycle:workflow_complete\n"));
 			logger.info(pc.gray("For remote fixture execution, use: kici run remote [fixture] [options]"));
-			logger.info(pc.gray("For local workflow execution, use: kici run local <event> [options]\n"));
+			logger.info(pc.gray("For local workflow execution, use: kici run <event> --local\n"));
 			return true;
 		}
 		if (!isKnownEventArg(event)) {