linmux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charlie Helman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# linmux
+
+> One CLI for Linear across **all** your workspaces — the full GraphQL surface (~500 ops), multiple workspaces in a single session, and stable versioned JSON built for AI agents.
+
+[![CI](https://github.com/ChuckMayo/linear-multi-workspace-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ChuckMayo/linear-multi-workspace-cli/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/linmux.svg)](https://www.npmjs.com/package/linmux)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
+
+`linmux` is a single shell-out CLI for Linear. It registers **as many Linear workspaces as you have** and lets one agent session route any command at any of them, it reaches **every operation in Linear's GraphQL schema** (~500, not a curated handful), and it emits a stable, versioned JSON envelope on every call. No per-workspace server to stand up — if your agent can run a shell command, it can drive Linear.
+
+```bash
+npx -y linmux@latest workspace add acme     --token lin_api_...
+npx -y linmux@latest workspace add personal --token lin_api_...
+npx -y linmux@latest issue list --workspace acme     --team ENG  --json
+npx -y linmux@latest issue list --workspace personal --team SIDE --json
+```
+
+> **Alpha (v0.1.0).** First public release, solo-maintained. Personal API keys only (no OAuth yet). The JSON envelope (`data.*` paths) is the stable contract; everything else may move. See [Project status](#project-status).
+
+---
+
+## Why this exists
+
+Linear's official MCP server is good, and it works in any MCP-capable agent. Two things it doesn't do — by design — are where `linmux` earns its place:
+
+- **Multiple workspaces in one session.** A Linear personal API key is scoped to a single workspace, and the official MCP authorizes one workspace per connection. To work across three workspaces you stand up three MCP server entries and juggle which is which. `linmux` registers all of them once and resolves a workspace **per command** (`--workspace <name>`), so a single session moves freely between them.
+- **The full API surface.** The official MCP exposes a curated subset of operations. `linmux` generates every operation in Linear's vendored GraphQL schema and dispatches it through a `raw` layer — so when you need `IssueBatchCreate` or some field the curated commands don't expose, it's already there.
+
+On top of those two, it's a plain shell-out: versioned JSON for agents to parse without prompting, token-saving flags for high-volume loops, and self-describing schemas so an agent can learn the surface on its own.
+
+| Capability                                   | Official Linear MCP             | `linmux`                              |
+| -------------------------------------------- | ------------------------------- | ------------------------------------- |
+| Multiple Linear workspaces in one session    | ❌ one workspace per connection | ✅ N workspaces, chosen per command   |
+| Full GraphQL surface (~500 ops)              | ⚠️ curated subset               | ✅ every operation, via the raw layer |
+| Adding a workspace                           | OAuth + a server entry each     | one `workspace add`, no server to run |
+| Transport                                    | MCP server (any MCP client)     | shell-out CLI (any agent that shells) |
+| Output for agents                            | MCP structured results          | versioned JSON envelope on stdout     |
+| Token-saving / self-discovery flags          | n/a                             | `--no-meta`, `--quiet`, `describe`, `list-tools` |
+
+Honest scope: other community CLIs (e.g. `schpet/linear-cli`) also do multi-workspace. What `linmux` bundles is multi-workspace **plus** the full surface **plus** an agent-stable JSON contract in one shell-out — that combination is the point, not multi-workspace alone.
+
+---
+
+## Quickstart
+
+### Requirements
+- Node.js **22** or newer
+- A Linear personal API key — generate one at [linear.app/settings/api](https://linear.app/settings/api)
+
+### 1. Register a workspace
+
+```bash
+npx -y linmux@latest workspace add acme --token lin_api_...
+```
+
+The workspace name is positional (`workspace add <name> --token ...`). The registry is a plain JSON file written with mode `0600` at `$XDG_CONFIG_HOME/linear-agent/config.json` (default `~/.config/linear-agent/config.json`; the directory name predates the rename — see [Project status](#project-status)). Tokens never leave your machine.
+
+### 2. Probe auth
+
+```bash
+npx -y linmux@latest whoami --json
+```
+
+Returns the resolved viewer + active workspace. Use it as your "did auth work" probe. (`me --json` returns viewer + organization.)
+
+### 3. Use it
+
+```bash
+# Curated commands
+npx -y linmux@latest issue list --team ENG --json
+npx -y linmux@latest issue create --team ENG --title "Fix the thing" --json
+npx -y linmux@latest comment create --issue ENG-123 --body "Done." --json
+
+# Any of the ~500 raw GraphQL operations
+npx -y linmux@latest describe IssueBatchCreate --json
+npx -y linmux@latest raw IssueBatchCreate --vars '{"input":{...}}' --json
+
+# Or an arbitrary GraphQL query
+npx -y linmux@latest graphql --query 'query { viewer { id } }' --json
+```
+
+Every command supports `--workspace <name>` to target a workspace inline — no `workspace use` required.
+
+---
+
+## The JSON envelope contract
+
+Every command emits a versioned envelope. Pin tests against `data.*` paths, not human prose. The `meta.workspace` field tells you which workspace served the call.
+
+**Success:**
+```json
+{
+  "$apiVersion": "1",
+  "ok": true,
+  "data": { /* command-specific payload */ },
+  "meta": { "command": "issue list", "workspace": "acme" }
+}
+```
+
+**Failure:**
+```json
+{
+  "$apiVersion": "1",
+  "ok": false,
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Title is required",
+    "transient": false,
+    "details": { "field": "title" }
+  },
+  "meta": { "command": "issue create" }
+}
+```
+
+`ok: true` → exit 0. `ok: false` → exit > 0 (see the error-code taxonomy via `describe`). `error.transient: true` means a retry is appropriate.
+
+Token-saving flags:
+- `--no-meta` — drop the `meta` block from success envelopes (~150–250 bytes saved per call)
+- `--quiet` — implies `--no-meta` + suppresses pretty banners
+- `--retry N` — add N transient-error retries on top of the defaults
+
+---
+
+## Multiple Linear workspaces, one session
+
+Register as many workspaces as you like:
+
+```bash
+npx -y linmux@latest workspace add work --token lin_api_...
+npx -y linmux@latest workspace add oss  --token lin_api_...
+npx -y linmux@latest workspace add side --token lin_api_...
+npx -y linmux@latest workspace list --json
+```
+
+Then route any command at any workspace per-call:
+
+```bash
+npx -y linmux@latest issue list --workspace work --team ENG  --json
+npx -y linmux@latest issue list --workspace oss  --team CORE --json
+```
+
+Workspace resolution order: `--workspace <name>` flag → `LINEAR_WORKSPACE` env var → registry's active workspace → sole registered workspace → `LINEAR_API_KEY` env var (bypasses the registry entirely; useful in CI).
+
+---
+
+## Agent integrations
+
+### Claude Code (bundled skill)
+
+```bash
+npx -y linmux@latest install-skill
+```
+
+Copies a Claude Code skill to `~/.claude/skills/linmux/SKILL.md`. The skill tells Claude when to invoke `linmux`, the envelope shape, and the self-discovery commands (`describe`, `list-tools`, `schema`).
+
+### Codex CLI, Gemini CLI, Cursor, anything else
+
+There's no plugin to install — point your agent at the binary:
+
+```bash
+# Codex CLI
+codex exec "list my open Linear issues using 'npx -y linmux@latest issue list --json'"
+
+# Gemini CLI / Cursor / Copilot CLI / etc. — same pattern: shell out to npx -y linmux@latest <cmd> --json
+```
+
+For best results, give your agent a short system prompt: auth lives in `LINEAR_API_KEY` or `linmux workspace add`; pass `--json`; `linmux list-tools --json` enumerates everything; `linmux describe <cmd> --json` returns the Zod-derived input/output schema for any command or raw operation.
+
+---
+
+## Self-discovery
+
+The CLI is introspectable so agents can learn the surface without external docs:
+
+```bash
+linmux list-tools --json               # every curated + raw command, one line each
+linmux describe issue create --json    # full Zod schema: required/optional flags, output shape, examples
+linmux schema --json                   # the entire vendored Linear GraphQL schema (introspection JSON)
+```
+
+`describe` is generated from the same Zod schemas that validate flags at runtime, so it's the canonical contract for what a command accepts and returns. Agents should prefer `describe` over reading source.
+
+---
+
+## Architecture
+
+- **Language:** TypeScript, ESM-only, Node 22+
+- **CLI framework:** [oclif](https://oclif.io/) (built-in `--json` mode, topic-based command organization)
+- **API client:** [`@linear/sdk`](https://www.npmjs.com/package/@linear/sdk) (official, codegen'd from Linear's GraphQL schema)
+- **Raw layer:** every operation in Linear's vendored schema is generated as a `TypedDocumentNode` and dispatched via the SDK's `rawRequest` escape hatch
+- **Validation:** [Zod 4](https://zod.dev/) for flag parsing AND output schema generation (`describe` reuses the same schemas)
+- **Bundling:** [tsdown](https://tsdown.dev/) for fast cold-start (<500 ms median target)
+- **Config:** a custom 0600 JSON store (no external config dependency); just workspace names + tokens + an active-workspace pointer
+
+The CLI stores nothing beyond the workspace registry and a single active-workspace pointer. No telemetry, no analytics, no network calls outside the Linear API.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ChuckMayo/linear-multi-workspace-cli.git
+cd linear-multi-workspace-cli
+npm install
+cp .env.example .env  # add your LINEAR_API_KEY for smoke tests
+npm run build
+npm test
+```
+
+Useful scripts:
+- `npm run lint` — Biome lint + format check
+- `npm run typecheck` — `tsc --noEmit`
+- `npm run codegen` — re-vendor the Linear schema + regenerate the raw operation registry
+- `npm run smoke:phase-2` — end-to-end smoke against a real workspace (requires `.env`; **writes to live Linear**)
+
+The vendored Linear schema lives at `schema.graphql`. A weekly GitHub Action (`schema-diff.yml`) detects drift against the live Linear API and opens a sync PR for additive changes.
+
+---
+
+## Project status
+
+**v0.1.0 — alpha, first public release, solo-maintained.** The curated command surface, raw-layer dispatch, JSON envelope contract, multi-workspace registry, and the Claude Code skill bundle are all in place and covered by the test suite.
+
+Known limitations:
+- Personal API keys only — no OAuth.
+- The on-disk config directory is `~/.config/linear-agent/` (the tool's former name), retained so existing registrations survive the rename. A clean migration to `~/.config/linmux/` is a follow-up.
+- Native Windows path defaults (`%APPDATA%`) are out of scope; XDG paths work on Linux/macOS and on Windows shells that set `XDG_CONFIG_HOME`.
+
+---
+
+## Contributing
+
+This repository is **maintained by [@ChuckMayo](https://github.com/ChuckMayo)**. External pull requests are not accepted at this stage — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the rationale and the right way to contribute (issues, discussions, forks).
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/run.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execute } from '@oclif/core'
+
+await execute({ dir: import.meta.url })

package/dist/commands/comment/create.js

@@ -0,0 +1,94 @@
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { commentCreateRuntime } from "../../lib/comment-create-runtime.js";
+import { Command, Flags } from "@oclif/core";
+//#region src/commands/comment/create.ts
+/**
+* `linmux comment create` -- Phase 2 PLAN 02-06 Task 1, CMT-01.create.
+*
+* Write command. Creates a Linear comment with `--issue` (UUID or ENG-123)
+* + `--body`. Optional `--parent <comment-uuid>` for threaded replies.
+*
+* Per RESEARCH 02-06 line 887, CommentCreateInput.issueId accepts a Linear
+* identifier (ENG-123) directly -- the runtime passes the user value through
+* without a client-side resolution round-trip.
+*
+* WSP-06 + required-flag validation both run in the runtime BEFORE any SDK
+* call.
+*
+* Implementation lives in `src/lib/comment-create-runtime.ts` per the Phase 1
+* PLAN-04 invariant. This file exports BOTH the oclif Command class AND a
+* named `runCommentCreate(args)` function.
+*/
+async function runCommentCreate(args) {
+	const runArgs = {
+		commandPath: "comment create",
+		pretty: args.pretty,
+		handler: async (retryOpts) => {
+			const runtimeFlags = {};
+			if (args.workspace !== void 0) runtimeFlags.workspace = args.workspace;
+			if (args.fields !== void 0) runtimeFlags.fields = args.fields;
+			if (args.allowActiveWorkspaceWrite !== void 0) runtimeFlags.allowActiveWorkspaceWrite = args.allowActiveWorkspaceWrite;
+			if (args.issue !== void 0) runtimeFlags.issue = args.issue;
+			if (args.body !== void 0) runtimeFlags.body = args.body;
+			if (args.parent !== void 0) runtimeFlags.parent = args.parent;
+			const result = await commentCreateRuntime({
+				args: {},
+				flags: runtimeFlags,
+				env: process.env,
+				retryOptsOverride: retryOpts
+			});
+			return {
+				data: result.data,
+				meta: result.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 CommentCreate = class CommentCreate extends Command {
+	static description = "Create a comment on a Linear issue. --issue + --body required; --parent optional for threaded replies.";
+	static enableJsonFlag = true;
+	static flags = {
+		...BASE_FLAGS,
+		workspace: Flags.string({ description: "Workspace name (overrides active default and LINEAR_WORKSPACE)" }),
+		"allow-active-workspace-write": Flags.boolean({ description: "Per-invocation opt-in to use the active default workspace for this write (WSP-06)" }),
+		fields: Flags.string({
+			description: "Field preset (ids|defaults|full) or comma-separated list",
+			default: "defaults"
+		}),
+		issue: Flags.string({
+			required: true,
+			description: "Issue UUID or identifier (ENG-123) to comment on (required)"
+		}),
+		body: Flags.string({
+			required: true,
+			description: "Comment body (markdown) (required)"
+		}),
+		parent: Flags.string({ description: "Parent comment UUID (for threaded replies)" })
+	};
+	async run() {
+		const { flags } = await this.parse(CommentCreate);
+		const callArgs = {
+			pretty: flags.pretty,
+			allowActiveWorkspaceWrite: flags["allow-active-workspace-write"]
+		};
+		if (flags.workspace !== void 0) callArgs.workspace = flags.workspace;
+		if (flags.fields !== void 0) callArgs.fields = flags.fields;
+		if (flags.issue !== void 0) callArgs.issue = flags.issue;
+		if (flags.body !== void 0) callArgs.body = flags.body;
+		if (flags.parent !== void 0) callArgs.parent = flags.parent;
+		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 runCommentCreate(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 { CommentCreate as default, runCommentCreate };

package/dist/commands/comment/delete.js

@@ -0,0 +1,74 @@
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { commentDeleteRuntime } from "../../lib/comment-delete-runtime.js";
+import { Args, Command, Flags } from "@oclif/core";
+//#region src/commands/comment/delete.ts
+/**
+* `linmux comment delete <id>` -- Phase 2 PLAN 02-06 Task 2,
+* CMT-01.delete.
+*
+* Write command. Deletes a Linear comment. WSP-06 enforced. NO `--yes` gate
+* -- comments are individually low-stakes; --yes is reserved for irreversible
+* operations (only `issue purge` per CONTEXT line 49). Linear's UI also
+* offers undo for comment deletion.
+*
+* Implementation lives in `src/lib/comment-delete-runtime.ts` per the Phase 1
+* PLAN-04 invariant. This file exports BOTH the oclif Command class AND a
+* named `runCommentDelete(args)` function.
+*/
+async function runCommentDelete(args) {
+	const runArgs = {
+		commandPath: "comment delete",
+		pretty: args.pretty,
+		handler: async (retryOpts) => {
+			const runtimeFlags = {};
+			if (args.workspace !== void 0) runtimeFlags.workspace = args.workspace;
+			if (args.allowActiveWorkspaceWrite !== void 0) runtimeFlags.allowActiveWorkspaceWrite = args.allowActiveWorkspaceWrite;
+			const result = await commentDeleteRuntime({
+				args: { id: args.id },
+				flags: runtimeFlags,
+				env: process.env,
+				retryOptsOverride: retryOpts
+			});
+			return {
+				data: result.data,
+				meta: result.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 CommentDelete = class CommentDelete extends Command {
+	static description = "Delete a Linear comment by UUID.";
+	static enableJsonFlag = true;
+	static args = { id: Args.string({
+		required: true,
+		description: "Comment UUID"
+	}) };
+	static flags = {
+		...BASE_FLAGS,
+		workspace: Flags.string({ description: "Workspace name (overrides active default and LINEAR_WORKSPACE)" }),
+		"allow-active-workspace-write": Flags.boolean({ description: "Per-invocation opt-in to use the active default workspace for this write (WSP-06)" })
+	};
+	async run() {
+		const { args, flags } = await this.parse(CommentDelete);
+		const callArgs = {
+			id: args.id,
+			pretty: flags.pretty,
+			allowActiveWorkspaceWrite: flags["allow-active-workspace-write"]
+		};
+		if (flags.workspace !== void 0) callArgs.workspace = flags.workspace;
+		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 runCommentDelete(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 { CommentDelete as default, runCommentDelete };

package/dist/commands/comment/list.js

@@ -0,0 +1,84 @@
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { PAGINATION_FLAGS } from "../../core/pagination/flags.js";
+import "../../core/pagination/index.js";
+import { commentListRuntime } from "../../lib/comment-list-runtime.js";
+import { Command, Flags } from "@oclif/core";
+//#region src/commands/comment/list.ts
+/**
+* `linmux comment list` -- Phase 2 PLAN 02-06 Task 1, CMT-01.list.
+*
+* Read command. Lists comments either workspace-wide or scoped to a single
+* issue (--issue ENG-123 or UUID). NO WSP-06 enforcement -- reads are
+* allowed against the active default workspace.
+*
+* Implementation lives in `src/lib/comment-list-runtime.ts` per the Phase 1
+* PLAN-04 invariant. This file exports BOTH the oclif Command class AND a
+* named `runCommentList(args)` async function so tests can call the runtime
+* without spawning a subprocess.
+*/
+async function runCommentList(args) {
+	const runArgs = {
+		commandPath: "comment list",
+		pretty: args.pretty,
+		handler: async (retryOpts) => {
+			const runtimeFlags = {};
+			if (args.workspace !== void 0) runtimeFlags.workspace = args.workspace;
+			if (args.fields !== void 0) runtimeFlags.fields = args.fields;
+			if (args.limit !== void 0) runtimeFlags.limit = args.limit;
+			if (args.cursor !== void 0) runtimeFlags.cursor = args.cursor;
+			if (args.issue !== void 0) runtimeFlags.issue = args.issue;
+			if (args.include !== void 0) runtimeFlags.include = args.include;
+			const result = await commentListRuntime({
+				flags: runtimeFlags,
+				env: process.env,
+				retryOptsOverride: retryOpts
+			});
+			return {
+				data: result.data,
+				meta: result.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 CommentList = class CommentList extends Command {
+	static description = "List Linear comments. Pass --issue ENG-123 (or UUID) to scope to one issue, otherwise lists workspace-wide.";
+	static enableJsonFlag = true;
+	static flags = {
+		...BASE_FLAGS,
+		...PAGINATION_FLAGS,
+		workspace: Flags.string({ description: "Workspace name (overrides active default and LINEAR_WORKSPACE)" }),
+		fields: Flags.string({
+			description: "Field preset (ids|defaults|full) or comma-separated list",
+			default: "defaults"
+		}),
+		issue: Flags.string({ description: "Filter to comments on this issue (UUID or ENG-123)" }),
+		include: Flags.string({
+			description: "Hydrate related entities in a single GraphQL round-trip (e.g. reactions, parent). Available: reactions, parent.",
+			multiple: true
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(CommentList);
+		const callArgs = { pretty: flags.pretty };
+		if (flags.workspace !== void 0) callArgs.workspace = flags.workspace;
+		if (flags.fields !== void 0) callArgs.fields = flags.fields;
+		if (flags.limit !== void 0) callArgs.limit = flags.limit;
+		if (flags.cursor !== void 0) callArgs.cursor = flags.cursor;
+		if (flags.issue !== void 0) callArgs.issue = flags.issue;
+		if (flags.include !== void 0) callArgs.include = flags.include;
+		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 runCommentList(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 { CommentList as default, runCommentList };

package/dist/commands/comment/update.js

@@ -0,0 +1,80 @@
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { commentUpdateRuntime } from "../../lib/comment-update-runtime.js";
+import { Args, Command, Flags } from "@oclif/core";
+//#region src/commands/comment/update.ts
+/**
+* `linmux comment update <id>` -- Phase 2 PLAN 02-06 Task 2, CMT-01.update.
+*
+* Write command. Updates a Linear comment's body. WSP-06 enforcement and
+* VALIDATION_NO_FIELDS guard both run in the runtime BEFORE any SDK call.
+*
+* Implementation lives in `src/lib/comment-update-runtime.ts` per the Phase 1
+* PLAN-04 invariant. This file exports BOTH the oclif Command class AND a
+* named `runCommentUpdate(args)` function.
+*/
+async function runCommentUpdate(args) {
+	const runArgs = {
+		commandPath: "comment update",
+		pretty: args.pretty,
+		handler: async (retryOpts) => {
+			const runtimeFlags = {};
+			if (args.workspace !== void 0) runtimeFlags.workspace = args.workspace;
+			if (args.fields !== void 0) runtimeFlags.fields = args.fields;
+			if (args.allowActiveWorkspaceWrite !== void 0) runtimeFlags.allowActiveWorkspaceWrite = args.allowActiveWorkspaceWrite;
+			if (args.body !== void 0) runtimeFlags.body = args.body;
+			const result = await commentUpdateRuntime({
+				args: { id: args.id },
+				flags: runtimeFlags,
+				env: process.env,
+				retryOptsOverride: retryOpts
+			});
+			return {
+				data: result.data,
+				meta: result.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 CommentUpdate = class CommentUpdate extends Command {
+	static description = "Update a Linear comment. --body is the only updatable field; pass \"\" to clear.";
+	static enableJsonFlag = true;
+	static args = { id: Args.string({
+		required: true,
+		description: "Comment UUID"
+	}) };
+	static flags = {
+		...BASE_FLAGS,
+		workspace: Flags.string({ description: "Workspace name (overrides active default and LINEAR_WORKSPACE)" }),
+		"allow-active-workspace-write": Flags.boolean({ description: "Per-invocation opt-in to use the active default workspace for this write (WSP-06)" }),
+		fields: Flags.string({
+			description: "Field preset (ids|defaults|full) or comma-separated list",
+			default: "defaults"
+		}),
+		body: Flags.string({ description: "New comment body (markdown). Pass \"\" to clear." })
+	};
+	async run() {
+		const { args, flags } = await this.parse(CommentUpdate);
+		const callArgs = {
+			id: args.id,
+			pretty: flags.pretty,
+			allowActiveWorkspaceWrite: flags["allow-active-workspace-write"]
+		};
+		if (flags.workspace !== void 0) callArgs.workspace = flags.workspace;
+		if (flags.fields !== void 0) callArgs.fields = flags.fields;
+		if (flags.body !== void 0) callArgs.body = flags.body;
+		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 runCommentUpdate(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 { CommentUpdate as default, runCommentUpdate };

package/dist/commands/cycle/current.js

@@ -0,0 +1,78 @@
+import { BASE_FLAGS, runCommand } from "../../lib/workspace-runtime.js";
+import { cycleCurrentRuntime } from "../../lib/cycle-current-runtime.js";
+import { Command, Flags } from "@oclif/core";
+//#region src/commands/cycle/current.ts
+/**
+* `linmux cycle current --team <ref>` -- Phase 2 PLAN 02-08 Task 1,
+* CYC-01.current.
+*
+* Single-entity read. Fetches the active cycle for a specific team. The
+* `--team` flag is REQUIRED -- the runtime throws WORKFLOW_TEAM_REQUIRED
+* (exit 2) BEFORE any SDK call when --team is absent. We deliberately do
+* NOT mark the oclif flag as `required: true` because that would surface a
+* generic oclif USAGE message rather than the structured agent-readable
+* error envelope.
+*
+* NO WSP-06 enforcement -- reads are allowed against the active default
+* workspace.
+*
+* Implementation lives in `src/lib/cycle-current-runtime.ts` per the Phase 1
+* PLAN-04 invariant. This file exports BOTH the oclif Command class AND a
+* named `runCycleCurrent(args)` async function so tests can call the runtime
+* without spawning a subprocess.
+*/
+async function runCycleCurrent(args) {
+	const runArgs = {
+		commandPath: "cycle current",
+		pretty: args.pretty,
+		handler: async (retryOpts) => {
+			const runtimeFlags = {};
+			if (args.workspace !== void 0) runtimeFlags.workspace = args.workspace;
+			if (args.fields !== void 0) runtimeFlags.fields = args.fields;
+			if (args.team !== void 0) runtimeFlags.team = args.team;
+			const result = await cycleCurrentRuntime({
+				flags: runtimeFlags,
+				env: process.env,
+				retryOptsOverride: retryOpts
+			});
+			return {
+				data: result.data,
+				meta: result.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 CycleCurrent = class CycleCurrent extends Command {
+	static description = "Get the active cycle for a team. --team is REQUIRED.";
+	static enableJsonFlag = true;
+	static flags = {
+		...BASE_FLAGS,
+		workspace: Flags.string({ description: "Workspace name (overrides active default and LINEAR_WORKSPACE)" }),
+		team: Flags.string({ description: "Team key (e.g. \"ENG\"), name, or UUID -- REQUIRED" }),
+		fields: Flags.string({
+			description: "Field preset (ids|defaults|full) or comma-separated list",
+			default: "defaults"
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(CycleCurrent);
+		const callArgs = { pretty: flags.pretty };
+		if (flags.workspace !== void 0) callArgs.workspace = flags.workspace;
+		if (flags.fields !== void 0) callArgs.fields = flags.fields;
+		if (flags.team !== void 0) callArgs.team = flags.team;
+		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 runCycleCurrent(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 { CycleCurrent as default, runCycleCurrent };