linmux 0.1.0

package/dist/commands/workspace/remove.js

@@ -0,0 +1,63 @@
+import { LinearAgentError } from "../../core/errors/error.js";
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { updateConfig } from "../../core/config/store.js";
+import "../../core/config/index.js";
+import { Args, Command } from "@oclif/core";
+//#region src/commands/workspace/remove.ts
+async function runWorkspaceRemove(args) {
+	const runArgs = {
+		commandPath: "workspace remove",
+		pretty: args.pretty,
+		handler: async (_retryOpts) => {
+			let nextActive = null;
+			updateConfig((current) => {
+				if (!Object.hasOwn(current.workspaces, args.name)) throw LinearAgentError.workspace.notFound(args.name);
+				const remaining = {};
+				for (const [k, v] of Object.entries(current.workspaces)) if (k !== args.name) remaining[k] = v;
+				if (current.active === args.name) nextActive = Object.keys(remaining).sort()[0] ?? null;
+				else nextActive = current.active;
+				return {
+					active: nextActive,
+					workspaces: remaining
+				};
+			});
+			return {
+				data: {
+					removed: args.name,
+					active: nextActive
+				},
+				meta: {}
+			};
+		}
+	};
+	if (args.noMeta !== void 0) runArgs.noMeta = args.noMeta;
+	if (args.quiet !== void 0) runArgs.quiet = args.quiet;
+	if (args.retry !== void 0) runArgs.retry = args.retry;
+	return runCommand(runArgs);
+}
+var WorkspaceRemove = class WorkspaceRemove extends Command {
+	static description = "Remove a workspace from local config";
+	static enableJsonFlag = true;
+	static args = { name: Args.string({
+		required: true,
+		description: "Name of the workspace to remove"
+	}) };
+	static flags = { ...BASE_FLAGS };
+	async run() {
+		const { args, flags } = await this.parse(WorkspaceRemove);
+		const callArgs = {
+			name: args.name,
+			pretty: flags.pretty
+		};
+		if (flags.quiet !== void 0) callArgs.quiet = flags.quiet;
+		if (flags.noMeta !== void 0) callArgs.noMeta = flags.noMeta;
+		if (flags.retry !== void 0) callArgs.retry = flags.retry;
+		const out = await runWorkspaceRemove(callArgs);
+		if (!flags.json) process.stdout.write(out.stdout);
+		if (out.stderr) process.stderr.write(out.stderr);
+		if (out.exitCode !== 0) process.exitCode = out.exitCode;
+		return JSON.parse(out.stdout);
+	}
+};
+//#endregion
+export { WorkspaceRemove as default, runWorkspaceRemove };

package/dist/commands/workspace/replace-token.js

@@ -0,0 +1,89 @@
+import { LinearAgentError } from "../../core/errors/error.js";
+import { withFetchInterception } from "../../core/transport/fetch-interceptor.js";
+import { withRateLimitRetry } from "../../core/transport/rate-limit.js";
+import "../../core/transport/index.js";
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { createLinearClient } from "../../core/client/factory.js";
+import "../../core/client/index.js";
+import { loadConfig, saveConfig } from "../../core/config/store.js";
+import "../../core/config/index.js";
+import { Args, Command, Flags } from "@oclif/core";
+//#region src/commands/workspace/replace-token.ts
+async function runWorkspaceReplaceToken(args) {
+	const runArgs = {
+		commandPath: "workspace replace-token",
+		pretty: args.pretty,
+		handler: async (retryOpts) => {
+			const config = loadConfig();
+			const entry = config.workspaces[args.name];
+			if (!entry) throw LinearAgentError.workspace.notFound(args.name);
+			const expectedOrgId = entry.organizationId;
+			const client = createLinearClient({
+				name: null,
+				token: args.token,
+				organizationId: null,
+				source: "api-key-env"
+			});
+			const effectiveRetryOpts = args.retryOptsOverride ?? retryOpts;
+			const actualOrgId = await withFetchInterception(async () => {
+				const viewer = await withRateLimitRetry(() => client.viewer, effectiveRetryOpts);
+				return (await withRateLimitRetry(() => viewer.organization, effectiveRetryOpts)).id;
+			});
+			if (actualOrgId !== expectedOrgId) throw LinearAgentError.workspace.tokenMismatch(expectedOrgId, actualOrgId);
+			saveConfig({
+				...config,
+				workspaces: {
+					...config.workspaces,
+					[args.name]: {
+						...entry,
+						token: args.token
+					}
+				}
+			});
+			return {
+				data: {
+					name: args.name,
+					organizationId: expectedOrgId
+				},
+				meta: { workspace: args.name }
+			};
+		}
+	};
+	if (args.noMeta !== void 0) runArgs.noMeta = args.noMeta;
+	if (args.quiet !== void 0) runArgs.quiet = args.quiet;
+	if (args.retry !== void 0) runArgs.retry = args.retry;
+	return runCommand(runArgs);
+}
+var WorkspaceReplaceToken = class WorkspaceReplaceToken extends Command {
+	static description = "Rotate the API token for a registered workspace";
+	static enableJsonFlag = true;
+	static args = { name: Args.string({
+		required: true,
+		description: "Name of the workspace to rotate"
+	}) };
+	static flags = {
+		token: Flags.string({
+			required: true,
+			description: "New Linear personal API key (lin_api_*)"
+		}),
+		...BASE_FLAGS
+	};
+	async run() {
+		const { args, flags } = await this.parse(WorkspaceReplaceToken);
+		const callArgs = {
+			name: args.name,
+			token: flags.token,
+			pretty: flags.pretty
+		};
+		if (flags.quiet !== void 0) callArgs.quiet = flags.quiet;
+		if (flags.noMeta !== void 0) callArgs.noMeta = flags.noMeta;
+		if (flags.retry !== void 0) callArgs.retry = flags.retry;
+		const out = await runWorkspaceReplaceToken(callArgs);
+		if (!flags.json) process.stdout.write(out.stdout);
+		if (out.stderr) process.stderr.write(out.stderr);
+		if (out.exitCode !== 0) process.exitCode = out.exitCode;
+		return JSON.parse(out.stdout);
+	}
+};
+//#endregion
+export { WorkspaceReplaceToken as default, runWorkspaceReplaceToken };

package/dist/commands/workspace/use.js

@@ -0,0 +1,54 @@
+import { LinearAgentError } from "../../core/errors/error.js";
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { updateConfig } from "../../core/config/store.js";
+import "../../core/config/index.js";
+import { Args, Command } from "@oclif/core";
+//#region src/commands/workspace/use.ts
+async function runWorkspaceUse(args) {
+	const runArgs = {
+		commandPath: "workspace use",
+		pretty: args.pretty,
+		handler: async (_retryOpts) => {
+			return {
+				data: { active: updateConfig((current) => {
+					if (!Object.hasOwn(current.workspaces, args.name)) throw LinearAgentError.workspace.notFound(args.name);
+					return {
+						...current,
+						active: args.name
+					};
+				}).active },
+				meta: { workspace: args.name }
+			};
+		}
+	};
+	if (args.noMeta !== void 0) runArgs.noMeta = args.noMeta;
+	if (args.quiet !== void 0) runArgs.quiet = args.quiet;
+	if (args.retry !== void 0) runArgs.retry = args.retry;
+	return runCommand(runArgs);
+}
+var WorkspaceUse = class WorkspaceUse extends Command {
+	static description = "Set the active default workspace";
+	static enableJsonFlag = true;
+	static args = { name: Args.string({
+		required: true,
+		description: "Name of the workspace to make active"
+	}) };
+	static flags = { ...BASE_FLAGS };
+	async run() {
+		const { args, flags } = await this.parse(WorkspaceUse);
+		const callArgs = {
+			name: args.name,
+			pretty: flags.pretty
+		};
+		if (flags.quiet !== void 0) callArgs.quiet = flags.quiet;
+		if (flags.noMeta !== void 0) callArgs.noMeta = flags.noMeta;
+		if (flags.retry !== void 0) callArgs.retry = flags.retry;
+		const out = await runWorkspaceUse(callArgs);
+		if (!flags.json) process.stdout.write(out.stdout);
+		if (out.stderr) process.stderr.write(out.stderr);
+		if (out.exitCode !== 0) process.exitCode = out.exitCode;
+		return JSON.parse(out.stdout);
+	}
+};
+//#endregion
+export { WorkspaceUse as default, runWorkspaceUse };

package/dist/core/client/factory.js

@@ -0,0 +1,28 @@
+import { LinearClient } from "@linear/sdk";
+//#region src/core/client/factory.ts
+/**
+* KRN-05: a fresh `LinearClient` per CLI invocation.
+*
+* This factory is deliberately uncached. Every call constructs a new
+* `LinearClient` from the resolved token. The token-pinning bug class
+* (PITFALLS § Pitfall 2 — "stale token reused after workspace switch") is
+* impossible by construction.
+*
+* Why no caching:
+*   - Each CLI invocation is a fresh process. There is no "warm" client to
+*     reuse across invocations.
+*   - Within a single invocation, workspace is resolved exactly once at
+*     startup; we never switch mid-process.
+*   - Even if we DID cache, the cache key would have to include the resolved
+*     token — at which point the cache buys us nothing on a single-workspace
+*     invocation and is actively dangerous if a future refactor tries to
+*     share clients across workspaces.
+*
+* The SDK handles Linear's no-`Bearer ` Authorization header convention
+* internally; the caller passes `apiKey` and never touches the header.
+*/
+function createLinearClient(resolved) {
+	return new LinearClient({ apiKey: resolved.token });
+}
+//#endregion
+export { createLinearClient };

package/dist/core/client/index.js

@@ -0,0 +1,2 @@
+import "./factory.js";
+export {};

package/dist/core/config/index.js

@@ -0,0 +1,4 @@
+import "./paths.js";
+import "./schema.js";
+import "./store.js";
+export {};

package/dist/core/config/paths.js

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+//#region src/core/config/paths.ts
+/**
+* Resolve the directory the config file lives in.
+*
+* Order:
+*   1. `$XDG_CONFIG_HOME/linear-agent`  if the env var is set and non-empty
+*   2. `~/.config/linear-agent`         otherwise
+*
+* NOTE: the on-disk directory name is intentionally kept as `linear-agent`
+* (the CLI's former name) so existing registered workspaces survive the
+* rename to `linmux` without a migration. Do not change this string without a
+* read-side fallback that copies the legacy config — see CHANGELOG 0.1.0.
+*
+* Cross-platform note: this honors XDG on Linux/macOS (and on Windows when
+* a shell sets the env explicitly). Native Windows path defaults
+* (`%APPDATA%\linear-agent`) are out of scope for v1 — see PROJECT.md
+* runtime parity matrix; the file mode story doesn't apply on NTFS anyway.
+*/
+function configDir() {
+	const xdg = process.env.XDG_CONFIG_HOME;
+	return join(xdg && xdg.length > 0 ? xdg : join(homedir(), ".config"), "linear-agent");
+}
+/** Full path to the JSON config file (`<configDir>/config.json`). */
+function configPath() {
+	return join(configDir(), "config.json");
+}
+//#endregion
+export { configDir, configPath };

package/dist/core/config/schema.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+//#region src/core/config/schema.ts
+/**
+* Schema for one entry in the workspaces map.
+*
+* `token` holds a Linear Personal API key. The redactor scrubs the token
+* value out of any rendered envelope; the schema treats it as an
+* opaque non-empty string so we never reveal/decode it client-side.
+*
+* `organizationId` is captured at `workspace add` time via the SDK's
+* `viewer.organization.id` query (PLAN-04 wires this in). The schema
+* reserves the column here.
+*/
+const WorkspaceEntrySchema = z.object({
+	name: z.string().min(1),
+	token: z.string().min(1),
+	organizationId: z.string().min(1),
+	createdAt: z.string().datetime(),
+	lastUsedAt: z.string().datetime().optional()
+});
+/**
+* Top-level config shape: `{ active, workspaces }`.
+*
+* Invariant: when `active` is non-null, it MUST exist as a key in
+* `workspaces` (refine below). This catches hand-edited configs that
+* dangle the active pointer at a removed workspace.
+*/
+const ConfigSchema = z.object({
+	active: z.string().min(1).nullable(),
+	workspaces: z.record(z.string(), WorkspaceEntrySchema)
+}).refine((c) => c.active === null || Object.hasOwn(c.workspaces, c.active), {
+	message: "active references an unregistered workspace",
+	path: ["active"]
+});
+//#endregion
+export { ConfigSchema, WorkspaceEntrySchema };

package/dist/core/config/store.js

@@ -0,0 +1,149 @@
+import { LinearAgentError } from "../errors/error.js";
+import { configPath } from "./paths.js";
+import { ConfigSchema } from "./schema.js";
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+//#region src/core/config/store.ts
+/**
+* ConfigStore — atomic, 0600-aware reader/writer for the workspace registry.
+*
+* Design rationale (PITFALLS § Pitfalls 3,4 + CONTEXT § Config Storage):
+*
+*   We do NOT use `conf@^14` for this file. `conf` is excellent for general
+*   user-config storage but does not enforce a strict 0600 mode on read,
+*   which is precisely the property we need for token-bearing files. Wrapping
+*   `conf` to add the mode check would split logic across two libraries; a
+*   ~80 LOC bespoke writer is simpler to audit and easier to keep correct.
+*
+*   The store enforces three contract guarantees:
+*     1. The file mode on disk is exactly 0600 after every write.
+*     2. Reading a file whose mode is broader than 0600 fails closed with
+*        `CONFIG_PERMISSIONS_TOO_BROAD` (exit 11) BEFORE returning data.
+*     3. Writes are atomic from a reader's perspective: a sibling temp file
+*        (created with mode 0600 + fsync'd) is `rename`d into place. Readers
+*        never see a partial file.
+*
+*   Cross-platform note: POSIX modes don't apply on NTFS, so the
+*   permission-check is a no-op on Windows. v1 documents this as a known
+*   limitation; multi-user Windows boxes are outside the v1 threat model.
+*/
+const REQUIRED_DIR_MODE = 448;
+const IS_WINDOWS = process.platform === "win32";
+/**
+* Read the config file. Returns the empty config (`{ active: null, workspaces: {} }`)
+* if the file is missing — the very first `workspace add` writes it.
+*
+* Throws:
+*   - `CONFIG_PERMISSIONS_TOO_BROAD` (exit 11) if the file mode is broader
+*     than 0600 on a POSIX platform. Recovery: `chmod 600 <path>`.
+*   - `VALIDATION_FAILED` (exit 12) on malformed JSON or schema mismatch.
+*/
+function loadConfig(opts = {}) {
+	const target = opts.path ?? configPath();
+	let stat;
+	try {
+		stat = statSync(target);
+	} catch (e) {
+		if (isErrnoException(e) && e.code === "ENOENT") return cloneEmpty();
+		throw LinearAgentError.generic(`failed to stat config file: ${e?.message ?? String(e)}`);
+	}
+	if (!IS_WINDOWS) {
+		const fileMode = stat.mode & 511;
+		if (fileMode !== 384) throw LinearAgentError.auth.configPermissionsTooBroad(target, octal(fileMode));
+	}
+	let raw;
+	try {
+		raw = readFileSync(target, "utf8");
+	} catch (e) {
+		throw LinearAgentError.generic(`failed to read config file: ${e?.message ?? String(e)}`);
+	}
+	let parsedJson;
+	try {
+		parsedJson = JSON.parse(raw);
+	} catch (e) {
+		throw LinearAgentError.validation.failed("config file is not valid JSON", {
+			stage: "json-parse",
+			path: target,
+			parseError: e?.message ?? String(e)
+		});
+	}
+	const result = ConfigSchema.safeParse(parsedJson);
+	if (!result.success) throw LinearAgentError.validation.failed("config file failed schema validation", {
+		stage: "schema",
+		path: target,
+		issues: result.error.issues
+	});
+	return result.data;
+}
+/**
+* Write the config to disk atomically with mode 0600.
+*
+* The write protocol:
+*   1. Ensure parent directory exists with mode 0700 (recursive).
+*   2. Open a sibling temp file with `O_CREAT | O_WRONLY` and mode 0600.
+*   3. Write the serialized config + newline; `fsync`; `close`.
+*   4. `chmod 0600` defensively (umask may have masked the open() mode).
+*   5. `rename` the temp file over the target — atomic on POSIX.
+*   6. On any error mid-flight, attempt to unlink the temp file.
+*/
+function saveConfig(config, opts = {}) {
+	const validated = ConfigSchema.parse(config);
+	const target = opts.path ?? configPath();
+	const parent = dirname(target);
+	try {
+		mkdirSync(parent, {
+			recursive: true,
+			mode: REQUIRED_DIR_MODE
+		});
+	} catch (e) {
+		throw LinearAgentError.generic(`failed to create config directory: ${e?.message ?? String(e)}`);
+	}
+	const tempPath = `${target}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
+	let fd;
+	try {
+		fd = openSync(tempPath, "wx", 384);
+		const payload = `${JSON.stringify(validated, null, 2)}\n`;
+		writeSync(fd, payload);
+		fsyncSync(fd);
+		closeSync(fd);
+		fd = void 0;
+		if (!IS_WINDOWS) chmodSync(tempPath, 384);
+		renameSync(tempPath, target);
+	} catch (e) {
+		if (fd !== void 0) try {
+			closeSync(fd);
+		} catch {}
+		try {
+			unlinkSync(tempPath);
+		} catch {}
+		if (e instanceof LinearAgentError) throw e;
+		throw LinearAgentError.generic(`failed to write config file: ${e?.message ?? String(e)}`);
+	}
+}
+/**
+* Convenience: load → mutate → save in one call. Used by
+* `workspace add/use/remove/replace-token` in PLAN-04.
+*
+* Returns the saved config (post-mutator) so callers can inspect the result
+* without an extra `loadConfig` round-trip.
+*/
+function updateConfig(mutator, opts = {}) {
+	const next = mutator(loadConfig({ path: opts.path }));
+	saveConfig(next, opts);
+	return next;
+}
+function cloneEmpty() {
+	return {
+		active: null,
+		workspaces: {}
+	};
+}
+function octal(mode) {
+	return `0${mode.toString(8).padStart(3, "0")}`;
+}
+function isErrnoException(e) {
+	return e instanceof Error && typeof e.code === "string";
+}
+//#endregion
+export { loadConfig, saveConfig, updateConfig };

package/dist/core/errors/error.js

@@ -0,0 +1,142 @@
+//#region src/core/errors/error.ts
+/**
+* Substring patterns that must never appear in a LinearAgentError's
+* `message` field. The redactor (`src/core/redact/redact.ts`) is the
+* primary scrubber — this constructor-level guard is defense in depth
+* for callers that hand-craft messages.
+*
+* Linear PATs are formatted `lin_api_<base64-ish>` (and `lin_oauth_<...>`
+* for OAuth tokens). We forbid the literal prefixes anywhere in the
+* message string, not just at the start, because `Error("Authorization:
+* lin_api_...")` is the exact pattern callers tend to construct.
+*/
+const FORBIDDEN_TOKEN_PREFIXES = ["lin_api_", "lin_oauth_"];
+/** Codes whose default `transient` value is `true`. */
+const TRANSIENT_BY_DEFAULT = new Set(["RATELIMITED", "NETWORK_ERROR"]);
+/**
+* The single error class for the kernel. One base class with the code
+* enum, no per-code subclasses (over-engineering — see CONTEXT § specifics).
+*
+* Construction-time guarantees:
+*   - `code` is a member of the frozen taxonomy (TS-enforced).
+*   - `message` does NOT contain a literal `lin_api_` or `lin_oauth_`
+*     substring. This is defense in depth on top of the redactor — if a
+*     caller hand-crafts a message that bakes in a token, the constructor
+*     throws a *plain* `Error` (not a `LinearAgentError`) so the failure
+*     surfaces as a developer bug rather than a user-facing error.
+*   - `transient` defaults to `true` for `RATELIMITED` and `NETWORK_ERROR`,
+*     `false` for everything else. Callers may override.
+*/
+var LinearAgentError = class LinearAgentError extends Error {
+	name = "LinearAgentError";
+	code;
+	transient;
+	retryAfterMs;
+	details;
+	constructor(init) {
+		super(init.message);
+		for (const prefix of FORBIDDEN_TOKEN_PREFIXES) if (init.message.includes(prefix)) throw new Error(`token-shaped substring forbidden in error message (matched ${prefix}*); use the redactor or strip the token before constructing the error`);
+		this.code = init.code;
+		this.transient = init.transient ?? TRANSIENT_BY_DEFAULT.has(init.code);
+		if (init.retryAfterMs !== void 0) this.retryAfterMs = init.retryAfterMs;
+		if (init.details !== void 0) this.details = init.details;
+	}
+	static workspace = {
+		notResolved: (detail) => new LinearAgentError({
+			code: "WORKSPACE_NOT_RESOLVED",
+			message: detail ?? "no workspace could be resolved for this invocation"
+		}),
+		notFound: (name) => new LinearAgentError({
+			code: "WORKSPACE_NOT_FOUND",
+			message: `workspace not found: ${name}`,
+			details: { workspace: name }
+		}),
+		requiredForWrite: () => new LinearAgentError({
+			code: "WORKSPACE_REQUIRED_FOR_WRITE",
+			message: "write commands require an explicit --workspace flag, LINEAR_WORKSPACE env, or --allow-active-workspace-write opt-in"
+		}),
+		tokenMismatch: (expected, got) => new LinearAgentError({
+			code: "WORKSPACE_TOKEN_MISMATCH",
+			message: "token does not match the organizationId stored for this workspace",
+			details: {
+				expectedOrganizationId: expected,
+				gotOrganizationId: got
+			}
+		}),
+		alreadyExists: (name) => new LinearAgentError({
+			code: "WORKSPACE_ALREADY_EXISTS",
+			message: `workspace already registered: ${name} (use replace-token to rotate)`,
+			details: { workspace: name }
+		})
+	};
+	static auth = {
+		invalid: (detail) => new LinearAgentError({
+			code: "AUTH_INVALID",
+			message: detail ?? "authentication token is invalid or expired"
+		}),
+		configPermissionsTooBroad: (path, mode) => new LinearAgentError({
+			code: "CONFIG_PERMISSIONS_TOO_BROAD",
+			message: `config file mode is broader than 0600 (${mode}); run \`chmod 600 ${path}\``,
+			details: {
+				path,
+				mode
+			}
+		}),
+		configNotFound: (path) => new LinearAgentError({
+			code: "CONFIG_NOT_FOUND",
+			message: `config file not found: ${path}`,
+			details: { path }
+		})
+	};
+	static validation = {
+		failed: (detail, details) => new LinearAgentError({
+			code: "VALIDATION_FAILED",
+			message: detail,
+			...details !== void 0 ? { details } : {}
+		}),
+		invalidField: (field, allowed) => new LinearAgentError({
+			code: "INVALID_FIELD",
+			message: `unknown field: ${field}`,
+			details: allowed !== void 0 ? {
+				field,
+				allowed: [...allowed]
+			} : { field }
+		})
+	};
+	static linear = { apiError: (init) => new LinearAgentError({
+		code: "LINEAR_API_ERROR",
+		message: init.message,
+		...init.details !== void 0 ? { details: init.details } : {}
+	}) };
+	static rateLimited(retryAfterMs, details) {
+		return new LinearAgentError({
+			code: "RATELIMITED",
+			message: "Linear rate limit exceeded",
+			transient: true,
+			retryAfterMs,
+			...details !== void 0 ? { details } : {}
+		});
+	}
+	static network(detail, details) {
+		return new LinearAgentError({
+			code: "NETWORK_ERROR",
+			message: detail,
+			transient: true,
+			...details !== void 0 ? { details } : {}
+		});
+	}
+	static usage(detail) {
+		return new LinearAgentError({
+			code: "USAGE_ERROR",
+			message: detail
+		});
+	}
+	static generic(detail) {
+		return new LinearAgentError({
+			code: "GENERIC_ERROR",
+			message: detail
+		});
+	}
+};
+//#endregion
+export { LinearAgentError };

package/dist/core/errors/exit-codes.js

@@ -0,0 +1,70 @@
+//#region src/core/errors/exit-codes.ts
+/**
+* Canonical numeric exit codes per CONTEXT.md § Exit Code Taxonomy.
+*
+* Stays below 64 to avoid POSIX 125+ shell-reserved codes (clig.dev,
+* Wikipedia § Exit status). Agent runtimes can build retry logic on these
+* because every code is documented and stable.
+*/
+const EXIT_CODES = {
+	SUCCESS: 0,
+	GENERIC: 1,
+	USAGE: 2,
+	WORKSPACE: 10,
+	AUTH: 11,
+	VALIDATION: 12,
+	LINEAR_API: 13,
+	RATELIMITED: 14,
+	NETWORK: 15
+};
+/**
+* Map an `ErrorCode` to its canonical numeric exit code.
+*
+* Implemented as an exhaustive switch with a `_exhaustive: never` guard in
+* the default branch — adding a new code to `ERROR_CODES` without a
+* corresponding case will fail `tsc --noEmit`. This is exactly the
+* "hard-to-skip" property this kernel needs (T-01-03 in the threat model).
+*/
+function exitCodeFor(code) {
+	switch (code) {
+		case "WORKSPACE_NOT_RESOLVED":
+		case "WORKSPACE_NOT_FOUND":
+		case "WORKSPACE_REQUIRED_FOR_WRITE":
+		case "WORKSPACE_TOKEN_MISMATCH":
+		case "WORKSPACE_ALREADY_EXISTS": return EXIT_CODES.WORKSPACE;
+		case "AUTH_INVALID":
+		case "CONFIG_PERMISSIONS_TOO_BROAD":
+		case "CONFIG_NOT_FOUND": return EXIT_CODES.AUTH;
+		case "VALIDATION_FAILED":
+		case "INVALID_FIELD": return EXIT_CODES.VALIDATION;
+		case "LINEAR_API_ERROR": return EXIT_CODES.LINEAR_API;
+		case "RATELIMITED": return EXIT_CODES.RATELIMITED;
+		case "NETWORK_ERROR": return EXIT_CODES.NETWORK;
+		case "USAGE_ERROR":
+		case "VALIDATION_NO_FIELDS":
+		case "WORKFLOW_TEAM_REQUIRED":
+		case "CONFIRMATION_REQUIRED":
+		case "RAW_OPERATION_NOT_FOUND":
+		case "RAW_MUTATION_REQUIRES_FLAG":
+		case "OPERATION_SUBSCRIPTIONS_UNSUPPORTED":
+		case "GRAPHQL_QUERY_FILE_NOT_FOUND":
+		case "BATCH_REQUIRES_YES":
+		case "INVALID_INCLUDE":
+		case "DESCRIBE_COMMAND_NOT_FOUND": return EXIT_CODES.USAGE;
+		case "RAW_VARS_INVALID":
+		case "GRAPHQL_VALIDATION_FAILED":
+		case "BATCH_PLAN_INVALID": return EXIT_CODES.VALIDATION;
+		case "WORKFLOW_STATE_NOT_FOUND":
+		case "ISSUE_NOT_FOUND":
+		case "LABEL_NOT_FOUND":
+		case "TEAM_NOT_FOUND":
+		case "PROJECT_NOT_FOUND":
+		case "CYCLE_NOT_FOUND": return EXIT_CODES.LINEAR_API;
+		case "GENERIC_ERROR":
+		case "INSTALL_SKILL_BUNDLE_NOT_FOUND":
+		case "INSTALL_SKILL_WRITE_FAILED": return EXIT_CODES.GENERIC;
+		default: return code;
+	}
+}
+//#endregion
+export { exitCodeFor };