patchrelay 0.67.0 → 0.67.2

package/README.md

@@ -114,10 +114,12 @@ See the [merge-steward package README](./packages/merge-steward/README.md) for t
 
 ## Docs
 
+- [Concepts](./docs/concepts.md) — the shared mental model (three roles, four primitives, four states, carry-forward, eviction). Start here.
 - [Self-hosting and deployment](./docs/self-hosting.md) — install, ingress, OAuth and GitHub App setup
 - [Architecture](./docs/architecture.md) — components, ownership, state machine, failure taxonomy
 - [Operator guide](./docs/operator-guide.md) — daily loop, CLI cheatsheet, troubleshooting
-- [Merge queue](./docs/merge-queue.md) — the two-service delivery story
+- [Merge queue](./docs/merge-queue.md) — the three-service delivery story
+- [GitHub queue contract](./docs/github-queue-contract.md) — bus artifacts, identity algorithms, configurable names
 - [Prompting](./docs/prompting.md) — how workflow files and the built-in scaffold compose
 - [Secrets](./docs/secrets.md) — systemd credentials, resolution order
 - [review-quill reference](./docs/review-quill.md) · [merge-steward reference](./docs/merge-steward.md)

package/config/patchrelay.example.json

@@ -6,6 +6,7 @@
     "git_bin": "git",
     "codex": {
       "model": "gpt-5.5",
+      "triage_model": "gpt-5.4-mini",
       "reasoning_effort": "high",
       "developer_instructions": "Keep the public API stable for this installation unless the task explicitly requires a breaking change."
     }

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.67.0",
-  "commit": "3f61030e2318",
-  "builtAt": "2026-05-05T14:42:27.010Z"
+  "version": "0.67.2",
+  "commit": "8d3d15a51ae1",
+  "builtAt": "2026-05-10T15:37:09.721Z"
 }

package/dist/codex-app-server.js

@@ -17,6 +17,13 @@ const PUBLICATION_RECAP_DEVELOPER_INSTRUCTIONS = [
     "Use only the prior thread context and the facts in the current prompt.",
     "Return only the requested JSON object.",
 ].join("\n");
+const ISSUE_TRIAGE_DEVELOPER_INSTRUCTIONS = [
+    "You are PatchRelay's issue triage classifier.",
+    "This is a read-only preflight step used only to choose the execution shape for one Linear issue.",
+    "Do not run commands, do not call tools, do not edit files, and do not inspect or modify the repository.",
+    "Use only the facts in the current prompt.",
+    "Return only the requested JSON object.",
+].join("\n");
 export function resolveCodexAppServerLaunch(config) {
     if (!config.sourceBashrc) {
         return {
@@ -101,16 +108,30 @@ export class CodexAppServerClient extends EventEmitter {
         await Promise.race([exited, timeout]);
     }
     async startThread(options) {
+        return await this.startThreadWithOverrides(options, {});
+    }
+    async startThreadForIssueTriage() {
+        return await this.startThreadWithOverrides({ cwd: tmpdir() }, {
+            approvalPolicy: "never",
+            sandboxMode: "read-only",
+            model: this.config.triageModel ?? "gpt-5.4-mini",
+            modelProvider: this.config.triageModelProvider ?? this.config.modelProvider ?? null,
+            reasoningEffort: "low",
+            baseInstructions: null,
+            developerInstructions: ISSUE_TRIAGE_DEVELOPER_INSTRUCTIONS,
+        });
+    }
+    async startThreadWithOverrides(options, overrides) {
         const params = {
             cwd: options.cwd,
-            approvalPolicy: this.config.approvalPolicy,
-            sandbox: this.config.sandboxMode,
+            approvalPolicy: overrides.approvalPolicy ?? this.config.approvalPolicy,
+            sandbox: overrides.sandboxMode ?? this.config.sandboxMode,
             serviceName: this.config.serviceName ?? "patchrelay",
-            model: this.config.model ?? null,
-            modelProvider: this.config.modelProvider ?? null,
-            reasoningEffort: this.config.reasoningEffort ?? null,
-            baseInstructions: this.config.baseInstructions ?? null,
-            developerInstructions: this.config.developerInstructions ?? null,
+            model: "model" in overrides ? overrides.model ?? null : this.config.model ?? null,
+            modelProvider: "modelProvider" in overrides ? overrides.modelProvider ?? null : this.config.modelProvider ?? null,
+            reasoningEffort: "reasoningEffort" in overrides ? overrides.reasoningEffort ?? null : this.config.reasoningEffort ?? null,
+            baseInstructions: "baseInstructions" in overrides ? overrides.baseInstructions ?? null : this.config.baseInstructions ?? null,
+            developerInstructions: "developerInstructions" in overrides ? overrides.developerInstructions ?? null : this.config.developerInstructions ?? null,
             experimentalRawEvents: this.config.experimentalRawEvents ?? false,
         };
         const response = (await this.sendRequest("thread/start", params));
@@ -140,11 +161,11 @@ export class CodexAppServerClient extends EventEmitter {
             cwd: overrides?.cwd ?? cwd ?? null,
             approvalPolicy: overrides?.approvalPolicy ?? this.config.approvalPolicy,
             sandbox: overrides?.sandboxMode ?? this.config.sandboxMode,
-            model: overrides?.model ?? this.config.model ?? null,
-            modelProvider: overrides?.modelProvider ?? this.config.modelProvider ?? null,
-            reasoningEffort: overrides?.reasoningEffort ?? this.config.reasoningEffort ?? null,
-            baseInstructions: overrides?.baseInstructions ?? this.config.baseInstructions ?? null,
-            developerInstructions: overrides?.developerInstructions ?? this.config.developerInstructions ?? null,
+            model: overrides && "model" in overrides ? overrides.model ?? null : this.config.model ?? null,
+            modelProvider: overrides && "modelProvider" in overrides ? overrides.modelProvider ?? null : this.config.modelProvider ?? null,
+            reasoningEffort: overrides && "reasoningEffort" in overrides ? overrides.reasoningEffort ?? null : this.config.reasoningEffort ?? null,
+            baseInstructions: overrides && "baseInstructions" in overrides ? overrides.baseInstructions ?? null : this.config.baseInstructions ?? null,
+            developerInstructions: overrides && "developerInstructions" in overrides ? overrides.developerInstructions ?? null : this.config.developerInstructions ?? null,
         };
         if (this.config.persistExtendedHistory) {
             this.logger.warn("persistExtendedHistory is requested but not enabled in the active app-server capability handshake; ignoring");

package/dist/codex-thread-errors.js

@@ -0,0 +1,13 @@
+export class CodexThreadMaterializingError extends Error {
+    code = "thread_materializing";
+    constructor(threadId, attempts, cause) {
+        super(`Codex thread ${threadId} is not materialized yet after ${attempts} read attempt(s)`, { cause });
+        this.name = "CodexThreadMaterializingError";
+    }
+}
+export function isThreadMaterializingError(error) {
+    if (error instanceof CodexThreadMaterializingError)
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /not materialized yet|not materialized/i.test(message);
+}

package/dist/config.js

@@ -162,6 +162,8 @@ const configSchema = z.object({
             model: z.string().default("gpt-5.5"),
             model_provider: z.string().optional(),
             reasoning_effort: z.enum(["low", "medium", "high"]).optional(),
+            triage_model: z.string().default("gpt-5.4-mini"),
+            triage_model_provider: z.string().optional(),
             service_name: z.string().default("patchrelay"),
             base_instructions: z.string().optional(),
             developer_instructions: z.string().optional(),
@@ -580,6 +582,8 @@ export function loadConfig(configPath = process.env.PATCHRELAY_CONFIG ?? getDefa
                 ...(parsed.runner.codex.model ? { model: parsed.runner.codex.model } : {}),
                 ...(parsed.runner.codex.model_provider ? { modelProvider: parsed.runner.codex.model_provider } : {}),
                 ...(parsed.runner.codex.reasoning_effort ? { reasoningEffort: parsed.runner.codex.reasoning_effort } : {}),
+                ...(parsed.runner.codex.triage_model ? { triageModel: parsed.runner.codex.triage_model } : {}),
+                ...(parsed.runner.codex.triage_model_provider ? { triageModelProvider: parsed.runner.codex.triage_model_provider } : {}),
                 ...(parsed.runner.codex.service_name ? { serviceName: parsed.runner.codex.service_name } : {}),
                 ...(parsed.runner.codex.base_instructions ? { baseInstructions: parsed.runner.codex.base_instructions } : {}),
                 developerInstructions: mergeDeveloperInstructions(parsed.runner.codex.developer_instructions),

package/dist/db/issue-store.js

@@ -28,6 +28,14 @@ export class IssueStore {
                 sets.push("issue_class_source = @issueClassSource");
                 values.issueClassSource = params.issueClassSource;
             }
+            if (params.issueTriageHash !== undefined) {
+                sets.push("issue_triage_hash = @issueTriageHash");
+                values.issueTriageHash = params.issueTriageHash;
+            }
+            if (params.issueTriageResultJson !== undefined) {
+                sets.push("issue_triage_result_json = @issueTriageResultJson");
+                values.issueTriageResultJson = params.issueTriageResultJson;
+            }
             if (params.parentLinearIssueId !== undefined) {
                 sets.push("parent_linear_issue_id = @parentLinearIssueId");
                 values.parentLinearIssueId = params.parentLinearIssueId;
@@ -257,7 +265,7 @@ export class IssueStore {
         else {
             this.connection.prepare(`
         INSERT INTO issues (
-          project_id, linear_issue_id, delegated_to_patchrelay, issue_class, issue_class_source, parent_linear_issue_id, parent_issue_key, issue_key, title, description, url,
+          project_id, linear_issue_id, delegated_to_patchrelay, issue_class, issue_class_source, issue_triage_hash, issue_triage_result_json, parent_linear_issue_id, parent_issue_key, issue_key, title, description, url,
           priority, estimate,
           current_linear_state, current_linear_state_type, factory_state, pending_run_type, pending_run_context_json,
           branch_name, worktree_path, thread_id, active_run_id, status_comment_id,
@@ -272,7 +280,7 @@ export class IssueStore {
           ci_repair_attempts, queue_repair_attempts, review_fix_attempts, zombie_recovery_attempts, last_zombie_recovery_at, orchestration_settle_until,
           updated_at
         ) VALUES (
-          @projectId, @linearIssueId, @delegatedToPatchRelay, @issueClass, @issueClassSource, @parentLinearIssueId, @parentIssueKey, @issueKey, @title, @description, @url,
+          @projectId, @linearIssueId, @delegatedToPatchRelay, @issueClass, @issueClassSource, @issueTriageHash, @issueTriageResultJson, @parentLinearIssueId, @parentIssueKey, @issueKey, @title, @description, @url,
           @priority, @estimate,
           @currentLinearState, @currentLinearStateType, @factoryState, @pendingRunType, @pendingRunContextJson,
           @branchName, @worktreePath, @threadId, @activeRunId, @statusCommentId,
@@ -293,6 +301,8 @@ export class IssueStore {
                 delegatedToPatchRelay: params.delegatedToPatchRelay === false ? 0 : 1,
                 issueClass: params.issueClass ?? null,
                 issueClassSource: params.issueClassSource ?? null,
+                issueTriageHash: params.issueTriageHash ?? null,
+                issueTriageResultJson: params.issueTriageResultJson ?? null,
                 parentLinearIssueId: params.parentLinearIssueId ?? null,
                 parentIssueKey: params.parentIssueKey ?? null,
                 issueKey: params.issueKey ?? null,
@@ -650,6 +660,12 @@ export function mapIssueRow(row) {
         ...(row.issue_class_source !== null && row.issue_class_source !== undefined
             ? { issueClassSource: String(row.issue_class_source) }
             : {}),
+        ...(row.issue_triage_hash !== null && row.issue_triage_hash !== undefined
+            ? { issueTriageHash: String(row.issue_triage_hash) }
+            : {}),
+        ...(row.issue_triage_result_json !== null && row.issue_triage_result_json !== undefined
+            ? { issueTriageResultJson: String(row.issue_triage_result_json) }
+            : {}),
         ...(row.parent_linear_issue_id !== null && row.parent_linear_issue_id !== undefined
             ? { parentLinearIssueId: String(row.parent_linear_issue_id) }
             : {}),

package/dist/db/migrations.js

@@ -6,6 +6,8 @@ CREATE TABLE IF NOT EXISTS issues (
   delegated_to_patchrelay INTEGER NOT NULL DEFAULT 1,
   issue_class TEXT,
   issue_class_source TEXT,
+  issue_triage_hash TEXT,
+  issue_triage_result_json TEXT,
   parent_linear_issue_id TEXT,
   parent_issue_key TEXT,
   issue_key TEXT,
@@ -264,6 +266,8 @@ export function runPatchRelayMigrations(connection) {
     addColumnIfMissing(connection, "issues", "delegated_to_patchrelay", "INTEGER NOT NULL DEFAULT 1");
     addColumnIfMissing(connection, "issues", "issue_class", "TEXT");
     addColumnIfMissing(connection, "issues", "issue_class_source", "TEXT");
+    addColumnIfMissing(connection, "issues", "issue_triage_hash", "TEXT");
+    addColumnIfMissing(connection, "issues", "issue_triage_result_json", "TEXT");
     addColumnIfMissing(connection, "issues", "parent_linear_issue_id", "TEXT");
     addColumnIfMissing(connection, "issues", "parent_issue_key", "TEXT");
     addColumnIfMissing(connection, "issues", "orchestration_settle_until", "TEXT");
@@ -353,6 +357,8 @@ export function runPatchRelayMigrations(connection) {
     addColumnIfMissing(connection, "linear_installations", "health_reason", "TEXT");
     addColumnIfMissing(connection, "linear_installations", "health_updated_at", "TEXT");
     removeRetiredIssueColumnsIfPresent(connection);
+    addColumnIfMissing(connection, "issues", "issue_triage_hash", "TEXT");
+    addColumnIfMissing(connection, "issues", "issue_triage_result_json", "TEXT");
 }
 function addColumnIfMissing(connection, table, column, definition) {
     const cols = connection.prepare(`PRAGMA table_info(${table})`).all();
@@ -377,6 +383,8 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         delegated_to_patchrelay INTEGER NOT NULL DEFAULT 1,
         issue_class TEXT,
         issue_class_source TEXT,
+        issue_triage_hash TEXT,
+        issue_triage_result_json TEXT,
         parent_linear_issue_id TEXT,
         parent_issue_key TEXT,
         issue_key TEXT,
@@ -444,6 +452,8 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         delegated_to_patchrelay,
         issue_class,
         issue_class_source,
+        issue_triage_hash,
+        issue_triage_result_json,
         parent_linear_issue_id,
         parent_issue_key,
         issue_key,
@@ -509,6 +519,8 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         COALESCE(delegated_to_patchrelay, 1),
         issue_class,
         issue_class_source,
+        issue_triage_hash,
+        issue_triage_result_json,
         parent_linear_issue_id,
         parent_issue_key,
         issue_key,

package/dist/issue-class.js

@@ -11,5 +11,8 @@ export function classifyIssue(params) {
     if (params.issue.issueClassSource === "explicit" && params.issue.issueClass === "implementation") {
         return { issueClass: "implementation", issueClassSource: "explicit" };
     }
+    if (params.issue.issueClassSource === "triage" && params.issue.issueClass) {
+        return { issueClass: params.issue.issueClass, issueClassSource: "triage" };
+    }
     return { issueClass: "implementation", issueClassSource: "heuristic" };
 }

package/dist/issue-triage.js

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+import { getThreadTurns } from "./codex-thread-utils.js";
+import { isThreadMaterializingError } from "./codex-thread-errors.js";
+import { extractFirstJsonObject, safeJsonParse } from "./utils.js";
+const TRIAGE_TIMEOUT_MS = 45_000;
+const TRIAGE_POLL_MS = 1_000;
+const MIN_CONFIDENCE = 0.55;
+export function buildIssueTriageHash(params) {
+    const payload = {
+        linearIssueId: params.issue.linearIssueId,
+        issueKey: params.issue.issueKey ?? null,
+        title: params.issue.title ?? "",
+        description: params.issue.description ?? "",
+        parentLinearIssueId: params.issue.parentLinearIssueId ?? null,
+        childIssues: params.childIssues.map((child) => ({
+            linearIssueId: child.linearIssueId,
+            issueKey: child.issueKey ?? null,
+            title: child.title ?? "",
+            currentLinearState: child.currentLinearState ?? null,
+            factoryState: child.factoryState,
+        })),
+    };
+    return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+export class IssueTriageService {
+    codex;
+    logger;
+    constructor(codex, logger) {
+        this.codex = codex;
+        this.logger = logger;
+    }
+    async classify(params) {
+        const thread = await this.codex.startThreadForIssueTriage();
+        const turn = await this.codex.startTurn({
+            threadId: thread.id,
+            ...(thread.cwd ? { cwd: thread.cwd } : {}),
+            input: buildIssueTriagePrompt(params),
+        });
+        const completedThread = await this.waitForTurn(thread.id, turn.turnId);
+        const completedTurn = getThreadTurns(completedThread).find((entry) => entry.id === turn.turnId);
+        const latestMessage = completedTurn?.items
+            .filter((item) => item.type === "agentMessage")
+            .at(-1)?.text;
+        const parsed = parseIssueTriageResult(latestMessage);
+        if (!parsed) {
+            this.logger.warn({ issueKey: params.issue.issueKey, linearIssueId: params.issue.linearIssueId, threadId: thread.id, turnId: turn.turnId }, "Issue triage returned invalid JSON");
+            return undefined;
+        }
+        if (parsed.confidence < MIN_CONFIDENCE) {
+            return {
+                ...parsed,
+                issueClass: "implementation",
+                reason: `Low confidence triage (${parsed.confidence}): ${parsed.reason}`,
+            };
+        }
+        return parsed;
+    }
+    async waitForTurn(threadId, turnId) {
+        const deadline = Date.now() + TRIAGE_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            let thread;
+            try {
+                thread = await this.codex.readThread(threadId, true);
+            }
+            catch (error) {
+                if (isThreadMaterializingError(error)) {
+                    await new Promise((resolve) => setTimeout(resolve, TRIAGE_POLL_MS));
+                    continue;
+                }
+                throw error;
+            }
+            const turn = getThreadTurns(thread).find((entry) => entry.id === turnId);
+            if (turn?.status === "completed") {
+                return thread;
+            }
+            if (turn?.status === "failed" || turn?.status === "interrupted") {
+                throw new Error(`Issue triage turn ${turnId} ended with status ${turn.status}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, TRIAGE_POLL_MS));
+        }
+        throw new Error(`Issue triage timed out after ${TRIAGE_TIMEOUT_MS}ms`);
+    }
+}
+function buildIssueTriagePrompt(params) {
+    return [
+        "PatchRelay issue triage",
+        "",
+        "Classify the Linear issue so PatchRelay can choose the right first worker prompt.",
+        "Do not solve the task, decompose the work, create a plan, or propose child issue titles.",
+        "Return exactly one JSON object and no extra prose.",
+        "",
+        "Schema:",
+        "{",
+        '  "issueClass": "implementation" | "orchestration",',
+        '  "intent": "code_change" | "split_into_children" | "investigate" | "review" | "coordination" | "needs_input",',
+        '  "confidence": 0.0,',
+        '  "reason": "one short sentence"',
+        "}",
+        "",
+        "Choose issueClass:",
+        '- "implementation" when the worker should directly change code, investigate a concrete bug, repair a PR, answer with repo findings, or do a single bounded task.',
+        '- "orchestration" when the worker should coordinate a parent issue, split work into child issues, supervise existing children, or converge already-delegated work instead of directly implementing the full scope.',
+        "",
+        "Facts:",
+        `- Issue: ${params.issue.issueKey ?? params.issue.linearIssueId}`,
+        `- Parent issue id: ${params.issue.parentLinearIssueId ?? "none"}`,
+        `- Title: ${params.issue.title ?? ""}`,
+        "Description:",
+        params.issue.description?.trim() ? params.issue.description.trim() : "(empty)",
+        "",
+        "Existing children:",
+        ...(params.childIssues.length > 0
+            ? params.childIssues.map((child) => {
+                const label = child.issueKey ?? child.linearIssueId;
+                const state = child.currentLinearState ? `; state ${child.currentLinearState}` : "";
+                return `- ${label}: ${child.title ?? "(untitled)"} (${child.factoryState}${state})`;
+            })
+            : ["- none"]),
+    ].join("\n");
+}
+function parseIssueTriageResult(text) {
+    if (!text)
+        return undefined;
+    const json = extractFirstJsonObject(text) ?? text;
+    const parsed = safeJsonParse(json);
+    if (!parsed)
+        return undefined;
+    const issueClass = parsed.issueClass;
+    const intent = parsed.intent;
+    const confidence = parsed.confidence;
+    const reason = parsed.reason;
+    if (issueClass !== "implementation" && issueClass !== "orchestration")
+        return undefined;
+    if (intent !== "code_change" &&
+        intent !== "split_into_children" &&
+        intent !== "investigate" &&
+        intent !== "review" &&
+        intent !== "coordination" &&
+        intent !== "needs_input")
+        return undefined;
+    if (typeof confidence !== "number" || !Number.isFinite(confidence))
+        return undefined;
+    if (typeof reason !== "string" || !reason.trim())
+        return undefined;
+    return {
+        issueClass,
+        intent,
+        confidence: Math.max(0, Math.min(1, confidence)),
+        reason: reason.trim().slice(0, 240),
+    };
+}

package/dist/prompting/patchrelay.js

@@ -179,6 +179,8 @@ function buildOrchestrationConstraints(context) {
         "",
         "This issue is orchestration work. Coordinate convergence instead of duplicating child implementation.",
         "Inspect the current child set before acting. Reuse existing child issues when they already cover the needed slices instead of creating duplicates.",
+        "Before creating child issues, list existing children and recent parent context, normalize the intended child purpose, and update or reuse matching issues.",
+        "When you create or reuse children, leave a concise parent-visible split manifest naming the child IDs and what each one covers.",
         "Babysit child progress and solve parent-owned integration or convergence issues when the delivered pieces do not yet fit together cleanly.",
         "Do not open an overlapping umbrella PR unless this parent owns unique direct work.",
         "Create new child issues only for genuinely missing required work needed to satisfy the parent goal.",
@@ -305,7 +307,7 @@ function buildRequestedChangesContext(runType, context) {
     else {
         const reviewer = typeof context?.reviewerName === "string" ? context.reviewerName : undefined;
         const reviewBody = typeof context?.reviewBody === "string" ? context.reviewBody.trim() : "";
-        lines.push("Requested changes on the existing PR branch.", "Goal: restore review readiness on the current PR branch. Push a newer head only when the fix actually changes the diff; if the reviewer-pass produces only comments, test wording, or PR-body changes, edit the PR body via `gh pr edit` instead.", "Address the real concern behind the feedback and verify nearby invariants in the touched flow before you publish.", reviewer ? `Reviewer: ${reviewer}` : "", reviewBody ? `Review summary:\n${reviewBody}` : "");
+        lines.push("Requested changes on the existing PR branch.", "Goal: restore review readiness on the current PR branch. Push a newer head only when the fix actually changes the diff; if the reviewer-pass produces only comments, test wording, or PR-body changes, edit the PR body via `gh pr edit` instead.", "Address the real concern behind the feedback and verify nearby invariants in the touched flow before you publish.", "For each review comment, identify the resource, epoch, or token it touches (e.g. session, capture, route, persistence handle, in-flight turn id), enumerate the other transitions that share that same resource, and verify each one before pushing — not just the exact path called out. If you find an adjacent transition that violates the same invariant, fix it in this iteration rather than waiting for the reviewer to surface it next round.", reviewer ? `Reviewer: ${reviewer}` : "", reviewBody ? `Review summary:\n${reviewBody}` : "");
         appendStructuredReviewContext(lines, context);
     }
     return lines.join("\n").trim();

package/dist/run-orchestrator.js

@@ -20,7 +20,9 @@ import { RunRecoveryService } from "./run-recovery-service.js";
 import { RunWakePlanner } from "./run-wake-planner.js";
 import { getRemainingZombieRecoveryDelayMs } from "./zombie-recovery.js";
 import { classifyIssue } from "./issue-class.js";
+import { buildIssueTriageHash, IssueTriageService } from "./issue-triage.js";
 import { loadConfig } from "./config.js";
+import { CodexThreadMaterializingError, isThreadMaterializingError } from "./codex-thread-errors.js";
 function lowerCaseFirst(value) {
     return value ? `${value.slice(0, 1).toLowerCase()}${value.slice(1)}` : value;
 }
@@ -62,6 +64,7 @@ export class RunOrchestrator {
     runCompletionPolicy;
     completionCheck;
     publicationRecap;
+    issueTriage;
     runNotificationHandler;
     runReconciler;
     mergedLinearCompletionReconciler;
@@ -99,6 +102,7 @@ export class RunOrchestrator {
         this.runCompletionPolicy = new RunCompletionPolicy(config, db, logger, this.leasePorts.withHeldLease);
         this.completionCheck = new CompletionCheckService(codex, logger);
         this.publicationRecap = new PublicationRecapService(codex, logger);
+        this.issueTriage = new IssueTriageService(codex, logger);
         this.runFinalizer = new RunFinalizer(db, logger, this.linearSync, this.enqueueIssue, this.leasePorts.withHeldLease, this.leasePorts.releaseLease, (lease, issue, runType, context, dedupeScope) => this.appendWakeEventWithLease(lease, issue, runType, context, dedupeScope), this.recoveryPorts.failRunAndClear, this.runCompletionPolicy, this.completionCheck, this.publicationRecap, feed);
         this.runLauncher = new RunLauncher(config, db, codex, logger, this.worktreeManager);
         this.runNotificationHandler = new RunNotificationHandler(config, db, logger, this.linearSync, this.runFinalizer, this.threadPorts.readThreadWithRetry, this.leasePorts.withHeldLease, this.leasePorts.heartbeatLease, this.leasePorts.releaseLease, feed);
@@ -176,17 +180,43 @@ export class RunOrchestrator {
             ...(childIssues.length > 0 ? { childIssues } : {}),
         };
     }
-    classifyTrackedIssue(issue) {
-        const childIssueCount = this.db.issues.listChildIssues(issue.projectId, issue.linearIssueId).length;
-        const classification = classifyIssue({ issue, childIssueCount });
+    async classifyTrackedIssue(issue) {
+        const childIssues = this.db.issues.listChildIssues(issue.projectId, issue.linearIssueId);
+        const classification = classifyIssue({ issue, childIssueCount: childIssues.length });
+        const triageHash = buildIssueTriageHash({ issue, childIssues });
+        const triageCacheFresh = issue.issueClassSource === "triage" && issue.issueTriageHash === triageHash;
         if (issue.issueClass === classification.issueClass && issue.issueClassSource === classification.issueClassSource) {
-            return issue;
+            if (classification.issueClassSource !== "triage" || triageCacheFresh) {
+                return issue;
+            }
         }
+        if (classification.issueClassSource === "heuristic" || (classification.issueClassSource === "triage" && !triageCacheFresh)) {
+            try {
+                const triage = await this.issueTriage.classify({ issue, childIssues });
+                if (triage) {
+                    return this.db.issues.upsertIssue({
+                        projectId: issue.projectId,
+                        linearIssueId: issue.linearIssueId,
+                        issueClass: triage.issueClass,
+                        issueClassSource: "triage",
+                        issueTriageHash: triageHash,
+                        issueTriageResultJson: JSON.stringify(triage),
+                    });
+                }
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.logger.warn({ issueKey: issue.issueKey, linearIssueId: issue.linearIssueId, error: err.message }, "Issue triage failed; falling back to heuristic classification");
+            }
+        }
+        const fallbackClassification = classification.issueClassSource === "triage" && !triageCacheFresh
+            ? { issueClass: "implementation", issueClassSource: "heuristic" }
+            : classification;
         return this.db.issues.upsertIssue({
             projectId: issue.projectId,
             linearIssueId: issue.linearIssueId,
-            issueClass: classification.issueClass,
-            issueClassSource: classification.issueClassSource,
+            issueClass: fallbackClassification.issueClass,
+            issueClassSource: fallbackClassification.issueClassSource,
         });
     }
     // ─── Run ────────────────────────────────────────────────────────
@@ -199,7 +229,9 @@ export class RunOrchestrator {
             return;
         }
         const initialIssue = this.db.issues.getIssue(item.projectId, item.issueId);
-        const issue = initialIssue ? this.classifyTrackedIssue(initialIssue) : undefined;
+        if (!initialIssue || initialIssue.activeRunId !== undefined)
+            return;
+        const issue = await this.classifyTrackedIssue(initialIssue);
         if (!issue || issue.activeRunId !== undefined)
             return;
         const issueSession = this.db.issueSessions.getIssueSession(item.projectId, item.issueId);
@@ -426,17 +458,26 @@ export class RunOrchestrator {
         return await this.runCompletionPolicy.resolveRequestedChangesWakeContext(issue, runType, context);
     }
     async readThreadWithRetry(threadId, maxRetries = 3) {
+        let lastError;
         for (let attempt = 0; attempt < maxRetries; attempt++) {
             try {
                 return await this.codex.readThread(threadId, true);
             }
-            catch {
-                if (attempt === maxRetries - 1)
-                    throw new Error(`Failed to read thread ${threadId} after ${maxRetries} attempts`);
+            catch (error) {
+                lastError = error;
+                if (attempt === maxRetries - 1) {
+                    if (isThreadMaterializingError(error)) {
+                        throw new CodexThreadMaterializingError(threadId, maxRetries, error);
+                    }
+                    throw new Error(`Failed to read thread ${threadId} after ${maxRetries} attempts`, { cause: error });
+                }
                 await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt + 1)));
             }
         }
-        throw new Error(`Failed to read thread ${threadId}`);
+        if (isThreadMaterializingError(lastError)) {
+            throw new CodexThreadMaterializingError(threadId, maxRetries, lastError);
+        }
+        throw new Error(`Failed to read thread ${threadId}`, { cause: lastError });
     }
     getHeldIssueSessionLease(projectId, linearIssueId) {
         return this.leaseService.getHeldLease(projectId, linearIssueId);

package/dist/run-reconciler.js

@@ -5,6 +5,14 @@ import { buildRunFailureActivity } from "./linear-session-reporting.js";
 import { getThreadTurns } from "./codex-thread-utils.js";
 import { resolveRecoverablePostRunState } from "./interrupted-run-recovery.js";
 import { resolveEffectiveActiveRun } from "./effective-active-run.js";
+import { isThreadMaterializingError } from "./codex-thread-errors.js";
+const THREAD_MATERIALIZATION_GRACE_MS = 10 * 60_000;
+function isWithinThreadMaterializationGrace(run, nowMs = Date.now()) {
+    const startedAtMs = Date.parse(run.startedAt);
+    if (!Number.isFinite(startedAtMs))
+        return true;
+    return nowMs - startedAtMs < THREAD_MATERIALIZATION_GRACE_MS;
+}
 export class RunReconciler {
     db;
     logger;
@@ -89,7 +97,15 @@ export class RunReconciler {
         try {
             thread = await this.readThreadWithRetry(run.threadId);
         }
-        catch {
+        catch (error) {
+            if (isThreadMaterializingError(error) && isWithinThreadMaterializationGrace(run)) {
+                this.logger.info({ issueKey: effectiveIssue.issueKey, runId: run.id, runType: run.runType, threadId: run.threadId }, "Codex thread still materializing during reconciliation; keeping run active");
+                void this.linearSync.syncSession(effectiveIssue, { activeRunType: run.runType });
+                if (acquiredRecoveryLease) {
+                    this.releaseLease(run.projectId, run.linearIssueId);
+                }
+                return;
+            }
             this.logger.warn({ issueKey: effectiveIssue.issueKey, runId: run.id, runType: run.runType, threadId: run.threadId }, "Stale thread during reconciliation");
             this.withHeldLease(run.projectId, run.linearIssueId, () => {
                 this.db.runs.finishRun(run.id, { status: "failed", failureReason: "Stale thread after restart" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.67.0",
+  "version": "0.67.2",
   "license": "MIT",
   "type": "module",
   "repository": {