@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/dist/orchestrator/src/cli/linearCliShell.js

@@ -0,0 +1,1200 @@
+/* eslint-disable patterns/prefer-logger-over-console */
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import process from 'node:process';
+import { resolveLinearSourceSetup, } from './control/linearDispatchSource.js';
+import { attachProviderLinearIssuePr, createProviderLinearFollowUpIssue, deleteProviderLinearWorkpadComment, getProviderLinearIssueContext, transitionProviderLinearIssueState, upsertProviderLinearWorkpadComment } from './control/providerLinearWorkflowFacade.js';
+import { appendProviderLinearAuditEntry, isProviderLinearParallelizationDecision, isProviderLinearParallelizationReason, isProviderLinearParallelizationReasonAllowed, resolveProviderLinearAuditPath, summarizeProviderLinearAuditPath } from './control/providerLinearWorkflowAudit.js';
+import { findDeterministicProviderMutationSuppression, isFollowUpParityMatrixSuppressionCode, resolveProviderLinearWorkerAttemptStartedAt } from './control/providerLinearWorkerTruth.js';
+import { resolveProviderLinearRuntimeProof } from './control/providerLinearRuntimeProof.js';
+import { resolveProviderLinearScreenshotProof } from './control/providerLinearScreenshotProof.js';
+import { runProviderLinearChildStreamShell } from './providerLinearChildStreamShell.js';
+import { runProviderLinearChildLaneShell } from './providerLinearChildLaneShell.js';
+import { PROVIDER_LINEAR_WORKER_PROOF_FILENAME, loadProviderLinearWorkerContext, refreshProviderLinearWorkerProofSnapshot } from './providerLinearWorkerRunner.js';
+const DEFAULT_DEPENDENCIES = {
+    getProviderLinearIssueContext,
+    upsertProviderLinearWorkpadComment,
+    deleteProviderLinearWorkpadComment,
+    transitionProviderLinearIssueState,
+    attachProviderLinearIssuePr,
+    runProviderLinearChildStreamShell,
+    runProviderLinearChildLaneShell,
+    createProviderLinearFollowUpIssue,
+    resolveProviderLinearRuntimeProof,
+    resolveProviderLinearScreenshotProof,
+    loadProviderLinearWorkerContext,
+    refreshProviderLinearWorkerProofSnapshot,
+    appendAuditEntry: appendProviderLinearAuditEntry,
+    readTextFile: async (path) => await readFile(path, 'utf8'),
+    getEnv: () => process.env,
+    getCwd: () => process.cwd(),
+    now: () => new Date().toISOString(),
+    log: (line) => console.log(line),
+    warn: (line) => console.warn(line),
+    setExitCode: (code) => {
+        process.exitCode = code;
+    }
+};
+const LINEAR_MUTATING_SUBCOMMANDS = new Set([
+    'upsert-workpad',
+    'delete-workpad',
+    'transition',
+    'attach-pr',
+    'parallelization',
+    'create-follow-up',
+    'child-stream',
+    'child-lane'
+]);
+export async function runLinearCliShell(params, overrides = {}) {
+    const dependencies = { ...DEFAULT_DEPENDENCIES, ...overrides };
+    try {
+        const env = dependencies.getEnv();
+        const positionals = [...params.positionals];
+        const subcommand = positionals.shift();
+        const wantsHelp = params.flags['help'] === true
+            || params.flags['--help'] === true
+            || params.flags['h'] === true
+            || !subcommand
+            || subcommand === 'help'
+            || subcommand === '--help'
+            || subcommand === '-h';
+        if (wantsHelp) {
+            params.printHelp();
+            return;
+        }
+        if (positionals.length > 0) {
+            throw usageError('linear_extra_arguments', `linear does not accept extra positional arguments: ${positionals.join(' ')}`);
+        }
+        await assertLinearMutationAllowed(subcommand, params.flags, env, dependencies.readTextFile);
+        switch (subcommand) {
+            case 'issue-context': {
+                assertAllowedFlags(params.flags, ['format', 'issue-id', 'workspace-id', 'team-id', 'project-id']);
+                const result = await dependencies.getProviderLinearIssueContext({
+                    issueId: requireFlag(params.flags, 'issue-id'),
+                    sourceSetup: readSourceSetup(params.flags),
+                    allowReadOnlyCacheReuse: true,
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'upsert-workpad': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'issue-id',
+                    'workspace-id',
+                    'team-id',
+                    'project-id',
+                    'body',
+                    'body-file',
+                    'comment-id'
+                ]);
+                const bodyInput = await resolveBodyInput(params.flags, dependencies.readTextFile, dependencies.getCwd());
+                const result = await dependencies.upsertProviderLinearWorkpadComment({
+                    issueId: requireFlag(params.flags, 'issue-id'),
+                    body: bodyInput.text,
+                    bodyFilePath: bodyInput.filePath,
+                    commentId: readStringFlag(params.flags, 'comment-id') ?? null,
+                    sourceSetup: readSourceSetup(params.flags),
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'delete-workpad': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'issue-id',
+                    'workspace-id',
+                    'team-id',
+                    'project-id',
+                    'comment-id'
+                ]);
+                const result = await dependencies.deleteProviderLinearWorkpadComment({
+                    issueId: requireFlag(params.flags, 'issue-id'),
+                    commentId: readStringFlag(params.flags, 'comment-id') ?? null,
+                    sourceSetup: readSourceSetup(params.flags),
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'transition': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'issue-id',
+                    'workspace-id',
+                    'team-id',
+                    'project-id',
+                    'state',
+                    'expected-state',
+                    'expected-state-type',
+                    'expected-updated-at',
+                    'force',
+                    'force-reason'
+                ]);
+                const result = await dependencies.transitionProviderLinearIssueState({
+                    issueId: requireFlag(params.flags, 'issue-id'),
+                    stateName: requireFlag(params.flags, 'state'),
+                    expectedStateName: readStringFlag(params.flags, 'expected-state') ?? null,
+                    expectedStateType: readStringFlag(params.flags, 'expected-state-type') ?? null,
+                    expectedUpdatedAt: readStringFlag(params.flags, 'expected-updated-at') ?? null,
+                    force: readBooleanFlag(params.flags, 'force'),
+                    forceReason: readRawStringFlag(params.flags, 'force-reason'),
+                    sourceSetup: readSourceSetup(params.flags),
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'attach-pr': {
+                assertAllowedFlags(params.flags, ['format', 'issue-id', 'workspace-id', 'team-id', 'project-id', 'url', 'title']);
+                const result = await dependencies.attachProviderLinearIssuePr({
+                    issueId: requireFlag(params.flags, 'issue-id'),
+                    url: requireFlag(params.flags, 'url'),
+                    title: readStringFlag(params.flags, 'title') ?? null,
+                    sourceSetup: readSourceSetup(params.flags),
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'parallelization': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'issue-id',
+                    'workspace-id',
+                    'team-id',
+                    'project-id',
+                    'decision',
+                    'reason',
+                    'summary'
+                ]);
+                const issueId = requireFlag(params.flags, 'issue-id');
+                const decision = requireParallelizationDecision(params.flags);
+                const reason = requireParallelizationReason(params.flags, decision);
+                const summary = requireParallelizationSummary(params.flags, decision, reason);
+                const proofRefreshContext = await resolveParallelizationProofRefreshContext(issueId, env, dependencies);
+                const result = {
+                    ok: true,
+                    operation: 'parallelization',
+                    issue_id: issueId,
+                    issue_identifier: proofRefreshContext?.issueIdentifier ?? null,
+                    source_setup: resolveAuditSourceSetup(params.flags, env),
+                    decision,
+                    reason,
+                    summary
+                };
+                await recordAuditResult(result, params.flags, env, dependencies);
+                await refreshParallelizationProofSnapshotBestEffort(result, proofRefreshContext, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'create-follow-up': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'issue-id',
+                    'workspace-id',
+                    'team-id',
+                    'project-id',
+                    'title',
+                    'description',
+                    'description-file',
+                    'intent-checksum',
+                    'intent-checksum-file',
+                    'non-goals',
+                    'non-goals-file',
+                    'not-done-if',
+                    'not-done-if-file',
+                    'acceptance-criteria',
+                    'acceptance-criteria-file',
+                    'parity-lane',
+                    'parity-matrix',
+                    'parity-matrix-file',
+                    'canonical-owner-key',
+                    'canonical-owner-key-file',
+                    'blocked-by-source'
+                ]);
+                const description = await resolveRequiredText(params.flags, dependencies.readTextFile, 'description', 'description-file');
+                const intentChecksum = await resolveRequiredText(params.flags, dependencies.readTextFile, 'intent-checksum', 'intent-checksum-file');
+                const nonGoals = await resolveRequiredText(params.flags, dependencies.readTextFile, 'non-goals', 'non-goals-file');
+                const notDoneIf = await resolveRequiredText(params.flags, dependencies.readTextFile, 'not-done-if', 'not-done-if-file');
+                const acceptanceCriteria = await resolveRequiredText(params.flags, dependencies.readTextFile, 'acceptance-criteria', 'acceptance-criteria-file');
+                const parityLane = readBooleanFlag(params.flags, 'parity-lane');
+                const parityMatrix = await resolveOptionalText(params.flags, dependencies.readTextFile, 'parity-matrix', 'parity-matrix-file');
+                const retrySuppressed = await resolveCreateFollowUpRetrySuppression({
+                    issueId: requireFlag(params.flags, 'issue-id'),
+                    parityLane,
+                    parityMatrix,
+                    env,
+                    dependencies
+                });
+                if (retrySuppressed) {
+                    await recordAuditResult(retrySuppressed, params.flags, env, dependencies);
+                    emitJsonResult(retrySuppressed, dependencies);
+                    return;
+                }
+                const result = await dependencies.createProviderLinearFollowUpIssue({
+                    issueId: requireFlag(params.flags, 'issue-id'),
+                    title: requireFlag(params.flags, 'title'),
+                    description,
+                    intentChecksum,
+                    nonGoals,
+                    notDoneIf,
+                    acceptanceCriteria,
+                    parityLane,
+                    parityMatrix,
+                    canonicalOwnerKey: await resolveOptionalText(params.flags, dependencies.readTextFile, 'canonical-owner-key', 'canonical-owner-key-file'),
+                    blockedBySource: readBooleanFlag(params.flags, 'blocked-by-source'),
+                    sourceSetup: readSourceSetup(params.flags),
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'runtime-proof': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'issue-id',
+                    'workspace-id',
+                    'team-id',
+                    'project-id',
+                    'origin',
+                    'kind',
+                    'proof-url',
+                    'title',
+                    'summary',
+                    'reachability-mode'
+                ]);
+                const issueId = requireFlag(params.flags, 'issue-id');
+                const sourceSetup = resolveAuditSourceSetup(params.flags, env);
+                const resolved = await dependencies.resolveProviderLinearRuntimeProof({
+                    repoRoot: resolveRuntimeProofRepoRoot(dependencies.getCwd(), env),
+                    origin: requireFlag(params.flags, 'origin'),
+                    kind: readStringFlag(params.flags, 'kind') ?? null,
+                    proofUrl: readStringFlag(params.flags, 'proof-url') ?? null,
+                    title: readRawStringFlag(params.flags, 'title'),
+                    summary: readRawStringFlag(params.flags, 'summary'),
+                    reachabilityMode: readStringFlag(params.flags, 'reachability-mode') ?? null
+                });
+                const result = resolved.ok
+                    ? {
+                        ok: true,
+                        operation: 'runtime-proof',
+                        issue_id: issueId,
+                        source_setup: sourceSetup,
+                        policy: resolved.policy,
+                        proof: resolved.proof,
+                        handoff: resolved.handoff,
+                        reachability: resolved.reachability
+                    }
+                    : {
+                        ok: false,
+                        operation: 'runtime-proof',
+                        issue_id: issueId,
+                        source_setup: sourceSetup,
+                        policy: resolved.policy,
+                        error: resolved.error
+                    };
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'screenshot-proof': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'issue-id',
+                    'workspace-id',
+                    'team-id',
+                    'project-id',
+                    'output',
+                    'display-id',
+                    'window-id',
+                    'open-preview'
+                ]);
+                const issueId = requireFlag(params.flags, 'issue-id');
+                const sourceSetup = resolveAuditSourceSetup(params.flags, env);
+                const resolved = await dependencies.resolveProviderLinearScreenshotProof({
+                    cwd: dependencies.getCwd(),
+                    outputPath: readRawStringFlag(params.flags, 'output') ?? null,
+                    displayId: readStringFlag(params.flags, 'display-id') ?? null,
+                    windowId: readStringFlag(params.flags, 'window-id') ?? null,
+                    openPreview: readBooleanFlag(params.flags, 'open-preview')
+                });
+                const result = resolved.ok
+                    ? {
+                        ok: true,
+                        operation: 'screenshot-proof',
+                        issue_id: issueId,
+                        source_setup: sourceSetup,
+                        capture: resolved.capture
+                    }
+                    : {
+                        ok: false,
+                        operation: 'screenshot-proof',
+                        issue_id: issueId,
+                        source_setup: sourceSetup,
+                        capture: resolved.capture,
+                        error: resolved.error
+                    };
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'child-stream': {
+                assertAllowedFlags(params.flags, ['format', 'pipeline', 'stream']);
+                const result = await dependencies.runProviderLinearChildStreamShell({
+                    pipelineId: requireFlag(params.flags, 'pipeline'),
+                    streamName: readStringFlag(params.flags, 'stream') ?? null,
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            case 'child-lane': {
+                assertAllowedFlags(params.flags, [
+                    'format',
+                    'action',
+                    'stream',
+                    'purpose',
+                    'files',
+                    'phases',
+                    'instructions',
+                    'instructions-file',
+                    'reason'
+                ]);
+                const result = await dependencies.runProviderLinearChildLaneShell({
+                    action: requireFlag(params.flags, 'action'),
+                    streamName: readStringFlag(params.flags, 'stream') ?? null,
+                    purpose: readRawStringFlag(params.flags, 'purpose') ?? null,
+                    files: readCommaSeparatedFlag(params.flags, 'files'),
+                    phases: readCommaSeparatedFlag(params.flags, 'phases'),
+                    instructions: await resolveOptionalText(params.flags, dependencies.readTextFile, 'instructions', 'instructions-file'),
+                    reason: readRawStringFlag(params.flags, 'reason') ?? null,
+                    env
+                });
+                await recordAuditResult(result, params.flags, env, dependencies);
+                emitJsonResult(result, dependencies);
+                return;
+            }
+            default:
+                throw usageError('linear_unknown_subcommand', `Unknown linear subcommand: ${subcommand}`);
+        }
+    }
+    catch (error) {
+        emitJsonResult(isLinearCliUsageError(error) ? error.result : failureResult('linear_cli_error', resolveErrorMessage(error), 500), dependencies);
+    }
+}
+async function resolveParallelizationProofRefreshContext(issueId, env, dependencies) {
+    try {
+        const context = await dependencies.loadProviderLinearWorkerContext(env);
+        if (context.pipelineId !== 'provider-linear-worker' || context.issueId !== issueId) {
+            return null;
+        }
+        return {
+            runDir: context.runDir,
+            issueId: context.issueId,
+            issueIdentifier: context.issueIdentifier
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveProviderLinearWorkerAttemptStartedAtForIssue(issueId, env, dependencies) {
+    const context = await resolveParallelizationProofRefreshContext(issueId, env, dependencies);
+    if (!context) {
+        return null;
+    }
+    try {
+        const raw = await dependencies.readTextFile(join(context.runDir, PROVIDER_LINEAR_WORKER_PROOF_FILENAME));
+        const parsed = JSON.parse(raw);
+        return resolveProviderLinearWorkerAttemptStartedAt(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveCreateFollowUpRetrySuppression(input) {
+    if (!input.parityLane || (input.parityMatrix?.trim().length ?? 0) > 0) {
+        return null;
+    }
+    const auditPath = resolveProviderLinearAuditPath(input.env);
+    if (!auditPath) {
+        return null;
+    }
+    const attemptStartedAt = await resolveProviderLinearWorkerAttemptStartedAtForIssue(input.issueId, input.env, input.dependencies);
+    if (!attemptStartedAt) {
+        return null;
+    }
+    let audit = null;
+    try {
+        audit = await summarizeProviderLinearAuditPath(auditPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        input.dependencies.warn(`linear create-follow-up warning: failed to summarize provider-linear audit at ${auditPath}; proceeding without retry suppression. error=${message}`);
+        return null;
+    }
+    const suppression = findDeterministicProviderMutationSuppression(audit, 'create-follow-up', {
+        recordedAtNotBefore: attemptStartedAt,
+        issueId: input.issueId
+    });
+    if (!suppression || !isFollowUpParityMatrixSuppressionCode(suppression.error_code)) {
+        return null;
+    }
+    return {
+        ok: false,
+        operation: 'create-follow-up',
+        error: {
+            code: 'linear_follow_up_parity_matrix_retry_suppressed',
+            message: `Same-attempt retry suppressed: ${suppression.instruction}`,
+            status: 409
+        }
+    };
+}
+async function refreshParallelizationProofSnapshotBestEffort(result, context, env, dependencies) {
+    if (!result.ok || !context) {
+        return;
+    }
+    const auditPath = resolveProviderLinearAuditPath(env);
+    try {
+        await dependencies.refreshProviderLinearWorkerProofSnapshot(context.runDir, auditPath, undefined, undefined, env);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        dependencies.warn(`linear parallelization warning: failed to refresh provider-linear-worker proof snapshot for ${context.issueIdentifier}: ${message}`);
+    }
+}
+function emitJsonResult(result, dependencies) {
+    dependencies.log(JSON.stringify(result, null, 2));
+    if (!result.ok) {
+        dependencies.setExitCode(1);
+    }
+}
+function assertAllowedFlags(flags, allowed) {
+    const allowedSet = new Set([...allowed, 'help', '--help', 'h']);
+    for (const key of Object.keys(flags)) {
+        if (!allowedSet.has(key)) {
+            throw usageError('linear_unknown_flag', `Unknown linear flag: --${key}`);
+        }
+    }
+    const format = flags['format'];
+    if (format !== undefined && format !== 'json') {
+        throw usageError('linear_format_unsupported', 'linear only supports --format json.');
+    }
+}
+function requireFlag(flags, key) {
+    const value = readStringFlag(flags, key);
+    if (!value) {
+        throw usageError('linear_missing_flag', `--${key} is required.`);
+    }
+    return value;
+}
+function readRawStringFlag(flags, key) {
+    const value = flags[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function readStringFlag(flags, key) {
+    const value = flags[key];
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function readBooleanFlag(flags, key) {
+    const value = flags[key];
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value !== 'string') {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return ['1', 'true', 'yes', 'on'].includes(normalized);
+}
+function requireParallelizationDecision(flags) {
+    const decision = readStringFlag(flags, 'decision');
+    if (!isProviderLinearParallelizationDecision(decision)) {
+        throw usageError('linear_parallelization_decision_invalid', 'linear parallelization requires --decision parallelize_now|stay_serial|forbid_parallel.');
+    }
+    return decision;
+}
+function requireParallelizationReason(flags, decision) {
+    const reason = readStringFlag(flags, 'reason');
+    if (!isProviderLinearParallelizationReason(reason)) {
+        throw usageError('linear_parallelization_reason_invalid', 'linear parallelization requires a recognized --reason code.');
+    }
+    if (!isProviderLinearParallelizationReasonAllowed(decision, reason)) {
+        throw usageError('linear_parallelization_reason_mismatch', `linear parallelization reason ${reason} is not allowed for decision ${decision}.`);
+    }
+    return reason;
+}
+function requireParallelizationSummary(flags, decision, reason) {
+    const summary = readStringFlag(flags, 'summary');
+    if (!summary) {
+        throw usageError('linear_parallelization_summary_missing', 'linear parallelization requires --summary with matrix/cap evidence for the decision.');
+    }
+    if (decision === 'stay_serial' && reason === 'single_bounded_change') {
+        const missingSlices = ['docs', 'test', 'research', 'review'].filter((slice) => !new RegExp(`(?:^|;)\\s*${slice}\\s*:\\s*[^;\\s][^;]*`, 'i').test(summary));
+        if (missingSlices.length > 0) {
+            throw usageError('linear_parallelization_single_bounded_change_summary_incomplete', `linear parallelization single_bounded_change summaries must explain why no docs/test/research/review slice can be separated safely with labeled slice evidence; missing: ${missingSlices.join(', ')}.`);
+        }
+    }
+    if (decision === 'stay_serial' &&
+        reason === 'existing_child_lane_active' &&
+        !/(?:^|;)\s*cap_exhausted\s*:\s*[^;\s][^;]*/iu.test(summary)) {
+        throw usageError('linear_parallelization_cap_exhausted_summary_missing', 'linear parallelization existing_child_lane_active summaries must include labeled cap_exhausted evidence, for example `cap_exhausted: 2/2 active child lanes`.');
+    }
+    return summary;
+}
+function readCommaSeparatedFlag(flags, key) {
+    const value = readRawStringFlag(flags, key);
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function readSourceSetup(flags) {
+    const workspaceId = readStringFlag(flags, 'workspace-id') ?? null;
+    const teamId = readStringFlag(flags, 'team-id') ?? null;
+    const projectId = readStringFlag(flags, 'project-id') ?? null;
+    if (!workspaceId && !teamId && !projectId) {
+        return null;
+    }
+    return {
+        provider: 'linear',
+        workspace_id: workspaceId,
+        team_id: teamId,
+        project_id: projectId
+    };
+}
+async function resolveBodyInput(flags, readTextFile, cwd) {
+    const inlineValue = readRawStringFlag(flags, 'body');
+    const fileValue = readStringFlag(flags, 'body-file');
+    const hasInlineValue = typeof inlineValue === 'string' && inlineValue.trim().length > 0;
+    if (hasInlineValue && fileValue) {
+        throw usageError('linear_body_conflict', 'Use either --body or --body-file, not both.');
+    }
+    if (hasInlineValue) {
+        return {
+            text: inlineValue,
+            filePath: null
+        };
+    }
+    if (!fileValue) {
+        throw usageError('linear_body_missing', '--body or --body-file is required.');
+    }
+    const resolvedFilePath = resolveInputFilePath(fileValue, cwd);
+    let fileText;
+    try {
+        fileText = await readTextFile(resolvedFilePath);
+    }
+    catch {
+        throw usageError('linear_body_file_unreadable', '--body-file must reference a readable file.');
+    }
+    if (fileText.trim().length === 0) {
+        throw usageError('linear_body_missing', '--body or --body-file is required.');
+    }
+    return {
+        text: fileText,
+        filePath: resolvedFilePath
+    };
+}
+function resolveInputFilePath(filePath, cwd) {
+    return isAbsolute(filePath) ? filePath : resolve(cwd, filePath);
+}
+async function resolveOptionalText(flags, readTextFile, inlineFlag, fileFlag) {
+    const inlineValue = readRawStringFlag(flags, inlineFlag);
+    const fileValue = readStringFlag(flags, fileFlag);
+    const hasInlineValue = typeof inlineValue === 'string' && inlineValue.trim().length > 0;
+    if (hasInlineValue && fileValue) {
+        throw usageError(`linear_${inlineFlag.replace(/-/gu, '_')}_conflict`, `Use either --${inlineFlag} or --${fileFlag}, not both.`);
+    }
+    if (hasInlineValue) {
+        return inlineValue;
+    }
+    if (!fileValue) {
+        return null;
+    }
+    let fileText;
+    try {
+        fileText = await readTextFile(fileValue);
+    }
+    catch {
+        throw usageError(`linear_${fileFlag.replace(/-/gu, '_')}_unreadable`, `--${fileFlag} must reference a readable file.`);
+    }
+    return fileText.trim().length > 0 ? fileText : null;
+}
+async function resolveRequiredText(flags, readTextFile, inlineFlag, fileFlag) {
+    const inlineValue = readRawStringFlag(flags, inlineFlag);
+    const fileValue = readStringFlag(flags, fileFlag);
+    const hasInlineValue = typeof inlineValue === 'string' && inlineValue.trim().length > 0;
+    if (hasInlineValue && fileValue) {
+        throw usageError(`linear_${inlineFlag.replace(/-/gu, '_')}_conflict`, `Use either --${inlineFlag} or --${fileFlag}, not both.`);
+    }
+    if (hasInlineValue) {
+        return inlineValue;
+    }
+    if (fileValue) {
+        let fileText;
+        try {
+            fileText = await readTextFile(fileValue);
+        }
+        catch {
+            throw usageError(`linear_${fileFlag.replace(/-/gu, '_')}_unreadable`, `--${fileFlag} must reference a readable file.`);
+        }
+        if (fileText.trim().length === 0) {
+            throw usageError(`linear_${inlineFlag.replace(/-/gu, '_')}_missing`, `--${inlineFlag} or --${fileFlag} is required.`);
+        }
+        return fileText;
+    }
+    throw usageError(`linear_${inlineFlag.replace(/-/gu, '_')}_missing`, `--${inlineFlag} or --${fileFlag} is required.`);
+}
+function usageError(code, message) {
+    return cliError(code, message, 422);
+}
+function cliError(code, message, status) {
+    const error = new Error(message);
+    error.result = failureResult(code, message, status);
+    return error;
+}
+function isLinearCliUsageError(error) {
+    return (error instanceof Error
+        && typeof error.result?.error?.code === 'string'
+        && typeof error.result?.error?.message === 'string'
+        && typeof error.result?.error?.status === 'number');
+}
+function failureResult(code, message, status) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message,
+            status
+        }
+    };
+}
+async function assertLinearMutationAllowed(subcommand, flags, env, readTextFile) {
+    if (!LINEAR_MUTATING_SUBCOMMANDS.has(subcommand)) {
+        return;
+    }
+    const pipelineIdFromEnv = readStringEnv(env, 'CODEX_ORCHESTRATOR_PIPELINE_ID');
+    const isChildLane = pipelineIdFromEnv === 'provider-linear-child-lane';
+    const manifestPath = readStringEnv(env, 'CODEX_ORCHESTRATOR_MANIFEST_PATH');
+    if (!manifestPath) {
+        if (isChildLane) {
+            throw cliError('provider_worker_parent_mutation_required', `${subcommand} is only available to the parent provider-linear-worker; subordinate same-issue child lanes are read-only for Linear mutations.`, 409);
+        }
+        return;
+    }
+    let manifestRecord;
+    try {
+        manifestRecord = JSON.parse(await readTextFile(manifestPath));
+    }
+    catch {
+        if (isChildLane) {
+            throw cliError('provider_worker_parent_mutation_required', `${subcommand} is only available to the parent provider-linear-worker; subordinate same-issue child lanes are read-only for Linear mutations.`, 409);
+        }
+        return;
+    }
+    const pipelineId = readUnknownString(manifestRecord.pipeline_id) ?? readUnknownString(manifestRecord.pipelineId);
+    const parentRunId = readUnknownString(manifestRecord.parent_run_id) ?? readUnknownString(manifestRecord.parentRunId);
+    if (pipelineId !== 'provider-linear-child-lane' || !parentRunId) {
+        return;
+    }
+    throw cliError('provider_worker_parent_mutation_required', `${subcommand} is only available to the parent provider-linear-worker; subordinate same-issue child lanes are read-only for Linear mutations.`, 409);
+}
+function resolveErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function readStringEnv(env, key) {
+    const value = env[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+async function recordAuditResult(result, flags, env, dependencies) {
+    const auditPath = resolveProviderLinearAuditPath(env);
+    if (!auditPath) {
+        return;
+    }
+    try {
+        await dependencies.appendAuditEntry(auditPath, buildAuditEntry(result, flags, env, dependencies.now()));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        dependencies.warn(`linear audit warning: failed to append audit entry to ${auditPath}: ${message}`);
+    }
+}
+function buildAuditEntry(result, flags, env, recordedAt) {
+    const requestedIssueId = readStringFlag(flags, 'issue-id') ?? null;
+    const sourceSetup = resolveAuditSourceSetup(flags, env);
+    const followUpAuditFields = resolveFollowUpAuditFields(result);
+    if (!result.ok) {
+        if (result.operation === 'child-stream') {
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: false,
+                issue_id: result.issue_id ?? requestedIssueId,
+                issue_identifier: result.issue_identifier,
+                source_setup: result.source_setup ?? sourceSetup,
+                action: result.stream ? `stream:${result.stream}` : null,
+                via: result.pipeline_id ? `pipeline:${result.pipeline_id}` : null,
+                state: result.child_run?.status ?? null,
+                follow_up_issue_id: null,
+                follow_up_issue_identifier: null,
+                failed_relation_type: null,
+                comment_id: null,
+                attachment_id: null,
+                error_code: result.error.code,
+                error_message: result.error.message
+            };
+        }
+        if (result.operation === 'child-lane') {
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: false,
+                issue_id: result.issue_id ?? requestedIssueId,
+                issue_identifier: result.issue_identifier,
+                source_setup: result.source_setup ?? sourceSetup,
+                action: result.stream ? `${result.action}:${result.stream}` : result.action,
+                via: result.child_lane ? `pipeline:${result.child_lane.pipeline_id}` : null,
+                state: result.child_lane?.decision ?? result.child_run?.status ?? null,
+                follow_up_issue_id: null,
+                follow_up_issue_identifier: null,
+                failed_relation_type: null,
+                comment_id: null,
+                attachment_id: null,
+                error_code: result.error.code,
+                error_message: result.error.message
+            };
+        }
+        if (result.operation === 'screenshot-proof') {
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: false,
+                issue_id: result.issue_id ?? requestedIssueId,
+                issue_identifier: null,
+                source_setup: result.source_setup ?? sourceSetup,
+                action: result.capture?.mode ?? null,
+                via: result.capture ? `cleanup:${result.capture.cleanup.status}` : null,
+                state: null,
+                follow_up_issue_id: null,
+                follow_up_issue_identifier: null,
+                failed_relation_type: null,
+                comment_id: null,
+                attachment_id: null,
+                error_code: result.error.code,
+                error_message: result.error.message
+            };
+        }
+        return {
+            recorded_at: recordedAt,
+            operation: result.operation,
+            ok: false,
+            issue_id: requestedIssueId,
+            issue_identifier: null,
+            source_setup: sourceSetup,
+            action: null,
+            via: null,
+            state: null,
+            ...followUpAuditFields,
+            comment_id: null,
+            attachment_id: null,
+            ...resolveTransitionAuditFieldsFromFailure(result, resolveRequestedTransitionAuditFields(flags)),
+            error_code: result.error.code,
+            error_message: result.error.message
+        };
+    }
+    switch (result.operation) {
+        case 'issue-context':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: null,
+                via: null,
+                state: result.issue.state?.name ?? null,
+                ...followUpAuditFields,
+                comment_id: result.issue.workpad_comment?.id ?? null,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+        case 'upsert-workpad':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: result.action,
+                via: null,
+                state: null,
+                ...followUpAuditFields,
+                comment_id: result.comment.id,
+                attachment_id: null,
+                ...(Array.isArray(result.embedded_assets) && result.embedded_assets.length > 0
+                    ? {
+                        asset_urls: result.embedded_assets.map((entry) => entry.asset_url)
+                    }
+                    : {}),
+                error_code: null,
+                error_message: null
+            };
+        case 'delete-workpad':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: result.action,
+                via: null,
+                state: null,
+                ...followUpAuditFields,
+                comment_id: result.comment_id,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+        case 'transition':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: result.action,
+                via: null,
+                state: result.issue.state?.name ?? result.target_state.name,
+                ...followUpAuditFields,
+                comment_id: null,
+                attachment_id: null,
+                ...resolveTransitionAuditFieldsFromSuccess(result),
+                error_code: null,
+                error_message: null
+            };
+        case 'attach-pr':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: result.action,
+                via: result.via,
+                state: null,
+                ...followUpAuditFields,
+                comment_id: null,
+                attachment_id: result.attachment.id,
+                error_code: null,
+                error_message: null
+            };
+        case 'parallelization':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue_id,
+                issue_identifier: result.issue_identifier,
+                source_setup: result.source_setup,
+                action: result.decision,
+                via: result.summary,
+                state: result.reason,
+                ...followUpAuditFields,
+                comment_id: null,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+        case 'create-follow-up':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: result.action,
+                via: result.relations.blocked_by_source ? 'related+blocks' : 'related',
+                state: result.follow_up_issue.state?.name ?? null,
+                ...followUpAuditFields,
+                comment_id: null,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+        case 'runtime-proof':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue_id,
+                issue_identifier: null,
+                source_setup: result.source_setup,
+                action: result.proof?.kind ?? 'policy',
+                via: `permit:${result.policy.permit_status}`,
+                state: null,
+                ...followUpAuditFields,
+                comment_id: null,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+        case 'screenshot-proof':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue_id,
+                issue_identifier: null,
+                source_setup: result.source_setup,
+                action: result.capture.mode,
+                via: `cleanup:${result.capture.cleanup.status}`,
+                state: null,
+                ...followUpAuditFields,
+                comment_id: null,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+        case 'child-stream':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: `stream:${result.stream}`,
+                via: `pipeline:${result.pipeline_id}`,
+                state: result.child_run.status,
+                follow_up_issue_id: null,
+                follow_up_issue_identifier: null,
+                failed_relation_type: null,
+                comment_id: null,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+        case 'child-lane':
+            return {
+                recorded_at: recordedAt,
+                operation: result.operation,
+                ok: true,
+                issue_id: result.issue.id,
+                issue_identifier: result.issue.identifier,
+                source_setup: result.source_setup,
+                action: `${result.action}:${result.stream}`,
+                via: `pipeline:${result.child_lane.pipeline_id}`,
+                state: result.child_lane.decision,
+                follow_up_issue_id: null,
+                follow_up_issue_identifier: null,
+                failed_relation_type: null,
+                comment_id: null,
+                attachment_id: null,
+                error_code: null,
+                error_message: null
+            };
+    }
+}
+function resolveTransitionAuditFieldsFromSuccess(result) {
+    return {
+        previous_state: result.previous_state?.name ?? null,
+        previous_state_type: result.previous_state?.type ?? null,
+        target_state: result.target_state.name,
+        target_state_type: result.target_state.type ?? null,
+        issue_updated_at: result.issue.updated_at ?? null,
+        expected_state: result.transition_guard?.expected_state ?? null,
+        expected_state_type: result.transition_guard?.expected_state_type ?? null,
+        expected_updated_at: result.transition_guard?.expected_updated_at ?? null,
+        force: result.transition_guard?.force ?? null,
+        force_reason: result.transition_guard?.force_reason ?? null
+    };
+}
+function resolveRequestedTransitionAuditFields(flags) {
+    const hasForce = Object.prototype.hasOwnProperty.call(flags, 'force');
+    return {
+        expected_state: readStringFlag(flags, 'expected-state') ?? null,
+        expected_state_type: readStringFlag(flags, 'expected-state-type') ?? null,
+        expected_updated_at: readStringFlag(flags, 'expected-updated-at') ?? null,
+        force: hasForce ? readBooleanFlag(flags, 'force') : null,
+        force_reason: normalizeOptionalAuditString(readRawStringFlag(flags, 'force-reason'))
+    };
+}
+function resolveTransitionAuditFieldsFromFailure(result, fallbackGuardFields = {}) {
+    if (result.operation !== 'transition') {
+        return {};
+    }
+    const details = result.error.details && typeof result.error.details === 'object'
+        ? result.error.details
+        : null;
+    const issueId = details ? normalizeOptionalAuditString(details.issue_id) : null;
+    const issueIdentifier = details ? normalizeOptionalAuditString(details.issue_identifier) : null;
+    const expectedState = details
+        ? normalizeOptionalAuditString(details.expected_state)
+        : null;
+    const expectedStateType = details
+        ? normalizeOptionalAuditString(details.expected_state_type)
+        : null;
+    const expectedUpdatedAt = details
+        ? normalizeOptionalAuditString(details.expected_updated_at)
+        : null;
+    const force = details && typeof details.force === 'boolean'
+        ? details.force
+        : (fallbackGuardFields.force ?? null);
+    const forceReason = details
+        ? normalizeOptionalAuditString(details.force_reason)
+        : null;
+    return {
+        ...(issueId ? { issue_id: issueId } : {}),
+        ...(issueIdentifier ? { issue_identifier: issueIdentifier } : {}),
+        previous_state: details ? normalizeOptionalAuditString(details.previous_state) : null,
+        previous_state_type: details ? normalizeOptionalAuditString(details.previous_state_type) : null,
+        target_state: details ? normalizeOptionalAuditString(details.target_state) : null,
+        target_state_type: details ? normalizeOptionalAuditString(details.target_state_type) : null,
+        issue_updated_at: details ? normalizeOptionalAuditString(details.issue_updated_at) : null,
+        expected_state: expectedState ?? fallbackGuardFields.expected_state ?? null,
+        expected_state_type: expectedStateType ?? fallbackGuardFields.expected_state_type ?? null,
+        expected_updated_at: expectedUpdatedAt ?? fallbackGuardFields.expected_updated_at ?? null,
+        force,
+        force_reason: forceReason ?? fallbackGuardFields.force_reason ?? null
+    };
+}
+function normalizeOptionalAuditString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function resolveFollowUpAuditFields(result) {
+    if (result.ok) {
+        if (result.operation !== 'create-follow-up') {
+            return {
+                follow_up_issue_id: null,
+                follow_up_issue_identifier: null,
+                failed_relation_type: null
+            };
+        }
+        return {
+            follow_up_issue_id: result.follow_up_issue.id,
+            follow_up_issue_identifier: result.follow_up_issue.identifier,
+            failed_relation_type: null
+        };
+    }
+    if (result.operation !== 'create-follow-up') {
+        return {
+            follow_up_issue_id: null,
+            follow_up_issue_identifier: null,
+            failed_relation_type: null
+        };
+    }
+    const details = result.error.details;
+    const followUpIssue = readIssueLikeRecord(details?.follow_up_issue)
+        ?? readIssueLikeRecord(details?.created_issue);
+    return {
+        follow_up_issue_id: readRecordString(followUpIssue, 'id'),
+        follow_up_issue_identifier: readRecordString(followUpIssue, 'identifier'),
+        failed_relation_type: readUnknownString(details?.failed_relation_type)
+    };
+}
+function readIssueLikeRecord(value) {
+    return value && typeof value === 'object' ? value : null;
+}
+function readRecordString(record, key) {
+    if (!record) {
+        return null;
+    }
+    return readUnknownString(record[key]);
+}
+function readUnknownString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function resolveAuditSourceSetup(flags, env) {
+    const sourceSetup = readSourceSetup(flags);
+    if (sourceSetup) {
+        return sourceSetup;
+    }
+    const resolved = resolveLinearSourceSetup({
+        provider: 'linear',
+        workspace_id: null,
+        team_id: null,
+        project_id: null
+    }, env);
+    return resolved.workspace_id || resolved.team_id || resolved.project_id ? resolved : null;
+}
+function resolveRuntimeProofRepoRoot(cwd, env) {
+    const configuredRoot = normalizeEnvPath(env.CODEX_ORCHESTRATOR_ROOT);
+    if (!configuredRoot) {
+        return resolveRepoRootFromHint(cwd);
+    }
+    const configuredHint = isAbsolute(configuredRoot) ? configuredRoot : resolve(cwd, configuredRoot);
+    return resolveRepoRootFromHint(configuredHint);
+}
+function resolveRepoRootFromHint(rootHint) {
+    const normalizedHint = resolve(rootHint);
+    const gitBoundary = findNearestGitBoundary(normalizedHint);
+    let current = normalizedHint;
+    while (current) {
+        if (existsSync(join(current, 'tasks', 'index.json'))) {
+            return current;
+        }
+        if (gitBoundary && current === gitBoundary) {
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return gitBoundary ?? normalizedHint;
+}
+function findNearestGitBoundary(start) {
+    let current = resolve(start);
+    while (current) {
+        if (existsSync(join(current, '.git'))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+function normalizeEnvPath(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}