@slaw-ai/server 2026.611.0

package/dist/services/issues.js

@@ -0,0 +1,4705 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { and, asc, desc, eq, gt, inArray, isNull, like, lt, ne, notInArray, or, sql } from "drizzle-orm";
+import { activityLog, agentWakeupRequests, agents, approvals, assets, squads, squadMemberships, documentRevisions, documents, goals, heartbeatRuns, executionWorkspaces, issueApprovals, issueAttachments, issueInboxArchives, issueLabels, issuePlanDecompositions, issueRecoveryActions, issueRelations, issueComments, issueDocuments, issueReadStates, issueThreadInteractions, issues, labels, projectWorkspaces, projects, workspaceOperations, } from "@slaw-ai/db";
+import { clampIssueRequestDepth, extractAgentMentionIds, extractProjectMentionIds, issueCommentAuthorTypeSchema, issueCommentMetadataSchema, issueCommentPresentationSchema, isUuidLike, normalizeIssueIdentifier as normalizeIssueReferenceIdentifier, } from "@slaw-ai/shared";
+import { conflict, HttpError, notFound, unprocessable } from "../errors.js";
+import { logger } from "../middleware/logger.js";
+import { parseObject } from "../adapters/utils.js";
+import { defaultIssueExecutionWorkspaceSettingsForProject, gateProjectExecutionWorkspacePolicy, issueExecutionWorkspaceModeForPersistedWorkspace, parseIssueExecutionWorkspaceSettings, parseProjectExecutionWorkspacePolicy, } from "./execution-workspace-policy.js";
+import { mergeExecutionWorkspaceConfig } from "./execution-workspaces.js";
+import { buildInitialIssueMonitorFields, normalizeIssueExecutionPolicy } from "./issue-execution-policy.js";
+import { instanceSettingsService } from "./instance-settings.js";
+import { redactCurrentUserText } from "../log-redaction.js";
+import { redactSensitiveText } from "../redaction.js";
+import { resolveIssueGoalId, resolveNextIssueGoalId } from "./issue-goal-fallback.js";
+import { getRunLogStore } from "./run-log-store.js";
+import { getDefaultSquadGoal } from "./goals.js";
+import { isVerifiedIssueTreeControlInteractionWake, issueTreeControlService, } from "./issue-tree-control.js";
+import { parseIssueGraphLivenessIncidentKey, RECOVERY_ORIGIN_KINDS, } from "./recovery/origins.js";
+import { classifyIssueGraphLiveness } from "./recovery/issue-graph-liveness.js";
+const ALL_ISSUE_STATUSES = ["backlog", "todo", "in_progress", "in_review", "blocked", "done", "cancelled"];
+const MAX_ISSUE_COMMENT_PAGE_LIMIT = 500;
+export const ISSUE_LIST_DEFAULT_LIMIT = 500;
+export const ISSUE_LIST_MAX_LIMIT = 1000;
+const ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE = 500;
+export const MAX_CHILD_ISSUES_CREATED_BY_HELPER = 25;
+const MAX_CHILD_COMPLETION_SUMMARIES = 20;
+const CHILD_COMPLETION_SUMMARY_BODY_MAX_CHARS = 500;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_LOG_BYTES = 2_000_000;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_CHUNK_BYTES = 256_000;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_END_SLACK_MS = 60_000;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_PARALLEL_READS = 8;
+function assertTransition(from, to) {
+    if (from === to)
+        return;
+    if (!ALL_ISSUE_STATUSES.includes(to)) {
+        throw conflict(`Unknown issue status: ${to}`);
+    }
+}
+function applyStatusSideEffects(status, patch) {
+    if (!status)
+        return patch;
+    if (status === "in_progress" && !patch.startedAt) {
+        patch.startedAt = new Date();
+    }
+    if (status === "done") {
+        patch.completedAt = new Date();
+    }
+    if (status === "cancelled") {
+        patch.cancelledAt = new Date();
+    }
+    return patch;
+}
+function readStringFromRecord(record, key) {
+    if (!record || typeof record !== "object")
+        return null;
+    const value = record[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function buildReusedExecutionWorkspaceConfigPatchFromIssueSettings(settings) {
+    return {
+        environmentId: settings?.environmentId ?? null,
+        provisionCommand: settings?.workspaceStrategy?.provisionCommand ?? null,
+        teardownCommand: settings?.workspaceStrategy?.teardownCommand ?? null,
+        workspaceRuntime: settings?.workspaceRuntime ?? null,
+    };
+}
+function toTimestampMs(value) {
+    if (!value)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    const timestamp = date.getTime();
+    return Number.isFinite(timestamp) ? timestamp : null;
+}
+export function deriveIssueCommentRunLogAttribution(comments, runs) {
+    const derivedByCommentId = new Map();
+    for (const comment of comments) {
+        if (comment.authorAgentId || !comment.authorUserId || comment.createdByRunId)
+            continue;
+        const commentCreatedAtMs = toTimestampMs(comment.createdAt);
+        if (commentCreatedAtMs === null)
+            continue;
+        let bestMatch = null;
+        for (const run of runs) {
+            const runStartMs = toTimestampMs(run.startedAt ?? run.createdAt);
+            const runEndMs = toTimestampMs(run.finishedAt ?? run.createdAt);
+            if (runStartMs === null || runEndMs === null)
+                continue;
+            if (commentCreatedAtMs < runStartMs
+                || commentCreatedAtMs > runEndMs + ISSUE_COMMENT_RUN_LOG_DERIVATION_END_SLACK_MS) {
+                continue;
+            }
+            if (!run.logContent.includes(`comment id: ${comment.id}`))
+                continue;
+            const distanceMs = Math.abs(runEndMs - commentCreatedAtMs);
+            if (!bestMatch || distanceMs < bestMatch.distanceMs) {
+                bestMatch = {
+                    runId: run.runId,
+                    agentId: run.agentId,
+                    distanceMs,
+                };
+            }
+        }
+        if (!bestMatch)
+            continue;
+        derivedByCommentId.set(comment.id, {
+            derivedAuthorAgentId: bestMatch.agentId,
+            derivedCreatedByRunId: bestMatch.runId,
+            derivedAuthorSource: "run_log_comment_post",
+        });
+    }
+    return derivedByCommentId;
+}
+function serializeAcceptedPlanDecomposition(decomposition) {
+    return {
+        id: decomposition.id,
+        squadId: decomposition.squadId,
+        sourceIssueId: decomposition.sourceIssueId,
+        acceptedPlanRevisionId: decomposition.acceptedPlanRevisionId,
+        acceptedInteractionId: decomposition.acceptedInteractionId,
+        status: decomposition.status,
+        requestFingerprint: decomposition.requestFingerprint,
+        // Intentionally omit requestedChildren here; the API only needs stable counts
+        // and child ids, while the durable table keeps the full child draft payload.
+        requestedChildCount: decomposition.requestedChildCount,
+        childIssueIds: normalizeIssuePlanDecompositionChildIds(decomposition.childIssueIds),
+        ownerAgentId: decomposition.ownerAgentId,
+        ownerUserId: decomposition.ownerUserId,
+        ownerRunId: decomposition.ownerRunId,
+        completedAt: decomposition.completedAt,
+        createdAt: decomposition.createdAt,
+        updatedAt: decomposition.updatedAt,
+    };
+}
+function sameRunLock(checkoutRunId, actorRunId) {
+    if (actorRunId)
+        return checkoutRunId === actorRunId;
+    return checkoutRunId == null;
+}
+const TERMINAL_HEARTBEAT_RUN_STATUSES = new Set(["succeeded", "failed", "cancelled", "timed_out"]);
+const ISSUE_LIST_DESCRIPTION_MAX_CHARS = 1200;
+const ISSUE_LIST_DESCRIPTION_MAX_BYTES = ISSUE_LIST_DESCRIPTION_MAX_CHARS * 4;
+function escapeLikePattern(value) {
+    return value.replace(/[\\%_]/g, "\\$&");
+}
+export function clampIssueListLimit(limit) {
+    return Math.min(ISSUE_LIST_MAX_LIMIT, Math.max(1, Math.floor(limit)));
+}
+function chunkList(values, size) {
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size) {
+        chunks.push(values.slice(index, index + size));
+    }
+    return chunks;
+}
+function truncateInlineSummary(value, maxChars = CHILD_COMPLETION_SUMMARY_BODY_MAX_CHARS) {
+    const normalized = value?.trim();
+    if (!normalized)
+        return null;
+    return normalized.length > maxChars ? `${normalized.slice(0, Math.max(0, maxChars - 15)).trimEnd()} [truncated]` : normalized;
+}
+function truncateByCodePoint(value, maxChars) {
+    if (value.length <= maxChars)
+        return value;
+    return Array.from(value).slice(0, maxChars).join("");
+}
+function decodeDatabaseTextPreview(value, maxChars) {
+    if (value == null)
+        return null;
+    return truncateByCodePoint(Buffer.from(value, "base64").toString("utf8"), maxChars);
+}
+function appendAcceptanceCriteriaToDescription(description, acceptanceCriteria) {
+    const criteria = (acceptanceCriteria ?? []).map((item) => item.trim()).filter(Boolean);
+    if (criteria.length === 0)
+        return description ?? null;
+    const base = description?.trim() ?? "";
+    const criteriaMarkdown = ["## Acceptance Criteria", "", ...criteria.map((item) => `- ${item}`)].join("\n");
+    return base ? `${base}\n\n${criteriaMarkdown}` : criteriaMarkdown;
+}
+function normalizeAcceptedPlanDecompositionFingerprintValue(value) {
+    if (value === undefined)
+        return null;
+    if (value == null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeAcceptedPlanDecompositionFingerprintValue(item));
+    }
+    if (typeof value === "object") {
+        const record = value;
+        return Object.fromEntries(Object.keys(record)
+            .sort()
+            .map((key) => [key, normalizeAcceptedPlanDecompositionFingerprintValue(record[key])]));
+    }
+    return String(value);
+}
+const ACCEPTED_PLAN_DECOMPOSITION_FINGERPRINT_CHILD_METADATA_KEYS = new Set([
+    "id",
+    "squadId",
+    "parentId",
+    "identifier",
+    "checkoutRunId",
+    "executionRunId",
+    "executionLockedAt",
+    "startedAt",
+    "completedAt",
+    "cancelledAt",
+    "hiddenAt",
+    "createdAt",
+    "updatedAt",
+    "createdByAgentId",
+    "createdByUserId",
+    "updatedByAgentId",
+    "updatedByUserId",
+    "actorAgentId",
+    "actorUserId",
+]);
+function normalizeAcceptedPlanDecompositionFingerprintChild(child) {
+    return Object.fromEntries(Object.entries(child).filter(([key]) => !ACCEPTED_PLAN_DECOMPOSITION_FINGERPRINT_CHILD_METADATA_KEYS.has(key)));
+}
+function createAcceptedPlanDecompositionRequestFingerprint(input) {
+    const canonical = JSON.stringify(normalizeAcceptedPlanDecompositionFingerprintValue({
+        acceptedPlanRevisionId: input.acceptedPlanRevisionId,
+        children: input.children.map(normalizeAcceptedPlanDecompositionFingerprintChild),
+    }));
+    return createHash("sha256").update(canonical).digest("hex");
+}
+function normalizeIssuePlanDecompositionChildIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.length > 0);
+}
+export function readAcceptedPlanConfirmationTarget(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const target = payload.target;
+    if (!target || typeof target !== "object" || Array.isArray(target))
+        return null;
+    const record = target;
+    if (record.type !== "issue_document")
+        return null;
+    const revisionId = readStringFromRecord(record, "revisionId");
+    const key = readStringFromRecord(record, "key");
+    const issueId = readStringFromRecord(record, "issueId");
+    if (!revisionId || !key || !issueId)
+        return null;
+    return { revisionId, key, issueId };
+}
+async function resolveAcceptedPlanClaimOwner(input) {
+    const nextOwner = {
+        ownerAgentId: input.actorAgentId ?? null,
+        ownerUserId: input.actorUserId ?? null,
+        ownerRunId: input.actorRunId ?? null,
+    };
+    if (input.claim.ownerAgentId === nextOwner.ownerAgentId
+        && input.claim.ownerUserId === nextOwner.ownerUserId
+        && input.claim.ownerRunId === nextOwner.ownerRunId) {
+        return nextOwner;
+    }
+    if (!input.claim.ownerRunId) {
+        return nextOwner;
+    }
+    const existingOwnerRun = await input.dbOrTx
+        .select({ status: heartbeatRuns.status })
+        .from(heartbeatRuns)
+        .where(eq(heartbeatRuns.id, input.claim.ownerRunId))
+        .then((rows) => rows[0] ?? null);
+    if (existingOwnerRun && !TERMINAL_HEARTBEAT_RUN_STATUSES.has(existingOwnerRun.status)) {
+        return {
+            ownerAgentId: input.claim.ownerAgentId,
+            ownerUserId: input.claim.ownerUserId,
+            ownerRunId: input.claim.ownerRunId,
+        };
+    }
+    return nextOwner;
+}
+async function findAcceptedPlanDocumentInteraction(dbOrTx, input) {
+    const rows = await dbOrTx
+        .select({
+        id: issueThreadInteractions.id,
+        payload: issueThreadInteractions.payload,
+    })
+        .from(issueThreadInteractions)
+        .where(and(eq(issueThreadInteractions.squadId, input.squadId), eq(issueThreadInteractions.issueId, input.sourceIssueId), eq(issueThreadInteractions.kind, "request_confirmation"), eq(issueThreadInteractions.status, "accepted")))
+        .orderBy(desc(issueThreadInteractions.resolvedAt), desc(issueThreadInteractions.createdAt));
+    for (const row of rows) {
+        const target = readAcceptedPlanConfirmationTarget(row.payload);
+        if (target?.issueId === input.sourceIssueId &&
+            target.key === "plan" &&
+            target.revisionId === input.acceptedPlanRevisionId) {
+            return { id: row.id };
+        }
+    }
+    return null;
+}
+function createIssueDependencyReadiness(issueId) {
+    return {
+        issueId,
+        blockerIssueIds: [],
+        unresolvedBlockerIssueIds: [],
+        unresolvedBlockerCount: 0,
+        pendingFinalizeBlockerIssueIds: [],
+        allBlockersDone: true,
+        isDependencyReady: true,
+    };
+}
+/**
+ * Returns the set of execution-workspace ids whose most recent workspace operation
+ * is NOT a successful `workspace_finalize`. These workspaces have either an in-flight
+ * run, a failed finalize, or never reached the finalize barrier — dependents that
+ * read this workspace must wait until finalize succeeds.
+ *
+ * Workspaces with no recorded operations are considered finalized (nothing has
+ * touched them since they were realized).
+ */
+export async function listUnfinalizedExecutionWorkspaceIds(dbOrTx, squadId, executionWorkspaceIds) {
+    const unfinalized = new Set();
+    if (executionWorkspaceIds.length === 0)
+        return unfinalized;
+    // Pull every workspace op for the candidate workspaces and pick the latest per
+    // workspace in memory. Per-workspace LATERAL queries would be tighter, but the
+    // candidate set is tiny in practice (one workspace per blocker per readiness call).
+    const rows = await dbOrTx
+        .select({
+        executionWorkspaceId: workspaceOperations.executionWorkspaceId,
+        phase: workspaceOperations.phase,
+        status: workspaceOperations.status,
+        startedAt: workspaceOperations.startedAt,
+    })
+        .from(workspaceOperations)
+        .where(and(eq(workspaceOperations.squadId, squadId), inArray(workspaceOperations.executionWorkspaceId, executionWorkspaceIds)));
+    const latestByWorkspace = new Map();
+    for (const row of rows) {
+        if (!row.executionWorkspaceId)
+            continue;
+        const current = latestByWorkspace.get(row.executionWorkspaceId);
+        if (!current || row.startedAt > current.startedAt) {
+            latestByWorkspace.set(row.executionWorkspaceId, {
+                phase: row.phase,
+                status: row.status,
+                startedAt: row.startedAt,
+            });
+        }
+    }
+    for (const workspaceId of executionWorkspaceIds) {
+        const latest = latestByWorkspace.get(workspaceId);
+        if (!latest)
+            continue; // no ops recorded → treat as finalized
+        if (latest.phase === "workspace_finalize" && latest.status === "succeeded")
+            continue;
+        unfinalized.add(workspaceId);
+    }
+    return unfinalized;
+}
+async function listIssueDependencyReadinessMap(dbOrTx, squadId, issueIds) {
+    const uniqueIssueIds = [...new Set(issueIds.filter(Boolean))];
+    const readinessMap = new Map();
+    for (const issueId of uniqueIssueIds) {
+        readinessMap.set(issueId, createIssueDependencyReadiness(issueId));
+    }
+    if (uniqueIssueIds.length === 0)
+        return readinessMap;
+    const blockerRows = await dbOrTx
+        .select({
+        issueId: issueRelations.relatedIssueId,
+        blockerIssueId: issueRelations.issueId,
+        blockerStatus: issues.status,
+        blockerExecutionWorkspaceId: issues.executionWorkspaceId,
+    })
+        .from(issueRelations)
+        .innerJoin(issues, eq(issueRelations.issueId, issues.id))
+        .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks"), inArray(issueRelations.relatedIssueId, uniqueIssueIds)));
+    // Collect executionWorkspaceIds of "done" blockers — these are the only ones
+    // subject to the workspace-finalize barrier. Blockers that aren't done already
+    // mark the dependent as not-ready and don't need a finalize check.
+    const doneBlockerWorkspaceIds = new Set();
+    for (const row of blockerRows) {
+        if (row.blockerStatus === "done" && row.blockerExecutionWorkspaceId) {
+            doneBlockerWorkspaceIds.add(row.blockerExecutionWorkspaceId);
+        }
+    }
+    const unfinalizedWorkspaceIds = await listUnfinalizedExecutionWorkspaceIds(dbOrTx, squadId, [...doneBlockerWorkspaceIds]);
+    for (const row of blockerRows) {
+        const current = readinessMap.get(row.issueId) ?? createIssueDependencyReadiness(row.issueId);
+        current.blockerIssueIds.push(row.blockerIssueId);
+        // Only done blockers resolve dependents; cancelled blockers stay unresolved
+        // until an operator removes or replaces the blocker relationship explicitly.
+        if (row.blockerStatus !== "done") {
+            current.unresolvedBlockerIssueIds.push(row.blockerIssueId);
+            current.unresolvedBlockerCount += 1;
+            current.allBlockersDone = false;
+            current.isDependencyReady = false;
+        }
+        else if (row.blockerExecutionWorkspaceId &&
+            unfinalizedWorkspaceIds.has(row.blockerExecutionWorkspaceId)) {
+            // Workspace-finalize barrier: the blocker's most recent run on its
+            // execution workspace hasn't recorded a successful workspace_finalize.
+            // Treat the dependent as not-ready until sync-back lands (or the run
+            // finalizes); a subsequent finalize wake will re-evaluate readiness.
+            // `allBlockersDone` is cleared too so that callers using it as a
+            // proxy for "this dependent can proceed" still see the gate.
+            current.unresolvedBlockerIssueIds.push(row.blockerIssueId);
+            current.unresolvedBlockerCount += 1;
+            current.pendingFinalizeBlockerIssueIds.push(row.blockerIssueId);
+            current.allBlockersDone = false;
+            current.isDependencyReady = false;
+        }
+        readinessMap.set(row.issueId, current);
+    }
+    return readinessMap;
+}
+async function listUnresolvedBlockerIssueIds(dbOrTx, squadId, blockerIssueIds) {
+    const uniqueBlockerIssueIds = [...new Set(blockerIssueIds.filter(Boolean))];
+    if (uniqueBlockerIssueIds.length === 0)
+        return [];
+    return dbOrTx
+        .select({ id: issues.id })
+        .from(issues)
+        .where(and(eq(issues.squadId, squadId), inArray(issues.id, uniqueBlockerIssueIds), 
+    // Cancelled blockers intentionally remain unresolved until the relation changes.
+    ne(issues.status, "done")))
+        .then((rows) => rows.map((row) => row.id));
+}
+async function getProjectDefaultGoalId(db, squadId, projectId) {
+    if (!projectId)
+        return null;
+    const row = await db
+        .select({ goalId: projects.goalId })
+        .from(projects)
+        .where(and(eq(projects.id, projectId), eq(projects.squadId, squadId)))
+        .then((rows) => rows[0] ?? null);
+    return row?.goalId ?? null;
+}
+async function getWorkspaceInheritanceIssue(db, squadId, issueId) {
+    const issue = await db
+        .select({
+        id: issues.id,
+        projectId: issues.projectId,
+        projectWorkspaceId: issues.projectWorkspaceId,
+        executionWorkspaceId: issues.executionWorkspaceId,
+        executionWorkspaceSettings: issues.executionWorkspaceSettings,
+    })
+        .from(issues)
+        .where(and(eq(issues.id, issueId), eq(issues.squadId, squadId)))
+        .then((rows) => rows[0] ?? null);
+    if (!issue) {
+        throw notFound("Workspace inheritance issue not found");
+    }
+    return issue;
+}
+function touchedByUserCondition(squadId, userId) {
+    return sql `
+    (
+      ${issues.createdByUserId} = ${userId}
+      OR ${issues.assigneeUserId} = ${userId}
+      OR EXISTS (
+        SELECT 1
+        FROM ${issueReadStates}
+        WHERE ${issueReadStates.issueId} = ${issues.id}
+          AND ${issueReadStates.squadId} = ${squadId}
+          AND ${issueReadStates.userId} = ${userId}
+      )
+      OR EXISTS (
+        SELECT 1
+        FROM ${issueComments}
+        WHERE ${issueComments.issueId} = ${issues.id}
+          AND ${issueComments.squadId} = ${squadId}
+          AND ${issueComments.authorUserId} = ${userId}
+      )
+    )
+  `;
+}
+function participatedByAgentCondition(squadId, agentId) {
+    return sql `
+    (
+      ${issues.createdByAgentId} = ${agentId}
+      OR ${issues.assigneeAgentId} = ${agentId}
+      OR EXISTS (
+        SELECT 1
+        FROM ${issueComments}
+        WHERE ${issueComments.issueId} = ${issues.id}
+          AND ${issueComments.squadId} = ${squadId}
+          AND ${issueComments.authorAgentId} = ${agentId}
+      )
+      OR EXISTS (
+        SELECT 1
+        FROM ${activityLog}
+        WHERE ${activityLog.squadId} = ${squadId}
+          AND ${activityLog.entityType} = 'issue'
+          AND ${activityLog.entityId} = ${issues.id}::text
+          AND ${activityLog.agentId} = ${agentId}
+      )
+    )
+  `;
+}
+function myLastCommentAtExpr(squadId, userId) {
+    return sql `
+    (
+      SELECT MAX(${issueComments.createdAt})
+      FROM ${issueComments}
+      WHERE ${issueComments.issueId} = ${issues.id}
+        AND ${issueComments.squadId} = ${squadId}
+        AND ${issueComments.authorUserId} = ${userId}
+    )
+  `;
+}
+function myLastReadAtExpr(squadId, userId) {
+    return sql `
+    (
+      SELECT MAX(${issueReadStates.lastReadAt})
+      FROM ${issueReadStates}
+      WHERE ${issueReadStates.issueId} = ${issues.id}
+        AND ${issueReadStates.squadId} = ${squadId}
+        AND ${issueReadStates.userId} = ${userId}
+    )
+  `;
+}
+function myLastTouchAtExpr(squadId, userId) {
+    const myLastCommentAt = myLastCommentAtExpr(squadId, userId);
+    const myLastReadAt = myLastReadAtExpr(squadId, userId);
+    return sql `
+    GREATEST(
+      COALESCE(${myLastCommentAt}, to_timestamp(0)),
+      COALESCE(${myLastReadAt}, to_timestamp(0)),
+      COALESCE(CASE WHEN ${issues.createdByUserId} = ${userId} THEN ${issues.createdAt} ELSE NULL END, to_timestamp(0)),
+      COALESCE(CASE WHEN ${issues.assigneeUserId} = ${userId} THEN ${issues.updatedAt} ELSE NULL END, to_timestamp(0))
+    )
+  `;
+}
+function lastExternalCommentAtExpr(squadId, userId) {
+    return sql `
+    (
+      SELECT MAX(${issueComments.createdAt})
+      FROM ${issueComments}
+      WHERE ${issueComments.issueId} = ${issues.id}
+        AND ${issueComments.squadId} = ${squadId}
+        AND (
+          ${issueComments.authorUserId} IS NULL
+          OR ${issueComments.authorUserId} <> ${userId}
+        )
+    )
+  `;
+}
+function issueLastActivityAtExpr(squadId, userId) {
+    const lastExternalCommentAt = lastExternalCommentAtExpr(squadId, userId);
+    const myLastTouchAt = myLastTouchAtExpr(squadId, userId);
+    return sql `
+    GREATEST(
+      COALESCE(${lastExternalCommentAt}, to_timestamp(0)),
+      CASE
+        WHEN ${issues.updatedAt} > COALESCE(${myLastTouchAt}, to_timestamp(0))
+        THEN ${issues.updatedAt}
+        ELSE to_timestamp(0)
+      END
+    )
+  `;
+}
+const ISSUE_LOCAL_INBOX_ACTIVITY_ACTIONS = [
+    "issue.read_marked",
+    "issue.read_unmarked",
+    "issue.inbox_archived",
+    "issue.inbox_unarchived",
+];
+function issueLatestCommentAtExpr(squadId) {
+    return sql `
+    (
+      SELECT MAX(${issueComments.createdAt})
+      FROM ${issueComments}
+      WHERE ${issueComments.issueId} = ${issues.id}
+        AND ${issueComments.squadId} = ${squadId}
+    )
+  `;
+}
+function issueLatestLogAtExpr(squadId) {
+    return sql `
+    (
+      SELECT MAX(${activityLog.createdAt})
+      FROM ${activityLog}
+      WHERE ${activityLog.squadId} = ${squadId}
+        AND ${activityLog.entityType} = 'issue'
+        AND ${activityLog.entityId} = ${issues.id}::text
+        AND ${activityLog.action} NOT IN (${sql.join(ISSUE_LOCAL_INBOX_ACTIVITY_ACTIONS.map((action) => sql `${action}`), sql `, `)})
+    )
+  `;
+}
+function issueCanonicalLastActivityAtExpr(squadId) {
+    const latestCommentAt = issueLatestCommentAtExpr(squadId);
+    const latestLogAt = issueLatestLogAtExpr(squadId);
+    return sql `
+    GREATEST(
+      ${issues.updatedAt},
+      COALESCE(${latestCommentAt}, to_timestamp(0)),
+      COALESCE(${latestLogAt}, to_timestamp(0))
+    )
+  `;
+}
+function unreadForUserCondition(squadId, userId) {
+    const touchedCondition = touchedByUserCondition(squadId, userId);
+    const myLastTouchAt = myLastTouchAtExpr(squadId, userId);
+    return sql `
+    (
+      ${touchedCondition}
+      AND EXISTS (
+        SELECT 1
+        FROM ${issueComments}
+        WHERE ${issueComments.issueId} = ${issues.id}
+          AND ${issueComments.squadId} = ${squadId}
+          AND (
+            ${issueComments.authorUserId} IS NULL
+            OR ${issueComments.authorUserId} <> ${userId}
+          )
+          AND ${issueComments.createdAt} > ${myLastTouchAt}
+      )
+    )
+  `;
+}
+function inboxVisibleForUserCondition(squadId, userId) {
+    const issueLastActivityAt = issueLastActivityAtExpr(squadId, userId);
+    return sql `
+    NOT EXISTS (
+      SELECT 1
+      FROM ${issueInboxArchives}
+      WHERE ${issueInboxArchives.issueId} = ${issues.id}
+        AND ${issueInboxArchives.squadId} = ${squadId}
+        AND ${issueInboxArchives.userId} = ${userId}
+        AND ${issueInboxArchives.archivedAt} >= ${issueLastActivityAt}
+    )
+  `;
+}
+const LEGACY_PLUGIN_OPERATION_ORIGIN_KINDS = [
+    "plugin:slaw.content-machine:case",
+    "plugin:slaw.content-machine:evaluation",
+    "plugin:slaw.content-machine:source-sync",
+];
+function nonPluginOperationIssueCondition() {
+    return sql `NOT (
+    ${issues.originKind} LIKE 'plugin:%:operation'
+    OR ${issues.originKind} LIKE 'plugin:%:operation:%'
+    OR ${inArray(issues.originKind, LEGACY_PLUGIN_OPERATION_ORIGIN_KINDS)}
+  )`;
+}
+function shouldIncludePluginOperationIssues(filters) {
+    return Boolean(filters?.includePluginOperations ||
+        filters?.originKind ||
+        filters?.originKindPrefix ||
+        filters?.originId ||
+        filters?.projectId);
+}
+/** Named entities commonly emitted in saved issue bodies; unknown `&name;` sequences are left unchanged. */
+const WELL_KNOWN_NAMED_HTML_ENTITIES = {
+    amp: "&",
+    apos: "'",
+    copy: "\u00A9",
+    gt: ">",
+    lt: "<",
+    nbsp: "\u00A0",
+    quot: '"',
+    ensp: "\u2002",
+    emsp: "\u2003",
+    thinsp: "\u2009",
+};
+function decodeNumericHtmlEntity(digits, radix) {
+    const n = Number.parseInt(digits, radix);
+    if (Number.isNaN(n) || n < 0 || n > 0x10ffff)
+        return null;
+    try {
+        return String.fromCodePoint(n);
+    }
+    catch {
+        return null;
+    }
+}
+/** Decodes HTML character references in a raw @mention capture so UI-encoded bodies match agent names. */
+export function normalizeAgentMentionToken(raw) {
+    let s = raw.replace(/&#x([0-9a-fA-F]+);/gi, (full, hex) => decodeNumericHtmlEntity(hex, 16) ?? full);
+    s = s.replace(/&#([0-9]+);/g, (full, dec) => decodeNumericHtmlEntity(dec, 10) ?? full);
+    s = s.replace(/&([a-z][a-z0-9]*);/gi, (full, name) => {
+        const decoded = WELL_KNOWN_NAMED_HTML_ENTITIES[name.toLowerCase()];
+        return decoded !== undefined ? decoded : full;
+    });
+    return s.trim();
+}
+export function deriveIssueUserContext(issue, userId, stats) {
+    const normalizeDate = (value) => {
+        if (!value)
+            return null;
+        if (value instanceof Date)
+            return Number.isNaN(value.getTime()) ? null : value;
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    };
+    const myLastCommentAt = normalizeDate(stats?.myLastCommentAt);
+    const myLastReadAt = normalizeDate(stats?.myLastReadAt);
+    const createdTouchAt = issue.createdByUserId === userId ? normalizeDate(issue.createdAt) : null;
+    const assignedTouchAt = issue.assigneeUserId === userId ? normalizeDate(issue.updatedAt) : null;
+    const myLastTouchAt = [myLastCommentAt, myLastReadAt, createdTouchAt, assignedTouchAt]
+        .filter((value) => value instanceof Date)
+        .sort((a, b) => b.getTime() - a.getTime())[0] ?? null;
+    const lastExternalCommentAt = normalizeDate(stats?.lastExternalCommentAt);
+    const isUnreadForMe = Boolean(myLastTouchAt &&
+        lastExternalCommentAt &&
+        lastExternalCommentAt.getTime() > myLastTouchAt.getTime());
+    return {
+        myLastTouchAt,
+        lastExternalCommentAt,
+        isUnreadForMe,
+    };
+}
+function latestIssueActivityAt(...values) {
+    const normalized = values
+        .map((value) => {
+        if (!value)
+            return null;
+        if (value instanceof Date)
+            return Number.isNaN(value.getTime()) ? null : value;
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    })
+        .filter((value) => value instanceof Date)
+        .sort((a, b) => b.getTime() - a.getTime());
+    return normalized[0] ?? null;
+}
+function issueListOrderBy(squadId, { hasSearch, priorityOrder, searchOrder, sortField, sortDir, }) {
+    const canonicalLastActivityAt = issueCanonicalLastActivityAtExpr(squadId);
+    if (sortField === "updated") {
+        const activityOrder = sortDir === "asc"
+            ? asc(canonicalLastActivityAt)
+            : desc(canonicalLastActivityAt);
+        const updatedOrder = sortDir === "asc" ? asc(issues.updatedAt) : desc(issues.updatedAt);
+        const idOrder = sortDir === "asc" ? asc(issues.id) : desc(issues.id);
+        return hasSearch
+            ? [asc(searchOrder), activityOrder, updatedOrder, idOrder]
+            : [activityOrder, updatedOrder, idOrder];
+    }
+    return [
+        hasSearch ? asc(searchOrder) : asc(priorityOrder),
+        asc(priorityOrder),
+        desc(canonicalLastActivityAt),
+        desc(issues.updatedAt),
+        desc(issues.id),
+    ];
+}
+async function labelMapForIssues(dbOrTx, issueIds) {
+    const map = new Map();
+    if (issueIds.length === 0)
+        return map;
+    for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const rows = await dbOrTx
+            .select({
+            issueId: issueLabels.issueId,
+            label: labels,
+        })
+            .from(issueLabels)
+            .innerJoin(labels, eq(issueLabels.labelId, labels.id))
+            .where(inArray(issueLabels.issueId, issueIdChunk))
+            .orderBy(asc(labels.name), asc(labels.id));
+        for (const row of rows) {
+            const existing = map.get(row.issueId);
+            if (existing)
+                existing.push(row.label);
+            else
+                map.set(row.issueId, [row.label]);
+        }
+    }
+    return map;
+}
+async function withIssueLabels(dbOrTx, rows) {
+    if (rows.length === 0)
+        return [];
+    const labelsByIssueId = await labelMapForIssues(dbOrTx, rows.map((row) => row.id));
+    return rows.map((row) => {
+        const issueLabels = labelsByIssueId.get(row.id) ?? [];
+        return {
+            ...row,
+            labels: issueLabels,
+            labelIds: issueLabels.map((label) => label.id),
+        };
+    });
+}
+const ACTIVE_RUN_STATUSES = ["queued", "running"];
+const BLOCKER_ATTENTION_ACTIVE_RUN_STATUSES = ["queued", "running"];
+const BLOCKER_ATTENTION_ACTIVE_WAKE_STATUSES = ["queued", "deferred_issue_execution"];
+const BLOCKER_ATTENTION_PENDING_INTERACTION_STATUSES = ["pending"];
+const BLOCKER_ATTENTION_PENDING_APPROVAL_STATUSES = ["pending", "revision_requested"];
+const BLOCKER_ATTENTION_OPEN_RECOVERY_ORIGIN_KIND = "harness_liveness_escalation";
+const PRODUCTIVITY_REVIEW_ORIGIN_KIND = "issue_productivity_review";
+const PRODUCTIVITY_REVIEW_TERMINAL_STATUSES = ["done", "cancelled"];
+const PRODUCTIVITY_REVIEW_ACTIVITY_ACTIONS = [
+    "issue.productivity_review_created",
+    "issue.productivity_review_updated",
+];
+const PRODUCTIVITY_REVIEW_TRIGGERS = [
+    "no_comment_streak",
+    "long_active_duration",
+    "high_churn",
+];
+const BLOCKER_ATTENTION_OPEN_RECOVERY_TERMINAL_STATUSES = ["done", "cancelled"];
+const BLOCKER_ATTENTION_MAX_DEPTH = 8;
+const BLOCKER_ATTENTION_MAX_NODES = 2000;
+const BLOCKER_ATTENTION_INVOKABLE_AGENT_STATUSES = new Set(["active", "idle", "running", "error"]);
+async function activeRunMapForIssues(dbOrTx, issueRows) {
+    const map = new Map();
+    const runIds = issueRows
+        .map((row) => row.executionRunId)
+        .filter((id) => id != null);
+    if (runIds.length === 0)
+        return map;
+    for (const runIdChunk of chunkList([...new Set(runIds)], ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const rows = await dbOrTx
+            .select({
+            id: heartbeatRuns.id,
+            status: heartbeatRuns.status,
+            agentId: heartbeatRuns.agentId,
+            invocationSource: heartbeatRuns.invocationSource,
+            triggerDetail: heartbeatRuns.triggerDetail,
+            startedAt: heartbeatRuns.startedAt,
+            finishedAt: heartbeatRuns.finishedAt,
+            createdAt: heartbeatRuns.createdAt,
+        })
+            .from(heartbeatRuns)
+            .where(and(inArray(heartbeatRuns.id, runIdChunk), inArray(heartbeatRuns.status, ACTIVE_RUN_STATUSES)));
+        for (const row of rows) {
+            map.set(row.id, row);
+        }
+    }
+    return map;
+}
+function createIssueBlockerAttention(input = {}) {
+    return {
+        state: input.state ?? "none",
+        reason: input.reason ?? null,
+        unresolvedBlockerCount: input.unresolvedBlockerCount ?? 0,
+        coveredBlockerCount: input.coveredBlockerCount ?? 0,
+        stalledBlockerCount: input.stalledBlockerCount ?? 0,
+        attentionBlockerCount: input.attentionBlockerCount ?? 0,
+        sampleBlockerIdentifier: input.sampleBlockerIdentifier ?? null,
+        sampleStalledBlockerIdentifier: input.sampleStalledBlockerIdentifier ?? null,
+    };
+}
+function blockerSampleIdentifier(node) {
+    return node?.identifier ?? node?.id ?? null;
+}
+function appendBlockerAttentionEdges(edgesByIssueId, rows) {
+    for (const row of rows) {
+        const existing = edgesByIssueId.get(row.issueId) ?? [];
+        if (!existing.some((edge) => edge.blockerIssueId === row.blockerIssueId)) {
+            existing.push(row);
+            edgesByIssueId.set(row.issueId, existing);
+        }
+    }
+}
+function summarizeIssueRelationRow(row) {
+    return {
+        id: row.relatedId,
+        identifier: row.identifier,
+        title: row.title,
+        status: row.status,
+        priority: row.priority,
+        assigneeAgentId: row.assigneeAgentId,
+        assigneeUserId: row.assigneeUserId,
+    };
+}
+async function terminalExplicitBlockersByRoot(squadId, roots, dbOrTx) {
+    const rootIds = [...new Set(roots.map((root) => root.id))];
+    const terminalByRoot = new Map();
+    if (rootIds.length === 0)
+        return terminalByRoot;
+    const nodesById = new Map();
+    const edgesByIssueId = new Map();
+    for (const root of roots)
+        nodesById.set(root.id, root);
+    let frontier = rootIds;
+    for (let depth = 0; frontier.length > 0 && depth < BLOCKER_ATTENTION_MAX_DEPTH; depth += 1) {
+        const nextFrontier = new Set();
+        for (const chunk of chunkList([...new Set(frontier)], ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+            const rows = await dbOrTx
+                .select({
+                currentIssueId: issueRelations.relatedIssueId,
+                relatedId: issues.id,
+                identifier: issues.identifier,
+                title: issues.title,
+                status: issues.status,
+                priority: issues.priority,
+                assigneeAgentId: issues.assigneeAgentId,
+                assigneeUserId: issues.assigneeUserId,
+            })
+                .from(issueRelations)
+                .innerJoin(issues, eq(issueRelations.issueId, issues.id))
+                .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks"), inArray(issueRelations.relatedIssueId, chunk), eq(issues.squadId, squadId), ne(issues.status, "done")));
+            for (const row of rows) {
+                const existingEdges = edgesByIssueId.get(row.currentIssueId) ?? [];
+                if (!existingEdges.includes(row.relatedId)) {
+                    existingEdges.push(row.relatedId);
+                    edgesByIssueId.set(row.currentIssueId, existingEdges);
+                }
+                if (!nodesById.has(row.relatedId)) {
+                    nodesById.set(row.relatedId, summarizeIssueRelationRow(row));
+                    nextFrontier.add(row.relatedId);
+                }
+            }
+        }
+        if (nodesById.size > BLOCKER_ATTENTION_MAX_NODES)
+            break;
+        frontier = [...nextFrontier];
+    }
+    const collectTerminal = (issueId, seen) => {
+        if (seen.has(issueId))
+            return [];
+        const node = nodesById.get(issueId);
+        if (!node || node.status === "done")
+            return [];
+        const nextSeen = new Set(seen);
+        nextSeen.add(issueId);
+        const downstreamIds = edgesByIssueId.get(issueId) ?? [];
+        if (downstreamIds.length === 0)
+            return [node];
+        return downstreamIds.flatMap((downstreamId) => collectTerminal(downstreamId, nextSeen));
+    };
+    for (const rootId of rootIds) {
+        const deduped = new Map();
+        for (const blocker of collectTerminal(rootId, new Set())) {
+            if (blocker.id !== rootId)
+                deduped.set(blocker.id, blocker);
+        }
+        if (deduped.size > 0) {
+            terminalByRoot.set(rootId, [...deduped.values()].sort((a, b) => a.title.localeCompare(b.title)));
+        }
+    }
+    return terminalByRoot;
+}
+function readProductivityReviewTrigger(value) {
+    if (typeof value !== "string")
+        return null;
+    return PRODUCTIVITY_REVIEW_TRIGGERS.includes(value)
+        ? value
+        : null;
+}
+function readProductivityReviewStreak(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return null;
+    return Math.floor(value);
+}
+async function listIssueProductivityReviewMap(dbOrTx, squadId, sourceIssueIds) {
+    const map = new Map();
+    if (sourceIssueIds.length === 0)
+        return map;
+    const reviewRows = [];
+    for (const chunk of chunkList([...new Set(sourceIssueIds)], ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const rows = await dbOrTx
+            .select({
+            sourceIssueId: issues.originId,
+            reviewIssueId: issues.id,
+            reviewIdentifier: issues.identifier,
+            status: issues.status,
+            priority: issues.priority,
+            createdAt: issues.createdAt,
+            updatedAt: issues.updatedAt,
+        })
+            .from(issues)
+            .where(and(eq(issues.squadId, squadId), eq(issues.originKind, PRODUCTIVITY_REVIEW_ORIGIN_KIND), inArray(issues.originId, chunk), isNull(issues.hiddenAt), notInArray(issues.status, PRODUCTIVITY_REVIEW_TERMINAL_STATUSES)))
+            .orderBy(desc(issues.createdAt), desc(issues.id));
+        reviewRows.push(...rows);
+    }
+    if (reviewRows.length === 0)
+        return map;
+    const reviewIssueIds = reviewRows.map((row) => row.reviewIssueId);
+    const triggerByReviewIssueId = new Map();
+    for (const chunk of chunkList(reviewIssueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const detailRows = await dbOrTx
+            .select({
+            entityId: activityLog.entityId,
+            details: activityLog.details,
+            createdAt: activityLog.createdAt,
+        })
+            .from(activityLog)
+            .where(and(eq(activityLog.squadId, squadId), eq(activityLog.entityType, "issue"), inArray(activityLog.entityId, chunk), inArray(activityLog.action, PRODUCTIVITY_REVIEW_ACTIVITY_ACTIONS)))
+            .orderBy(desc(activityLog.createdAt));
+        for (const row of detailRows) {
+            if (triggerByReviewIssueId.has(row.entityId))
+                continue;
+            triggerByReviewIssueId.set(row.entityId, {
+                trigger: readProductivityReviewTrigger(row.details?.trigger),
+                noCommentStreak: readProductivityReviewStreak(row.details?.noCommentStreak),
+            });
+        }
+    }
+    for (const row of reviewRows) {
+        if (!row.sourceIssueId)
+            continue;
+        if (map.has(row.sourceIssueId))
+            continue;
+        const detail = triggerByReviewIssueId.get(row.reviewIssueId);
+        map.set(row.sourceIssueId, {
+            reviewIssueId: row.reviewIssueId,
+            reviewIdentifier: row.reviewIdentifier,
+            status: row.status,
+            priority: row.priority,
+            trigger: detail?.trigger ?? null,
+            noCommentStreak: detail?.noCommentStreak ?? null,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        });
+    }
+    return map;
+}
+async function listIssueBlockerAttentionMap(dbOrTx, squadId, issueRows) {
+    const roots = issueRows.filter((row) => row.squadId === squadId && row.status === "blocked");
+    const attentionMap = new Map();
+    for (const row of issueRows) {
+        if (row.status !== "blocked") {
+            attentionMap.set(row.id, createIssueBlockerAttention());
+        }
+    }
+    if (roots.length === 0)
+        return attentionMap;
+    const nodesById = new Map();
+    const edgesByIssueId = new Map();
+    for (const root of roots)
+        nodesById.set(root.id, { ...root });
+    let frontier = roots.map((root) => root.id);
+    let truncated = false;
+    for (let depth = 0; frontier.length > 0 && depth < BLOCKER_ATTENTION_MAX_DEPTH; depth += 1) {
+        const nextFrontier = new Set();
+        for (const chunk of chunkList([...new Set(frontier)], ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+            const explicitBlockerRowsPromise = dbOrTx
+                .select({
+                issueId: issueRelations.relatedIssueId,
+                blockerIssueId: issues.id,
+                id: issues.id,
+                squadId: issues.squadId,
+                parentId: issues.parentId,
+                identifier: issues.identifier,
+                title: issues.title,
+                status: issues.status,
+                executionRunId: issues.executionRunId,
+                assigneeAgentId: issues.assigneeAgentId,
+                assigneeUserId: issues.assigneeUserId,
+            })
+                .from(issueRelations)
+                .innerJoin(issues, eq(issueRelations.issueId, issues.id))
+                .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks"), inArray(issueRelations.relatedIssueId, chunk), eq(issues.squadId, squadId), ne(issues.status, "done")));
+            const childRowsPromise = dbOrTx
+                .select({
+                issueId: issues.parentId,
+                blockerIssueId: issues.id,
+                id: issues.id,
+                squadId: issues.squadId,
+                parentId: issues.parentId,
+                identifier: issues.identifier,
+                title: issues.title,
+                status: issues.status,
+                executionRunId: issues.executionRunId,
+                assigneeAgentId: issues.assigneeAgentId,
+                assigneeUserId: issues.assigneeUserId,
+            })
+                .from(issues)
+                .where(and(eq(issues.squadId, squadId), inArray(issues.parentId, chunk), ne(issues.status, "done")));
+            const [explicitBlockerRows, childRows] = await Promise.all([
+                explicitBlockerRowsPromise,
+                childRowsPromise,
+            ]);
+            appendBlockerAttentionEdges(edgesByIssueId, [
+                ...explicitBlockerRows
+                    .filter((row) => row.issueId !== null)
+                    .map((row) => ({ issueId: row.issueId, blockerIssueId: row.blockerIssueId })),
+                ...childRows
+                    .filter((row) => row.issueId !== null)
+                    .map((row) => ({ issueId: row.issueId, blockerIssueId: row.blockerIssueId })),
+            ]);
+            for (const row of [...explicitBlockerRows, ...childRows]) {
+                if (!row.issueId || nodesById.has(row.blockerIssueId))
+                    continue;
+                nodesById.set(row.blockerIssueId, {
+                    id: row.blockerIssueId,
+                    squadId: row.squadId,
+                    parentId: row.parentId,
+                    identifier: row.identifier,
+                    title: row.title,
+                    status: row.status,
+                    executionRunId: row.executionRunId,
+                    assigneeAgentId: row.assigneeAgentId,
+                    assigneeUserId: row.assigneeUserId,
+                });
+                nextFrontier.add(row.blockerIssueId);
+            }
+        }
+        if (nodesById.size > BLOCKER_ATTENTION_MAX_NODES) {
+            truncated = true;
+            break;
+        }
+        frontier = [...nextFrontier];
+    }
+    if (frontier.length > 0)
+        truncated = true;
+    const nodeIds = [...nodesById.keys()];
+    const activeIssueIds = new Set();
+    const agentIds = new Set();
+    const issueIdByExecutionRunId = new Map();
+    for (const node of nodesById.values()) {
+        if (node.assigneeAgentId)
+            agentIds.add(node.assigneeAgentId);
+        if (node.executionRunId)
+            issueIdByExecutionRunId.set(node.executionRunId, node.id);
+    }
+    for (const chunk of chunkList([...issueIdByExecutionRunId.keys()], ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const runRows = await dbOrTx
+            .select({
+            id: heartbeatRuns.id,
+        })
+            .from(heartbeatRuns)
+            .where(and(eq(heartbeatRuns.squadId, squadId), inArray(heartbeatRuns.status, BLOCKER_ATTENTION_ACTIVE_RUN_STATUSES), inArray(heartbeatRuns.id, chunk)));
+        for (const row of runRows) {
+            const issueId = issueIdByExecutionRunId.get(row.id);
+            if (issueId)
+                activeIssueIds.add(issueId);
+        }
+    }
+    for (const chunk of chunkList(nodeIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const wakeRowsPromise = dbOrTx
+            .select({
+            issueId: sql `${agentWakeupRequests.payload} ->> 'issueId'`,
+        })
+            .from(agentWakeupRequests)
+            .where(and(eq(agentWakeupRequests.squadId, squadId), inArray(agentWakeupRequests.status, BLOCKER_ATTENTION_ACTIVE_WAKE_STATUSES), sql `${agentWakeupRequests.runId} is null`, inArray(sql `${agentWakeupRequests.payload} ->> 'issueId'`, chunk)));
+        const wakeRows = await wakeRowsPromise;
+        for (const row of wakeRows) {
+            if (row.issueId)
+                activeIssueIds.add(row.issueId);
+        }
+    }
+    const explicitWaitCandidateIds = [...nodesById.values()]
+        .filter((node) => node.status !== "done")
+        .map((node) => node.id);
+    const explicitWaitingIssueIds = new Set();
+    if (explicitWaitCandidateIds.length > 0) {
+        for (const chunk of chunkList(explicitWaitCandidateIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+            const interactionRows = await dbOrTx
+                .select({ issueId: issueThreadInteractions.issueId })
+                .from(issueThreadInteractions)
+                .where(and(eq(issueThreadInteractions.squadId, squadId), inArray(issueThreadInteractions.status, BLOCKER_ATTENTION_PENDING_INTERACTION_STATUSES), inArray(issueThreadInteractions.issueId, chunk)));
+            for (const row of interactionRows)
+                explicitWaitingIssueIds.add(row.issueId);
+            const approvalRows = await dbOrTx
+                .select({ issueId: issueApprovals.issueId })
+                .from(issueApprovals)
+                .innerJoin(approvals, eq(issueApprovals.approvalId, approvals.id))
+                .where(and(eq(issueApprovals.squadId, squadId), inArray(approvals.status, BLOCKER_ATTENTION_PENDING_APPROVAL_STATUSES), inArray(issueApprovals.issueId, chunk)));
+            for (const row of approvalRows)
+                explicitWaitingIssueIds.add(row.issueId);
+        }
+        // Recovery rows are intentionally squad-wide: a liveness escalation for
+        // the same leaf blocker represents an active waiting path even when that
+        // blocker is reached through another blocked graph.
+        const recoveryRows = await dbOrTx
+            .select({ id: issues.id, originId: issues.originId })
+            .from(issues)
+            .where(and(eq(issues.squadId, squadId), eq(issues.originKind, BLOCKER_ATTENTION_OPEN_RECOVERY_ORIGIN_KIND), isNull(issues.hiddenAt), notInArray(issues.status, BLOCKER_ATTENTION_OPEN_RECOVERY_TERMINAL_STATUSES)));
+        for (const row of recoveryRows) {
+            const parsed = parseIssueGraphLivenessIncidentKey(row.originId);
+            if (!parsed || parsed.squadId !== squadId)
+                continue;
+            explicitWaitingIssueIds.add(row.id);
+            explicitWaitingIssueIds.add(parsed.issueId);
+            explicitWaitingIssueIds.add(parsed.leafIssueId);
+        }
+        const recoveryActionRows = await dbOrTx
+            .select({ sourceIssueId: issueRecoveryActions.sourceIssueId })
+            .from(issueRecoveryActions)
+            .where(and(eq(issueRecoveryActions.squadId, squadId), inArray(issueRecoveryActions.status, ["active", "escalated"]), inArray(issueRecoveryActions.sourceIssueId, explicitWaitCandidateIds)));
+        for (const row of recoveryActionRows)
+            explicitWaitingIssueIds.add(row.sourceIssueId);
+    }
+    const agentRows = agentIds.size > 0
+        ? await dbOrTx
+            .select({
+            id: agents.id,
+            squadId: agents.squadId,
+            status: agents.status,
+        })
+            .from(agents)
+            .where(and(eq(agents.squadId, squadId), inArray(agents.id, [...agentIds])))
+        : [];
+    const agentsById = new Map(agentRows.map((agent) => [agent.id, agent]));
+    const classifyPath = (nodeId, seen) => {
+        const sample = blockerSampleIdentifier(nodesById.get(nodeId));
+        if (truncated || seen.has(nodeId)) {
+            return { covered: false, stalled: false, sampleBlockerIdentifier: sample, sampleStalledBlockerIdentifier: null };
+        }
+        const node = nodesById.get(nodeId);
+        if (!node || node.squadId !== squadId) {
+            return { covered: false, stalled: false, sampleBlockerIdentifier: nodeId, sampleStalledBlockerIdentifier: null };
+        }
+        const nodeSample = blockerSampleIdentifier(node);
+        if (node.status === "done") {
+            return { covered: true, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+        }
+        if (explicitWaitingIssueIds.has(node.id)) {
+            return { covered: true, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+        }
+        if (node.assigneeUserId && node.status !== "cancelled") {
+            return { covered: true, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+        }
+        if (node.status === "in_review") {
+            const hasWaitingPath = activeIssueIds.has(node.id) || Boolean(node.assigneeUserId);
+            if (hasWaitingPath) {
+                return { covered: true, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+            }
+            return { covered: false, stalled: true, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: nodeSample };
+        }
+        if (activeIssueIds.has(node.id)) {
+            return { covered: true, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+        }
+        if (node.status === "cancelled") {
+            return { covered: false, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+        }
+        if (node.status === "backlog" && node.assigneeAgentId) {
+            return { covered: false, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+        }
+        const downstream = (edgesByIssueId.get(node.id) ?? []).filter((edge) => nodesById.get(edge.blockerIssueId)?.status !== "done");
+        if (downstream.length > 0) {
+            const nextSeen = new Set(seen);
+            nextSeen.add(nodeId);
+            const classified = downstream.map((edge) => classifyPath(edge.blockerIssueId, nextSeen));
+            const stalledChild = classified.find((result) => result.stalled || result.sampleStalledBlockerIdentifier);
+            const sampleStalled = stalledChild?.sampleStalledBlockerIdentifier ?? null;
+            const hardAttention = classified.find((result) => !result.covered && !result.stalled);
+            if (hardAttention) {
+                return {
+                    covered: false,
+                    stalled: false,
+                    sampleBlockerIdentifier: hardAttention.sampleBlockerIdentifier,
+                    sampleStalledBlockerIdentifier: sampleStalled,
+                };
+            }
+            const stalledEntry = classified.find((result) => result.stalled);
+            if (stalledEntry) {
+                return {
+                    covered: false,
+                    stalled: true,
+                    sampleBlockerIdentifier: stalledEntry.sampleBlockerIdentifier,
+                    sampleStalledBlockerIdentifier: sampleStalled,
+                };
+            }
+            return {
+                covered: true,
+                stalled: false,
+                sampleBlockerIdentifier: classified[0]?.sampleBlockerIdentifier ?? nodeSample,
+                sampleStalledBlockerIdentifier: null,
+            };
+        }
+        if (node.assigneeAgentId) {
+            const assignee = agentsById.get(node.assigneeAgentId);
+            if (!assignee || assignee.squadId !== squadId || !BLOCKER_ATTENTION_INVOKABLE_AGENT_STATUSES.has(assignee.status)) {
+                return { covered: false, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+            }
+        }
+        return { covered: false, stalled: false, sampleBlockerIdentifier: nodeSample, sampleStalledBlockerIdentifier: null };
+    };
+    for (const root of roots) {
+        const topLevelEdges = (edgesByIssueId.get(root.id) ?? []).filter((edge) => nodesById.get(edge.blockerIssueId)?.status !== "done");
+        if (topLevelEdges.length === 0) {
+            attentionMap.set(root.id, createIssueBlockerAttention({
+                state: "needs_attention",
+                reason: "attention_required",
+            }));
+            continue;
+        }
+        const classified = topLevelEdges.map((edge) => ({
+            edge,
+            result: classifyPath(edge.blockerIssueId, new Set([root.id])),
+        }));
+        const coveredBlockerCount = classified.filter((entry) => entry.result.covered).length;
+        const stalledBlockerCount = classified.filter((entry) => entry.result.stalled).length;
+        const attentionBlockerCount = classified.length - coveredBlockerCount - stalledBlockerCount;
+        const hardAttentionEntry = classified.find((entry) => !entry.result.covered && !entry.result.stalled);
+        const stalledEntry = classified.find((entry) => entry.result.stalled);
+        const sampleEntry = hardAttentionEntry ?? stalledEntry ?? classified[0] ?? null;
+        const sampleNode = sampleEntry ? nodesById.get(sampleEntry.edge.blockerIssueId) : null;
+        const sampleStalledFromChain = classified
+            .map((entry) => entry.result.sampleStalledBlockerIdentifier)
+            .find((value) => value);
+        let state;
+        let reason;
+        if (attentionBlockerCount > 0) {
+            state = "needs_attention";
+            reason = "attention_required";
+        }
+        else if (stalledBlockerCount > 0) {
+            state = "stalled";
+            reason = "stalled_review";
+        }
+        else {
+            state = "covered";
+            reason = topLevelEdges.every((edge) => nodesById.get(edge.blockerIssueId)?.parentId === root.id)
+                ? "active_child"
+                : "active_dependency";
+        }
+        attentionMap.set(root.id, createIssueBlockerAttention({
+            state,
+            reason,
+            unresolvedBlockerCount: topLevelEdges.length,
+            coveredBlockerCount,
+            stalledBlockerCount,
+            attentionBlockerCount,
+            sampleBlockerIdentifier: sampleEntry?.result.sampleBlockerIdentifier ?? blockerSampleIdentifier(sampleNode),
+            sampleStalledBlockerIdentifier: stalledEntry?.result.sampleStalledBlockerIdentifier ?? sampleStalledFromChain ?? null,
+        }));
+    }
+    return attentionMap;
+}
+const issueListSelect = {
+    id: issues.id,
+    squadId: issues.squadId,
+    projectId: issues.projectId,
+    projectWorkspaceId: issues.projectWorkspaceId,
+    goalId: issues.goalId,
+    parentId: issues.parentId,
+    title: issues.title,
+    description: sql `
+    CASE
+      WHEN ${issues.description} IS NULL THEN NULL
+      ELSE encode(
+        substring(
+          convert_to(${issues.description}, current_setting('server_encoding'))
+          FROM 1 FOR ${ISSUE_LIST_DESCRIPTION_MAX_BYTES}
+        ),
+        'base64'
+      )
+    END
+  `,
+    status: issues.status,
+    workMode: issues.workMode,
+    priority: issues.priority,
+    assigneeAgentId: issues.assigneeAgentId,
+    assigneeUserId: issues.assigneeUserId,
+    checkoutRunId: issues.checkoutRunId,
+    executionRunId: issues.executionRunId,
+    executionAgentNameKey: issues.executionAgentNameKey,
+    executionLockedAt: issues.executionLockedAt,
+    createdByAgentId: issues.createdByAgentId,
+    createdByUserId: issues.createdByUserId,
+    issueNumber: issues.issueNumber,
+    identifier: issues.identifier,
+    originKind: issues.originKind,
+    originId: issues.originId,
+    originRunId: issues.originRunId,
+    originFingerprint: issues.originFingerprint,
+    requestDepth: issues.requestDepth,
+    billingCode: issues.billingCode,
+    assigneeAdapterOverrides: issues.assigneeAdapterOverrides,
+    executionPolicy: sql `null`,
+    executionState: sql `null`,
+    monitorNextCheckAt: issues.monitorNextCheckAt,
+    monitorWakeRequestedAt: issues.monitorWakeRequestedAt,
+    monitorLastTriggeredAt: issues.monitorLastTriggeredAt,
+    monitorAttemptCount: issues.monitorAttemptCount,
+    monitorNotes: issues.monitorNotes,
+    monitorScheduledBy: issues.monitorScheduledBy,
+    executionWorkspaceId: issues.executionWorkspaceId,
+    executionWorkspacePreference: issues.executionWorkspacePreference,
+    executionWorkspaceSettings: sql `null`,
+    startedAt: issues.startedAt,
+    completedAt: issues.completedAt,
+    cancelledAt: issues.cancelledAt,
+    hiddenAt: issues.hiddenAt,
+    createdAt: issues.createdAt,
+    updatedAt: issues.updatedAt,
+};
+function withActiveRuns(issueRows, runMap) {
+    return issueRows.map((row) => ({
+        ...row,
+        activeRun: row.executionRunId ? (runMap.get(row.executionRunId) ?? null) : null,
+    }));
+}
+async function userCommentStatsForIssues(dbOrTx, squadId, userId, issueIds) {
+    const stats = [];
+    for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const rows = await dbOrTx
+            .select({
+            issueId: issueComments.issueId,
+            myLastCommentAt: sql `
+          MAX(CASE WHEN ${issueComments.authorUserId} = ${userId} THEN ${issueComments.createdAt} END)
+        `,
+            lastExternalCommentAt: sql `
+          MAX(
+            CASE
+              WHEN ${issueComments.authorUserId} IS NULL OR ${issueComments.authorUserId} <> ${userId}
+              THEN ${issueComments.createdAt}
+            END
+          )
+        `,
+        })
+            .from(issueComments)
+            .where(and(eq(issueComments.squadId, squadId), inArray(issueComments.issueId, issueIdChunk)))
+            .groupBy(issueComments.issueId);
+        stats.push(...rows);
+    }
+    return stats;
+}
+async function userReadStatsForIssues(dbOrTx, squadId, userId, issueIds) {
+    const stats = [];
+    for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const rows = await dbOrTx
+            .select({
+            issueId: issueReadStates.issueId,
+            myLastReadAt: issueReadStates.lastReadAt,
+        })
+            .from(issueReadStates)
+            .where(and(eq(issueReadStates.squadId, squadId), eq(issueReadStates.userId, userId), inArray(issueReadStates.issueId, issueIdChunk)));
+        stats.push(...rows);
+    }
+    return stats;
+}
+async function lastActivityStatsForIssues(dbOrTx, squadId, issueIds) {
+    const byIssueId = new Map();
+    for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const [commentRows, logRows] = await Promise.all([
+            dbOrTx
+                .select({
+                issueId: issueComments.issueId,
+                latestCommentAt: sql `MAX(${issueComments.createdAt})`,
+            })
+                .from(issueComments)
+                .where(and(eq(issueComments.squadId, squadId), inArray(issueComments.issueId, issueIdChunk)))
+                .groupBy(issueComments.issueId),
+            dbOrTx
+                .select({
+                issueId: activityLog.entityId,
+                latestLogAt: sql `MAX(${activityLog.createdAt})`,
+            })
+                .from(activityLog)
+                .where(and(eq(activityLog.squadId, squadId), eq(activityLog.entityType, "issue"), inArray(activityLog.entityId, issueIdChunk), sql `${activityLog.action} NOT IN (${sql.join(ISSUE_LOCAL_INBOX_ACTIVITY_ACTIONS.map((action) => sql `${action}`), sql `, `)})`))
+                .groupBy(activityLog.entityId),
+        ]);
+        for (const row of commentRows) {
+            byIssueId.set(row.issueId, {
+                issueId: row.issueId,
+                latestCommentAt: row.latestCommentAt,
+                latestLogAt: null,
+            });
+        }
+        for (const row of logRows) {
+            const existing = byIssueId.get(row.issueId);
+            if (existing)
+                existing.latestLogAt = row.latestLogAt;
+            else {
+                byIssueId.set(row.issueId, {
+                    issueId: row.issueId,
+                    latestCommentAt: null,
+                    latestLogAt: row.latestLogAt,
+                });
+            }
+        }
+    }
+    return [...byIssueId.values()];
+}
+async function blockedByMapForIssues(dbOrTx, squadId, issueIds) {
+    const map = new Map();
+    const uniqueIssueIds = [...new Set(issueIds)];
+    if (uniqueIssueIds.length === 0)
+        return map;
+    for (const issueId of uniqueIssueIds) {
+        map.set(issueId, []);
+    }
+    for (const issueIdChunk of chunkList(uniqueIssueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const rows = await dbOrTx
+            .select({
+            currentIssueId: issueRelations.relatedIssueId,
+            relatedId: issues.id,
+            identifier: issues.identifier,
+            title: issues.title,
+            status: issues.status,
+            priority: issues.priority,
+            assigneeAgentId: issues.assigneeAgentId,
+            assigneeUserId: issues.assigneeUserId,
+        })
+            .from(issueRelations)
+            .innerJoin(issues, eq(issueRelations.issueId, issues.id))
+            .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks"), inArray(issueRelations.relatedIssueId, issueIdChunk)));
+        for (const row of rows) {
+            const blockedBy = map.get(row.currentIssueId);
+            if (!blockedBy)
+                continue;
+            blockedBy.push({
+                id: row.relatedId,
+                identifier: row.identifier,
+                title: row.title,
+                status: row.status,
+                priority: row.priority,
+                assigneeAgentId: row.assigneeAgentId,
+                assigneeUserId: row.assigneeUserId,
+            });
+        }
+    }
+    for (const blockedBy of map.values()) {
+        blockedBy.sort((a, b) => a.title.localeCompare(b.title));
+    }
+    return map;
+}
+const BLOCKED_INBOX_TERMINAL_STATUSES = ["done", "cancelled"];
+const BLOCKED_INBOX_ACTIVE_RUN_STATUSES = ["queued", "running"];
+const BLOCKED_INBOX_ACTIVE_WAKE_STATUSES = ["queued", "deferred_issue_execution"];
+const BLOCKED_INBOX_PENDING_INTERACTION_STATUSES = ["pending"];
+const BLOCKED_INBOX_PENDING_APPROVAL_STATUSES = ["pending", "revision_requested"];
+const BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS = ["harness_liveness_escalation", "stranded_issue_recovery"];
+const BLOCKED_INBOX_SUCCESSFUL_RUN_HANDOFF_ACTIONS = [
+    "issue.successful_run_handoff_required",
+    "issue.successful_run_handoff_resolved",
+    "issue.successful_run_handoff_escalated",
+];
+function issueRef(row) {
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        identifier: row.identifier,
+        title: row.title,
+        status: row.status,
+        priority: row.priority,
+        assigneeAgentId: row.assigneeAgentId,
+        assigneeUserId: row.assigneeUserId,
+    };
+}
+function isoDate(value) {
+    if (!value)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function attentionBase(input) {
+    return {
+        kind: "blocked",
+        state: input.state,
+        reason: input.reason,
+        severity: input.severity,
+        stoppedSinceAt: isoDate(input.stoppedSinceAt),
+        owner: input.owner,
+        action: input.action,
+        sourceIssue: input.sourceIssue,
+        leafIssue: input.leafIssue ?? null,
+        recoveryIssue: input.recoveryIssue ?? null,
+        approvalId: input.approvalId ?? null,
+        interactionId: input.interactionId ?? null,
+        sampleIssueIdentifier: input.sampleIssueIdentifier
+            ?? input.leafIssue?.identifier
+            ?? input.recoveryIssue?.identifier
+            ?? input.sourceIssue?.identifier
+            ?? null,
+        redaction: {
+            externalDetailsRedacted: input.externalDetailsRedacted ?? false,
+            secretFieldsOmitted: true,
+        },
+    };
+}
+function readSuccessfulRunHandoffFromActivity(row) {
+    const details = row.details ?? {};
+    const state = row.action === "issue.successful_run_handoff_required"
+        ? "required"
+        : row.action === "issue.successful_run_handoff_resolved"
+            ? "resolved"
+            : row.action === "issue.successful_run_handoff_escalated"
+                ? "escalated"
+                : null;
+    if (!state)
+        return null;
+    const detectedProgressSummary = readStringFromRecord(details, "detectedProgressSummary")
+        ?? readStringFromRecord(details, "detected_progress_summary")
+        ?? null;
+    return {
+        state,
+        required: state === "required",
+        sourceRunId: readStringFromRecord(details, "sourceRunId")
+            ?? readStringFromRecord(details, "source_run_id")
+            ?? readStringFromRecord(details, "resumeFromRunId")
+            ?? row.runId
+            ?? null,
+        correctiveRunId: readStringFromRecord(details, "correctiveRunId")
+            ?? readStringFromRecord(details, "corrective_run_id")
+            ?? (state !== "required" ? row.runId : null),
+        assigneeAgentId: readStringFromRecord(details, "assigneeAgentId")
+            ?? readStringFromRecord(details, "agentId")
+            ?? row.agentId
+            ?? null,
+        detectedProgressSummary: detectedProgressSummary ? redactSensitiveText(detectedProgressSummary) : null,
+        createdAt: row.createdAt,
+    };
+}
+async function listSuccessfulRunHandoffMapForIssues(dbOrTx, squadId, issueIds) {
+    const uniqueIssueIds = [...new Set(issueIds)];
+    const states = new Map();
+    if (uniqueIssueIds.length === 0)
+        return states;
+    for (const issueIdChunk of chunkList(uniqueIssueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+        const rows = await dbOrTx
+            .select({
+            entityId: activityLog.entityId,
+            action: activityLog.action,
+            agentId: activityLog.agentId,
+            runId: activityLog.runId,
+            details: activityLog.details,
+            createdAt: activityLog.createdAt,
+        })
+            .from(activityLog)
+            .where(and(eq(activityLog.squadId, squadId), eq(activityLog.entityType, "issue"), inArray(activityLog.entityId, issueIdChunk), inArray(activityLog.action, [...BLOCKED_INBOX_SUCCESSFUL_RUN_HANDOFF_ACTIONS])))
+            .orderBy(activityLog.entityId, desc(activityLog.createdAt), desc(activityLog.id));
+        for (const row of rows) {
+            if (states.has(row.entityId))
+                continue;
+            const state = readSuccessfulRunHandoffFromActivity(row);
+            if (state)
+                states.set(row.entityId, state);
+        }
+    }
+    return states;
+}
+function externalWaitFromDescription(description) {
+    if (!description)
+        return null;
+    const owner = description.match(/^\s*external owner\s*:\s*(.+)$/im)?.[1]?.trim();
+    const action = description.match(/^\s*external action\s*:\s*(.+)$/im)?.[1]?.trim();
+    if (!owner || !action)
+        return null;
+    return {
+        owner: owner.slice(0, 120),
+        action: action.slice(0, 240),
+    };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function redactExternalWaitDescription(description, external) {
+    if (!description)
+        return null;
+    let redacted = description
+        .split(/\r?\n/)
+        .filter((line) => !/^\s*external\s+(?:owner|action)\s*:/i.test(line))
+        .join("\n");
+    for (const value of [external?.owner, external?.action]) {
+        if (!value)
+            continue;
+        redacted = redacted.replace(new RegExp(escapeRegExp(value), "gi"), "[redacted external wait detail]");
+    }
+    redacted = redacted.replace(/\n{3,}/g, "\n\n").trim();
+    return redacted.length > 0 ? redacted : null;
+}
+function blockedInboxResponseDescription(attention, row) {
+    if (!attention.redaction.externalDetailsRedacted)
+        return row.description;
+    return redactExternalWaitDescription(row.description, externalWaitFromDescription(row.description));
+}
+function blockedInboxSearchText(attention, row) {
+    return [
+        row.identifier,
+        row.title,
+        blockedInboxResponseDescription(attention, row),
+        attention.sourceIssue?.identifier,
+        attention.sourceIssue?.title,
+        attention.leafIssue?.identifier,
+        attention.leafIssue?.title,
+        attention.recoveryIssue?.identifier,
+        attention.recoveryIssue?.title,
+        attention.action.label,
+        attention.action.detail,
+    ]
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .join(" ")
+        .toLowerCase();
+}
+function blockedInboxSeverityRank(severity) {
+    switch (severity) {
+        case "critical":
+            return 0;
+        case "high":
+            return 1;
+        case "medium":
+            return 2;
+        case "low":
+            return 3;
+    }
+}
+function issuePriorityRank(priority) {
+    switch (priority) {
+        case "critical":
+            return 0;
+        case "high":
+            return 1;
+        case "medium":
+            return 2;
+        case "low":
+            return 3;
+        default:
+            return 4;
+    }
+}
+function compareBlockedInboxRows(left, right) {
+    const leftAttention = left.blockedInboxAttention;
+    const rightAttention = right.blockedInboxAttention;
+    const severity = blockedInboxSeverityRank(leftAttention.severity)
+        - blockedInboxSeverityRank(rightAttention.severity);
+    if (severity !== 0)
+        return severity;
+    const leftStopped = leftAttention.stoppedSinceAt
+        ? new Date(leftAttention.stoppedSinceAt).getTime()
+        : Number.POSITIVE_INFINITY;
+    const rightStopped = rightAttention.stoppedSinceAt
+        ? new Date(rightAttention.stoppedSinceAt).getTime()
+        : Number.POSITIVE_INFINITY;
+    if (leftStopped !== rightStopped)
+        return leftStopped - rightStopped;
+    const priority = issuePriorityRank(left.priority) - issuePriorityRank(right.priority);
+    if (priority !== 0)
+        return priority;
+    const leftActivity = left.lastActivityAt ? new Date(left.lastActivityAt).getTime() : new Date(left.updatedAt).getTime();
+    const rightActivity = right.lastActivityAt ? new Date(right.lastActivityAt).getTime() : new Date(right.updatedAt).getTime();
+    if (leftActivity !== rightActivity)
+        return rightActivity - leftActivity;
+    return right.id.localeCompare(left.id);
+}
+async function listIssueBlockedInboxAttentionMap(dbOrTx, squadId, issueRows) {
+    const rowIssueIds = [...new Set(issueRows.map((row) => row.id))];
+    const result = new Map();
+    if (rowIssueIds.length === 0)
+        return result;
+    const [graphIssueRows, graphRelationRows, squadAgentRows] = await Promise.all([
+        dbOrTx
+            .select()
+            .from(issues)
+            .where(and(eq(issues.squadId, squadId), isNull(issues.hiddenAt), notInArray(issues.status, [...BLOCKED_INBOX_TERMINAL_STATUSES]))),
+        dbOrTx
+            .select({
+            squadId: issueRelations.squadId,
+            blockerIssueId: issueRelations.issueId,
+            blockedIssueId: issueRelations.relatedIssueId,
+        })
+            .from(issueRelations)
+            .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks"))),
+        dbOrTx
+            .select({
+            id: agents.id,
+            squadId: agents.squadId,
+            name: agents.name,
+            role: agents.role,
+            title: agents.title,
+            status: agents.status,
+            reportsTo: agents.reportsTo,
+        })
+            .from(agents)
+            .where(eq(agents.squadId, squadId)),
+    ]);
+    const graphIssues = graphIssueRows;
+    const graphRelations = graphRelationRows;
+    const squadAgents = squadAgentRows;
+    const graphIssueIds = graphIssues.map((issue) => issue.id);
+    const issuesById = new Map(graphIssues.map((issue) => [issue.id, issue]));
+    const [activeRunRows, wakeRows, scheduledRetryRows, interactionRows, approvalRows, handoffMap] = await Promise.all([
+        graphIssueIds.length === 0
+            ? Promise.resolve([])
+            : dbOrTx
+                .select({
+                squadId: heartbeatRuns.squadId,
+                issueId: sql `${heartbeatRuns.contextSnapshot} ->> 'issueId'`,
+                agentId: heartbeatRuns.agentId,
+                status: heartbeatRuns.status,
+            })
+                .from(heartbeatRuns)
+                .where(and(eq(heartbeatRuns.squadId, squadId), inArray(heartbeatRuns.status, [...BLOCKED_INBOX_ACTIVE_RUN_STATUSES]), inArray(sql `${heartbeatRuns.contextSnapshot} ->> 'issueId'`, graphIssueIds))),
+        graphIssueIds.length === 0
+            ? Promise.resolve([])
+            : dbOrTx
+                .select({
+                squadId: agentWakeupRequests.squadId,
+                issueId: sql `${agentWakeupRequests.payload} ->> 'issueId'`,
+                agentId: agentWakeupRequests.agentId,
+                status: agentWakeupRequests.status,
+            })
+                .from(agentWakeupRequests)
+                .where(and(eq(agentWakeupRequests.squadId, squadId), inArray(agentWakeupRequests.status, [...BLOCKED_INBOX_ACTIVE_WAKE_STATUSES]), sql `${agentWakeupRequests.runId} is null`, inArray(sql `${agentWakeupRequests.payload} ->> 'issueId'`, graphIssueIds))),
+        graphIssueIds.length === 0
+            ? Promise.resolve([])
+            : dbOrTx
+                .select({
+                squadId: heartbeatRuns.squadId,
+                issueId: sql `${heartbeatRuns.contextSnapshot} ->> 'issueId'`,
+                agentId: heartbeatRuns.agentId,
+                status: heartbeatRuns.status,
+            })
+                .from(heartbeatRuns)
+                .where(and(eq(heartbeatRuns.squadId, squadId), eq(heartbeatRuns.status, "scheduled_retry"), inArray(sql `${heartbeatRuns.contextSnapshot} ->> 'issueId'`, graphIssueIds))),
+        graphIssueIds.length === 0
+            ? Promise.resolve([])
+            : dbOrTx
+                .select({
+                id: issueThreadInteractions.id,
+                issueId: issueThreadInteractions.issueId,
+                kind: issueThreadInteractions.kind,
+                createdAt: issueThreadInteractions.createdAt,
+            })
+                .from(issueThreadInteractions)
+                .where(and(eq(issueThreadInteractions.squadId, squadId), inArray(issueThreadInteractions.status, [...BLOCKED_INBOX_PENDING_INTERACTION_STATUSES]), inArray(issueThreadInteractions.issueId, graphIssueIds))),
+        graphIssueIds.length === 0
+            ? Promise.resolve([])
+            : dbOrTx
+                .select({
+                approvalId: approvals.id,
+                issueId: issueApprovals.issueId,
+                createdAt: approvals.createdAt,
+            })
+                .from(issueApprovals)
+                .innerJoin(approvals, eq(issueApprovals.approvalId, approvals.id))
+                .where(and(eq(issueApprovals.squadId, squadId), eq(approvals.squadId, squadId), inArray(approvals.status, [...BLOCKED_INBOX_PENDING_APPROVAL_STATUSES]), inArray(issueApprovals.issueId, graphIssueIds))),
+        listSuccessfulRunHandoffMapForIssues(dbOrTx, squadId, rowIssueIds),
+    ]);
+    const pendingInteractions = interactionRows.map((row) => ({
+        squadId,
+        issueId: row.issueId,
+        status: "pending",
+    }));
+    const pendingApprovals = approvalRows.map((row) => ({
+        squadId,
+        issueId: row.issueId,
+        status: "pending",
+    }));
+    const openRecoveryIssues = graphIssues
+        .filter((issue) => BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS.includes(issue.originKind))
+        .flatMap((issue) => {
+        const entries = [{ squadId, issueId: issue.id, status: issue.status }];
+        if (issue.originKind === "harness_liveness_escalation") {
+            const parsed = parseIssueGraphLivenessIncidentKey(issue.originId);
+            if (parsed?.squadId === squadId) {
+                entries.push({ squadId, issueId: parsed.issueId, status: issue.status });
+                entries.push({ squadId, issueId: parsed.leafIssueId, status: issue.status });
+            }
+        }
+        else if (issue.originKind === "stranded_issue_recovery" && issue.originId) {
+            entries.push({ squadId, issueId: issue.originId, status: issue.status });
+        }
+        return entries;
+    });
+    const findings = classifyIssueGraphLiveness({
+        issues: graphIssues.map((issue) => ({
+            id: issue.id,
+            squadId: issue.squadId,
+            identifier: issue.identifier,
+            title: issue.title,
+            status: issue.status,
+            projectId: issue.projectId,
+            goalId: issue.goalId,
+            parentId: issue.parentId,
+            assigneeAgentId: issue.assigneeAgentId,
+            assigneeUserId: issue.assigneeUserId,
+            createdByAgentId: issue.createdByAgentId,
+            createdByUserId: issue.createdByUserId,
+            executionPolicy: issue.executionPolicy,
+            executionState: issue.executionState,
+            monitorNextCheckAt: issue.monitorNextCheckAt,
+            monitorAttemptCount: issue.monitorAttemptCount,
+        })),
+        relations: graphRelations,
+        agents: squadAgents,
+        activeRuns: activeRunRows
+            .flatMap((row) => row.issueId
+            ? [{ squadId: row.squadId, issueId: row.issueId, agentId: row.agentId, status: row.status }]
+            : []),
+        queuedWakeRequests: [
+            ...wakeRows,
+            ...scheduledRetryRows,
+        ]
+            .flatMap((row) => row.issueId
+            ? [{ squadId: row.squadId, issueId: row.issueId, agentId: row.agentId, status: row.status }]
+            : []),
+        pendingInteractions,
+        pendingApprovals,
+        openRecoveryIssues,
+        now: new Date(),
+    });
+    const findingByIssueId = new Map();
+    for (const finding of findings) {
+        if (!findingByIssueId.has(finding.issueId))
+            findingByIssueId.set(finding.issueId, finding);
+    }
+    const interactionByIssueId = new Map();
+    for (const row of interactionRows) {
+        if (!interactionByIssueId.has(row.issueId))
+            interactionByIssueId.set(row.issueId, row);
+    }
+    const approvalByIssueId = new Map();
+    for (const row of approvalRows) {
+        if (!approvalByIssueId.has(row.issueId))
+            approvalByIssueId.set(row.issueId, row);
+    }
+    for (const row of issueRows) {
+        if (row.squadId !== squadId || BLOCKED_INBOX_TERMINAL_STATUSES.includes(row.status) || row.hiddenAt) {
+            continue;
+        }
+        const source = issueRef(row);
+        const handoff = handoffMap.get(row.id);
+        if (handoff && (handoff.required || handoff.state === "escalated")) {
+            result.set(row.id, attentionBase({
+                state: "missing_disposition",
+                reason: "missing_successful_run_disposition",
+                severity: "high",
+                stoppedSinceAt: handoff.createdAt ?? row.updatedAt,
+                owner: {
+                    type: row.assigneeAgentId ? "agent" : row.assigneeUserId ? "user" : "unknown",
+                    agentId: row.assigneeAgentId,
+                    userId: row.assigneeUserId,
+                    label: null,
+                },
+                action: {
+                    label: "Choose disposition",
+                    detail: "Choose exactly one final disposition: done, cancelled, review/input, blocked with owner, delegated follow-up, or queued continuation.",
+                },
+                sourceIssue: source,
+            }));
+            continue;
+        }
+        if (BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS.includes(row.originKind)) {
+            let sourceIssue = null;
+            let leafIssue = null;
+            if (row.originKind === "harness_liveness_escalation") {
+                const parsed = parseIssueGraphLivenessIncidentKey(row.originId);
+                if (parsed?.squadId === squadId) {
+                    sourceIssue = issueRef(issuesById.get(parsed.issueId));
+                    leafIssue = issueRef(issuesById.get(parsed.leafIssueId));
+                }
+            }
+            else if (row.originKind === "stranded_issue_recovery" && row.originId) {
+                sourceIssue = issueRef(issuesById.get(row.originId));
+            }
+            result.set(row.id, attentionBase({
+                state: "recovery_open",
+                reason: "open_recovery_issue",
+                severity: "high",
+                stoppedSinceAt: row.createdAt,
+                owner: {
+                    type: row.assigneeAgentId ? "agent" : row.assigneeUserId ? "user" : "unknown",
+                    agentId: row.assigneeAgentId,
+                    userId: row.assigneeUserId,
+                    label: null,
+                },
+                action: {
+                    label: "Resolve recovery",
+                    detail: "Restore a live path for the source work or record why this recovery issue is a false positive.",
+                },
+                sourceIssue: sourceIssue ?? source,
+                leafIssue,
+                recoveryIssue: source,
+            }));
+            continue;
+        }
+        const interaction = interactionByIssueId.get(row.id);
+        if (interaction) {
+            const isUserQuestion = interaction.kind === "ask_user_questions" && Boolean(row.assigneeUserId);
+            result.set(row.id, attentionBase({
+                state: "awaiting_decision",
+                reason: isUserQuestion ? "pending_user_decision" : "pending_operator_decision",
+                severity: "medium",
+                stoppedSinceAt: interaction.createdAt,
+                owner: isUserQuestion
+                    ? { type: "user", agentId: null, userId: row.assigneeUserId, label: null }
+                    : { type: "operator", agentId: null, userId: null, label: "Operator" },
+                action: {
+                    label: isUserQuestion ? "Answer question" : "Answer confirmation",
+                    detail: "Respond to the pending issue-thread interaction so the assignee has a live next action.",
+                },
+                sourceIssue: source,
+                interactionId: interaction.id,
+            }));
+            continue;
+        }
+        const approval = approvalByIssueId.get(row.id);
+        if (approval) {
+            result.set(row.id, attentionBase({
+                state: "awaiting_decision",
+                reason: "pending_operator_decision",
+                severity: "medium",
+                stoppedSinceAt: approval.createdAt,
+                owner: { type: "operator", agentId: null, userId: null, label: "Operator" },
+                action: {
+                    label: "Decide approval",
+                    detail: "Approve, reject, or request revision on the linked approval.",
+                },
+                sourceIssue: source,
+                approvalId: approval.approvalId,
+            }));
+            continue;
+        }
+        const finding = findingByIssueId.get(row.id);
+        if (finding) {
+            const leaf = finding.dependencyPath.length > 1
+                ? issuesById.get(finding.dependencyPath[finding.dependencyPath.length - 1].issueId)
+                : issuesById.get(finding.recoveryIssueId);
+            const ownerAgentId = finding.state === "blocked_by_unassigned_issue"
+                ? null
+                : finding.recommendedOwnerAgentId ?? row.assigneeAgentId ?? leaf?.assigneeAgentId ?? null;
+            result.set(row.id, attentionBase({
+                state: "needs_attention",
+                reason: finding.state,
+                severity: finding.state === "blocked_by_assigned_backlog_issue"
+                    || finding.state === "in_review_without_action_path"
+                    ? "high"
+                    : finding.severity === "critical" ? "critical" : "high",
+                stoppedSinceAt: leaf?.updatedAt ?? row.updatedAt,
+                owner: {
+                    type: ownerAgentId ? "agent" : leaf?.assigneeUserId ? "user" : "unknown",
+                    agentId: ownerAgentId,
+                    userId: leaf?.assigneeUserId ?? null,
+                    label: null,
+                },
+                action: {
+                    label: (() => {
+                        switch (finding.state) {
+                            case "blocked_by_unassigned_issue":
+                                return "Assign blocker";
+                            case "blocked_by_assigned_backlog_issue":
+                                return "Resume parked blocker";
+                            case "blocked_by_uninvokable_assignee":
+                                return "Assign active owner";
+                            case "blocked_by_cancelled_issue":
+                                return "Replace blocker";
+                            case "invalid_review_participant":
+                                return "Repair review participant";
+                            case "in_review_without_action_path":
+                                return "Choose review path";
+                        }
+                    })(),
+                    detail: finding.recommendedAction,
+                },
+                sourceIssue: source,
+                leafIssue: issueRef(leaf),
+                recoveryIssue: issueRef(issuesById.get(finding.recoveryIssueId)),
+                sampleIssueIdentifier: leaf?.identifier ?? finding.identifier,
+            }));
+            continue;
+        }
+        const hasMonitor = Boolean(row.monitorNextCheckAt && row.monitorNextCheckAt.getTime() > Date.now());
+        const external = row.status === "blocked" && !hasMonitor ? externalWaitFromDescription(row.description) : null;
+        if (external) {
+            result.set(row.id, attentionBase({
+                state: "external_wait",
+                reason: "external_owner_action",
+                severity: "medium",
+                stoppedSinceAt: row.updatedAt,
+                owner: { type: "external", agentId: null, userId: null, label: null },
+                action: {
+                    label: "External owner action",
+                    detail: null,
+                },
+                sourceIssue: source,
+                externalDetailsRedacted: true,
+            }));
+            continue;
+        }
+        const blockerAttention = await listIssueBlockerAttentionMap(dbOrTx, squadId, [row]);
+        const blockerState = blockerAttention.get(row.id);
+        if (row.status === "blocked" && (blockerState?.state === "needs_attention" || blockerState?.state === "stalled")) {
+            result.set(row.id, attentionBase({
+                state: "needs_attention",
+                reason: "blocked_chain_stalled",
+                severity: "high",
+                stoppedSinceAt: row.updatedAt,
+                owner: { type: "unknown", agentId: null, userId: null, label: null },
+                action: {
+                    label: "Inspect blocker chain",
+                    detail: "Inspect the stalled blocker or review leaf and make the next owner/action explicit.",
+                },
+                sourceIssue: source,
+                sampleIssueIdentifier: blockerState.sampleStalledBlockerIdentifier ?? blockerState.sampleBlockerIdentifier,
+            }));
+        }
+    }
+    return result;
+}
+async function blockedInboxIssueConditions(dbOrTx, squadId, filters) {
+    const conditions = [
+        eq(issues.squadId, squadId),
+        isNull(issues.hiddenAt),
+        notInArray(issues.status, [...BLOCKED_INBOX_TERMINAL_STATUSES]),
+    ];
+    const touchedByUserId = filters?.touchedByUserId?.trim() || undefined;
+    const inboxArchivedByUserId = filters?.inboxArchivedByUserId?.trim() || undefined;
+    const unreadForUserId = filters?.unreadForUserId?.trim() || undefined;
+    const contextUserId = unreadForUserId ?? touchedByUserId ?? inboxArchivedByUserId;
+    if (filters?.descendantOf) {
+        conditions.push(sql `
+      ${issues.id} IN (
+        WITH RECURSIVE descendants(id) AS (
+          SELECT ${issues.id}
+          FROM ${issues}
+          WHERE ${issues.squadId} = ${squadId}
+            AND ${issues.parentId} = ${filters.descendantOf}
+          UNION
+          SELECT ${issues.id}
+          FROM ${issues}
+          JOIN descendants ON ${issues.parentId} = descendants.id
+          WHERE ${issues.squadId} = ${squadId}
+        )
+        SELECT id FROM descendants
+      )
+    `);
+    }
+    if (filters?.status) {
+        const statuses = filters.status.split(",").map((status) => status.trim()).filter(Boolean);
+        if (statuses.length > 0) {
+            conditions.push(statuses.length === 1 ? eq(issues.status, statuses[0]) : inArray(issues.status, statuses));
+        }
+    }
+    if (filters?.assigneeAgentId)
+        conditions.push(eq(issues.assigneeAgentId, filters.assigneeAgentId));
+    if (filters?.participantAgentId)
+        conditions.push(participatedByAgentCondition(squadId, filters.participantAgentId));
+    if (filters?.assigneeUserId)
+        conditions.push(eq(issues.assigneeUserId, filters.assigneeUserId));
+    if (touchedByUserId)
+        conditions.push(touchedByUserCondition(squadId, touchedByUserId));
+    if (inboxArchivedByUserId)
+        conditions.push(inboxVisibleForUserCondition(squadId, inboxArchivedByUserId));
+    if (unreadForUserId)
+        conditions.push(unreadForUserCondition(squadId, unreadForUserId));
+    if (filters?.projectId)
+        conditions.push(eq(issues.projectId, filters.projectId));
+    if (filters?.workspaceId) {
+        conditions.push(or(eq(issues.executionWorkspaceId, filters.workspaceId), eq(issues.projectWorkspaceId, filters.workspaceId)));
+    }
+    if (filters?.executionWorkspaceId)
+        conditions.push(eq(issues.executionWorkspaceId, filters.executionWorkspaceId));
+    if (filters?.parentId)
+        conditions.push(eq(issues.parentId, filters.parentId));
+    if (filters?.originKind)
+        conditions.push(eq(issues.originKind, filters.originKind));
+    if (filters?.originKindPrefix)
+        conditions.push(like(issues.originKind, `${filters.originKindPrefix}%`));
+    if (filters?.originId)
+        conditions.push(eq(issues.originId, filters.originId));
+    if (!shouldIncludePluginOperationIssues(filters))
+        conditions.push(nonPluginOperationIssueCondition());
+    if (filters?.labelId) {
+        const labeledIssueIds = await dbOrTx
+            .select({ issueId: issueLabels.issueId })
+            .from(issueLabels)
+            .where(and(eq(issueLabels.squadId, squadId), eq(issueLabels.labelId, filters.labelId)));
+        if (labeledIssueIds.length === 0)
+            return { conditions: [sql `false`], contextUserId };
+        conditions.push(inArray(issues.id, labeledIssueIds.map((row) => row.issueId)));
+    }
+    if (filters?.excludeRoutineExecutions && !filters?.originKind && !filters?.originId) {
+        conditions.push(ne(issues.originKind, "routine_execution"));
+    }
+    return { conditions, contextUserId };
+}
+async function listBlockedInboxIssues(dbOrTx, squadId, filters) {
+    const { conditions, contextUserId } = await blockedInboxIssueConditions(dbOrTx, squadId, filters);
+    const rows = (await dbOrTx
+        .select(issueListSelect)
+        .from(issues)
+        .where(and(...conditions))
+        .orderBy(desc(issueCanonicalLastActivityAtExpr(squadId)), desc(issues.updatedAt), desc(issues.id)))
+        .map((row) => ({
+        ...row,
+        description: decodeDatabaseTextPreview(row.description, ISSUE_LIST_DESCRIPTION_MAX_CHARS),
+    }));
+    const withLabels = await withIssueLabels(dbOrTx, rows);
+    const withRuns = withActiveRuns(withLabels, await activeRunMapForIssues(dbOrTx, withLabels));
+    if (withRuns.length === 0)
+        return [];
+    const issueIds = withRuns.map((row) => row.id);
+    const [statsRows, readRows, lastActivityRows, blockedByMap, blockerAttentionByIssueId, productivityReviewByIssueId, blockedInboxAttentionByIssueId,] = await Promise.all([
+        contextUserId ? userCommentStatsForIssues(dbOrTx, squadId, contextUserId, issueIds) : Promise.resolve([]),
+        contextUserId ? userReadStatsForIssues(dbOrTx, squadId, contextUserId, issueIds) : Promise.resolve([]),
+        lastActivityStatsForIssues(dbOrTx, squadId, issueIds),
+        blockedByMapForIssues(dbOrTx, squadId, issueIds),
+        listIssueBlockerAttentionMap(dbOrTx, squadId, withRuns),
+        listIssueProductivityReviewMap(dbOrTx, squadId, issueIds),
+        listIssueBlockedInboxAttentionMap(dbOrTx, squadId, withRuns),
+    ]);
+    const rawSearchInput = filters?.q?.trim() ?? "";
+    const rawSearch = rawSearchInput.toLowerCase();
+    const commentSearchMatchIssueIds = new Set();
+    if (rawSearchInput) {
+        const containsPattern = `%${escapeLikePattern(rawSearchInput)}%`;
+        for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+            const rows = await dbOrTx
+                .select({ issueId: issueComments.issueId })
+                .from(issueComments)
+                .where(and(eq(issueComments.squadId, squadId), inArray(issueComments.issueId, issueIdChunk), sql `${issueComments.body} ILIKE ${containsPattern} ESCAPE '\\'`));
+            for (const row of rows)
+                commentSearchMatchIssueIds.add(row.issueId);
+        }
+    }
+    const statsByIssueId = new Map(statsRows.map((row) => [row.issueId, row]));
+    const readByIssueId = new Map(readRows.map((row) => [row.issueId, row.myLastReadAt]));
+    const lastActivityByIssueId = new Map(lastActivityRows.map((row) => [row.issueId, row]));
+    const enriched = withRuns.flatMap((row) => {
+        const blockedInboxAttention = blockedInboxAttentionByIssueId.get(row.id);
+        if (!blockedInboxAttention)
+            return [];
+        if (rawSearch
+            && !blockedInboxSearchText(blockedInboxAttention, row).includes(rawSearch)
+            && !commentSearchMatchIssueIds.has(row.id))
+            return [];
+        const activity = lastActivityByIssueId.get(row.id);
+        const lastActivityAt = latestIssueActivityAt(row.updatedAt, activity?.latestCommentAt ?? null, activity?.latestLogAt ?? null) ?? row.updatedAt;
+        return [{
+                ...row,
+                description: blockedInboxResponseDescription(blockedInboxAttention, row),
+                blockedBy: blockedByMap.get(row.id) ?? [],
+                lastActivityAt,
+                ...(blockerAttentionByIssueId.has(row.id) ? { blockerAttention: blockerAttentionByIssueId.get(row.id) } : {}),
+                blockedInboxAttention,
+                ...(productivityReviewByIssueId.has(row.id)
+                    ? { productivityReview: productivityReviewByIssueId.get(row.id) }
+                    : {}),
+                ...(contextUserId
+                    ? deriveIssueUserContext(row, contextUserId, {
+                        myLastCommentAt: statsByIssueId.get(row.id)?.myLastCommentAt ?? null,
+                        myLastReadAt: readByIssueId.get(row.id) ?? null,
+                        lastExternalCommentAt: statsByIssueId.get(row.id)?.lastExternalCommentAt ?? null,
+                    })
+                    : {}),
+            }];
+    }).sort(compareBlockedInboxRows);
+    const offset = typeof filters?.offset === "number" && Number.isFinite(filters.offset)
+        ? Math.max(0, Math.floor(filters.offset))
+        : 0;
+    const limit = typeof filters?.limit === "number" && Number.isFinite(filters.limit)
+        ? Math.max(1, Math.floor(filters.limit))
+        : undefined;
+    return limit === undefined ? enriched.slice(offset) : enriched.slice(offset, offset + limit);
+}
+async function countBlockedInboxIssues(dbOrTx, squadId, filters) {
+    const { conditions } = await blockedInboxIssueConditions(dbOrTx, squadId, filters);
+    const rows = (await dbOrTx
+        .select()
+        .from(issues)
+        .where(and(...conditions)));
+    if (rows.length === 0)
+        return 0;
+    const blockedInboxAttentionByIssueId = await listIssueBlockedInboxAttentionMap(dbOrTx, squadId, rows);
+    const rawSearchInput = filters?.q?.trim() ?? "";
+    const rawSearch = rawSearchInput.toLowerCase();
+    const commentSearchMatchIssueIds = new Set();
+    if (rawSearchInput) {
+        const issueIds = rows.map((row) => row.id);
+        const containsPattern = `%${escapeLikePattern(rawSearchInput)}%`;
+        for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+            const commentRows = await dbOrTx
+                .select({ issueId: issueComments.issueId })
+                .from(issueComments)
+                .where(and(eq(issueComments.squadId, squadId), inArray(issueComments.issueId, issueIdChunk), sql `${issueComments.body} ILIKE ${containsPattern} ESCAPE '\\'`));
+            for (const row of commentRows)
+                commentSearchMatchIssueIds.add(row.issueId);
+        }
+    }
+    return rows.reduce((count, row) => {
+        const attention = blockedInboxAttentionByIssueId.get(row.id);
+        if (!attention)
+            return count;
+        if (rawSearch
+            && !blockedInboxSearchText(attention, row).includes(rawSearch)
+            && !commentSearchMatchIssueIds.has(row.id))
+            return count;
+        return count + 1;
+    }, 0);
+}
+export function issueService(db) {
+    const instanceSettings = instanceSettingsService(db);
+    const treeControlSvc = issueTreeControlService(db);
+    async function getIssueByUuid(id) {
+        const row = await db
+            .select()
+            .from(issues)
+            .where(eq(issues.id, id))
+            .then((rows) => rows[0] ?? null);
+        if (!row)
+            return null;
+        const [enriched] = await withIssueLabels(db, [row]);
+        return enriched;
+    }
+    async function getIssueByIdentifier(identifier) {
+        const row = await db
+            .select()
+            .from(issues)
+            .where(eq(issues.identifier, identifier.toUpperCase()))
+            .then((rows) => rows[0] ?? null);
+        if (!row)
+            return null;
+        const [enriched] = await withIssueLabels(db, [row]);
+        return enriched;
+    }
+    async function getCurrentScheduledRetryForIssue(issueId, squadId) {
+        const row = await db
+            .select({
+            runId: heartbeatRuns.id,
+            status: heartbeatRuns.status,
+            agentId: heartbeatRuns.agentId,
+            agentName: agents.name,
+            retryOfRunId: heartbeatRuns.retryOfRunId,
+            scheduledRetryAt: heartbeatRuns.scheduledRetryAt,
+            scheduledRetryAttempt: heartbeatRuns.scheduledRetryAttempt,
+            scheduledRetryReason: heartbeatRuns.scheduledRetryReason,
+            error: heartbeatRuns.error,
+            errorCode: heartbeatRuns.errorCode,
+        })
+            .from(heartbeatRuns)
+            .innerJoin(agents, eq(heartbeatRuns.agentId, agents.id))
+            .where(and(eq(heartbeatRuns.squadId, squadId), eq(heartbeatRuns.status, "scheduled_retry"), sql `${heartbeatRuns.contextSnapshot} ->> 'issueId' = ${issueId}`))
+            .orderBy(asc(heartbeatRuns.scheduledRetryAt), asc(heartbeatRuns.createdAt), asc(heartbeatRuns.id))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+        return row ? { ...row, status: "scheduled_retry" } : null;
+    }
+    function deriveIssueCommentAuthorType(comment) {
+        const explicit = issueCommentAuthorTypeSchema.safeParse(comment.authorType);
+        if (explicit.success)
+            return explicit.data;
+        if (comment.authorAgentId)
+            return "agent";
+        if (comment.authorUserId)
+            return "user";
+        return "system";
+    }
+    function assertIssueCommentAuthorTypeAllowed(actor, authorType) {
+        if (actor.agentId && authorType !== "agent") {
+            throw unprocessable("Comment authorType must match authenticated actor");
+        }
+        if (actor.userId && authorType !== "user") {
+            throw unprocessable("Comment authorType must match authenticated actor");
+        }
+        if (!actor.agentId && !actor.userId && authorType !== "system") {
+            throw unprocessable("System comments cannot use user or agent authorType without an author id");
+        }
+    }
+    function redactIssueComment(comment, censorUsernameInLogs) {
+        return {
+            ...comment,
+            authorType: deriveIssueCommentAuthorType(comment),
+            body: redactCurrentUserText(comment.body, { enabled: censorUsernameInLogs }),
+            presentation: issueCommentPresentationSchema.nullable().catch(null).parse(comment.presentation ?? null),
+            metadata: issueCommentMetadataSchema.nullable().catch(null).parse(comment.metadata ?? null),
+        };
+    }
+    async function readRunLogText(run) {
+        if (run.logStore !== "local_file" || !run.logRef)
+            return "";
+        const logBytes = Number(run.logBytes ?? 0);
+        if (!Number.isFinite(logBytes) || logBytes <= 0)
+            return "";
+        const store = getRunLogStore();
+        let offset = 0;
+        let content = "";
+        let nextOffset = 0;
+        try {
+            while (nextOffset !== undefined) {
+                const remainingBytes = ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_LOG_BYTES - Buffer.byteLength(content, "utf8");
+                if (remainingBytes <= 0)
+                    break;
+                const chunk = await store.read({ store: "local_file", logRef: run.logRef }, {
+                    offset,
+                    limitBytes: Math.min(ISSUE_COMMENT_RUN_LOG_DERIVATION_CHUNK_BYTES, remainingBytes),
+                });
+                content += chunk.content;
+                nextOffset = chunk.nextOffset;
+                offset = chunk.nextOffset ?? 0;
+            }
+        }
+        catch (err) {
+            if (err instanceof HttpError && err.status === 404) {
+                logger.warn({ err, runId: run.runId ?? undefined, logRef: run.logRef }, "missing heartbeat run log while deriving issue comment metadata");
+                return content;
+            }
+            throw err;
+        }
+        return content;
+    }
+    async function enrichCommentsWithDerivedAgentAttribution(comments) {
+        const candidates = comments.filter((comment) => !comment.authorAgentId
+            && !!comment.authorUserId
+            && !comment.createdByRunId);
+        if (candidates.length === 0)
+            return comments;
+        const squadId = comments[0]?.squadId ?? null;
+        const issueId = comments[0]?.issueId ?? null;
+        if (!squadId || !issueId)
+            return comments;
+        const minCommentCreatedAtMs = candidates.reduce((min, comment) => {
+            const timestamp = toTimestampMs(comment.createdAt);
+            if (timestamp === null)
+                return min;
+            return min === null ? timestamp : Math.min(min, timestamp);
+        }, null);
+        const maxCommentCreatedAtMs = candidates.reduce((max, comment) => {
+            const timestamp = toTimestampMs(comment.createdAt);
+            if (timestamp === null)
+                return max;
+            return max === null ? timestamp : Math.max(max, timestamp);
+        }, null);
+        if (minCommentCreatedAtMs === null || maxCommentCreatedAtMs === null)
+            return comments;
+        const minCommentCreatedAt = new Date(minCommentCreatedAtMs).toISOString();
+        const maxCommentCreatedAt = new Date(maxCommentCreatedAtMs + ISSUE_COMMENT_RUN_LOG_DERIVATION_END_SLACK_MS).toISOString();
+        const runs = await db
+            .select({
+            runId: heartbeatRuns.id,
+            agentId: heartbeatRuns.agentId,
+            createdAt: heartbeatRuns.createdAt,
+            startedAt: heartbeatRuns.startedAt,
+            finishedAt: heartbeatRuns.finishedAt,
+            logStore: heartbeatRuns.logStore,
+            logRef: heartbeatRuns.logRef,
+            logBytes: heartbeatRuns.logBytes,
+        })
+            .from(heartbeatRuns)
+            .where(and(eq(heartbeatRuns.squadId, squadId), or(sql `${heartbeatRuns.contextSnapshot} ->> 'issueId' = ${issueId}`, sql `exists (
+              select 1
+              from ${activityLog}
+              where ${activityLog.squadId} = ${squadId}
+                and ${activityLog.entityType} = 'issue'
+                and ${activityLog.entityId} = ${issueId}
+                and ${activityLog.runId} = ${heartbeatRuns.id}
+            )`), sql `coalesce(${heartbeatRuns.finishedAt}, ${heartbeatRuns.createdAt}) >= ${minCommentCreatedAt}::timestamptz`, sql `coalesce(${heartbeatRuns.startedAt}, ${heartbeatRuns.createdAt}) <= ${maxCommentCreatedAt}::timestamptz`))
+            .orderBy(desc(heartbeatRuns.createdAt));
+        if (runs.length === 0)
+            return comments;
+        const runsWithLogs = [];
+        for (let index = 0; index < runs.length; index += ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_PARALLEL_READS) {
+            const batch = runs.slice(index, index + ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_PARALLEL_READS);
+            const batchWithLogs = await Promise.all(batch.map(async (run) => ({
+                ...run,
+                logContent: await readRunLogText(run),
+            })));
+            runsWithLogs.push(...batchWithLogs);
+        }
+        const derivedByCommentId = deriveIssueCommentRunLogAttribution(candidates, runsWithLogs);
+        if (derivedByCommentId.size === 0)
+            return comments;
+        return comments.map((comment) => {
+            const derived = derivedByCommentId.get(comment.id);
+            return derived ? { ...comment, ...derived } : comment;
+        });
+    }
+    async function assertAssignableAgent(squadId, agentId) {
+        const assignee = await db
+            .select({
+            id: agents.id,
+            squadId: agents.squadId,
+            status: agents.status,
+        })
+            .from(agents)
+            .where(eq(agents.id, agentId))
+            .then((rows) => rows[0] ?? null);
+        if (!assignee)
+            throw notFound("Assignee agent not found");
+        if (assignee.squadId !== squadId) {
+            throw unprocessable("Assignee must belong to same squad");
+        }
+        if (assignee.status === "pending_approval") {
+            throw conflict("Cannot assign work to pending approval agents");
+        }
+        if (assignee.status === "terminated") {
+            throw conflict("Cannot assign work to terminated agents");
+        }
+    }
+    async function isTreeHoldInteractionCheckoutAllowed(squadId, checkoutRunId, _gate) {
+        if (!checkoutRunId)
+            return false;
+        const run = await db
+            .select({
+            id: heartbeatRuns.id,
+            agentId: heartbeatRuns.agentId,
+            wakeupRequestId: heartbeatRuns.wakeupRequestId,
+            contextSnapshot: heartbeatRuns.contextSnapshot,
+        })
+            .from(heartbeatRuns)
+            .where(and(eq(heartbeatRuns.id, checkoutRunId), eq(heartbeatRuns.squadId, squadId)))
+            .then((rows) => rows[0] ?? null);
+        const issueId = readStringFromRecord(run?.contextSnapshot, "issueId");
+        if (!run || !issueId)
+            return false;
+        return isVerifiedIssueTreeControlInteractionWake(db, {
+            squadId,
+            issueId,
+            agentId: run.agentId,
+            runId: run.id,
+            wakeupRequestId: run.wakeupRequestId,
+            contextSnapshot: run.contextSnapshot,
+        });
+    }
+    async function assertAssignableUser(squadId, userId) {
+        const membership = await db
+            .select({ id: squadMemberships.id })
+            .from(squadMemberships)
+            .where(and(eq(squadMemberships.squadId, squadId), eq(squadMemberships.principalType, "user"), eq(squadMemberships.principalId, userId), eq(squadMemberships.status, "active")))
+            .then((rows) => rows[0] ?? null);
+        if (!membership) {
+            throw notFound("Assignee user not found");
+        }
+    }
+    async function assertValidProjectWorkspace(squadId, projectId, projectWorkspaceId, dbOrTx = db) {
+        const workspace = await dbOrTx
+            .select({
+            id: projectWorkspaces.id,
+            squadId: projectWorkspaces.squadId,
+            projectId: projectWorkspaces.projectId,
+        })
+            .from(projectWorkspaces)
+            .where(eq(projectWorkspaces.id, projectWorkspaceId))
+            .then((rows) => rows[0] ?? null);
+        if (!workspace)
+            throw notFound("Project workspace not found");
+        if (workspace.squadId !== squadId)
+            throw unprocessable("Project workspace must belong to same squad");
+        if (projectId && workspace.projectId !== projectId) {
+            throw unprocessable("Project workspace must belong to the selected project");
+        }
+    }
+    async function assertValidExecutionWorkspace(squadId, projectId, executionWorkspaceId, dbOrTx = db) {
+        const workspace = await dbOrTx
+            .select({
+            id: executionWorkspaces.id,
+            squadId: executionWorkspaces.squadId,
+            projectId: executionWorkspaces.projectId,
+        })
+            .from(executionWorkspaces)
+            .where(eq(executionWorkspaces.id, executionWorkspaceId))
+            .then((rows) => rows[0] ?? null);
+        if (!workspace)
+            throw notFound("Execution workspace not found");
+        if (workspace.squadId !== squadId)
+            throw unprocessable("Execution workspace must belong to same squad");
+        if (projectId && workspace.projectId !== projectId) {
+            throw unprocessable("Execution workspace must belong to the selected project");
+        }
+    }
+    async function assertValidLabelIds(squadId, labelIds, dbOrTx = db) {
+        if (labelIds.length === 0)
+            return;
+        const existing = await dbOrTx
+            .select({ id: labels.id })
+            .from(labels)
+            .where(and(eq(labels.squadId, squadId), inArray(labels.id, labelIds)));
+        if (existing.length !== new Set(labelIds).size) {
+            throw unprocessable("One or more labels are invalid for this squad");
+        }
+    }
+    async function syncIssueLabels(issueId, squadId, labelIds, dbOrTx = db) {
+        const deduped = [...new Set(labelIds)];
+        await assertValidLabelIds(squadId, deduped, dbOrTx);
+        await dbOrTx.delete(issueLabels).where(eq(issueLabels.issueId, issueId));
+        if (deduped.length === 0)
+            return;
+        await dbOrTx.insert(issueLabels).values(deduped.map((labelId) => ({
+            issueId,
+            labelId,
+            squadId,
+        })));
+    }
+    async function getIssueRelationSummaryMap(squadId, issueIds, dbOrTx = db) {
+        const uniqueIssueIds = [...new Set(issueIds)];
+        const empty = new Map();
+        for (const issueId of uniqueIssueIds) {
+            empty.set(issueId, { blockedBy: [], blocks: [] });
+        }
+        if (uniqueIssueIds.length === 0)
+            return empty;
+        const [blockedByRows, blockingRows] = await Promise.all([
+            dbOrTx
+                .select({
+                currentIssueId: issueRelations.relatedIssueId,
+                relatedId: issues.id,
+                identifier: issues.identifier,
+                title: issues.title,
+                status: issues.status,
+                priority: issues.priority,
+                assigneeAgentId: issues.assigneeAgentId,
+                assigneeUserId: issues.assigneeUserId,
+            })
+                .from(issueRelations)
+                .innerJoin(issues, eq(issueRelations.issueId, issues.id))
+                .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks"), inArray(issueRelations.relatedIssueId, uniqueIssueIds))),
+            dbOrTx
+                .select({
+                currentIssueId: issueRelations.issueId,
+                relatedId: issues.id,
+                identifier: issues.identifier,
+                title: issues.title,
+                status: issues.status,
+                priority: issues.priority,
+                assigneeAgentId: issues.assigneeAgentId,
+                assigneeUserId: issues.assigneeUserId,
+            })
+                .from(issueRelations)
+                .innerJoin(issues, eq(issueRelations.relatedIssueId, issues.id))
+                .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks"), inArray(issueRelations.issueId, uniqueIssueIds))),
+        ]);
+        for (const row of blockedByRows) {
+            empty.get(row.currentIssueId)?.blockedBy.push(summarizeIssueRelationRow(row));
+        }
+        for (const row of blockingRows) {
+            empty.get(row.currentIssueId)?.blocks.push(summarizeIssueRelationRow(row));
+        }
+        const terminalByRoot = await terminalExplicitBlockersByRoot(squadId, [...empty.values()].flatMap((relations) => relations.blockedBy), dbOrTx);
+        for (const relations of empty.values()) {
+            relations.blockedBy.sort((a, b) => a.title.localeCompare(b.title));
+            for (const blocker of relations.blockedBy) {
+                const terminalBlockers = terminalByRoot.get(blocker.id);
+                if (terminalBlockers && terminalBlockers.length > 0) {
+                    blocker.terminalBlockers = terminalBlockers;
+                }
+            }
+            relations.blocks.sort((a, b) => a.title.localeCompare(b.title));
+        }
+        return empty;
+    }
+    async function assertNoBlockingCycles(squadId, issueId, blockerIssueIds, dbOrTx = db) {
+        if (blockerIssueIds.length === 0)
+            return;
+        const rows = await dbOrTx
+            .select({
+            blockerIssueId: issueRelations.issueId,
+            blockedIssueId: issueRelations.relatedIssueId,
+        })
+            .from(issueRelations)
+            .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.type, "blocks")));
+        const adjacency = new Map();
+        for (const row of rows) {
+            const list = adjacency.get(row.blockerIssueId) ?? [];
+            list.push(row.blockedIssueId);
+            adjacency.set(row.blockerIssueId, list);
+        }
+        for (const blockerIssueId of blockerIssueIds) {
+            const queue = [...(adjacency.get(issueId) ?? [])];
+            const visited = new Set([issueId]);
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (current === blockerIssueId) {
+                    throw unprocessable("Blocking relations cannot contain cycles");
+                }
+                if (visited.has(current))
+                    continue;
+                visited.add(current);
+                queue.push(...(adjacency.get(current) ?? []));
+            }
+        }
+    }
+    async function syncBlockedByIssueIds(issueId, squadId, blockedByIssueIds, actor = {}, dbOrTx = db) {
+        const deduped = [...new Set(blockedByIssueIds)];
+        if (deduped.some((candidate) => candidate === issueId)) {
+            throw unprocessable("Issue cannot be blocked by itself");
+        }
+        if (deduped.length > 0) {
+            const lockedIssueIds = [issueId, ...deduped].sort();
+            await dbOrTx.execute(sql `SELECT ${issues.id} FROM ${issues}
+            WHERE ${and(eq(issues.squadId, squadId), inArray(issues.id, lockedIssueIds))}
+            ORDER BY ${issues.id}
+            FOR UPDATE`);
+            const relatedIssues = await dbOrTx
+                .select({ id: issues.id })
+                .from(issues)
+                .where(and(eq(issues.squadId, squadId), inArray(issues.id, deduped)));
+            if (relatedIssues.length !== deduped.length) {
+                throw unprocessable("Blocked-by issues must belong to the same squad");
+            }
+            await assertNoBlockingCycles(squadId, issueId, deduped, dbOrTx);
+        }
+        await dbOrTx
+            .delete(issueRelations)
+            .where(and(eq(issueRelations.squadId, squadId), eq(issueRelations.relatedIssueId, issueId), eq(issueRelations.type, "blocks")));
+        if (deduped.length === 0)
+            return;
+        await dbOrTx.insert(issueRelations).values(deduped.map((blockerIssueId) => ({
+            squadId,
+            issueId: blockerIssueId,
+            relatedIssueId: issueId,
+            type: "blocks",
+            createdByAgentId: actor.agentId ?? null,
+            createdByUserId: actor.userId ?? null,
+        })));
+    }
+    async function isTerminalOrMissingHeartbeatRun(runId) {
+        const run = await db
+            .select({ status: heartbeatRuns.status })
+            .from(heartbeatRuns)
+            .where(eq(heartbeatRuns.id, runId))
+            .then((rows) => rows[0] ?? null);
+        if (!run)
+            return true;
+        return TERMINAL_HEARTBEAT_RUN_STATUSES.has(run.status);
+    }
+    async function adoptStaleCheckoutRun(input) {
+        const stale = await isTerminalOrMissingHeartbeatRun(input.expectedCheckoutRunId);
+        if (!stale)
+            return null;
+        const now = new Date();
+        const adopted = await db
+            .update(issues)
+            .set({
+            checkoutRunId: input.actorRunId,
+            executionRunId: input.actorRunId,
+            executionLockedAt: now,
+            updatedAt: now,
+        })
+            .where(and(eq(issues.id, input.issueId), eq(issues.status, "in_progress"), eq(issues.assigneeAgentId, input.actorAgentId), eq(issues.checkoutRunId, input.expectedCheckoutRunId)))
+            .returning({
+            id: issues.id,
+            status: issues.status,
+            assigneeAgentId: issues.assigneeAgentId,
+            checkoutRunId: issues.checkoutRunId,
+            executionRunId: issues.executionRunId,
+        })
+            .then((rows) => rows[0] ?? null);
+        return adopted;
+    }
+    async function adoptUnownedCheckoutRun(input) {
+        const now = new Date();
+        const adopted = await db
+            .update(issues)
+            .set({
+            checkoutRunId: input.actorRunId,
+            executionRunId: input.actorRunId,
+            executionLockedAt: now,
+            updatedAt: now,
+        })
+            .where(and(eq(issues.id, input.issueId), eq(issues.status, "in_progress"), eq(issues.assigneeAgentId, input.actorAgentId), isNull(issues.checkoutRunId), or(isNull(issues.executionRunId), eq(issues.executionRunId, input.actorRunId))))
+            .returning({
+            id: issues.id,
+            status: issues.status,
+            assigneeAgentId: issues.assigneeAgentId,
+            checkoutRunId: issues.checkoutRunId,
+            executionRunId: issues.executionRunId,
+        })
+            .then((rows) => rows[0] ?? null);
+        return adopted;
+    }
+    async function clearExecutionRunIfTerminal(issueId) {
+        return db.transaction(async (tx) => {
+            await tx.execute(sql `select ${issues.id} from ${issues} where ${issues.id} = ${issueId} for update`);
+            const issue = await tx
+                .select({ executionRunId: issues.executionRunId })
+                .from(issues)
+                .where(eq(issues.id, issueId))
+                .then((rows) => rows[0] ?? null);
+            if (!issue?.executionRunId)
+                return false;
+            await tx.execute(sql `select ${heartbeatRuns.id} from ${heartbeatRuns} where ${heartbeatRuns.id} = ${issue.executionRunId} for update`);
+            const run = await tx
+                .select({ status: heartbeatRuns.status })
+                .from(heartbeatRuns)
+                .where(eq(heartbeatRuns.id, issue.executionRunId))
+                .then((rows) => rows[0] ?? null);
+            if (run && !TERMINAL_HEARTBEAT_RUN_STATUSES.has(run.status))
+                return false;
+            const updated = await tx
+                .update(issues)
+                .set({
+                executionRunId: null,
+                executionAgentNameKey: null,
+                executionLockedAt: null,
+                updatedAt: new Date(),
+            })
+                .where(and(eq(issues.id, issueId), eq(issues.executionRunId, issue.executionRunId)))
+                .returning({ id: issues.id })
+                .then((rows) => rows[0] ?? null);
+            return Boolean(updated);
+        });
+    }
+    return {
+        clearExecutionRunIfTerminal,
+        list: async (squadId, filters) => {
+            if (filters?.attention === "blocked") {
+                return listBlockedInboxIssues(db, squadId, {
+                    ...filters,
+                    includeBlockedBy: true,
+                    includeBlockedInboxAttention: true,
+                });
+            }
+            const conditions = [eq(issues.squadId, squadId)];
+            const limit = typeof filters?.limit === "number" && Number.isFinite(filters.limit)
+                ? Math.max(1, Math.floor(filters.limit))
+                : undefined;
+            const offset = typeof filters?.offset === "number" && Number.isFinite(filters.offset)
+                ? Math.max(0, Math.floor(filters.offset))
+                : 0;
+            const touchedByUserId = filters?.touchedByUserId?.trim() || undefined;
+            const inboxArchivedByUserId = filters?.inboxArchivedByUserId?.trim() || undefined;
+            const unreadForUserId = filters?.unreadForUserId?.trim() || undefined;
+            const contextUserId = unreadForUserId ?? touchedByUserId ?? inboxArchivedByUserId;
+            const includeBlockedBy = filters?.includeBlockedBy === true;
+            const includeBlockedInboxAttention = filters?.includeBlockedInboxAttention === true;
+            const rawSearch = filters?.q?.trim() ?? "";
+            const hasSearch = rawSearch.length > 0;
+            const escapedSearch = hasSearch ? escapeLikePattern(rawSearch) : "";
+            const startsWithPattern = `${escapedSearch}%`;
+            const containsPattern = `%${escapedSearch}%`;
+            const titleStartsWithMatch = sql `${issues.title} ILIKE ${startsWithPattern} ESCAPE '\\'`;
+            const titleContainsMatch = sql `${issues.title} ILIKE ${containsPattern} ESCAPE '\\'`;
+            const identifierStartsWithMatch = sql `${issues.identifier} ILIKE ${startsWithPattern} ESCAPE '\\'`;
+            const identifierContainsMatch = sql `${issues.identifier} ILIKE ${containsPattern} ESCAPE '\\'`;
+            const descriptionContainsMatch = sql `${issues.description} ILIKE ${containsPattern} ESCAPE '\\'`;
+            const commentContainsMatch = sql `
+        EXISTS (
+          SELECT 1
+          FROM ${issueComments}
+          WHERE ${issueComments.issueId} = ${issues.id}
+            AND ${issueComments.squadId} = ${squadId}
+            AND ${issueComments.body} ILIKE ${containsPattern} ESCAPE '\\'
+        )
+      `;
+            if (filters?.descendantOf) {
+                conditions.push(sql `
+          ${issues.id} IN (
+            WITH RECURSIVE descendants(id) AS (
+              SELECT ${issues.id}
+              FROM ${issues}
+              WHERE ${issues.squadId} = ${squadId}
+                AND ${issues.parentId} = ${filters.descendantOf}
+              UNION
+              SELECT ${issues.id}
+              FROM ${issues}
+              JOIN descendants ON ${issues.parentId} = descendants.id
+              WHERE ${issues.squadId} = ${squadId}
+            )
+            SELECT id FROM descendants
+          )
+        `);
+            }
+            if (filters?.status) {
+                const statuses = filters.status.split(",").map((s) => s.trim());
+                conditions.push(statuses.length === 1 ? eq(issues.status, statuses[0]) : inArray(issues.status, statuses));
+            }
+            if (filters?.assigneeAgentId) {
+                conditions.push(eq(issues.assigneeAgentId, filters.assigneeAgentId));
+            }
+            if (filters?.participantAgentId) {
+                conditions.push(participatedByAgentCondition(squadId, filters.participantAgentId));
+            }
+            if (filters?.assigneeUserId) {
+                conditions.push(eq(issues.assigneeUserId, filters.assigneeUserId));
+            }
+            if (touchedByUserId) {
+                conditions.push(touchedByUserCondition(squadId, touchedByUserId));
+            }
+            if (inboxArchivedByUserId) {
+                conditions.push(inboxVisibleForUserCondition(squadId, inboxArchivedByUserId));
+            }
+            if (unreadForUserId) {
+                conditions.push(unreadForUserCondition(squadId, unreadForUserId));
+            }
+            if (filters?.projectId)
+                conditions.push(eq(issues.projectId, filters.projectId));
+            if (filters?.workspaceId) {
+                conditions.push(or(eq(issues.executionWorkspaceId, filters.workspaceId), eq(issues.projectWorkspaceId, filters.workspaceId)));
+            }
+            if (filters?.executionWorkspaceId) {
+                conditions.push(eq(issues.executionWorkspaceId, filters.executionWorkspaceId));
+            }
+            if (filters?.parentId)
+                conditions.push(eq(issues.parentId, filters.parentId));
+            if (filters?.originKind)
+                conditions.push(eq(issues.originKind, filters.originKind));
+            if (filters?.originKindPrefix)
+                conditions.push(like(issues.originKind, `${filters.originKindPrefix}%`));
+            if (filters?.originId)
+                conditions.push(eq(issues.originId, filters.originId));
+            if (!shouldIncludePluginOperationIssues(filters)) {
+                conditions.push(nonPluginOperationIssueCondition());
+            }
+            if (filters?.labelId) {
+                const labeledIssueIds = await db
+                    .select({ issueId: issueLabels.issueId })
+                    .from(issueLabels)
+                    .where(and(eq(issueLabels.squadId, squadId), eq(issueLabels.labelId, filters.labelId)));
+                if (labeledIssueIds.length === 0)
+                    return [];
+                conditions.push(inArray(issues.id, labeledIssueIds.map((row) => row.issueId)));
+            }
+            if (hasSearch) {
+                conditions.push(or(titleContainsMatch, identifierContainsMatch, descriptionContainsMatch, commentContainsMatch));
+            }
+            if (filters?.excludeRoutineExecutions && !filters?.originKind && !filters?.originId) {
+                conditions.push(ne(issues.originKind, "routine_execution"));
+            }
+            conditions.push(isNull(issues.hiddenAt));
+            const priorityOrder = sql `CASE ${issues.priority} WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 ELSE 4 END`;
+            const searchOrder = sql `
+        CASE
+          WHEN ${titleStartsWithMatch} THEN 0
+          WHEN ${titleContainsMatch} THEN 1
+          WHEN ${identifierStartsWithMatch} THEN 2
+          WHEN ${identifierContainsMatch} THEN 3
+          WHEN ${commentContainsMatch} THEN 4
+          WHEN ${descriptionContainsMatch} THEN 5
+          ELSE 6
+        END
+      `;
+            const baseQuery = db
+                .select(issueListSelect)
+                .from(issues)
+                .where(and(...conditions))
+                .orderBy(...issueListOrderBy(squadId, {
+                hasSearch,
+                priorityOrder,
+                searchOrder,
+                sortField: filters?.sortField,
+                sortDir: filters?.sortDir,
+            }));
+            const pageQuery = offset > 0
+                ? (limit === undefined ? baseQuery.offset(offset) : baseQuery.limit(limit).offset(offset))
+                : (limit === undefined ? baseQuery : baseQuery.limit(limit));
+            const rows = (await pageQuery).map((row) => ({
+                ...row,
+                description: decodeDatabaseTextPreview(row.description, ISSUE_LIST_DESCRIPTION_MAX_CHARS),
+            }));
+            const withLabels = await withIssueLabels(db, rows);
+            const runMap = await activeRunMapForIssues(db, withLabels);
+            const withRuns = withActiveRuns(withLabels, runMap);
+            if (withRuns.length === 0) {
+                return withRuns;
+            }
+            const issueIds = withRuns.map((row) => row.id);
+            const [statsRows, readRows, lastActivityRows, blockedByMap] = await Promise.all([
+                contextUserId
+                    ? userCommentStatsForIssues(db, squadId, contextUserId, issueIds)
+                    : Promise.resolve([]),
+                contextUserId
+                    ? userReadStatsForIssues(db, squadId, contextUserId, issueIds)
+                    : Promise.resolve([]),
+                lastActivityStatsForIssues(db, squadId, issueIds),
+                includeBlockedBy
+                    ? blockedByMapForIssues(db, squadId, issueIds)
+                    : Promise.resolve(new Map()),
+            ]);
+            const statsByIssueId = new Map(statsRows.map((row) => [row.issueId, row]));
+            const lastActivityByIssueId = new Map(lastActivityRows.map((row) => [row.issueId, row]));
+            const [blockerAttentionByIssueId, productivityReviewByIssueId, blockedInboxAttentionByIssueId,] = await Promise.all([
+                listIssueBlockerAttentionMap(db, squadId, withRuns),
+                listIssueProductivityReviewMap(db, squadId, issueIds),
+                includeBlockedInboxAttention
+                    ? listIssueBlockedInboxAttentionMap(db, squadId, withRuns)
+                    : Promise.resolve(new Map()),
+            ]);
+            if (!contextUserId) {
+                return withRuns.map((row) => {
+                    const activity = lastActivityByIssueId.get(row.id);
+                    const lastActivityAt = latestIssueActivityAt(row.updatedAt, activity?.latestCommentAt ?? null, activity?.latestLogAt ?? null) ?? row.updatedAt;
+                    return {
+                        ...row,
+                        ...(includeBlockedBy ? { blockedBy: blockedByMap.get(row.id) ?? [] } : {}),
+                        lastActivityAt,
+                        ...(blockerAttentionByIssueId.has(row.id) ? { blockerAttention: blockerAttentionByIssueId.get(row.id) } : {}),
+                        ...(includeBlockedInboxAttention ? { blockedInboxAttention: blockedInboxAttentionByIssueId.get(row.id) ?? null } : {}),
+                        ...(productivityReviewByIssueId.has(row.id)
+                            ? { productivityReview: productivityReviewByIssueId.get(row.id) }
+                            : {}),
+                    };
+                });
+            }
+            const readByIssueId = new Map(readRows.map((row) => [row.issueId, row.myLastReadAt]));
+            return withRuns.map((row) => {
+                const activity = lastActivityByIssueId.get(row.id);
+                const lastActivityAt = latestIssueActivityAt(row.updatedAt, activity?.latestCommentAt ?? null, activity?.latestLogAt ?? null) ?? row.updatedAt;
+                return {
+                    ...row,
+                    ...(includeBlockedBy ? { blockedBy: blockedByMap.get(row.id) ?? [] } : {}),
+                    lastActivityAt,
+                    ...(blockerAttentionByIssueId.has(row.id) ? { blockerAttention: blockerAttentionByIssueId.get(row.id) } : {}),
+                    ...(includeBlockedInboxAttention ? { blockedInboxAttention: blockedInboxAttentionByIssueId.get(row.id) ?? null } : {}),
+                    ...(productivityReviewByIssueId.has(row.id)
+                        ? { productivityReview: productivityReviewByIssueId.get(row.id) }
+                        : {}),
+                    ...deriveIssueUserContext(row, contextUserId, {
+                        myLastCommentAt: statsByIssueId.get(row.id)?.myLastCommentAt ?? null,
+                        myLastReadAt: readByIssueId.get(row.id) ?? null,
+                        lastExternalCommentAt: statsByIssueId.get(row.id)?.lastExternalCommentAt ?? null,
+                    }),
+                };
+            });
+        },
+        count: async (squadId, filters) => {
+            if (filters?.attention === "blocked") {
+                return countBlockedInboxIssues(db, squadId, filters);
+            }
+            const conditions = [eq(issues.squadId, squadId), isNull(issues.hiddenAt)];
+            if (filters?.status) {
+                const statuses = filters.status.split(",").map((status) => status.trim()).filter(Boolean);
+                if (statuses.length === 1)
+                    conditions.push(eq(issues.status, statuses[0]));
+                else if (statuses.length > 1)
+                    conditions.push(inArray(issues.status, statuses));
+            }
+            if (filters?.assigneeAgentId)
+                conditions.push(eq(issues.assigneeAgentId, filters.assigneeAgentId));
+            if (filters?.assigneeUserId)
+                conditions.push(eq(issues.assigneeUserId, filters.assigneeUserId));
+            if (filters?.projectId)
+                conditions.push(eq(issues.projectId, filters.projectId));
+            if (filters?.workspaceId) {
+                conditions.push(or(eq(issues.executionWorkspaceId, filters.workspaceId), eq(issues.projectWorkspaceId, filters.workspaceId)));
+            }
+            if (filters?.executionWorkspaceId)
+                conditions.push(eq(issues.executionWorkspaceId, filters.executionWorkspaceId));
+            if (filters?.parentId)
+                conditions.push(eq(issues.parentId, filters.parentId));
+            if (filters?.originKind)
+                conditions.push(eq(issues.originKind, filters.originKind));
+            if (filters?.originKindPrefix)
+                conditions.push(like(issues.originKind, `${filters.originKindPrefix}%`));
+            if (filters?.originId)
+                conditions.push(eq(issues.originId, filters.originId));
+            if (!shouldIncludePluginOperationIssues(filters))
+                conditions.push(nonPluginOperationIssueCondition());
+            const [row] = await db
+                .select({ count: sql `count(*)` })
+                .from(issues)
+                .where(and(...conditions));
+            return Number(row?.count ?? 0);
+        },
+        countUnreadTouchedByUser: async (squadId, userId, status) => {
+            const conditions = [
+                eq(issues.squadId, squadId),
+                isNull(issues.hiddenAt),
+                nonPluginOperationIssueCondition(),
+                unreadForUserCondition(squadId, userId),
+            ];
+            if (status) {
+                const statuses = status.split(",").map((s) => s.trim()).filter(Boolean);
+                if (statuses.length === 1) {
+                    conditions.push(eq(issues.status, statuses[0]));
+                }
+                else if (statuses.length > 1) {
+                    conditions.push(inArray(issues.status, statuses));
+                }
+            }
+            const [row] = await db
+                .select({ count: sql `count(*)` })
+                .from(issues)
+                .where(and(...conditions));
+            return Number(row?.count ?? 0);
+        },
+        markRead: async (squadId, issueId, userId, readAt = new Date()) => {
+            const now = new Date();
+            const [row] = await db
+                .insert(issueReadStates)
+                .values({
+                squadId,
+                issueId,
+                userId,
+                lastReadAt: readAt,
+                updatedAt: now,
+            })
+                .onConflictDoUpdate({
+                target: [issueReadStates.squadId, issueReadStates.issueId, issueReadStates.userId],
+                set: {
+                    lastReadAt: readAt,
+                    updatedAt: now,
+                },
+            })
+                .returning();
+            return row;
+        },
+        markUnread: async (squadId, issueId, userId) => {
+            const deleted = await db
+                .delete(issueReadStates)
+                .where(and(eq(issueReadStates.squadId, squadId), eq(issueReadStates.issueId, issueId), eq(issueReadStates.userId, userId)))
+                .returning();
+            return deleted.length > 0;
+        },
+        archiveInbox: async (squadId, issueId, userId, archivedAt = new Date()) => {
+            const now = new Date();
+            const [row] = await db
+                .insert(issueInboxArchives)
+                .values({
+                squadId,
+                issueId,
+                userId,
+                archivedAt,
+                updatedAt: now,
+            })
+                .onConflictDoUpdate({
+                target: [issueInboxArchives.squadId, issueInboxArchives.issueId, issueInboxArchives.userId],
+                set: {
+                    archivedAt,
+                    updatedAt: now,
+                },
+            })
+                .returning();
+            return row;
+        },
+        unarchiveInbox: async (squadId, issueId, userId) => {
+            const [row] = await db
+                .delete(issueInboxArchives)
+                .where(and(eq(issueInboxArchives.squadId, squadId), eq(issueInboxArchives.issueId, issueId), eq(issueInboxArchives.userId, userId)))
+                .returning();
+            return row ?? null;
+        },
+        getById: async (raw) => {
+            const id = raw.trim();
+            const identifier = normalizeIssueReferenceIdentifier(id);
+            if (identifier) {
+                return getIssueByIdentifier(identifier);
+            }
+            if (!isUuidLike(id)) {
+                return null;
+            }
+            return getIssueByUuid(id);
+        },
+        getByIdentifier: async (identifier) => {
+            return getIssueByIdentifier(identifier);
+        },
+        getCurrentScheduledRetry: async (issueId) => {
+            const issue = await db
+                .select({ id: issues.id, squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, issueId))
+                .then((rows) => rows[0] ?? null);
+            if (!issue)
+                throw notFound("Issue not found");
+            return getCurrentScheduledRetryForIssue(issue.id, issue.squadId);
+        },
+        getRelationSummaries: async (issueId) => {
+            const issue = await db
+                .select({ id: issues.id, squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, issueId))
+                .then((rows) => rows[0] ?? null);
+            if (!issue)
+                throw notFound("Issue not found");
+            const relations = await getIssueRelationSummaryMap(issue.squadId, [issueId], db);
+            return relations.get(issueId) ?? { blockedBy: [], blocks: [] };
+        },
+        getDependencyReadiness: async (issueId, dbOrTx = db) => {
+            const issue = await dbOrTx
+                .select({ id: issues.id, squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, issueId))
+                .then((rows) => rows[0] ?? null);
+            if (!issue)
+                throw notFound("Issue not found");
+            const readiness = await listIssueDependencyReadinessMap(dbOrTx, issue.squadId, [issueId]);
+            return readiness.get(issueId) ?? createIssueDependencyReadiness(issueId);
+        },
+        listDependencyReadiness: async (squadId, issueIds, dbOrTx = db) => {
+            return listIssueDependencyReadinessMap(dbOrTx, squadId, issueIds);
+        },
+        listBlockerAttention: async (squadId, issueRows, dbOrTx = db) => {
+            return listIssueBlockerAttentionMap(dbOrTx, squadId, issueRows);
+        },
+        listProductivityReviews: async (squadId, sourceIssueIds, dbOrTx = db) => {
+            return listIssueProductivityReviewMap(dbOrTx, squadId, sourceIssueIds);
+        },
+        listWakeableBlockedDependents: async (blockerIssueId) => {
+            const blockerIssue = await db
+                .select({ id: issues.id, squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, blockerIssueId))
+                .then((rows) => rows[0] ?? null);
+            if (!blockerIssue)
+                return [];
+            const candidates = await db
+                .select({
+                id: issues.id,
+                assigneeAgentId: issues.assigneeAgentId,
+                status: issues.status,
+            })
+                .from(issueRelations)
+                .innerJoin(issues, eq(issueRelations.relatedIssueId, issues.id))
+                .where(and(eq(issueRelations.squadId, blockerIssue.squadId), eq(issueRelations.type, "blocks"), eq(issueRelations.issueId, blockerIssueId)));
+            if (candidates.length === 0)
+                return [];
+            const wakeableCandidates = candidates.filter((candidate) => candidate.assigneeAgentId && !["backlog", "done", "cancelled"].includes(candidate.status));
+            if (wakeableCandidates.length === 0)
+                return [];
+            // Defer to the unified readiness check so that a dependent only fires when
+            // (a) every blocker is done AND (b) every done blocker's workspace has
+            // recorded a successful workspace_finalize. The finalize hook also calls
+            // this function on completion, so a wake initially gated by an in-flight
+            // sync-back will re-fire once the restore lands locally.
+            const readinessMap = await listIssueDependencyReadinessMap(db, blockerIssue.squadId, wakeableCandidates.map((candidate) => candidate.id));
+            return wakeableCandidates
+                .map((candidate) => {
+                const readiness = readinessMap.get(candidate.id) ?? createIssueDependencyReadiness(candidate.id);
+                return { candidate, readiness };
+            })
+                .filter(({ readiness }) => readiness.isDependencyReady && readiness.blockerIssueIds.length > 0)
+                .map(({ candidate, readiness }) => ({
+                id: candidate.id,
+                assigneeAgentId: candidate.assigneeAgentId,
+                blockerIssueIds: readiness.blockerIssueIds,
+            }));
+        },
+        getWakeableParentAfterChildCompletion: async (parentIssueId) => {
+            const parent = await db
+                .select({
+                id: issues.id,
+                assigneeAgentId: issues.assigneeAgentId,
+                status: issues.status,
+                squadId: issues.squadId,
+            })
+                .from(issues)
+                .where(eq(issues.id, parentIssueId))
+                .then((rows) => rows[0] ?? null);
+            if (!parent || !parent.assigneeAgentId || ["backlog", "done", "cancelled"].includes(parent.status)) {
+                return null;
+            }
+            const children = await db
+                .select({
+                id: issues.id,
+                identifier: issues.identifier,
+                title: issues.title,
+                status: issues.status,
+                priority: issues.priority,
+                assigneeAgentId: issues.assigneeAgentId,
+                assigneeUserId: issues.assigneeUserId,
+                updatedAt: issues.updatedAt,
+            })
+                .from(issues)
+                .where(and(eq(issues.squadId, parent.squadId), eq(issues.parentId, parentIssueId)))
+                .orderBy(asc(issues.issueNumber), asc(issues.createdAt));
+            if (children.length === 0)
+                return null;
+            if (!children.every((child) => child.status === "done" || child.status === "cancelled")) {
+                return null;
+            }
+            const childIdsForSummaries = children.slice(0, MAX_CHILD_COMPLETION_SUMMARIES).map((child) => child.id);
+            const commentRows = childIdsForSummaries.length > 0
+                ? await db
+                    .select({
+                    issueId: issueComments.issueId,
+                    body: issueComments.body,
+                    createdAt: issueComments.createdAt,
+                })
+                    .from(issueComments)
+                    .where(and(eq(issueComments.squadId, parent.squadId), inArray(issueComments.issueId, childIdsForSummaries)))
+                    .orderBy(desc(issueComments.createdAt), desc(issueComments.id))
+                : [];
+            const latestCommentByIssueId = new Map();
+            for (const comment of commentRows) {
+                if (!latestCommentByIssueId.has(comment.issueId)) {
+                    latestCommentByIssueId.set(comment.issueId, comment.body);
+                }
+            }
+            const childIssueSummaries = children
+                .slice(0, MAX_CHILD_COMPLETION_SUMMARIES)
+                .map((child) => ({
+                ...child,
+                summary: truncateInlineSummary(latestCommentByIssueId.get(child.id)),
+            }));
+            return {
+                id: parent.id,
+                assigneeAgentId: parent.assigneeAgentId,
+                childIssueIds: children.map((child) => child.id),
+                childIssueSummaries,
+                childIssueSummaryTruncated: children.length > childIssueSummaries.length,
+            };
+        },
+        createChild: async (parentIssueId, data) => {
+            const parent = await db
+                .select()
+                .from(issues)
+                .where(eq(issues.id, parentIssueId))
+                .then((rows) => rows[0] ?? null);
+            if (!parent)
+                throw notFound("Parent issue not found");
+            const [{ childCount }] = await db
+                .select({ childCount: sql `count(*)::int` })
+                .from(issues)
+                .where(and(eq(issues.squadId, parent.squadId), eq(issues.parentId, parent.id)));
+            if (childCount >= MAX_CHILD_ISSUES_CREATED_BY_HELPER) {
+                throw unprocessable(`Parent issue already has the maximum ${MAX_CHILD_ISSUES_CREATED_BY_HELPER} child issues for this helper`);
+            }
+            const { acceptanceCriteria, blockParentUntilDone, actorAgentId, actorUserId, ...issueData } = data;
+            const child = await issueService(db).create(parent.squadId, {
+                ...issueData,
+                parentId: parent.id,
+                projectId: issueData.projectId ?? parent.projectId,
+                goalId: issueData.goalId ?? parent.goalId,
+                requestDepth: clampIssueRequestDepth(Math.max(clampIssueRequestDepth(parent.requestDepth) + 1, issueData.requestDepth ?? 0)),
+                description: appendAcceptanceCriteriaToDescription(issueData.description, acceptanceCriteria),
+                inheritExecutionWorkspaceFromIssueId: parent.id,
+            });
+            if (blockParentUntilDone) {
+                const existingBlockers = await db
+                    .select({ blockerIssueId: issueRelations.issueId })
+                    .from(issueRelations)
+                    .where(and(eq(issueRelations.squadId, parent.squadId), eq(issueRelations.relatedIssueId, parent.id), eq(issueRelations.type, "blocks")));
+                await syncBlockedByIssueIds(parent.id, parent.squadId, [...new Set([...existingBlockers.map((row) => row.blockerIssueId), child.id])], { agentId: actorAgentId ?? null, userId: actorUserId ?? null });
+            }
+            return {
+                issue: child,
+                parentBlockerAdded: Boolean(blockParentUntilDone),
+            };
+        },
+        decomposeAcceptedPlan: async (sourceIssueId, data) => {
+            const sourceIssue = await db
+                .select({
+                id: issues.id,
+                squadId: issues.squadId,
+                projectId: issues.projectId,
+                goalId: issues.goalId,
+            })
+                .from(issues)
+                .where(eq(issues.id, sourceIssueId))
+                .then((rows) => rows[0] ?? null);
+            if (!sourceIssue)
+                throw notFound("Source issue not found");
+            const requestFingerprint = createAcceptedPlanDecompositionRequestFingerprint({
+                acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+                children: data.children,
+            });
+            const initialClaim = await db.transaction(async (tx) => {
+                await tx.execute(sql `select ${issues.id} from ${issues} where ${issues.id} = ${sourceIssue.id} for update`);
+                const belongsToPlanDocument = await tx
+                    .select({ revisionId: documentRevisions.id })
+                    .from(issueDocuments)
+                    .innerJoin(documentRevisions, eq(issueDocuments.documentId, documentRevisions.documentId))
+                    .where(and(eq(issueDocuments.squadId, sourceIssue.squadId), eq(issueDocuments.issueId, sourceIssue.id), eq(issueDocuments.key, "plan"), eq(documentRevisions.id, data.acceptedPlanRevisionId)))
+                    .then((rows) => rows[0] ?? null);
+                if (!belongsToPlanDocument) {
+                    throw unprocessable("acceptedPlanRevisionId must belong to the source issue's plan document");
+                }
+                const acceptedInteraction = await findAcceptedPlanDocumentInteraction(tx, {
+                    squadId: sourceIssue.squadId,
+                    sourceIssueId: sourceIssue.id,
+                    acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+                });
+                if (!acceptedInteraction) {
+                    throw unprocessable("acceptedPlanRevisionId must have an accepted plan confirmation");
+                }
+                const existing = await tx
+                    .select()
+                    .from(issuePlanDecompositions)
+                    .where(and(eq(issuePlanDecompositions.squadId, sourceIssue.squadId), eq(issuePlanDecompositions.sourceIssueId, sourceIssue.id), eq(issuePlanDecompositions.acceptedPlanRevisionId, data.acceptedPlanRevisionId)))
+                    .then((rows) => rows[0] ?? null);
+                const now = new Date();
+                if (!existing) {
+                    const [created] = await tx
+                        .insert(issuePlanDecompositions)
+                        .values({
+                        squadId: sourceIssue.squadId,
+                        sourceIssueId: sourceIssue.id,
+                        acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+                        acceptedInteractionId: acceptedInteraction.id,
+                        status: "in_flight",
+                        requestFingerprint,
+                        requestedChildCount: data.children.length,
+                        requestedChildren: data.children,
+                        childIssueIds: [],
+                        ownerAgentId: data.actorAgentId ?? null,
+                        ownerUserId: data.actorUserId ?? null,
+                        ownerRunId: data.actorRunId ?? null,
+                        updatedAt: now,
+                    })
+                        .returning();
+                    if (!created)
+                        throw new Error("Failed to create accepted-plan decomposition claim");
+                    return created;
+                }
+                if (existing.requestFingerprint !== requestFingerprint) {
+                    throw conflict("Accepted-plan decomposition already exists for this revision with a different child set");
+                }
+                return existing;
+            });
+            let currentClaim = initialClaim;
+            const newlyCreatedIssues = [];
+            while (true) {
+                const step = await db.transaction(async (tx) => {
+                    await tx.execute(sql `select ${issuePlanDecompositions.id}
+                from ${issuePlanDecompositions}
+                where ${issuePlanDecompositions.id} = ${currentClaim.id}
+                for update`);
+                    const claim = await tx
+                        .select()
+                        .from(issuePlanDecompositions)
+                        .where(eq(issuePlanDecompositions.id, currentClaim.id))
+                        .then((rows) => rows[0] ?? null);
+                    if (!claim)
+                        throw notFound("Accepted-plan decomposition claim not found");
+                    if (claim.requestFingerprint !== requestFingerprint) {
+                        throw conflict("Accepted-plan decomposition already exists for this revision with a different child set");
+                    }
+                    const existingChildIssueIds = normalizeIssuePlanDecompositionChildIds(claim.childIssueIds);
+                    if (claim.status === "completed" || existingChildIssueIds.length >= data.children.length) {
+                        const nextIds = existingChildIssueIds.slice(0, data.children.length);
+                        if (claim.status === "completed" && nextIds.length === data.children.length) {
+                            return {
+                                claim,
+                                createdIssue: null,
+                            };
+                        }
+                        const completedAt = claim.completedAt ?? new Date();
+                        const ownerPatch = await resolveAcceptedPlanClaimOwner({
+                            dbOrTx: tx,
+                            claim,
+                            actorAgentId: data.actorAgentId,
+                            actorUserId: data.actorUserId,
+                            actorRunId: data.actorRunId,
+                        });
+                        const [completed] = await tx
+                            .update(issuePlanDecompositions)
+                            .set({
+                            status: "completed",
+                            childIssueIds: nextIds,
+                            completedAt,
+                            ...ownerPatch,
+                            updatedAt: completedAt,
+                        })
+                            .where(eq(issuePlanDecompositions.id, claim.id))
+                            .returning();
+                        if (!completed)
+                            throw new Error("Failed to complete accepted-plan decomposition claim");
+                        return {
+                            claim: completed,
+                            createdIssue: null,
+                        };
+                    }
+                    const nextChildInput = data.children[existingChildIssueIds.length];
+                    if (!nextChildInput) {
+                        throw new Error("Accepted-plan decomposition child cursor moved past the requested children");
+                    }
+                    const createdChild = await issueService(tx).createChild(sourceIssue.id, nextChildInput);
+                    const nextIds = [...existingChildIssueIds, createdChild.issue.id];
+                    const now = new Date();
+                    const nextStatus = nextIds.length === data.children.length ? "completed" : "in_flight";
+                    const ownerPatch = await resolveAcceptedPlanClaimOwner({
+                        dbOrTx: tx,
+                        claim,
+                        actorAgentId: data.actorAgentId,
+                        actorUserId: data.actorUserId,
+                        actorRunId: data.actorRunId,
+                    });
+                    const [updatedClaim] = await tx
+                        .update(issuePlanDecompositions)
+                        .set({
+                        status: nextStatus,
+                        childIssueIds: nextIds,
+                        completedAt: nextStatus === "completed" ? now : null,
+                        ...ownerPatch,
+                        updatedAt: now,
+                    })
+                        .where(eq(issuePlanDecompositions.id, claim.id))
+                        .returning();
+                    if (!updatedClaim)
+                        throw new Error("Failed to persist accepted-plan decomposition progress");
+                    return {
+                        claim: updatedClaim,
+                        createdIssue: createdChild.issue,
+                    };
+                });
+                currentClaim = step.claim;
+                if (step.createdIssue) {
+                    newlyCreatedIssues.push(step.createdIssue);
+                }
+                if (step.claim.status === "completed")
+                    break;
+            }
+            const childIssueIds = normalizeIssuePlanDecompositionChildIds(currentClaim.childIssueIds);
+            const childIssueRows = childIssueIds.length > 0
+                ? await db
+                    .select()
+                    .from(issues)
+                    .where(and(eq(issues.squadId, sourceIssue.squadId), inArray(issues.id, childIssueIds)))
+                : [];
+            const childIssueMap = new Map(childIssueRows.map((row) => [row.id, row]));
+            const orderedChildIssues = childIssueIds
+                .map((childIssueId) => childIssueMap.get(childIssueId))
+                .filter((row) => Boolean(row));
+            const decomposition = serializeAcceptedPlanDecomposition(currentClaim);
+            return {
+                decomposition,
+                childIssueIds: decomposition.childIssueIds,
+                childIssues: orderedChildIssues,
+                newlyCreatedIssues,
+            };
+        },
+        listAcceptedPlanDecompositions: async (sourceIssueId) => {
+            const sourceIssue = await db
+                .select({ id: issues.id, squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, sourceIssueId))
+                .then((rows) => rows[0] ?? null);
+            if (!sourceIssue)
+                return [];
+            const rows = await db
+                .select({
+                decomposition: issuePlanDecompositions,
+                revisionNumber: documentRevisions.revisionNumber,
+            })
+                .from(issuePlanDecompositions)
+                .leftJoin(documentRevisions, eq(documentRevisions.id, issuePlanDecompositions.acceptedPlanRevisionId))
+                .where(and(eq(issuePlanDecompositions.squadId, sourceIssue.squadId), eq(issuePlanDecompositions.sourceIssueId, sourceIssue.id)))
+                .orderBy(desc(issuePlanDecompositions.createdAt));
+            if (rows.length === 0)
+                return [];
+            const allChildIds = new Set();
+            for (const row of rows) {
+                for (const childId of normalizeIssuePlanDecompositionChildIds(row.decomposition.childIssueIds)) {
+                    allChildIds.add(childId);
+                }
+            }
+            const childIssueRows = allChildIds.size > 0
+                ? await db
+                    .select({
+                    id: issues.id,
+                    identifier: issues.identifier,
+                    title: issues.title,
+                    status: issues.status,
+                    priority: issues.priority,
+                    assigneeAgentId: issues.assigneeAgentId,
+                    assigneeUserId: issues.assigneeUserId,
+                })
+                    .from(issues)
+                    .where(and(eq(issues.squadId, sourceIssue.squadId), inArray(issues.id, Array.from(allChildIds))))
+                : [];
+            const childIssueMap = new Map(childIssueRows.map((row) => [row.id, row]));
+            return rows.map((row) => {
+                const decomposition = serializeAcceptedPlanDecomposition(row.decomposition);
+                const childIds = decomposition.childIssueIds;
+                return {
+                    ...decomposition,
+                    acceptedPlanRevisionNumber: row.revisionNumber ?? null,
+                    childIssues: childIds
+                        .map((childId) => childIssueMap.get(childId) ?? null)
+                        .filter((entry) => entry !== null),
+                };
+            });
+        },
+        create: async (squadId, data) => {
+            const { labelIds: inputLabelIds, blockedByIssueIds, inheritExecutionWorkspaceFromIssueId, ...issueData } = data;
+            const isolatedWorkspacesEnabled = (await instanceSettings.getExperimental()).enableIsolatedWorkspaces;
+            if (!isolatedWorkspacesEnabled) {
+                delete issueData.executionWorkspaceId;
+                delete issueData.executionWorkspacePreference;
+                delete issueData.executionWorkspaceSettings;
+            }
+            if (data.assigneeAgentId && data.assigneeUserId) {
+                throw unprocessable("Issue can only have one assignee");
+            }
+            if (data.assigneeAgentId) {
+                await assertAssignableAgent(squadId, data.assigneeAgentId);
+            }
+            if (data.assigneeUserId) {
+                await assertAssignableUser(squadId, data.assigneeUserId);
+            }
+            if (data.status === "in_progress" && !data.assigneeAgentId && !data.assigneeUserId) {
+                throw unprocessable("in_progress issues require an assignee");
+            }
+            return db.transaction(async (tx) => {
+                const defaultSquadGoal = await getDefaultSquadGoal(tx, squadId);
+                const projectGoalId = await getProjectDefaultGoalId(tx, squadId, issueData.projectId);
+                let projectWorkspaceId = issueData.projectWorkspaceId ?? null;
+                let executionWorkspaceId = issueData.executionWorkspaceId ?? null;
+                let executionWorkspacePreference = issueData.executionWorkspacePreference ?? null;
+                let executionWorkspaceSettings = issueData.executionWorkspaceSettings ?? null;
+                const workspaceInheritanceIssueId = inheritExecutionWorkspaceFromIssueId ?? issueData.parentId ?? null;
+                const hasExplicitExecutionWorkspaceOverride = issueData.executionWorkspaceId !== undefined ||
+                    issueData.executionWorkspacePreference !== undefined ||
+                    issueData.executionWorkspaceSettings !== undefined;
+                if (workspaceInheritanceIssueId) {
+                    const workspaceSource = await getWorkspaceInheritanceIssue(tx, squadId, workspaceInheritanceIssueId);
+                    if (projectWorkspaceId == null && workspaceSource.projectWorkspaceId) {
+                        projectWorkspaceId = workspaceSource.projectWorkspaceId;
+                    }
+                    if (isolatedWorkspacesEnabled &&
+                        !hasExplicitExecutionWorkspaceOverride &&
+                        workspaceSource.executionWorkspaceId) {
+                        const sourceWorkspace = await tx
+                            .select({
+                            id: executionWorkspaces.id,
+                            mode: executionWorkspaces.mode,
+                        })
+                            .from(executionWorkspaces)
+                            .where(eq(executionWorkspaces.id, workspaceSource.executionWorkspaceId))
+                            .then((rows) => rows[0] ?? null);
+                        if (sourceWorkspace) {
+                            executionWorkspaceId = sourceWorkspace.id;
+                            executionWorkspacePreference = "reuse_existing";
+                            executionWorkspaceSettings = {
+                                ...(workspaceSource.executionWorkspaceSettings ?? {}),
+                                mode: issueExecutionWorkspaceModeForPersistedWorkspace(sourceWorkspace.mode),
+                            };
+                        }
+                    }
+                }
+                // Cache the project policy lookup for this insert. Both the
+                // default-settings block and the assignee-environment-promotion block
+                // need the same row; without caching they'd issue two round-trips.
+                let projectPolicyCached = null;
+                let projectPolicyLoaded = false;
+                const loadProjectPolicyOnce = async () => {
+                    if (projectPolicyLoaded)
+                        return projectPolicyCached;
+                    projectPolicyLoaded = true;
+                    if (!issueData.projectId)
+                        return null;
+                    const projectRow = await tx
+                        .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
+                        .from(projects)
+                        .where(and(eq(projects.id, issueData.projectId), eq(projects.squadId, squadId)))
+                        .then((rows) => rows[0] ?? null);
+                    projectPolicyCached = parseProjectExecutionWorkspacePolicy(projectRow?.executionWorkspacePolicy);
+                    return projectPolicyCached;
+                };
+                if (executionWorkspaceSettings == null &&
+                    executionWorkspaceId == null &&
+                    issueData.projectId) {
+                    executionWorkspaceSettings =
+                        defaultIssueExecutionWorkspaceSettingsForProject(gateProjectExecutionWorkspacePolicy(await loadProjectPolicyOnce(), isolatedWorkspacesEnabled));
+                }
+                if (data.assigneeAgentId && isolatedWorkspacesEnabled) {
+                    const currentWorkspaceSettings = executionWorkspaceSettings == null
+                        ? {}
+                        : parseObject(executionWorkspaceSettings);
+                    const issueHasEnvironmentSelection = Object.prototype.hasOwnProperty.call(currentWorkspaceSettings, "environmentId");
+                    // Don't promote the assignee agent's defaultEnvironmentId if either
+                    // the issue or the project policy already specifies an environment.
+                    // resolveExecutionWorkspaceEnvironmentId treats issue settings as
+                    // higher priority than project policy, so promoting the agent's
+                    // default to issue settings would invert the documented priority
+                    // (project policy must win over agent default when explicitly set).
+                    let projectHasEnvironmentSelection = false;
+                    if (!issueHasEnvironmentSelection && issueData.projectId) {
+                        const projectPolicy = await loadProjectPolicyOnce();
+                        projectHasEnvironmentSelection = projectPolicy?.environmentId !== undefined;
+                    }
+                    if (!issueHasEnvironmentSelection && !projectHasEnvironmentSelection) {
+                        const assigneeAgent = await tx
+                            .select({ defaultEnvironmentId: agents.defaultEnvironmentId })
+                            .from(agents)
+                            .where(and(eq(agents.id, data.assigneeAgentId), eq(agents.squadId, squadId)))
+                            .then((rows) => rows[0] ?? null);
+                        if (typeof assigneeAgent?.defaultEnvironmentId === "string" && assigneeAgent.defaultEnvironmentId.length > 0) {
+                            executionWorkspaceSettings = {
+                                ...currentWorkspaceSettings,
+                                environmentId: assigneeAgent.defaultEnvironmentId,
+                            };
+                        }
+                    }
+                }
+                if (!projectWorkspaceId && issueData.projectId) {
+                    const project = await tx
+                        .select({
+                        executionWorkspacePolicy: projects.executionWorkspacePolicy,
+                    })
+                        .from(projects)
+                        .where(and(eq(projects.id, issueData.projectId), eq(projects.squadId, squadId)))
+                        .then((rows) => rows[0] ?? null);
+                    const projectPolicy = parseProjectExecutionWorkspacePolicy(project?.executionWorkspacePolicy);
+                    projectWorkspaceId = projectPolicy?.defaultProjectWorkspaceId ?? null;
+                    if (!projectWorkspaceId) {
+                        projectWorkspaceId = await tx
+                            .select({ id: projectWorkspaces.id })
+                            .from(projectWorkspaces)
+                            .where(and(eq(projectWorkspaces.projectId, issueData.projectId), eq(projectWorkspaces.squadId, squadId)))
+                            .orderBy(desc(projectWorkspaces.isPrimary), asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id))
+                            .then((rows) => rows[0]?.id ?? null);
+                    }
+                }
+                if (projectWorkspaceId) {
+                    await assertValidProjectWorkspace(squadId, issueData.projectId, projectWorkspaceId, tx);
+                }
+                if (executionWorkspaceId) {
+                    await assertValidExecutionWorkspace(squadId, issueData.projectId, executionWorkspaceId, tx);
+                }
+                // Self-correcting counter: use MAX(issue_number) + 1 if the counter
+                // has drifted below the actual max, preventing identifier collisions.
+                const [maxRow] = await tx
+                    .select({ maxNum: sql `coalesce(max(${issues.issueNumber}), 0)` })
+                    .from(issues)
+                    .where(eq(issues.squadId, squadId));
+                const currentMax = maxRow?.maxNum ?? 0;
+                const [squad] = await tx
+                    .update(squads)
+                    .set({
+                    issueCounter: sql `greatest(${squads.issueCounter}, ${currentMax}) + 1`,
+                })
+                    .where(eq(squads.id, squadId))
+                    .returning({ issueCounter: squads.issueCounter, issuePrefix: squads.issuePrefix });
+                const issueNumber = squad.issueCounter;
+                const identifier = `${squad.issuePrefix}-${issueNumber}`;
+                const values = {
+                    ...issueData,
+                    requestDepth: clampIssueRequestDepth(issueData.requestDepth),
+                    originKind: issueData.originKind ?? "manual",
+                    goalId: resolveIssueGoalId({
+                        projectId: issueData.projectId,
+                        goalId: issueData.goalId,
+                        projectGoalId,
+                        defaultGoalId: defaultSquadGoal?.id ?? null,
+                    }),
+                    ...(projectWorkspaceId ? { projectWorkspaceId } : {}),
+                    ...(executionWorkspaceId ? { executionWorkspaceId } : {}),
+                    ...(executionWorkspacePreference ? { executionWorkspacePreference } : {}),
+                    ...(executionWorkspaceSettings ? { executionWorkspaceSettings } : {}),
+                    squadId,
+                    issueNumber,
+                    identifier,
+                };
+                if (values.status === "in_progress" && !values.startedAt) {
+                    values.startedAt = new Date();
+                }
+                if (values.status === "done") {
+                    values.completedAt = new Date();
+                }
+                if (values.status === "cancelled") {
+                    values.cancelledAt = new Date();
+                }
+                Object.assign(values, buildInitialIssueMonitorFields({
+                    policy: normalizeIssueExecutionPolicy(issueData.executionPolicy ?? null),
+                    status: values.status ?? "backlog",
+                    assigneeAgentId: values.assigneeAgentId ?? null,
+                    assigneeUserId: values.assigneeUserId ?? null,
+                }));
+                const [issue] = await tx.insert(issues).values(values).returning();
+                if (inputLabelIds) {
+                    await syncIssueLabels(issue.id, squadId, inputLabelIds, tx);
+                }
+                if (blockedByIssueIds !== undefined) {
+                    await syncBlockedByIssueIds(issue.id, squadId, blockedByIssueIds, {
+                        agentId: issueData.createdByAgentId ?? null,
+                        userId: issueData.createdByUserId ?? null,
+                    }, tx);
+                }
+                const [enriched] = await withIssueLabels(tx, [issue]);
+                return enriched;
+            });
+        },
+        update: async (id, data, dbOrTx = db) => {
+            const existing = await dbOrTx
+                .select()
+                .from(issues)
+                .where(eq(issues.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!existing)
+                return null;
+            const { labelIds: nextLabelIds, blockedByIssueIds, actorAgentId, actorUserId, ...issueData } = data;
+            const isolatedWorkspacesEnabled = (await instanceSettings.getExperimental()).enableIsolatedWorkspaces;
+            if (!isolatedWorkspacesEnabled) {
+                delete issueData.executionWorkspaceId;
+                delete issueData.executionWorkspacePreference;
+                delete issueData.executionWorkspaceSettings;
+            }
+            if (issueData.status) {
+                assertTransition(existing.status, issueData.status);
+            }
+            const patch = {
+                ...issueData,
+                updatedAt: new Date(),
+            };
+            if (issueData.requestDepth !== undefined) {
+                patch.requestDepth = clampIssueRequestDepth(issueData.requestDepth);
+            }
+            const nextAssigneeAgentId = issueData.assigneeAgentId !== undefined ? issueData.assigneeAgentId : existing.assigneeAgentId;
+            const nextAssigneeUserId = issueData.assigneeUserId !== undefined ? issueData.assigneeUserId : existing.assigneeUserId;
+            if (nextAssigneeAgentId && nextAssigneeUserId) {
+                throw unprocessable("Issue can only have one assignee");
+            }
+            if (patch.status === "in_progress" && !nextAssigneeAgentId && !nextAssigneeUserId) {
+                throw unprocessable("in_progress issues require an assignee");
+            }
+            if (patch.status === "in_progress") {
+                const unresolvedBlockerIssueIds = blockedByIssueIds !== undefined
+                    ? await listUnresolvedBlockerIssueIds(dbOrTx, existing.squadId, blockedByIssueIds)
+                    : (await listIssueDependencyReadinessMap(dbOrTx, existing.squadId, [id])).get(id)?.unresolvedBlockerIssueIds ?? [];
+                if (unresolvedBlockerIssueIds.length > 0) {
+                    throw unprocessable("Issue is blocked by unresolved blockers", { unresolvedBlockerIssueIds });
+                }
+            }
+            if (issueData.assigneeAgentId) {
+                await assertAssignableAgent(existing.squadId, issueData.assigneeAgentId);
+            }
+            if (issueData.assigneeUserId) {
+                await assertAssignableUser(existing.squadId, issueData.assigneeUserId);
+            }
+            const nextProjectId = issueData.projectId !== undefined ? issueData.projectId : existing.projectId;
+            const nextProjectWorkspaceId = issueData.projectWorkspaceId !== undefined ? issueData.projectWorkspaceId : existing.projectWorkspaceId;
+            const nextExecutionWorkspaceId = issueData.executionWorkspaceId !== undefined ? issueData.executionWorkspaceId : existing.executionWorkspaceId;
+            const nextExecutionWorkspacePreference = issueData.executionWorkspacePreference !== undefined
+                ? issueData.executionWorkspacePreference
+                : existing.executionWorkspacePreference;
+            const nextExecutionWorkspaceSettings = issueData.executionWorkspaceSettings !== undefined
+                ? parseIssueExecutionWorkspaceSettings(issueData.executionWorkspaceSettings)
+                : parseIssueExecutionWorkspaceSettings(existing.executionWorkspaceSettings);
+            if (nextProjectWorkspaceId) {
+                await assertValidProjectWorkspace(existing.squadId, nextProjectId, nextProjectWorkspaceId);
+            }
+            if (nextExecutionWorkspaceId) {
+                await assertValidExecutionWorkspace(existing.squadId, nextProjectId, nextExecutionWorkspaceId);
+            }
+            applyStatusSideEffects(issueData.status, patch);
+            if (issueData.status && issueData.status !== "done") {
+                patch.completedAt = null;
+            }
+            if (issueData.status && issueData.status !== "cancelled") {
+                patch.cancelledAt = null;
+            }
+            if (issueData.status && issueData.status !== "in_progress") {
+                patch.checkoutRunId = null;
+                // Fix B: also clear the execution lock when leaving in_progress
+                patch.executionRunId = null;
+                patch.executionAgentNameKey = null;
+                patch.executionLockedAt = null;
+            }
+            if ((issueData.assigneeAgentId !== undefined && issueData.assigneeAgentId !== existing.assigneeAgentId) ||
+                (issueData.assigneeUserId !== undefined && issueData.assigneeUserId !== existing.assigneeUserId)) {
+                patch.checkoutRunId = null;
+                // Fix B: clear execution lock on reassignment, matching checkoutRunId clear
+                patch.executionRunId = null;
+                patch.executionAgentNameKey = null;
+                patch.executionLockedAt = null;
+            }
+            const runUpdate = async (tx) => {
+                const defaultSquadGoal = await getDefaultSquadGoal(tx, existing.squadId);
+                const [currentProjectGoalId, nextProjectGoalId] = await Promise.all([
+                    getProjectDefaultGoalId(tx, existing.squadId, existing.projectId),
+                    getProjectDefaultGoalId(tx, existing.squadId, issueData.projectId !== undefined ? issueData.projectId : existing.projectId),
+                ]);
+                // Mirror the create() path: when the assignee changes to a non-null
+                // agent, default the issue's executionWorkspaceSettings.environmentId
+                // to the new agent's defaultEnvironmentId. Skip when:
+                //   - this update explicitly sets executionWorkspaceSettings.environmentId
+                //     (caller is making a deliberate override; respect it), OR
+                //   - the project policy already specifies an environmentId (project
+                //     policy must win over agent default per the documented priority
+                //     order in resolveExecutionWorkspaceEnvironmentId), OR
+                //   - the issue already has an environmentId that was *not* the prior
+                //     assignee's default (i.e., the operator set it explicitly in an
+                //     earlier update; preserve their choice). When the existing
+                //     environmentId matches the prior assignee's default, treat it as
+                //     auto-promoted and refresh it to the new assignee's default.
+                const assigneeChanged = issueData.assigneeAgentId !== undefined &&
+                    issueData.assigneeAgentId !== null &&
+                    issueData.assigneeAgentId !== existing.assigneeAgentId;
+                const explicitEnvInThisUpdate = issueData.executionWorkspaceSettings !== undefined &&
+                    Object.prototype.hasOwnProperty.call(parseObject(issueData.executionWorkspaceSettings), "environmentId");
+                if (assigneeChanged && isolatedWorkspacesEnabled && !explicitEnvInThisUpdate) {
+                    let projectHasEnvironmentSelection = false;
+                    if (nextProjectId) {
+                        const projectRow = await tx
+                            .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
+                            .from(projects)
+                            .where(and(eq(projects.id, nextProjectId), eq(projects.squadId, existing.squadId)))
+                            .then((rows) => rows[0] ?? null);
+                        const projectPolicy = parseProjectExecutionWorkspacePolicy(projectRow?.executionWorkspacePolicy);
+                        projectHasEnvironmentSelection = projectPolicy?.environmentId !== undefined;
+                    }
+                    if (!projectHasEnvironmentSelection) {
+                        const baseSettings = nextExecutionWorkspaceSettings == null
+                            ? {}
+                            : parseObject(nextExecutionWorkspaceSettings);
+                        const existingEnvId = typeof baseSettings.environmentId === "string"
+                            ? baseSettings.environmentId
+                            : null;
+                        const agentRows = await tx
+                            .select({ id: agents.id, defaultEnvironmentId: agents.defaultEnvironmentId })
+                            .from(agents)
+                            .where(and(eq(agents.squadId, existing.squadId), inArray(agents.id, [issueData.assigneeAgentId, existing.assigneeAgentId].filter((value) => typeof value === "string"))));
+                        const newAssignee = agentRows.find((row) => row.id === issueData.assigneeAgentId);
+                        const previousAssignee = existing.assigneeAgentId
+                            ? agentRows.find((row) => row.id === existing.assigneeAgentId)
+                            : null;
+                        const newDefaultEnvId = typeof newAssignee?.defaultEnvironmentId === "string" && newAssignee.defaultEnvironmentId.length > 0
+                            ? newAssignee.defaultEnvironmentId
+                            : null;
+                        const previousDefaultEnvId = typeof previousAssignee?.defaultEnvironmentId === "string" && previousAssignee.defaultEnvironmentId.length > 0
+                            ? previousAssignee.defaultEnvironmentId
+                            : null;
+                        const existingEnvWasAutoPromoted = existingEnvId === null ||
+                            (previousDefaultEnvId !== null && existingEnvId === previousDefaultEnvId);
+                        if (newDefaultEnvId && existingEnvWasAutoPromoted) {
+                            patch.executionWorkspaceSettings = {
+                                ...baseSettings,
+                                environmentId: newDefaultEnvId,
+                            };
+                        }
+                    }
+                }
+                patch.goalId = resolveNextIssueGoalId({
+                    currentProjectId: existing.projectId,
+                    currentGoalId: existing.goalId,
+                    currentProjectGoalId,
+                    projectId: issueData.projectId,
+                    goalId: issueData.goalId,
+                    projectGoalId: nextProjectGoalId,
+                    defaultGoalId: defaultSquadGoal?.id ?? null,
+                });
+                const updated = await tx
+                    .update(issues)
+                    .set(patch)
+                    .where(eq(issues.id, id))
+                    .returning()
+                    .then((rows) => rows[0] ?? null);
+                if (!updated)
+                    return null;
+                if (nextLabelIds !== undefined) {
+                    await syncIssueLabels(updated.id, existing.squadId, nextLabelIds, tx);
+                }
+                if (blockedByIssueIds !== undefined) {
+                    await syncBlockedByIssueIds(updated.id, existing.squadId, blockedByIssueIds, {
+                        agentId: actorAgentId ?? null,
+                        userId: actorUserId ?? null,
+                    }, tx);
+                }
+                if (issueData.executionWorkspaceSettings !== undefined &&
+                    nextExecutionWorkspaceId &&
+                    nextExecutionWorkspacePreference === "reuse_existing") {
+                    const workspace = await tx
+                        .select({
+                        id: executionWorkspaces.id,
+                        metadata: executionWorkspaces.metadata,
+                    })
+                        .from(executionWorkspaces)
+                        .where(and(eq(executionWorkspaces.id, nextExecutionWorkspaceId), eq(executionWorkspaces.squadId, existing.squadId)))
+                        .then((rows) => rows[0] ?? null);
+                    if (workspace) {
+                        await tx
+                            .update(executionWorkspaces)
+                            .set({
+                            metadata: mergeExecutionWorkspaceConfig(workspace.metadata ?? null, buildReusedExecutionWorkspaceConfigPatchFromIssueSettings(nextExecutionWorkspaceSettings)),
+                            updatedAt: new Date(),
+                        })
+                            .where(eq(executionWorkspaces.id, workspace.id));
+                    }
+                }
+                const [enriched] = await withIssueLabels(tx, [updated]);
+                if ((issueData.status === "done" || issueData.status === "cancelled") &&
+                    existing.status !== issueData.status &&
+                    existing.originKind === RECOVERY_ORIGIN_KINDS.issueGraphLivenessEscalation) {
+                    const parsedIncident = parseIssueGraphLivenessIncidentKey(existing.originId);
+                    if (parsedIncident?.issueId && parsedIncident.squadId === existing.squadId) {
+                        await tx
+                            .delete(issueRelations)
+                            .where(and(eq(issueRelations.squadId, existing.squadId), eq(issueRelations.issueId, existing.id), eq(issueRelations.relatedIssueId, parsedIncident.issueId), eq(issueRelations.type, "blocks")));
+                    }
+                }
+                return enriched;
+            };
+            return dbOrTx === db ? db.transaction(runUpdate) : runUpdate(dbOrTx);
+        },
+        clearExecutionWorkspaceEnvironmentSelection: async (squadId, environmentId) => {
+            const rows = await db
+                .select({
+                id: issues.id,
+                executionWorkspaceSettings: issues.executionWorkspaceSettings,
+            })
+                .from(issues)
+                .where(eq(issues.squadId, squadId));
+            let cleared = 0;
+            for (const row of rows) {
+                const settings = parseIssueExecutionWorkspaceSettings(row.executionWorkspaceSettings);
+                if (settings?.environmentId !== environmentId)
+                    continue;
+                await db
+                    .update(issues)
+                    .set({
+                    executionWorkspaceSettings: {
+                        ...settings,
+                        environmentId: null,
+                    },
+                    updatedAt: new Date(),
+                })
+                    .where(eq(issues.id, row.id));
+                cleared += 1;
+            }
+            return cleared;
+        },
+        remove: (id) => db.transaction(async (tx) => {
+            const attachmentAssetIds = await tx
+                .select({ assetId: issueAttachments.assetId })
+                .from(issueAttachments)
+                .where(eq(issueAttachments.issueId, id));
+            const issueDocumentIds = await tx
+                .select({ documentId: issueDocuments.documentId })
+                .from(issueDocuments)
+                .where(eq(issueDocuments.issueId, id));
+            const removedIssue = await tx
+                .delete(issues)
+                .where(eq(issues.id, id))
+                .returning()
+                .then((rows) => rows[0] ?? null);
+            if (removedIssue && attachmentAssetIds.length > 0) {
+                await tx
+                    .delete(assets)
+                    .where(inArray(assets.id, attachmentAssetIds.map((row) => row.assetId)));
+            }
+            if (removedIssue && issueDocumentIds.length > 0) {
+                await tx
+                    .delete(documents)
+                    .where(inArray(documents.id, issueDocumentIds.map((row) => row.documentId)));
+            }
+            if (!removedIssue)
+                return null;
+            const [enriched] = await withIssueLabels(tx, [removedIssue]);
+            return enriched;
+        }),
+        checkout: async (id, agentId, expectedStatuses, checkoutRunId) => {
+            const issueSquad = await db
+                .select({ squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!issueSquad)
+                throw notFound("Issue not found");
+            await assertAssignableAgent(issueSquad.squadId, agentId);
+            const now = new Date();
+            const activePauseHold = await treeControlSvc.getActivePauseHoldGate(issueSquad.squadId, id);
+            if (activePauseHold &&
+                !(await isTreeHoldInteractionCheckoutAllowed(issueSquad.squadId, checkoutRunId, activePauseHold))) {
+                throw conflict("Issue checkout blocked by active subtree pause hold", {
+                    issueId: id,
+                    holdId: activePauseHold.holdId,
+                    rootIssueId: activePauseHold.rootIssueId,
+                    mode: activePauseHold.mode,
+                    securityPrinciples: ["Complete Mediation", "Fail Securely", "Secure Defaults"],
+                });
+            }
+            await clearExecutionRunIfTerminal(id);
+            const dependencyReadiness = await listIssueDependencyReadinessMap(db, issueSquad.squadId, [id]);
+            const unresolvedBlockerIssueIds = dependencyReadiness.get(id)?.unresolvedBlockerIssueIds ?? [];
+            if (unresolvedBlockerIssueIds.length > 0) {
+                throw unprocessable("Issue is blocked by unresolved blockers", { unresolvedBlockerIssueIds });
+            }
+            const sameRunAssigneeCondition = checkoutRunId
+                ? and(eq(issues.assigneeAgentId, agentId), or(isNull(issues.checkoutRunId), eq(issues.checkoutRunId, checkoutRunId)))
+                : and(eq(issues.assigneeAgentId, agentId), isNull(issues.checkoutRunId));
+            const executionLockCondition = checkoutRunId
+                ? or(isNull(issues.executionRunId), eq(issues.executionRunId, checkoutRunId))
+                : isNull(issues.executionRunId);
+            const updated = await db
+                .update(issues)
+                .set({
+                assigneeAgentId: agentId,
+                assigneeUserId: null,
+                checkoutRunId,
+                executionRunId: checkoutRunId,
+                status: "in_progress",
+                startedAt: now,
+                updatedAt: now,
+            })
+                .where(and(eq(issues.id, id), inArray(issues.status, expectedStatuses), or(isNull(issues.assigneeAgentId), sameRunAssigneeCondition), executionLockCondition))
+                .returning()
+                .then((rows) => rows[0] ?? null);
+            if (updated) {
+                const [enriched] = await withIssueLabels(db, [updated]);
+                return enriched;
+            }
+            const current = await db
+                .select({
+                id: issues.id,
+                status: issues.status,
+                assigneeAgentId: issues.assigneeAgentId,
+                checkoutRunId: issues.checkoutRunId,
+                executionRunId: issues.executionRunId,
+            })
+                .from(issues)
+                .where(eq(issues.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!current)
+                throw notFound("Issue not found");
+            if (current.assigneeAgentId === agentId &&
+                current.status === "in_progress" &&
+                current.checkoutRunId == null &&
+                (current.executionRunId == null || current.executionRunId === checkoutRunId) &&
+                checkoutRunId) {
+                const adopted = await db
+                    .update(issues)
+                    .set({
+                    checkoutRunId,
+                    executionRunId: checkoutRunId,
+                    updatedAt: new Date(),
+                })
+                    .where(and(eq(issues.id, id), eq(issues.status, "in_progress"), eq(issues.assigneeAgentId, agentId), isNull(issues.checkoutRunId), or(isNull(issues.executionRunId), eq(issues.executionRunId, checkoutRunId))))
+                    .returning()
+                    .then((rows) => rows[0] ?? null);
+                if (adopted)
+                    return adopted;
+            }
+            if (checkoutRunId &&
+                current.assigneeAgentId === agentId &&
+                current.status === "in_progress" &&
+                current.checkoutRunId &&
+                current.checkoutRunId !== checkoutRunId) {
+                const adopted = await adoptStaleCheckoutRun({
+                    issueId: id,
+                    actorAgentId: agentId,
+                    actorRunId: checkoutRunId,
+                    expectedCheckoutRunId: current.checkoutRunId,
+                });
+                if (adopted) {
+                    const row = await db.select().from(issues).where(eq(issues.id, id)).then((rows) => rows[0] ?? null);
+                    if (!row)
+                        throw notFound("Issue not found");
+                    const [enriched] = await withIssueLabels(db, [row]);
+                    return enriched;
+                }
+            }
+            // If this run already owns it and it's in_progress, return it (no self-409)
+            if (current.assigneeAgentId === agentId &&
+                current.status === "in_progress" &&
+                sameRunLock(current.checkoutRunId, checkoutRunId)) {
+                const row = await db.select().from(issues).where(eq(issues.id, id)).then((rows) => rows[0] ?? null);
+                if (!row)
+                    throw notFound("Issue not found");
+                const [enriched] = await withIssueLabels(db, [row]);
+                return enriched;
+            }
+            throw conflict("Issue checkout conflict", {
+                issueId: current.id,
+                status: current.status,
+                assigneeAgentId: current.assigneeAgentId,
+                checkoutRunId: current.checkoutRunId,
+                executionRunId: current.executionRunId,
+            });
+        },
+        assertCheckoutOwner: async (id, actorAgentId, actorRunId) => {
+            await clearExecutionRunIfTerminal(id);
+            const current = await db
+                .select({
+                id: issues.id,
+                status: issues.status,
+                assigneeAgentId: issues.assigneeAgentId,
+                checkoutRunId: issues.checkoutRunId,
+                executionRunId: issues.executionRunId,
+            })
+                .from(issues)
+                .where(eq(issues.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!current)
+                throw notFound("Issue not found");
+            if (current.status === "in_progress" &&
+                current.assigneeAgentId === actorAgentId &&
+                sameRunLock(current.checkoutRunId, actorRunId)) {
+                return { ...current, adoptedFromRunId: null };
+            }
+            if (actorRunId &&
+                current.status === "in_progress" &&
+                current.assigneeAgentId === actorAgentId &&
+                current.checkoutRunId == null &&
+                (current.executionRunId == null || current.executionRunId === actorRunId)) {
+                const adopted = await adoptUnownedCheckoutRun({
+                    issueId: id,
+                    actorAgentId,
+                    actorRunId,
+                });
+                if (adopted) {
+                    return {
+                        ...adopted,
+                        adoptedFromRunId: null,
+                    };
+                }
+            }
+            if (actorRunId &&
+                current.status === "in_progress" &&
+                current.assigneeAgentId === actorAgentId &&
+                current.checkoutRunId &&
+                current.checkoutRunId !== actorRunId) {
+                const adopted = await adoptStaleCheckoutRun({
+                    issueId: id,
+                    actorAgentId,
+                    actorRunId,
+                    expectedCheckoutRunId: current.checkoutRunId,
+                });
+                if (adopted) {
+                    return {
+                        ...adopted,
+                        adoptedFromRunId: current.checkoutRunId,
+                    };
+                }
+            }
+            throw conflict("Issue run ownership conflict", {
+                issueId: current.id,
+                status: current.status,
+                assigneeAgentId: current.assigneeAgentId,
+                checkoutRunId: current.checkoutRunId,
+                executionRunId: current.executionRunId,
+                actorAgentId,
+                actorRunId,
+            });
+        },
+        release: async (id, actorAgentId, actorRunId) => {
+            await clearExecutionRunIfTerminal(id);
+            const existing = await db
+                .select()
+                .from(issues)
+                .where(eq(issues.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!existing)
+                return null;
+            if (actorAgentId && existing.assigneeAgentId && existing.assigneeAgentId !== actorAgentId) {
+                throw conflict("Only assignee can release issue");
+            }
+            if (actorAgentId &&
+                existing.status === "in_progress" &&
+                existing.assigneeAgentId === actorAgentId &&
+                existing.checkoutRunId &&
+                !sameRunLock(existing.checkoutRunId, actorRunId ?? null)) {
+                const stale = await isTerminalOrMissingHeartbeatRun(existing.checkoutRunId);
+                if (!stale) {
+                    throw conflict("Only checkout run can release issue", {
+                        issueId: existing.id,
+                        assigneeAgentId: existing.assigneeAgentId,
+                        checkoutRunId: existing.checkoutRunId,
+                        actorRunId: actorRunId ?? null,
+                    });
+                }
+            }
+            const updated = await db
+                .update(issues)
+                .set({
+                status: "todo",
+                assigneeAgentId: null,
+                checkoutRunId: null,
+                executionRunId: null,
+                executionAgentNameKey: null,
+                executionLockedAt: null,
+                updatedAt: new Date(),
+            })
+                .where(eq(issues.id, id))
+                .returning()
+                .then((rows) => rows[0] ?? null);
+            if (!updated)
+                return null;
+            const [enriched] = await withIssueLabels(db, [updated]);
+            return enriched;
+        },
+        adminForceRelease: async (id, options = {}) => db.transaction(async (tx) => {
+            await tx.execute(sql `select ${issues.id} from ${issues} where ${issues.id} = ${id} for update`);
+            const existing = await tx
+                .select({
+                id: issues.id,
+                checkoutRunId: issues.checkoutRunId,
+                executionRunId: issues.executionRunId,
+            })
+                .from(issues)
+                .where(eq(issues.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!existing)
+                return null;
+            const patch = {
+                checkoutRunId: null,
+                executionRunId: null,
+                executionAgentNameKey: null,
+                executionLockedAt: null,
+                updatedAt: new Date(),
+            };
+            if (options.clearAssignee) {
+                patch.assigneeAgentId = null;
+            }
+            const updated = await tx
+                .update(issues)
+                .set(patch)
+                .where(eq(issues.id, id))
+                .returning()
+                .then((rows) => rows[0] ?? null);
+            if (!updated)
+                return null;
+            const [enriched] = await withIssueLabels(tx, [updated]);
+            return {
+                issue: enriched,
+                previous: {
+                    checkoutRunId: existing.checkoutRunId,
+                    executionRunId: existing.executionRunId,
+                },
+            };
+        }),
+        listLabels: (squadId) => db.select().from(labels).where(eq(labels.squadId, squadId)).orderBy(asc(labels.name), asc(labels.id)),
+        getLabelById: (id) => db
+            .select()
+            .from(labels)
+            .where(eq(labels.id, id))
+            .then((rows) => rows[0] ?? null),
+        createLabel: async (squadId, data) => {
+            const [created] = await db
+                .insert(labels)
+                .values({
+                squadId,
+                name: data.name.trim(),
+                color: data.color,
+            })
+                .returning();
+            return created;
+        },
+        deleteLabel: async (id) => db
+            .delete(labels)
+            .where(eq(labels.id, id))
+            .returning()
+            .then((rows) => rows[0] ?? null),
+        listComments: async (issueId, opts) => {
+            const order = opts?.order === "asc" ? "asc" : "desc";
+            const afterCommentId = opts?.afterCommentId?.trim() || null;
+            const limit = opts?.limit && opts.limit > 0
+                ? Math.min(Math.floor(opts.limit), MAX_ISSUE_COMMENT_PAGE_LIMIT)
+                : null;
+            const conditions = [eq(issueComments.issueId, issueId)];
+            if (afterCommentId) {
+                const anchor = await db
+                    .select({
+                    id: issueComments.id,
+                    createdAt: issueComments.createdAt,
+                })
+                    .from(issueComments)
+                    .where(and(eq(issueComments.issueId, issueId), eq(issueComments.id, afterCommentId)))
+                    .then((rows) => rows[0] ?? null);
+                if (!anchor)
+                    return [];
+                const anchorCreatedAt = anchor.createdAt instanceof Date
+                    ? anchor.createdAt
+                    : new Date(String(anchor.createdAt));
+                conditions.push(order === "asc"
+                    ? or(gt(issueComments.createdAt, anchorCreatedAt), and(eq(issueComments.createdAt, anchorCreatedAt), gt(issueComments.id, anchor.id)))
+                    : or(lt(issueComments.createdAt, anchorCreatedAt), and(eq(issueComments.createdAt, anchorCreatedAt), lt(issueComments.id, anchor.id))));
+            }
+            const query = db
+                .select()
+                .from(issueComments)
+                .where(and(...conditions))
+                .orderBy(order === "asc" ? asc(issueComments.createdAt) : desc(issueComments.createdAt), order === "asc" ? asc(issueComments.id) : desc(issueComments.id));
+            const comments = limit ? await query.limit(limit) : await query;
+            const { censorUsernameInLogs } = await instanceSettings.getGeneral();
+            const enrichedComments = await enrichCommentsWithDerivedAgentAttribution(comments);
+            return enrichedComments.map((comment) => redactIssueComment(comment, censorUsernameInLogs));
+        },
+        getCommentCursor: async (issueId) => {
+            const [latest, countRow] = await Promise.all([
+                db
+                    .select({
+                    latestCommentId: issueComments.id,
+                    latestCommentAt: issueComments.createdAt,
+                })
+                    .from(issueComments)
+                    .where(eq(issueComments.issueId, issueId))
+                    .orderBy(desc(issueComments.createdAt), desc(issueComments.id))
+                    .limit(1)
+                    .then((rows) => rows[0] ?? null),
+                db
+                    .select({
+                    totalComments: sql `count(*)::int`,
+                })
+                    .from(issueComments)
+                    .where(eq(issueComments.issueId, issueId))
+                    .then((rows) => rows[0] ?? null),
+            ]);
+            return {
+                totalComments: Number(countRow?.totalComments ?? 0),
+                latestCommentId: latest?.latestCommentId ?? null,
+                latestCommentAt: latest?.latestCommentAt ?? null,
+            };
+        },
+        getComment: async (commentId) => {
+            const { censorUsernameInLogs } = await instanceSettings.getGeneral();
+            const comment = await db
+                .select()
+                .from(issueComments)
+                .where(eq(issueComments.id, commentId))
+                .then((rows) => rows[0] ?? null);
+            if (!comment)
+                return null;
+            const [enrichedComment] = await enrichCommentsWithDerivedAgentAttribution([comment]);
+            return redactIssueComment(enrichedComment ?? comment, censorUsernameInLogs);
+        },
+        removeComment: async (commentId) => {
+            const currentUserRedactionOptions = {
+                enabled: (await instanceSettings.getGeneral()).censorUsernameInLogs,
+            };
+            return db.transaction(async (tx) => {
+                const [comment] = await tx
+                    .delete(issueComments)
+                    .where(eq(issueComments.id, commentId))
+                    .returning();
+                if (!comment)
+                    return null;
+                await tx
+                    .update(issues)
+                    .set({ updatedAt: new Date() })
+                    .where(eq(issues.id, comment.issueId));
+                return redactIssueComment(comment, currentUserRedactionOptions.enabled);
+            });
+        },
+        addComment: async (issueId, body, actor, options) => {
+            const issue = await db
+                .select({ squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, issueId))
+                .then((rows) => rows[0] ?? null);
+            if (!issue)
+                throw notFound("Issue not found");
+            const currentUserRedactionOptions = {
+                enabled: (await instanceSettings.getGeneral()).censorUsernameInLogs,
+            };
+            const redactedBody = redactCurrentUserText(body, currentUserRedactionOptions);
+            const authorType = issueCommentAuthorTypeSchema.parse(options?.authorType ?? (actor.agentId ? "agent" : actor.userId ? "user" : "system"));
+            assertIssueCommentAuthorTypeAllowed(actor, authorType);
+            const presentation = issueCommentPresentationSchema.nullable().parse(options?.presentation ?? null);
+            const metadata = issueCommentMetadataSchema.nullable().parse(options?.metadata ?? null);
+            const createdAt = options?.createdAt ? new Date(options.createdAt) : null;
+            const [comment] = await db
+                .insert(issueComments)
+                .values({
+                squadId: issue.squadId,
+                issueId,
+                authorAgentId: actor.agentId ?? null,
+                authorUserId: actor.userId ?? null,
+                authorType,
+                createdByRunId: actor.runId ?? null,
+                body: redactedBody,
+                presentation,
+                metadata,
+                ...(createdAt && !Number.isNaN(createdAt.getTime()) ? { createdAt } : {}),
+            })
+                .returning();
+            // Update issue's updatedAt so comment activity is reflected in recency sorting
+            await db
+                .update(issues)
+                .set({ updatedAt: new Date() })
+                .where(eq(issues.id, issueId));
+            return redactIssueComment(comment, currentUserRedactionOptions.enabled);
+        },
+        createAttachment: async (input) => {
+            const issue = await db
+                .select({ id: issues.id, squadId: issues.squadId })
+                .from(issues)
+                .where(eq(issues.id, input.issueId))
+                .then((rows) => rows[0] ?? null);
+            if (!issue)
+                throw notFound("Issue not found");
+            if (input.issueCommentId) {
+                const comment = await db
+                    .select({ id: issueComments.id, squadId: issueComments.squadId, issueId: issueComments.issueId })
+                    .from(issueComments)
+                    .where(eq(issueComments.id, input.issueCommentId))
+                    .then((rows) => rows[0] ?? null);
+                if (!comment)
+                    throw notFound("Issue comment not found");
+                if (comment.squadId !== issue.squadId || comment.issueId !== issue.id) {
+                    throw unprocessable("Attachment comment must belong to same issue and squad");
+                }
+            }
+            return db.transaction(async (tx) => {
+                const [asset] = await tx
+                    .insert(assets)
+                    .values({
+                    squadId: issue.squadId,
+                    provider: input.provider,
+                    objectKey: input.objectKey,
+                    contentType: input.contentType,
+                    byteSize: input.byteSize,
+                    sha256: input.sha256,
+                    originalFilename: input.originalFilename ?? null,
+                    createdByAgentId: input.createdByAgentId ?? null,
+                    createdByUserId: input.createdByUserId ?? null,
+                })
+                    .returning();
+                const [attachment] = await tx
+                    .insert(issueAttachments)
+                    .values({
+                    squadId: issue.squadId,
+                    issueId: issue.id,
+                    assetId: asset.id,
+                    issueCommentId: input.issueCommentId ?? null,
+                })
+                    .returning();
+                return {
+                    id: attachment.id,
+                    squadId: attachment.squadId,
+                    issueId: attachment.issueId,
+                    issueCommentId: attachment.issueCommentId,
+                    assetId: attachment.assetId,
+                    provider: asset.provider,
+                    objectKey: asset.objectKey,
+                    contentType: asset.contentType,
+                    byteSize: asset.byteSize,
+                    sha256: asset.sha256,
+                    originalFilename: asset.originalFilename,
+                    createdByAgentId: asset.createdByAgentId,
+                    createdByUserId: asset.createdByUserId,
+                    createdAt: attachment.createdAt,
+                    updatedAt: attachment.updatedAt,
+                };
+            });
+        },
+        listAttachments: async (issueId) => db
+            .select({
+            id: issueAttachments.id,
+            squadId: issueAttachments.squadId,
+            issueId: issueAttachments.issueId,
+            issueCommentId: issueAttachments.issueCommentId,
+            assetId: issueAttachments.assetId,
+            provider: assets.provider,
+            objectKey: assets.objectKey,
+            contentType: assets.contentType,
+            byteSize: assets.byteSize,
+            sha256: assets.sha256,
+            originalFilename: assets.originalFilename,
+            createdByAgentId: assets.createdByAgentId,
+            createdByUserId: assets.createdByUserId,
+            createdAt: issueAttachments.createdAt,
+            updatedAt: issueAttachments.updatedAt,
+        })
+            .from(issueAttachments)
+            .innerJoin(assets, eq(issueAttachments.assetId, assets.id))
+            .where(eq(issueAttachments.issueId, issueId))
+            .orderBy(desc(issueAttachments.createdAt)),
+        getAttachmentById: async (id) => db
+            .select({
+            id: issueAttachments.id,
+            squadId: issueAttachments.squadId,
+            issueId: issueAttachments.issueId,
+            issueCommentId: issueAttachments.issueCommentId,
+            assetId: issueAttachments.assetId,
+            provider: assets.provider,
+            objectKey: assets.objectKey,
+            contentType: assets.contentType,
+            byteSize: assets.byteSize,
+            sha256: assets.sha256,
+            originalFilename: assets.originalFilename,
+            createdByAgentId: assets.createdByAgentId,
+            createdByUserId: assets.createdByUserId,
+            createdAt: issueAttachments.createdAt,
+            updatedAt: issueAttachments.updatedAt,
+        })
+            .from(issueAttachments)
+            .innerJoin(assets, eq(issueAttachments.assetId, assets.id))
+            .where(eq(issueAttachments.id, id))
+            .then((rows) => rows[0] ?? null),
+        removeAttachment: async (id) => db.transaction(async (tx) => {
+            const existing = await tx
+                .select({
+                id: issueAttachments.id,
+                squadId: issueAttachments.squadId,
+                issueId: issueAttachments.issueId,
+                issueCommentId: issueAttachments.issueCommentId,
+                assetId: issueAttachments.assetId,
+                provider: assets.provider,
+                objectKey: assets.objectKey,
+                contentType: assets.contentType,
+                byteSize: assets.byteSize,
+                sha256: assets.sha256,
+                originalFilename: assets.originalFilename,
+                createdByAgentId: assets.createdByAgentId,
+                createdByUserId: assets.createdByUserId,
+                createdAt: issueAttachments.createdAt,
+                updatedAt: issueAttachments.updatedAt,
+            })
+                .from(issueAttachments)
+                .innerJoin(assets, eq(issueAttachments.assetId, assets.id))
+                .where(eq(issueAttachments.id, id))
+                .then((rows) => rows[0] ?? null);
+            if (!existing)
+                return null;
+            await tx.delete(issueAttachments).where(eq(issueAttachments.id, id));
+            await tx.delete(assets).where(eq(assets.id, existing.assetId));
+            return existing;
+        }),
+        findMentionedAgents: async (squadId, body) => {
+            const re = /\B@([^\s@,!?.]+)/g;
+            const tokens = new Set();
+            let m;
+            while ((m = re.exec(body)) !== null) {
+                const normalized = normalizeAgentMentionToken(m[1]);
+                if (normalized)
+                    tokens.add(normalized.toLowerCase());
+            }
+            const explicitAgentMentionIds = extractAgentMentionIds(body);
+            if (tokens.size === 0 && explicitAgentMentionIds.length === 0)
+                return [];
+            const rows = await db.select({ id: agents.id, name: agents.name })
+                .from(agents).where(eq(agents.squadId, squadId));
+            const resolved = new Set(explicitAgentMentionIds);
+            for (const agent of rows) {
+                if (tokens.has(agent.name.toLowerCase())) {
+                    resolved.add(agent.id);
+                }
+            }
+            return [...resolved];
+        },
+        findMentionedProjectIds: async (issueId, opts) => {
+            const issue = await db
+                .select({
+                squadId: issues.squadId,
+                title: issues.title,
+                description: issues.description,
+            })
+                .from(issues)
+                .where(eq(issues.id, issueId))
+                .then((rows) => rows[0] ?? null);
+            if (!issue)
+                return [];
+            const mentionedIds = new Set();
+            for (const source of [issue.title, issue.description ?? ""]) {
+                for (const projectId of extractProjectMentionIds(source)) {
+                    mentionedIds.add(projectId);
+                }
+            }
+            if (opts?.includeCommentBodies !== false) {
+                const comments = await db
+                    .select({ body: issueComments.body })
+                    .from(issueComments)
+                    .where(eq(issueComments.issueId, issueId));
+                for (const comment of comments) {
+                    for (const projectId of extractProjectMentionIds(comment.body)) {
+                        mentionedIds.add(projectId);
+                    }
+                }
+            }
+            if (mentionedIds.size === 0)
+                return [];
+            const rows = await db
+                .select({ id: projects.id })
+                .from(projects)
+                .where(and(eq(projects.squadId, issue.squadId), inArray(projects.id, [...mentionedIds])));
+            const valid = new Set(rows.map((row) => row.id));
+            return [...mentionedIds].filter((projectId) => valid.has(projectId));
+        },
+        getAncestors: async (issueId) => {
+            const raw = [];
+            const visited = new Set([issueId]);
+            const start = await db.select().from(issues).where(eq(issues.id, issueId)).then(r => r[0] ?? null);
+            let currentId = start?.parentId ?? null;
+            while (currentId && !visited.has(currentId) && raw.length < 50) {
+                visited.add(currentId);
+                const parent = await db.select({
+                    id: issues.id, identifier: issues.identifier, title: issues.title, description: issues.description,
+                    status: issues.status, priority: issues.priority,
+                    assigneeAgentId: issues.assigneeAgentId, projectId: issues.projectId,
+                    goalId: issues.goalId, parentId: issues.parentId,
+                }).from(issues).where(eq(issues.id, currentId)).then(r => r[0] ?? null);
+                if (!parent)
+                    break;
+                raw.push({
+                    id: parent.id, identifier: parent.identifier ?? null, title: parent.title, description: parent.description ?? null,
+                    status: parent.status, priority: parent.priority,
+                    assigneeAgentId: parent.assigneeAgentId ?? null,
+                    projectId: parent.projectId ?? null, goalId: parent.goalId ?? null,
+                });
+                currentId = parent.parentId ?? null;
+            }
+            // Batch-fetch referenced projects and goals
+            const projectIds = [...new Set(raw.map(a => a.projectId).filter((id) => id != null))];
+            const goalIds = [...new Set(raw.map(a => a.goalId).filter((id) => id != null))];
+            const projectMap = new Map();
+            const goalMap = new Map();
+            if (projectIds.length > 0) {
+                const workspaceRows = await db
+                    .select()
+                    .from(projectWorkspaces)
+                    .where(inArray(projectWorkspaces.projectId, projectIds))
+                    .orderBy(desc(projectWorkspaces.isPrimary), asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id));
+                const workspaceMap = new Map();
+                for (const workspace of workspaceRows) {
+                    const existing = workspaceMap.get(workspace.projectId);
+                    if (existing)
+                        existing.push(workspace);
+                    else
+                        workspaceMap.set(workspace.projectId, [workspace]);
+                }
+                const rows = await db.select({
+                    id: projects.id, name: projects.name, description: projects.description,
+                    status: projects.status, goalId: projects.goalId,
+                }).from(projects).where(inArray(projects.id, projectIds));
+                for (const r of rows) {
+                    const projectWorkspaceRows = workspaceMap.get(r.id) ?? [];
+                    const workspaces = projectWorkspaceRows.map((workspace) => ({
+                        id: workspace.id,
+                        squadId: workspace.squadId,
+                        projectId: workspace.projectId,
+                        name: workspace.name,
+                        cwd: workspace.cwd,
+                        repoUrl: workspace.repoUrl ?? null,
+                        repoRef: workspace.repoRef ?? null,
+                        metadata: workspace.metadata ?? null,
+                        isPrimary: workspace.isPrimary,
+                        createdAt: workspace.createdAt,
+                        updatedAt: workspace.updatedAt,
+                    }));
+                    const primaryWorkspace = workspaces.find((workspace) => workspace.isPrimary) ?? workspaces[0] ?? null;
+                    projectMap.set(r.id, {
+                        ...r,
+                        workspaces,
+                        primaryWorkspace,
+                    });
+                    // Also collect goalIds from projects
+                    if (r.goalId && !goalIds.includes(r.goalId))
+                        goalIds.push(r.goalId);
+                }
+            }
+            if (goalIds.length > 0) {
+                const rows = await db.select({
+                    id: goals.id, title: goals.title, description: goals.description,
+                    level: goals.level, status: goals.status,
+                }).from(goals).where(inArray(goals.id, goalIds));
+                for (const r of rows)
+                    goalMap.set(r.id, r);
+            }
+            return raw.map(a => ({
+                ...a,
+                project: a.projectId ? projectMap.get(a.projectId) ?? null : null,
+                goal: a.goalId ? goalMap.get(a.goalId) ?? null : null,
+            }));
+        },
+    };
+}
+//# sourceMappingURL=issues.js.map