linmux 0.1.0

package/dist/lib/cycle-move-runtime.js

@@ -0,0 +1,142 @@
+import { LinearAgentError } from "../core/errors/error.js";
+import { getLastComplexity, withFetchInterception } from "../core/transport/fetch-interceptor.js";
+import { withRateLimitRetry } from "../core/transport/rate-limit.js";
+import "../core/transport/index.js";
+import { createLinearClient } from "../core/client/factory.js";
+import "../core/client/index.js";
+import { loadConfig } from "../core/config/store.js";
+import "../core/config/index.js";
+import { parseFields, project } from "../core/projection/project.js";
+import { resolveWorkspace } from "../core/workspace/resolver.js";
+import { requireExplicitWorkspaceForWrite } from "../core/workspace/write-guard.js";
+import { ISSUE_IDENTIFIER_RE } from "./filter-heuristics.js";
+import { resolveCycleId } from "../core/resolvers/cycle.js";
+import "../core/resolvers/index.js";
+//#region src/lib/cycle-move-runtime.ts
+async function cycleMoveRuntime(input) {
+	const config = (input.loadConfigOverride ?? loadConfig)();
+	const envForResolver = {};
+	if (input.env.LINEAR_WORKSPACE !== void 0) envForResolver.LINEAR_WORKSPACE = input.env.LINEAR_WORKSPACE;
+	if (input.env.LINEAR_API_KEY !== void 0) envForResolver.LINEAR_API_KEY = input.env.LINEAR_API_KEY;
+	const resolved = resolveWorkspace({
+		flags: input.flags.workspace ? { workspace: input.flags.workspace } : {},
+		env: envForResolver,
+		config
+	});
+	requireExplicitWorkspaceForWrite(resolved, input.flags.allowActiveWorkspaceWrite ?? false);
+	const fields = parseFields(input.flags.fields ?? "defaults", "issue");
+	const client = (input.clientFactoryOverride ?? createLinearClient)(resolved);
+	return withFetchInterception(async () => {
+		const workspaceKey = resolved.name ?? "_api-key-env_";
+		const ref = input.args.issue;
+		const issueObj = await resolveIssue(client, ref, input.retryOptsOverride);
+		if (!issueObj) throw new LinearAgentError({
+			code: "ISSUE_NOT_FOUND",
+			message: `issue not found: ${ref}`,
+			details: { ref }
+		});
+		const issueIdRaw = issueObj.id;
+		if (typeof issueIdRaw !== "string") throw new LinearAgentError({
+			code: "ISSUE_NOT_FOUND",
+			message: `issue not found: ${ref}`,
+			details: { ref }
+		});
+		const issueId = issueIdRaw;
+		const teamRaw = await Promise.resolve(issueObj.team);
+		const teamId = teamRaw && typeof teamRaw === "object" && typeof teamRaw.id === "string" ? teamRaw.id : void 0;
+		if (!teamId) throw new LinearAgentError({
+			code: "ISSUE_NOT_FOUND",
+			message: `issue has no team: ${ref}`,
+			details: { ref }
+		});
+		const cycleId = await resolveCycleId(client, workspaceKey, teamId, input.args.to, input.retryOptsOverride);
+		const payload = await withRateLimitRetry(() => client.updateIssue(issueId, { cycleId }), input.retryOptsOverride);
+		if (!payload.success) throw LinearAgentError.linear.apiError({
+			message: "updateIssue returned success=false",
+			details: { lastSyncId: payload.lastSyncId }
+		});
+		let updated;
+		if (payload.issue !== void 0) {
+			const u = await Promise.resolve(payload.issue);
+			if (u !== void 0 && u !== null) updated = u;
+		}
+		let data;
+		if (updated) data = project(await hydrateForProjection(updated, fields), fields);
+		else data = {
+			id: issueId,
+			cycleId
+		};
+		const complexity = getLastComplexity();
+		const meta = {
+			workspace: resolved.name,
+			workspaceSource: resolved.source,
+			...complexity !== void 0 ? { complexity } : {}
+		};
+		return {
+			data,
+			meta
+		};
+	});
+}
+/**
+* Resolve an issue reference (ENG-123 or UUID) to its full Issue object.
+* Mirrors `issue-update-runtime.ts`'s helper -- duplicated rather than
+* extracted because the rule-of-three threshold hasn't been hit yet (issue-get,
+* issue-transition, issue-update, and now cycle-move all carry their own
+* copies; a future refactor may consolidate them in `src/lib/issue-ref.ts`).
+*/
+async function resolveIssue(client, ref, retryOpts) {
+	const m = ISSUE_IDENTIFIER_RE.exec(ref);
+	if (m) {
+		const teamKey = m[1].toUpperCase();
+		const number = Number(m[2]);
+		const filter = {
+			team: { key: { eq: teamKey } },
+			number: { eq: number }
+		};
+		return (await withRateLimitRetry(() => client.issues({
+			filter,
+			first: 1
+		}), retryOpts)).nodes[0];
+	}
+	return await withRateLimitRetry(() => client.issue(ref), retryOpts) ?? void 0;
+}
+const RELATION_KEYS = new Set([
+	"state",
+	"assignee",
+	"team",
+	"project",
+	"cycle",
+	"parent"
+]);
+async function hydrateForProjection(iss, spec) {
+	const needs = neededRelations(spec);
+	if (needs.size === 0) {
+		const out = {};
+		for (const k of Object.keys(iss)) if (!RELATION_KEYS.has(k)) out[k] = iss[k];
+		return out;
+	}
+	const hydrated = {};
+	for (const k of Object.keys(iss)) if (RELATION_KEYS.has(k)) {
+		if (needs.has(k)) {
+			const value = iss[k];
+			hydrated[k] = await resolveLazy(value);
+		}
+	} else hydrated[k] = iss[k];
+	return hydrated;
+}
+function neededRelations(spec) {
+	if (spec === "*") return new Set(RELATION_KEYS);
+	const out = /* @__PURE__ */ new Set();
+	for (const path of spec) {
+		const head = path.split(".")[0];
+		if (head && RELATION_KEYS.has(head)) out.add(head);
+	}
+	return out;
+}
+async function resolveLazy(value) {
+	if (value && typeof value.then === "function") return await value;
+	return value;
+}
+//#endregion
+export { cycleMoveRuntime };

package/dist/lib/describe-runtime.js

@@ -0,0 +1,180 @@
+import { LinearAgentError } from "../core/errors/error.js";
+import { OPERATION_REGISTRY } from "../generated/operations.js";
+import { CURATED_REGISTRY } from "./introspection-registry.js";
+import { suggestClosest } from "./levenshtein.js";
+import { getLinearSchema } from "./schema-loader.js";
+import { getNamedType, isInterfaceType, isObjectType, isUnionType, printType } from "graphql";
+import { z } from "zod";
+//#region src/lib/describe-runtime.ts
+/**
+* `describeRuntime` — Phase 4 PLAN 04-03, INT-02.
+*
+* Returns input JSON Schema (from Zod) + examples for curated commands,
+* or input JSON Schema + SDL fragment for raw operations. Zero network calls.
+*
+* Disambiguation algorithm (CONTEXT.md § Specifics, RESEARCH § Pitfall 6):
+*   - target.includes(' ') || /^[a-z]/.test(target) → curated path
+*   - PascalCase single token (uppercase start, no spaces) → raw path
+*   - Not found → DESCRIBE_COMMAND_NOT_FOUND with Levenshtein suggestions
+*
+* Exports:
+*   - `describeRuntime` — named runtime function (test seam)
+*   - `describeRuntime` is the only export; command shim lives in src/commands/describe.ts
+*/
+/**
+* The Phase 1 envelope output schema for curated commands.
+*
+* Mirrors the real envelope contract from `src/core/output/envelope.ts`:
+*   - SuccessEnvelope: { $apiVersion, ok: true, data, meta: Meta }
+*   - SuccessEnvelopeNoMeta: { $apiVersion, ok: true, data } -- emitted when
+*     `--quiet` or `--no-meta` is set (Phase 6 PLAN 06-01, MNT-02).
+*   - FailureEnvelope: { $apiVersion, ok: false, error, meta: FailureMeta }
+*
+* Per CONTEXT.md § describe shape — v1 leaves `data: z.unknown()`.
+* Per-entity output schemas deferred to Phase 5/6.
+*
+* Phase 6 PLAN 06-01 (MNT-02) extends this to a 3-way union to reflect the
+* `--no-meta` / `--quiet` envelope variants.
+*
+* If you change the envelope shape in `src/core/output/envelope.ts`, the
+* snapshot tests in `test/lib/describe-runtime.test.ts` and
+* `test/commands/describe.test.ts` will fail until this schema is brought
+* back into parity — that's intentional.
+*/
+const PageInfoSchema = z.object({
+	hasNextPage: z.boolean(),
+	endCursor: z.string().nullable(),
+	hasPreviousPage: z.boolean(),
+	startCursor: z.string().nullable()
+});
+const ComplexitySchema = z.object({
+	cost: z.number(),
+	remaining: z.number()
+});
+const BatchSchema = z.object({
+	count: z.number(),
+	kinds: z.object({
+		query: z.number(),
+		mutation: z.number()
+	})
+});
+const WorkspaceSourceSchema = z.enum([
+	"flag",
+	"env",
+	"active",
+	"single",
+	"api-key-env"
+]);
+const MetaSchema = z.object({
+	command: z.string(),
+	workspace: z.string().nullable().optional(),
+	workspaceSource: WorkspaceSourceSchema.optional(),
+	pageInfo: PageInfoSchema.optional(),
+	complexity: ComplexitySchema.optional(),
+	totalCount: z.number().optional(),
+	batch: BatchSchema.optional()
+});
+const FailureMetaSchema = z.object({
+	command: z.string(),
+	workspace: z.string().nullable().optional(),
+	workspaceSource: WorkspaceSourceSchema.optional()
+});
+const SuccessEnvelopeSchema = z.object({
+	$apiVersion: z.literal("1"),
+	ok: z.literal(true),
+	data: z.unknown(),
+	meta: MetaSchema
+});
+const SuccessEnvelopeNoMetaSchema = z.object({
+	$apiVersion: z.literal("1"),
+	ok: z.literal(true),
+	data: z.unknown()
+});
+const FailureEnvelopeSchema = z.object({
+	$apiVersion: z.literal("1"),
+	ok: z.literal(false),
+	error: z.object({
+		code: z.string(),
+		message: z.string(),
+		transient: z.boolean(),
+		retryAfterMs: z.number().optional(),
+		details: z.record(z.string(), z.unknown()).optional()
+	}),
+	meta: FailureMetaSchema
+});
+const EnvelopeOutputSchema = z.union([
+	SuccessEnvelopeSchema,
+	SuccessEnvelopeNoMetaSchema,
+	FailureEnvelopeSchema
+]);
+/**
+* Standard z.toJSONSchema() options per CONTEXT.md § stack contract.
+* Always use draft-2020-12 + unrepresentable:'any' to avoid crashes on
+* z.transform() or z.unknown() fields in raw varsSchemas (RESEARCH Pitfall 1, 4).
+*/
+const JSON_SCHEMA_OPTS = {
+	target: "draft-2020-12",
+	unrepresentable: "any"
+};
+/**
+* Convert PascalCase operation name to camelCase for root-type field lookup.
+* e.g. 'IssueCreate' → 'issueCreate'
+*/
+function toCamelCase(pascal) {
+	return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+/**
+* Get a compact SDL fragment for the return type of a raw operation.
+* Falls back to a comment string if resolution fails (acceptable for v1).
+*/
+function getSdlFragment(operationName, kind) {
+	try {
+		const schema = getLinearSchema();
+		const rootType = kind === "query" ? schema.getQueryType() : schema.getMutationType();
+		const fieldName = toCamelCase(operationName);
+		const field = rootType?.getFields()[fieldName];
+		const returnType = field ? getNamedType(field.type) : void 0;
+		if (returnType && (isObjectType(returnType) || isInterfaceType(returnType) || isUnionType(returnType))) return printType(returnType);
+		return `# Return type: ${returnType?.name ?? "unknown"}\n# Use the 'schema' command for full type definitions.`;
+	} catch {
+		return `# Return type resolution unavailable. Use the 'schema' command for full definitions.`;
+	}
+}
+/**
+* Core runtime for `linmux describe <command>`.
+*
+* @throws {LinearAgentError} with code DESCRIBE_COMMAND_NOT_FOUND when target is not found
+*/
+async function describeRuntime(args) {
+	const target = args.args.command;
+	if (target.includes(" ") || /^[a-z]/.test(target)) {
+		const entry = CURATED_REGISTRY.find((e) => e.id === target);
+		if (entry) return { data: {
+			command: target,
+			kind: "curated",
+			input: z.toJSONSchema(entry.inputSchema, JSON_SCHEMA_OPTS),
+			output: z.toJSONSchema(EnvelopeOutputSchema, JSON_SCHEMA_OPTS),
+			examples: entry.examples
+		} };
+	} else {
+		const entry = Object.hasOwn(OPERATION_REGISTRY, target) ? OPERATION_REGISTRY[target] : void 0;
+		if (entry) return { data: {
+			command: target,
+			kind: "raw",
+			input: z.toJSONSchema(entry.varsSchema, JSON_SCHEMA_OPTS),
+			output: getSdlFragment(target, entry.kind),
+			examples: []
+		} };
+	}
+	const suggestions = suggestClosest(target, [...CURATED_REGISTRY.map((e) => e.id), ...Object.keys(OPERATION_REGISTRY)], 3);
+	throw new LinearAgentError({
+		code: "DESCRIBE_COMMAND_NOT_FOUND",
+		message: `unknown command: '${target}'. Did you mean: ${suggestions.join(", ")}?`,
+		details: {
+			target,
+			suggestions
+		}
+	});
+}
+//#endregion
+export { describeRuntime };

package/dist/lib/filter-heuristics.js

@@ -0,0 +1,59 @@
+//#region src/lib/filter-heuristics.ts
+/**
+* Filter heuristics — UUID/email/team-key/issue-identifier routing for
+* entity filter flags. Extracted from `issue-list-runtime.ts` (Phase 1) so
+* `issue search`, future entity lists, and resolvers share the same shape
+* detection without drift (Phase 2 PLAN 02-01 Task 2; CONTEXT § Specifics).
+*
+* `buildIssueFilter` mirrors the original Phase 1 behavior verbatim for the
+* three flags it accepted (`state`, `assignee`, `team`) and adds three
+* forward-looking flags (`label`, `project`, `cycle`) that downstream Phase
+* 2 plans will surface in their command flags.
+*/
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const TEAM_KEY_RE = /^[A-Z0-9]{2,6}$/i;
+/** Linear issue identifiers like `ENG-123`. */
+const ISSUE_IDENTIFIER_RE = /^([A-Z][A-Z0-9]+)-(\d+)$/i;
+/**
+* Classify a free-form identifier string into the routing bucket the typed
+* SDK filter shape expects (UUID → `id`, email → `email`, ENG → `key`,
+* `me` → `isMe`, `ENG-123` → issue identifier, anything else → name).
+*
+* The `me` literal is checked first because it would otherwise match the
+* 2-char team-key pattern.
+*/
+function classifyIdentifier(value) {
+	if (value === "me") return "me";
+	if (UUID_RE.test(value)) return "uuid";
+	if (EMAIL_RE.test(value)) return "email";
+	if (ISSUE_IDENTIFIER_RE.test(value)) return "issueIdentifier";
+	if (TEAM_KEY_RE.test(value)) return "teamKey";
+	return "name";
+}
+/**
+* Build a typed-SDK `IssueFilter` from free-form CLI flag values.
+*
+* Behavior matches Phase 1 `issue-list-runtime.ts:140-174` for the three
+* original flags (`state`, `assignee`, `team`) — verified by Test 31 in the
+* Plan 02-01 Task 2 test suite, which is a regression check against the
+* original implementation.
+*/
+function buildIssueFilter(flags) {
+	const filter = {};
+	if (flags.state) filter.state = UUID_RE.test(flags.state) ? { id: { eq: flags.state } } : { name: { eq: flags.state } };
+	if (flags.assignee) if (flags.assignee === "me") filter.assignee = { isMe: { eq: true } };
+	else if (EMAIL_RE.test(flags.assignee)) filter.assignee = { email: { eq: flags.assignee } };
+	else if (UUID_RE.test(flags.assignee)) filter.assignee = { id: { eq: flags.assignee } };
+	else filter.assignee = { email: { eq: flags.assignee } };
+	if (flags.team) if (UUID_RE.test(flags.team)) filter.team = { id: { eq: flags.team } };
+	else if (TEAM_KEY_RE.test(flags.team)) filter.team = { key: { eq: flags.team.toUpperCase() } };
+	else filter.team = { name: { eq: flags.team } };
+	if (flags.label) filter.labels = UUID_RE.test(flags.label) ? { id: { eq: flags.label } } : { name: { eq: flags.label } };
+	if (flags.project) filter.project = UUID_RE.test(flags.project) ? { id: { eq: flags.project } } : { name: { eq: flags.project } };
+	if (flags.cycle) filter.cycle = { id: { eq: flags.cycle } };
+	if (Object.keys(filter).length === 0) return void 0;
+	return filter;
+}
+//#endregion
+export { EMAIL_RE, ISSUE_IDENTIFIER_RE, TEAM_KEY_RE, UUID_RE, buildIssueFilter, classifyIdentifier };

package/dist/lib/graphql-runtime.js

@@ -0,0 +1,202 @@
+import { LinearAgentError } from "../core/errors/error.js";
+import { getLinearSchema } from "./schema-loader.js";
+import { redact } from "../core/redact/redact.js";
+import { getLastComplexity, withFetchInterception } from "../core/transport/fetch-interceptor.js";
+import { withRateLimitRetry } from "../core/transport/rate-limit.js";
+import "../core/transport/index.js";
+import { createLinearClient } from "../core/client/factory.js";
+import "../core/client/index.js";
+import { loadConfig } from "../core/config/store.js";
+import "../core/config/index.js";
+import { resolveWorkspace } from "../core/workspace/resolver.js";
+import { requireExplicitWorkspaceForWrite } from "../core/workspace/write-guard.js";
+import { parse, validate } from "graphql";
+import { readFile } from "node:fs/promises";
+//#region src/lib/graphql-runtime.ts
+/**
+* `graphql-runtime` — 8-step pipeline for the free-form GraphQL command.
+*
+* Phase 3 PLAN 03-03, RAW-03.
+*
+* Pipeline:
+*   1. resolveWorkspace (same precedence chain as all commands)
+*   2. Load query text: `--query='...'` (inline) OR `--query=@file.graphql` (file ref)
+*      ENOENT/EACCES → GRAPHQL_QUERY_FILE_NOT_FOUND
+*   3. parse(queryText) — try/catch; syntax errors → GRAPHQL_VALIDATION_FAILED (kind=parse)
+*   4. validate(getLinearSchema(), document) — non-empty → GRAPHQL_VALIDATION_FAILED (kind=validate)
+*      Runs against vendored schema BEFORE any Linear API call (saves quota, gives precise errors)
+*   5. Detect operation kind via .find(d => d.kind === 'OperationDefinition')
+*      Pitfall 5: NOT definitions[0] — first def could be a FragmentDefinition
+*      'subscription' → OPERATION_SUBSCRIPTIONS_UNSUPPORTED (exit 2)
+*   6. If 'mutation': WSP-06 FIRST (requireExplicitWorkspaceForWrite), THEN --allow-mutations check
+*      Order matters — missing workspace is the more dangerous mistake
+*   7. Load vars: inline JSON OR @file.json (file ref takes precedence)
+*   8. Dispatch via client.client.rawRequest wrapped in withFetchInterception + withRateLimitRetry
+*
+* Error codes introduced by this plan:
+*   - GRAPHQL_QUERY_FILE_NOT_FOUND (exit 2) — @file.graphql missing
+*   - GRAPHQL_VALIDATION_FAILED (exit 12) — parse or validate failure
+*   - OPERATION_SUBSCRIPTIONS_UNSUPPORTED (exit 2) — subscription op rejected
+*
+* Codes reused from prior plans (no new snapshots needed):
+*   - RAW_MUTATION_REQUIRES_FLAG (exit 2) — from 03-02
+*   - WORKSPACE_REQUIRED_FOR_WRITE (exit 10) — from Phase 1 WSP-06
+*   - LINEAR_API_ERROR (exit 13) — from Phase 1
+*/
+async function runGraphql(input) {
+	const config = (input.loadConfigOverride ?? loadConfig)();
+	const envForResolver = {};
+	if (input.env.LINEAR_WORKSPACE !== void 0) envForResolver.LINEAR_WORKSPACE = input.env.LINEAR_WORKSPACE;
+	if (input.env.LINEAR_API_KEY !== void 0) envForResolver.LINEAR_API_KEY = input.env.LINEAR_API_KEY;
+	const resolved = resolveWorkspace({
+		flags: input.flags.workspace ? { workspace: input.flags.workspace } : {},
+		env: envForResolver,
+		config
+	});
+	const queryText = await loadQueryText(input.flags.query);
+	let document;
+	try {
+		document = parse(queryText);
+	} catch (err) {
+		throw new LinearAgentError({
+			code: "GRAPHQL_VALIDATION_FAILED",
+			message: `query parse failed: ${err.message}`,
+			details: {
+				kind: "parse",
+				cause: err.message
+			}
+		});
+	}
+	const validationErrors = validate(getLinearSchema(), document);
+	if (validationErrors.length > 0) throw new LinearAgentError({
+		code: "GRAPHQL_VALIDATION_FAILED",
+		message: `query failed schema validation (${validationErrors.length} error${validationErrors.length === 1 ? "" : "s"})`,
+		details: {
+			kind: "validate",
+			errors: validationErrors.map((e) => ({
+				message: e.message,
+				locations: e.locations,
+				path: e.path
+			}))
+		}
+	});
+	const opDef = document.definitions.find((d) => d.kind === "OperationDefinition");
+	if (!opDef || opDef.kind !== "OperationDefinition") throw new LinearAgentError({
+		code: "GRAPHQL_VALIDATION_FAILED",
+		message: "query has no operation definition",
+		details: { kind: "no-operation" }
+	});
+	if (opDef.operation === "subscription") throw new LinearAgentError({
+		code: "OPERATION_SUBSCRIPTIONS_UNSUPPORTED",
+		message: "subscriptions are not supported in v1 — use query or mutation operations"
+	});
+	if (opDef.operation === "mutation") {
+		requireExplicitWorkspaceForWrite(resolved, input.flags["allow-active-workspace-write"] ?? false);
+		if (!input.flags["allow-mutations"]) throw new LinearAgentError({
+			code: "RAW_MUTATION_REQUIRES_FLAG",
+			message: "mutation queries require --allow-mutations to prevent accidental data modification"
+		});
+	}
+	const vars = await loadVars(input.flags.vars);
+	if (input.mockRawRequest) {
+		const response = await input.mockRawRequest(queryText, vars);
+		if (response.error !== void 0 || response.data === void 0) throw new LinearAgentError({
+			code: "LINEAR_API_ERROR",
+			message: redact(response.error ?? "graphql request returned no data"),
+			details: {
+				kind: "graphql-runtime",
+				cause: response.error !== void 0 ? redact(response.error) : void 0
+			}
+		});
+		const complexity = getLastComplexity();
+		return {
+			data: response.data,
+			meta: {
+				workspace: resolved.name,
+				workspaceSource: resolved.source,
+				...complexity !== void 0 ? { complexity } : {}
+			}
+		};
+	}
+	const client = createLinearClient(resolved);
+	return withFetchInterception(async () => {
+		const response = await withRateLimitRetry(() => client.client.rawRequest(queryText, vars), input.retryOptsOverride);
+		if (response.error !== void 0 || response.data === void 0) throw new LinearAgentError({
+			code: "LINEAR_API_ERROR",
+			message: redact(response.error ?? "graphql request returned no data"),
+			details: {
+				kind: "graphql-runtime",
+				cause: response.error !== void 0 ? redact(response.error) : void 0
+			}
+		});
+		const complexity = getLastComplexity();
+		return {
+			data: response.data,
+			meta: {
+				workspace: resolved.name,
+				workspaceSource: resolved.source,
+				...complexity !== void 0 ? { complexity } : {}
+			}
+		};
+	});
+}
+/**
+* Load query text from inline string or @file.graphql reference.
+* If the query starts with '@', treat the rest as a filesystem path.
+*/
+async function loadQueryText(query) {
+	if (!query.startsWith("@")) return query;
+	const filePath = query.slice(1);
+	try {
+		return await readFile(filePath, "utf8");
+	} catch (err) {
+		const code = err.code;
+		throw new LinearAgentError({
+			code: "GRAPHQL_QUERY_FILE_NOT_FOUND",
+			message: `query file not found or not readable: ${filePath}`,
+			details: {
+				path: filePath,
+				cause: code ?? err.message
+			}
+		});
+	}
+}
+/**
+* Load vars from inline JSON string or @file.json reference.
+* File reference takes precedence if both are provided (file path starts with '@').
+* Returns an empty object if no vars provided.
+*
+* Note: This helper is intentionally duplicated from raw-runtime (not shared)
+* to maintain cross-plan independence for wave-2 parallel execution (03-02 and
+* 03-03 run concurrently; sharing a helper file would create ordering constraints).
+*/
+async function loadVars(vars) {
+	if (!vars) return {};
+	if (vars.startsWith("@")) {
+		const filePath = vars.slice(1);
+		try {
+			const text = await readFile(filePath, "utf8");
+			return JSON.parse(text);
+		} catch (err) {
+			throw new LinearAgentError({
+				code: "RAW_VARS_INVALID",
+				message: `failed to read or parse vars file: ${filePath}`,
+				details: {
+					path: filePath,
+					cause: err.message
+				}
+			});
+		}
+	}
+	try {
+		return JSON.parse(vars);
+	} catch (err) {
+		throw new LinearAgentError({
+			code: "RAW_VARS_INVALID",
+			message: "failed to parse --vars as JSON",
+			details: { cause: err.message }
+		});
+	}
+}
+//#endregion
+export { runGraphql };

package/dist/lib/include-fragments.js

@@ -0,0 +1,73 @@
+import { LinearAgentError } from "../core/errors/error.js";
+//#region src/lib/include-fragments.ts
+/**
+* `--include` fragment map for Phase 3 RAW-04.
+*
+* Maps each Tier-1 command name to a record of include-key → inline GraphQL
+* fragment text. The fragment text is inlined directly into the composed
+* query string inside the `nodes { ... }` selection set.
+*
+* Security: include keys are validated by exact-match lookup against this
+* map (T-03-04-INCLUDE-INJECTION). Unknown keys → INVALID_INCLUDE BEFORE
+* any string concat. Fragment text is hand-authored, NOT user-supplied.
+*
+* Single-round-trip guarantee (T-03-04-N-PLUS-1): agents requesting
+* `issue list --include comments` get one composed rawRequest call instead
+* of 1+N separate SDK calls.
+*/
+const INCLUDE_FRAGMENT_MAP = {
+	"issue list": {
+		comments: "comments(first: 50) { nodes { id body createdAt user { id name } } }",
+		labels: "labels(first: 50) { nodes { id name color } }",
+		attachments: "attachments(first: 25) { nodes { id title url } }",
+		subscribers: "subscribers(first: 50) { nodes { id name } }",
+		history: "history(first: 50) { nodes { id createdAt actor { id name } } }"
+	},
+	"issue get": {
+		comments: "comments(first: 50) { nodes { id body createdAt user { id name } } }",
+		labels: "labels(first: 50) { nodes { id name color } }",
+		attachments: "attachments(first: 25) { nodes { id title url } }",
+		subscribers: "subscribers(first: 50) { nodes { id name } }",
+		history: "history(first: 50) { nodes { id createdAt actor { id name } } }"
+	},
+	"comment list": {
+		reactions: "reactions { id emoji }",
+		parent: "parent { id body }"
+	},
+	"project get": {
+		members: "members(first: 50) { nodes { id name email } }",
+		teams: "teams(first: 25) { nodes { id key name } }",
+		projectMilestones: "projectMilestones(first: 50) { nodes { id name targetDate } }",
+		documents: "documents(first: 25) { nodes { id title } }"
+	},
+	"cycle list": { issues: "issues(first: 50) { nodes { id identifier title } }" }
+};
+/**
+* Validates every requested include key against the command's allowed map.
+* Returns concatenated fragment text (each fragment joined with newline +
+* 6-space indent to fit inside the typical `nodes { ... }` indentation).
+*
+* Returns '' when requested is empty (runtimes branch on empty BEFORE calling).
+*
+* Throws LinearAgentError with code 'INVALID_INCLUDE' (exit 2) and
+* details.allowed (sorted alphabetically) + details.unknown on any miss.
+* The error is thrown BEFORE any string concat — unknown keys never reach
+* the composed query string (T-03-04-INCLUDE-INJECTION mitigation).
+*/
+function validateAndMergeIncludes(commandName, requested) {
+	if (requested.length === 0) return "";
+	const allowed = INCLUDE_FRAGMENT_MAP[commandName];
+	const allowedKeys = Object.keys(allowed).sort();
+	const unknown = requested.filter((k) => !(k in allowed));
+	if (unknown.length > 0) throw new LinearAgentError({
+		code: "INVALID_INCLUDE",
+		message: `unknown --include keys for ${commandName}: ${unknown.join(", ")}`,
+		details: {
+			unknown,
+			allowed: allowedKeys
+		}
+	});
+	return requested.map((k) => allowed[k]).join("\n      ");
+}
+//#endregion
+export { INCLUDE_FRAGMENT_MAP, validateAndMergeIncludes };