patchrelay 0.67.1 → 0.68.0

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.1",
-  "commit": "cda2d1d453d6",
-  "builtAt": "2026-05-05T20:30:58.013Z"
+  "version": "0.68.0",
+  "commit": "3a86b2f7100f",
+  "builtAt": "2026-05-13T20:52:25.195Z"
 }

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");
@@ -185,6 +206,20 @@ export class CodexAppServerClient extends EventEmitter {
             status: String(response.turn.status),
         };
     }
+    async setThreadGoal(options) {
+        const params = {
+            threadId: options.threadId,
+            objective: options.objective,
+        };
+        if (options.status !== undefined) {
+            params.status = options.status;
+        }
+        if (options.tokenBudget !== undefined) {
+            params.tokenBudget = options.tokenBudget;
+        }
+        const response = (await this.sendRequest("thread/goal/set", params));
+        return this.mapThreadGoal(response.goal);
+    }
     async readThread(threadId, includeTurns = true) {
         const response = (await this.sendRequest("thread/read", {
             threadId,
@@ -209,6 +244,18 @@ export class CodexAppServerClient extends EventEmitter {
             ],
         });
     }
+    mapThreadGoal(goal) {
+        return {
+            threadId: String(goal.threadId),
+            objective: String(goal.objective ?? ""),
+            status: String(goal.status ?? "active"),
+            ...(goal.tokenBudget === null || goal.tokenBudget === undefined ? { tokenBudget: null } : { tokenBudget: Number(goal.tokenBudget) }),
+            tokensUsed: Number(goal.tokensUsed ?? 0),
+            timeUsedSeconds: Number(goal.timeUsedSeconds ?? 0),
+            createdAt: Number(goal.createdAt ?? 0),
+            updatedAt: Number(goal.updatedAt ?? 0),
+        };
+    }
     sendNotification(method, params) {
         this.writeMessage({
             jsonrpc: "2.0",

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.",

package/dist/run-launcher.js

@@ -3,6 +3,7 @@ import { buildRunFailureActivity } from "./linear-session-reporting.js";
 import { loadPatchRelayRepoPrompting } from "./patchrelay-customization.js";
 import { buildRunPrompt as buildPatchRelayRunPrompt, findDisallowedPatchRelayPromptSectionIds, findUnknownPatchRelayPromptSectionIds, mergePromptCustomizationLayers, resolvePromptLayers, } from "./prompting/patchrelay.js";
 import { configureGitHubBotAuthForWorktree } from "./github-worktree-auth.js";
+import { sanitizeDiagnosticText } from "./utils.js";
 function slugify(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
 }
@@ -15,6 +16,28 @@ function shouldCompactThread(issue, threadGeneration, context) {
         && (threadGeneration ?? 0) >= 4
         && followUpCount >= 4;
 }
+function compactGoalText(value, maxLength = 600) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function extractIssueSection(description, heading) {
+    if (!description)
+        return undefined;
+    const headingLine = `## ${heading}`.toLowerCase();
+    const lines = description.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === headingLine);
+    if (start === -1)
+        return undefined;
+    const end = lines.findIndex((line, index) => index > start && /^##\s+/.test(line));
+    const body = lines.slice(start + 1, end === -1 ? undefined : end).join("\n").trim();
+    return body && body.length > 0 ? body : undefined;
+}
+export function buildInitialImplementationGoal(issue) {
+    const title = issue.title?.trim() || `Complete ${issue.issueKey ?? issue.linearIssueId}`;
+    const description = issue.description?.trim();
+    const goal = extractIssueSection(description, "Goal");
+    return compactGoalText(goal ? `${title}. ${goal}` : title);
+}
 export function shouldReuseIssueThread(params) {
     return Boolean(params.existingThreadId) && !params.compactThread && params.resumeThread;
 }
@@ -125,6 +148,8 @@ export class RunLauncher {
         let threadId;
         let turnId;
         let parentThreadId;
+        let createdThreadForRun = false;
+        const firstThreadForIssue = !params.issue.threadId;
         try {
             await this.worktreeManager.ensureIssueWorktree(params.project.repoPath, params.project.worktreeRoot, params.worktreePath, params.branchName, { allowExistingOutsideRoot: params.issue.branchName !== undefined });
             if (params.botIdentity) {
@@ -157,6 +182,7 @@ export class RunLauncher {
             else {
                 const thread = await this.codex.startThread({ cwd: params.worktreePath });
                 threadId = thread.id;
+                createdThreadForRun = true;
                 this.db.issueSessions.upsertIssueWithLease({ projectId: params.project.id, linearIssueId: params.issue.linearIssueId, leaseId: params.leaseId }, { projectId: params.project.id, linearIssueId: params.issue.linearIssueId, threadId });
             }
             try {
@@ -169,6 +195,7 @@ export class RunLauncher {
                     this.logger.info({ issueKey: params.issue.issueKey, staleThreadId: threadId }, "Thread is stale, retrying with fresh thread");
                     const thread = await this.codex.startThread({ cwd: params.worktreePath });
                     threadId = thread.id;
+                    createdThreadForRun = true;
                     this.db.issueSessions.upsertIssueWithLease({ projectId: params.project.id, linearIssueId: params.issue.linearIssueId, leaseId: params.leaseId }, { projectId: params.project.id, linearIssueId: params.issue.linearIssueId, threadId });
                     const turn = await this.codex.startTurn({ threadId, cwd: params.worktreePath, input: params.prompt });
                     turnId = turn.turnId;
@@ -177,6 +204,9 @@ export class RunLauncher {
                     throw turnError;
                 }
             }
+            if (createdThreadForRun && firstThreadForIssue && params.runType === "implementation") {
+                await this.setInitialImplementationGoal(threadId, params.issue);
+            }
             params.assertLaunchLease(params.run, "after starting the Codex turn");
             return { threadId, turnId, ...(parentThreadId ? { parentThreadId } : {}) };
         }
@@ -204,4 +234,22 @@ export class RunLauncher {
             throw error;
         }
     }
+    async setInitialImplementationGoal(threadId, issue) {
+        const goalSetter = this.codex.setThreadGoal;
+        if (typeof goalSetter !== "function") {
+            return;
+        }
+        const objective = buildInitialImplementationGoal(issue);
+        try {
+            await goalSetter.call(this.codex, { threadId, objective, status: "active" });
+            this.logger.info({ issueKey: issue.issueKey, threadId }, "Set Codex thread goal for implementation run");
+        }
+        catch (error) {
+            this.logger.warn({
+                issueKey: issue.issueKey,
+                threadId,
+                error: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
+            }, "Failed to set Codex thread goal for implementation run");
+        }
+    }
 }

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.1",
+  "version": "0.68.0",
   "license": "MIT",
   "type": "module",
   "repository": {