@paperclipai/server 0.3.1 → 2026.3.17-canary.2

package/dist/services/heartbeat.js

@@ -1,5 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
 import { and, asc, desc, eq, gt, inArray, sql } from "drizzle-orm";
 import { agents, agentRuntimeState, agentTaskSessions, agentWakeupRequests, heartbeatRunEvents, heartbeatRuns, issues, projects, projectWorkspaces, } from "@paperclipai/db";
 import { conflict, notFound } from "../errors.js";
@@ -10,19 +12,91 @@ import { getServerAdapter, runningProcesses } from "../adapters/index.js";
 import { createLocalAgentJwt } from "../agent-auth-jwt.js";
 import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js";
 import { costService } from "./costs.js";
+import { budgetService } from "./budgets.js";
 import { secretService } from "./secrets.js";
-import { resolveDefaultAgentWorkspaceDir } from "../home-paths.js";
+import { resolveDefaultAgentWorkspaceDir, resolveManagedProjectWorkspaceDir } from "../home-paths.js";
 import { summarizeHeartbeatRunResultJson } from "./heartbeat-run-summary.js";
-import { buildWorkspaceReadyComment, ensureRuntimeServicesForRun, persistAdapterManagedRuntimeServices, realizeExecutionWorkspace, releaseRuntimeServicesForRun, } from "./workspace-runtime.js";
+import { buildWorkspaceReadyComment, cleanupExecutionWorkspaceArtifacts, ensureRuntimeServicesForRun, persistAdapterManagedRuntimeServices, realizeExecutionWorkspace, releaseRuntimeServicesForRun, sanitizeRuntimeServiceBaseEnv, } from "./workspace-runtime.js";
 import { issueService } from "./issues.js";
-import { buildExecutionWorkspaceAdapterConfig, parseIssueExecutionWorkspaceSettings, parseProjectExecutionWorkspacePolicy, resolveExecutionWorkspaceMode, } from "./execution-workspace-policy.js";
+import { executionWorkspaceService } from "./execution-workspaces.js";
+import { workspaceOperationService } from "./workspace-operations.js";
+import { buildExecutionWorkspaceAdapterConfig, gateProjectExecutionWorkspacePolicy, parseIssueExecutionWorkspaceSettings, parseProjectExecutionWorkspacePolicy, resolveExecutionWorkspaceMode, } from "./execution-workspace-policy.js";
+import { instanceSettingsService } from "./instance-settings.js";
 import { redactCurrentUserText, redactCurrentUserValue } from "../log-redaction.js";
+import { hasSessionCompactionThresholds, resolveSessionCompactionPolicy, } from "@paperclipai/adapter-utils";
 const MAX_LIVE_LOG_CHUNK_BYTES = 8 * 1024;
 const HEARTBEAT_MAX_CONCURRENT_RUNS_DEFAULT = 1;
 const HEARTBEAT_MAX_CONCURRENT_RUNS_MAX = 10;
 const DEFERRED_WAKE_CONTEXT_KEY = "_paperclipWakeContext";
 const startLocksByAgent = new Map();
 const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__";
+const MANAGED_WORKSPACE_GIT_CLONE_TIMEOUT_MS = 10 * 60 * 1000;
+const execFile = promisify(execFileCallback);
+const SESSIONED_LOCAL_ADAPTERS = new Set([
+    "claude_local",
+    "codex_local",
+    "cursor",
+    "gemini_local",
+    "opencode_local",
+    "pi_local",
+]);
+function deriveRepoNameFromRepoUrl(repoUrl) {
+    const trimmed = repoUrl?.trim() ?? "";
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = new URL(trimmed);
+        const cleanedPath = parsed.pathname.replace(/\/+$/, "");
+        const repoName = cleanedPath.split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") ?? "";
+        return repoName || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function ensureManagedProjectWorkspace(input) {
+    const cwd = resolveManagedProjectWorkspaceDir({
+        companyId: input.companyId,
+        projectId: input.projectId,
+        repoName: deriveRepoNameFromRepoUrl(input.repoUrl),
+    });
+    await fs.mkdir(path.dirname(cwd), { recursive: true });
+    const stats = await fs.stat(cwd).catch(() => null);
+    if (!input.repoUrl) {
+        if (!stats) {
+            await fs.mkdir(cwd, { recursive: true });
+        }
+        return { cwd, warning: null };
+    }
+    const gitDirExists = await fs
+        .stat(path.resolve(cwd, ".git"))
+        .then((entry) => entry.isDirectory())
+        .catch(() => false);
+    if (gitDirExists) {
+        return { cwd, warning: null };
+    }
+    if (stats) {
+        const entries = await fs.readdir(cwd).catch(() => []);
+        if (entries.length > 0) {
+            return {
+                cwd,
+                warning: `Managed workspace path "${cwd}" already exists but is not a git checkout. Using it as-is.`,
+            };
+        }
+        await fs.rm(cwd, { recursive: true, force: true });
+    }
+    try {
+        await execFile("git", ["clone", input.repoUrl, cwd], {
+            env: sanitizeRuntimeServiceBaseEnv(process.env),
+            timeout: MANAGED_WORKSPACE_GIT_CLONE_TIMEOUT_MS,
+        });
+        return { cwd, warning: null };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to prepare managed checkout for "${input.repoUrl}" at "${cwd}": ${reason}`);
+    }
+}
 const heartbeatRunListColumns = {
     id: heartbeatRuns.id,
     companyId: heartbeatRuns.companyId,
@@ -76,9 +150,122 @@ async function withAgentStartLock(agentId, fn) {
         }
     }
 }
+export function prioritizeProjectWorkspaceCandidatesForRun(rows, preferredWorkspaceId) {
+    if (!preferredWorkspaceId)
+        return rows;
+    const preferredIndex = rows.findIndex((row) => row.id === preferredWorkspaceId);
+    if (preferredIndex <= 0)
+        return rows;
+    return [rows[preferredIndex], ...rows.slice(0, preferredIndex), ...rows.slice(preferredIndex + 1)];
+}
 function readNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
+function normalizeLedgerBillingType(value) {
+    const raw = readNonEmptyString(value);
+    switch (raw) {
+        case "api":
+        case "metered_api":
+            return "metered_api";
+        case "subscription":
+        case "subscription_included":
+            return "subscription_included";
+        case "subscription_overage":
+            return "subscription_overage";
+        case "credits":
+            return "credits";
+        case "fixed":
+            return "fixed";
+        default:
+            return "unknown";
+    }
+}
+function resolveLedgerBiller(result) {
+    return readNonEmptyString(result.biller) ?? readNonEmptyString(result.provider) ?? "unknown";
+}
+function normalizeBilledCostCents(costUsd, billingType) {
+    if (billingType === "subscription_included")
+        return 0;
+    if (typeof costUsd !== "number" || !Number.isFinite(costUsd))
+        return 0;
+    return Math.max(0, Math.round(costUsd * 100));
+}
+async function resolveLedgerScopeForRun(db, companyId, run) {
+    const context = parseObject(run.contextSnapshot);
+    const contextIssueId = readNonEmptyString(context.issueId);
+    const contextProjectId = readNonEmptyString(context.projectId);
+    if (!contextIssueId) {
+        return {
+            issueId: null,
+            projectId: contextProjectId,
+        };
+    }
+    const issue = await db
+        .select({
+        id: issues.id,
+        projectId: issues.projectId,
+    })
+        .from(issues)
+        .where(and(eq(issues.id, contextIssueId), eq(issues.companyId, companyId)))
+        .then((rows) => rows[0] ?? null);
+    return {
+        issueId: issue?.id ?? null,
+        projectId: issue?.projectId ?? contextProjectId,
+    };
+}
+function normalizeUsageTotals(usage) {
+    if (!usage)
+        return null;
+    return {
+        inputTokens: Math.max(0, Math.floor(asNumber(usage.inputTokens, 0))),
+        cachedInputTokens: Math.max(0, Math.floor(asNumber(usage.cachedInputTokens, 0))),
+        outputTokens: Math.max(0, Math.floor(asNumber(usage.outputTokens, 0))),
+    };
+}
+function readRawUsageTotals(usageJson) {
+    const parsed = parseObject(usageJson);
+    if (Object.keys(parsed).length === 0)
+        return null;
+    const inputTokens = Math.max(0, Math.floor(asNumber(parsed.rawInputTokens, asNumber(parsed.inputTokens, 0))));
+    const cachedInputTokens = Math.max(0, Math.floor(asNumber(parsed.rawCachedInputTokens, asNumber(parsed.cachedInputTokens, 0))));
+    const outputTokens = Math.max(0, Math.floor(asNumber(parsed.rawOutputTokens, asNumber(parsed.outputTokens, 0))));
+    if (inputTokens <= 0 && cachedInputTokens <= 0 && outputTokens <= 0) {
+        return null;
+    }
+    return {
+        inputTokens,
+        cachedInputTokens,
+        outputTokens,
+    };
+}
+function deriveNormalizedUsageDelta(current, previous) {
+    if (!current)
+        return null;
+    if (!previous)
+        return { ...current };
+    const inputTokens = current.inputTokens >= previous.inputTokens
+        ? current.inputTokens - previous.inputTokens
+        : current.inputTokens;
+    const cachedInputTokens = current.cachedInputTokens >= previous.cachedInputTokens
+        ? current.cachedInputTokens - previous.cachedInputTokens
+        : current.cachedInputTokens;
+    const outputTokens = current.outputTokens >= previous.outputTokens
+        ? current.outputTokens - previous.outputTokens
+        : current.outputTokens;
+    return {
+        inputTokens: Math.max(0, inputTokens),
+        cachedInputTokens: Math.max(0, cachedInputTokens),
+        outputTokens: Math.max(0, outputTokens),
+    };
+}
+function formatCount(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "0";
+    return value.toLocaleString("en-US");
+}
+export function parseSessionCompactionPolicy(agent) {
+    return resolveSessionCompactionPolicy(agent.adapterType, agent.runtimeConfig).policy;
+}
 export function resolveRuntimeSessionParamsForWorkspace(input) {
     const { agentId, previousSessionParams, resolvedWorkspace } = input;
     const previousSessionId = readNonEmptyString(previousSessionParams?.sessionId);
@@ -164,26 +351,19 @@ function deriveTaskKey(contextSnapshot, payload) {
         null);
 }
 export function shouldResetTaskSessionForWake(contextSnapshot) {
+    if (contextSnapshot?.forceFreshSession === true)
+        return true;
     const wakeReason = readNonEmptyString(contextSnapshot?.wakeReason);
     if (wakeReason === "issue_assigned")
         return true;
-    const wakeSource = readNonEmptyString(contextSnapshot?.wakeSource);
-    if (wakeSource === "timer")
-        return true;
-    const wakeTriggerDetail = readNonEmptyString(contextSnapshot?.wakeTriggerDetail);
-    return wakeSource === "on_demand" && wakeTriggerDetail === "manual";
+    return false;
 }
 function describeSessionResetReason(contextSnapshot) {
+    if (contextSnapshot?.forceFreshSession === true)
+        return "forceFreshSession was requested";
     const wakeReason = readNonEmptyString(contextSnapshot?.wakeReason);
     if (wakeReason === "issue_assigned")
         return "wake reason is issue_assigned";
-    const wakeSource = readNonEmptyString(contextSnapshot?.wakeSource);
-    if (wakeSource === "timer")
-        return "wake source is timer";
-    const wakeTriggerDetail = readNonEmptyString(contextSnapshot?.wakeTriggerDetail);
-    if (wakeSource === "on_demand" && wakeTriggerDetail === "manual") {
-        return "this is a manual invoke";
-    }
     return null;
 }
 function deriveCommentId(contextSnapshot, payload) {
@@ -328,9 +508,17 @@ function resolveNextSessionState(input) {
     };
 }
 export function heartbeatService(db) {
+    const instanceSettings = instanceSettingsService(db);
     const runLogStore = getRunLogStore();
     const secretsSvc = secretService(db);
     const issuesSvc = issueService(db);
+    const executionWorkspacesSvc = executionWorkspaceService(db);
+    const workspaceOperationsSvc = workspaceOperationService(db);
+    const activeRunExecutions = new Set();
+    const budgetHooks = {
+        cancelWorkForScope: cancelBudgetScopeWork,
+    };
+    const budgets = budgetService(db, budgetHooks);
     async function getAgent(agentId) {
         return db
             .select()
@@ -359,6 +547,143 @@ export function heartbeatService(db) {
             .where(and(eq(agentTaskSessions.companyId, companyId), eq(agentTaskSessions.agentId, agentId), eq(agentTaskSessions.adapterType, adapterType), eq(agentTaskSessions.taskKey, taskKey)))
             .then((rows) => rows[0] ?? null);
     }
+    async function getLatestRunForSession(agentId, sessionId, opts) {
+        const conditions = [
+            eq(heartbeatRuns.agentId, agentId),
+            eq(heartbeatRuns.sessionIdAfter, sessionId),
+        ];
+        if (opts?.excludeRunId) {
+            conditions.push(sql `${heartbeatRuns.id} <> ${opts.excludeRunId}`);
+        }
+        return db
+            .select()
+            .from(heartbeatRuns)
+            .where(and(...conditions))
+            .orderBy(desc(heartbeatRuns.createdAt))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+    }
+    async function getOldestRunForSession(agentId, sessionId) {
+        return db
+            .select({
+            id: heartbeatRuns.id,
+            createdAt: heartbeatRuns.createdAt,
+        })
+            .from(heartbeatRuns)
+            .where(and(eq(heartbeatRuns.agentId, agentId), eq(heartbeatRuns.sessionIdAfter, sessionId)))
+            .orderBy(asc(heartbeatRuns.createdAt), asc(heartbeatRuns.id))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+    }
+    async function resolveNormalizedUsageForSession(input) {
+        const { agentId, runId, sessionId, rawUsage } = input;
+        if (!sessionId || !rawUsage) {
+            return {
+                normalizedUsage: rawUsage,
+                previousRawUsage: null,
+                derivedFromSessionTotals: false,
+            };
+        }
+        const previousRun = await getLatestRunForSession(agentId, sessionId, { excludeRunId: runId });
+        const previousRawUsage = readRawUsageTotals(previousRun?.usageJson);
+        return {
+            normalizedUsage: deriveNormalizedUsageDelta(rawUsage, previousRawUsage),
+            previousRawUsage,
+            derivedFromSessionTotals: previousRawUsage !== null,
+        };
+    }
+    async function evaluateSessionCompaction(input) {
+        const { agent, sessionId, issueId } = input;
+        if (!sessionId) {
+            return {
+                rotate: false,
+                reason: null,
+                handoffMarkdown: null,
+                previousRunId: null,
+            };
+        }
+        const policy = parseSessionCompactionPolicy(agent);
+        if (!policy.enabled || !hasSessionCompactionThresholds(policy)) {
+            return {
+                rotate: false,
+                reason: null,
+                handoffMarkdown: null,
+                previousRunId: null,
+            };
+        }
+        const fetchLimit = Math.max(policy.maxSessionRuns > 0 ? policy.maxSessionRuns + 1 : 0, 4);
+        const runs = await db
+            .select({
+            id: heartbeatRuns.id,
+            createdAt: heartbeatRuns.createdAt,
+            usageJson: heartbeatRuns.usageJson,
+            resultJson: heartbeatRuns.resultJson,
+            error: heartbeatRuns.error,
+        })
+            .from(heartbeatRuns)
+            .where(and(eq(heartbeatRuns.agentId, agent.id), eq(heartbeatRuns.sessionIdAfter, sessionId)))
+            .orderBy(desc(heartbeatRuns.createdAt))
+            .limit(fetchLimit);
+        if (runs.length === 0) {
+            return {
+                rotate: false,
+                reason: null,
+                handoffMarkdown: null,
+                previousRunId: null,
+            };
+        }
+        const latestRun = runs[0] ?? null;
+        const oldestRun = policy.maxSessionAgeHours > 0
+            ? await getOldestRunForSession(agent.id, sessionId)
+            : runs[runs.length - 1] ?? latestRun;
+        const latestRawUsage = readRawUsageTotals(latestRun?.usageJson);
+        const sessionAgeHours = latestRun && oldestRun
+            ? Math.max(0, (new Date(latestRun.createdAt).getTime() - new Date(oldestRun.createdAt).getTime()) / (1000 * 60 * 60))
+            : 0;
+        let reason = null;
+        if (policy.maxSessionRuns > 0 && runs.length > policy.maxSessionRuns) {
+            reason = `session exceeded ${policy.maxSessionRuns} runs`;
+        }
+        else if (policy.maxRawInputTokens > 0 &&
+            latestRawUsage &&
+            latestRawUsage.inputTokens >= policy.maxRawInputTokens) {
+            reason =
+                `session raw input reached ${formatCount(latestRawUsage.inputTokens)} tokens ` +
+                    `(threshold ${formatCount(policy.maxRawInputTokens)})`;
+        }
+        else if (policy.maxSessionAgeHours > 0 && sessionAgeHours >= policy.maxSessionAgeHours) {
+            reason = `session age reached ${Math.floor(sessionAgeHours)} hours`;
+        }
+        if (!reason || !latestRun) {
+            return {
+                rotate: false,
+                reason: null,
+                handoffMarkdown: null,
+                previousRunId: latestRun?.id ?? null,
+            };
+        }
+        const latestSummary = summarizeHeartbeatRunResultJson(latestRun.resultJson);
+        const latestTextSummary = readNonEmptyString(latestSummary?.summary) ??
+            readNonEmptyString(latestSummary?.result) ??
+            readNonEmptyString(latestSummary?.message) ??
+            readNonEmptyString(latestRun.error);
+        const handoffMarkdown = [
+            "Paperclip session handoff:",
+            `- Previous session: ${sessionId}`,
+            issueId ? `- Issue: ${issueId}` : "",
+            `- Rotation reason: ${reason}`,
+            latestTextSummary ? `- Last run summary: ${latestTextSummary}` : "",
+            "Continue from the current task state. Rebuild only the minimum context you need.",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        return {
+            rotate: true,
+            reason,
+            handoffMarkdown,
+            previousRunId: latestRun.id,
+        };
+    }
     async function resolveSessionBeforeForWakeup(agent, taskKey) {
         if (taskKey) {
             const codec = getAdapterSessionCodec(agent.adapterType);
@@ -374,23 +699,30 @@ export function heartbeatService(db) {
     async function resolveWorkspaceForRun(agent, context, previousSessionParams, opts) {
         const issueId = readNonEmptyString(context.issueId);
         const contextProjectId = readNonEmptyString(context.projectId);
-        const issueProjectId = issueId
+        const contextProjectWorkspaceId = readNonEmptyString(context.projectWorkspaceId);
+        const issueProjectRef = issueId
             ? await db
-                .select({ projectId: issues.projectId })
+                .select({
+                projectId: issues.projectId,
+                projectWorkspaceId: issues.projectWorkspaceId,
+            })
                 .from(issues)
                 .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
-                .then((rows) => rows[0]?.projectId ?? null)
+                .then((rows) => rows[0] ?? null)
             : null;
+        const issueProjectId = issueProjectRef?.projectId ?? null;
+        const preferredProjectWorkspaceId = issueProjectRef?.projectWorkspaceId ?? contextProjectWorkspaceId ?? null;
         const resolvedProjectId = issueProjectId ?? contextProjectId;
         const useProjectWorkspace = opts?.useProjectWorkspace !== false;
         const workspaceProjectId = useProjectWorkspace ? resolvedProjectId : null;
-        const projectWorkspaceRows = workspaceProjectId
+        const unorderedProjectWorkspaceRows = workspaceProjectId
             ? await db
                 .select()
                 .from(projectWorkspaces)
                 .where(and(eq(projectWorkspaces.companyId, agent.companyId), eq(projectWorkspaces.projectId, workspaceProjectId)))
                 .orderBy(asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id))
             : [];
+        const projectWorkspaceRows = prioritizeProjectWorkspaceCandidatesForRun(unorderedProjectWorkspaceRows, preferredProjectWorkspaceId);
         const workspaceHints = projectWorkspaceRows.map((workspace) => ({
             workspaceId: workspace.id,
             cwd: readNonEmptyString(workspace.cwd),
@@ -398,12 +730,35 @@ export function heartbeatService(db) {
             repoRef: readNonEmptyString(workspace.repoRef),
         }));
         if (projectWorkspaceRows.length > 0) {
+            const preferredWorkspace = preferredProjectWorkspaceId
+                ? projectWorkspaceRows.find((workspace) => workspace.id === preferredProjectWorkspaceId) ?? null
+                : null;
             const missingProjectCwds = [];
             let hasConfiguredProjectCwd = false;
+            let preferredWorkspaceWarning = null;
+            if (preferredProjectWorkspaceId && !preferredWorkspace) {
+                preferredWorkspaceWarning =
+                    `Selected project workspace "${preferredProjectWorkspaceId}" is not available on this project.`;
+            }
             for (const workspace of projectWorkspaceRows) {
-                const projectCwd = readNonEmptyString(workspace.cwd);
+                let projectCwd = readNonEmptyString(workspace.cwd);
+                let managedWorkspaceWarning = null;
                 if (!projectCwd || projectCwd === REPO_ONLY_CWD_SENTINEL) {
-                    continue;
+                    try {
+                        const managedWorkspace = await ensureManagedProjectWorkspace({
+                            companyId: agent.companyId,
+                            projectId: workspaceProjectId ?? resolvedProjectId ?? workspace.projectId,
+                            repoUrl: readNonEmptyString(workspace.repoUrl),
+                        });
+                        projectCwd = managedWorkspace.cwd;
+                        managedWorkspaceWarning = managedWorkspace.warning;
+                    }
+                    catch (error) {
+                        if (preferredWorkspace?.id === workspace.id) {
+                            preferredWorkspaceWarning = error instanceof Error ? error.message : String(error);
+                        }
+                        continue;
+                    }
                 }
                 hasConfiguredProjectCwd = true;
                 const projectCwdExists = await fs
@@ -419,14 +774,21 @@ export function heartbeatService(db) {
                         repoUrl: workspace.repoUrl,
                         repoRef: workspace.repoRef,
                         workspaceHints,
-                        warnings: [],
+                        warnings: [preferredWorkspaceWarning, managedWorkspaceWarning].filter((value) => Boolean(value)),
                     };
                 }
+                if (preferredWorkspace?.id === workspace.id) {
+                    preferredWorkspaceWarning =
+                        `Selected project workspace path "${projectCwd}" is not available yet.`;
+                }
                 missingProjectCwds.push(projectCwd);
             }
             const fallbackCwd = resolveDefaultAgentWorkspaceDir(agent.id);
             await fs.mkdir(fallbackCwd, { recursive: true });
             const warnings = [];
+            if (preferredWorkspaceWarning) {
+                warnings.push(preferredWorkspaceWarning);
+            }
             if (missingProjectCwds.length > 0) {
                 const firstMissing = missingProjectCwds[0];
                 const extraMissingCount = Math.max(0, missingProjectCwds.length - 1);
@@ -448,6 +810,23 @@ export function heartbeatService(db) {
                 warnings,
             };
         }
+        if (workspaceProjectId) {
+            const managedWorkspace = await ensureManagedProjectWorkspace({
+                companyId: agent.companyId,
+                projectId: workspaceProjectId,
+                repoUrl: null,
+            });
+            return {
+                cwd: managedWorkspace.cwd,
+                source: "project_primary",
+                projectId: resolvedProjectId,
+                workspaceId: null,
+                repoUrl: null,
+                repoRef: null,
+                workspaceHints,
+                warnings: managedWorkspace.warning ? [managedWorkspace.warning] : [],
+            };
+        }
         const sessionCwd = readNonEmptyString(previousSessionParams?.cwd);
         if (sessionCwd) {
             const sessionCwdExists = await fs
@@ -638,6 +1017,24 @@ export function heartbeatService(db) {
     async function claimQueuedRun(run) {
         if (run.status !== "queued")
             return run;
+        const agent = await getAgent(run.agentId);
+        if (!agent) {
+            await cancelRunInternal(run.id, "Cancelled because the agent no longer exists");
+            return null;
+        }
+        if (agent.status === "paused" || agent.status === "terminated" || agent.status === "pending_approval") {
+            await cancelRunInternal(run.id, "Cancelled because the agent is not invokable");
+            return null;
+        }
+        const context = parseObject(run.contextSnapshot);
+        const budgetBlock = await budgets.getInvocationBlock(run.companyId, run.agentId, {
+            issueId: readNonEmptyString(context.issueId),
+            projectId: readNonEmptyString(context.projectId),
+        });
+        if (budgetBlock) {
+            await cancelRunInternal(run.id, budgetBlock.reason);
+            return null;
+        }
         const claimedAt = new Date();
         const claimed = await db
             .update(heartbeatRuns)
@@ -710,14 +1107,14 @@ export function heartbeatService(db) {
     async function reapOrphanedRuns(opts) {
         const staleThresholdMs = opts?.staleThresholdMs ?? 0;
         const now = new Date();
-        // Find all runs in "queued" or "running" state
+        // Find all runs stuck in "running" state (queued runs are legitimately waiting; resumeQueuedRuns handles them)
         const activeRuns = await db
             .select()
             .from(heartbeatRuns)
-            .where(inArray(heartbeatRuns.status, ["queued", "running"]));
+            .where(eq(heartbeatRuns.status, "running"));
         const reaped = [];
         for (const run of activeRuns) {
-            if (runningProcesses.has(run.id))
+            if (runningProcesses.has(run.id) || activeRunExecutions.has(run.id))
                 continue;
             // Apply staleness threshold to avoid false positives
             if (staleThresholdMs > 0) {
@@ -754,14 +1151,28 @@ export function heartbeatService(db) {
         }
         return { reaped: reaped.length, runIds: reaped };
     }
-    async function updateRuntimeState(agent, run, result, session) {
+    async function resumeQueuedRuns() {
+        const queuedRuns = await db
+            .select({ agentId: heartbeatRuns.agentId })
+            .from(heartbeatRuns)
+            .where(eq(heartbeatRuns.status, "queued"));
+        const agentIds = [...new Set(queuedRuns.map((r) => r.agentId))];
+        for (const agentId of agentIds) {
+            await startNextQueuedRunForAgent(agentId);
+        }
+    }
+    async function updateRuntimeState(agent, run, result, session, normalizedUsage) {
         await ensureRuntimeState(agent);
-        const usage = result.usage;
+        const usage = normalizedUsage ?? normalizeUsageTotals(result.usage);
         const inputTokens = usage?.inputTokens ?? 0;
         const outputTokens = usage?.outputTokens ?? 0;
         const cachedInputTokens = usage?.cachedInputTokens ?? 0;
-        const additionalCostCents = Math.max(0, Math.round((result.costUsd ?? 0) * 100));
+        const billingType = normalizeLedgerBillingType(result.billingType);
+        const additionalCostCents = normalizeBilledCostCents(result.costUsd, billingType);
         const hasTokenUsage = inputTokens > 0 || outputTokens > 0 || cachedInputTokens > 0;
+        const provider = result.provider ?? "unknown";
+        const biller = resolveLedgerBiller(result);
+        const ledgerScope = await resolveLedgerScopeForRun(db, agent.companyId, run);
         await db
             .update(agentRuntimeState)
             .set({
@@ -778,12 +1189,18 @@ export function heartbeatService(db) {
         })
             .where(eq(agentRuntimeState.agentId, agent.id));
         if (additionalCostCents > 0 || hasTokenUsage) {
-            const costs = costService(db);
+            const costs = costService(db, budgetHooks);
             await costs.createEvent(agent.companyId, {
+                heartbeatRunId: run.id,
                 agentId: agent.id,
-                provider: result.provider ?? "unknown",
+                issueId: ledgerScope.issueId,
+                projectId: ledgerScope.projectId,
+                provider,
+                biller,
+                billingType,
                 model: result.model ?? "unknown",
                 inputTokens,
+                cachedInputTokens,
                 outputTokens,
                 costCents: additionalCostCents,
                 occurredAt: new Date(),
@@ -795,6 +1212,9 @@ export function heartbeatService(db) {
             const agent = await getAgent(agentId);
             if (!agent)
                 return [];
+            if (agent.status === "paused" || agent.status === "terminated" || agent.status === "pending_approval") {
+                return [];
+            }
             const policy = parseHeartbeatPolicy(agent);
             const runningCount = await countRunningRunsForAgent(agentId);
             const availableSlots = Math.max(0, policy.maxConcurrentRuns - runningCount);
@@ -838,273 +1258,234 @@ export function heartbeatService(db) {
             }
             run = claimed;
         }
-        const agent = await getAgent(run.agentId);
-        if (!agent) {
-            await setRunStatus(runId, "failed", {
-                error: "Agent not found",
-                errorCode: "agent_not_found",
-                finishedAt: new Date(),
-            });
-            await setWakeupStatus(run.wakeupRequestId, "failed", {
-                finishedAt: new Date(),
-                error: "Agent not found",
-            });
-            const failedRun = await getRun(runId);
-            if (failedRun)
-                await releaseIssueExecutionAndPromote(failedRun);
-            return;
-        }
-        const runtime = await ensureRuntimeState(agent);
-        const context = parseObject(run.contextSnapshot);
-        const taskKey = deriveTaskKey(context, null);
-        const sessionCodec = getAdapterSessionCodec(agent.adapterType);
-        const issueId = readNonEmptyString(context.issueId);
-        const issueAssigneeConfig = issueId
-            ? await db
-                .select({
-                projectId: issues.projectId,
-                assigneeAgentId: issues.assigneeAgentId,
-                assigneeAdapterOverrides: issues.assigneeAdapterOverrides,
-                executionWorkspaceSettings: issues.executionWorkspaceSettings,
-            })
-                .from(issues)
-                .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
-                .then((rows) => rows[0] ?? null)
-            : null;
-        const issueAssigneeOverrides = issueAssigneeConfig && issueAssigneeConfig.assigneeAgentId === agent.id
-            ? parseIssueAssigneeAdapterOverrides(issueAssigneeConfig.assigneeAdapterOverrides)
-            : null;
-        const issueExecutionWorkspaceSettings = parseIssueExecutionWorkspaceSettings(issueAssigneeConfig?.executionWorkspaceSettings);
-        const contextProjectId = readNonEmptyString(context.projectId);
-        const executionProjectId = issueAssigneeConfig?.projectId ?? contextProjectId;
-        const projectExecutionWorkspacePolicy = executionProjectId
-            ? await db
-                .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
-                .from(projects)
-                .where(and(eq(projects.id, executionProjectId), eq(projects.companyId, agent.companyId)))
-                .then((rows) => parseProjectExecutionWorkspacePolicy(rows[0]?.executionWorkspacePolicy))
-            : null;
-        const taskSession = taskKey
-            ? await getTaskSession(agent.companyId, agent.id, agent.adapterType, taskKey)
-            : null;
-        const resetTaskSession = shouldResetTaskSessionForWake(context);
-        const sessionResetReason = describeSessionResetReason(context);
-        const taskSessionForRun = resetTaskSession ? null : taskSession;
-        const previousSessionParams = normalizeSessionParams(sessionCodec.deserialize(taskSessionForRun?.sessionParamsJson ?? null));
-        const config = parseObject(agent.adapterConfig);
-        const executionWorkspaceMode = resolveExecutionWorkspaceMode({
-            projectPolicy: projectExecutionWorkspacePolicy,
-            issueSettings: issueExecutionWorkspaceSettings,
-            legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
-        });
-        const resolvedWorkspace = await resolveWorkspaceForRun(agent, context, previousSessionParams, { useProjectWorkspace: executionWorkspaceMode !== "agent_default" });
-        const workspaceManagedConfig = buildExecutionWorkspaceAdapterConfig({
-            agentConfig: config,
-            projectPolicy: projectExecutionWorkspacePolicy,
-            issueSettings: issueExecutionWorkspaceSettings,
-            mode: executionWorkspaceMode,
-            legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
-        });
-        const mergedConfig = issueAssigneeOverrides?.adapterConfig
-            ? { ...workspaceManagedConfig, ...issueAssigneeOverrides.adapterConfig }
-            : workspaceManagedConfig;
-        const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(agent.companyId, mergedConfig);
-        const issueRef = issueId
-            ? await db
-                .select({
-                id: issues.id,
-                identifier: issues.identifier,
-                title: issues.title,
-            })
-                .from(issues)
-                .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
-                .then((rows) => rows[0] ?? null)
-            : null;
-        const executionWorkspace = await realizeExecutionWorkspace({
-            base: {
-                baseCwd: resolvedWorkspace.cwd,
-                source: resolvedWorkspace.source,
-                projectId: resolvedWorkspace.projectId,
-                workspaceId: resolvedWorkspace.workspaceId,
-                repoUrl: resolvedWorkspace.repoUrl,
-                repoRef: resolvedWorkspace.repoRef,
-            },
-            config: resolvedConfig,
-            issue: issueRef,
-            agent: {
-                id: agent.id,
-                name: agent.name,
-                companyId: agent.companyId,
-            },
-        });
-        const runtimeSessionResolution = resolveRuntimeSessionParamsForWorkspace({
-            agentId: agent.id,
-            previousSessionParams,
-            resolvedWorkspace: {
-                ...resolvedWorkspace,
-                cwd: executionWorkspace.cwd,
-            },
-        });
-        const runtimeSessionParams = runtimeSessionResolution.sessionParams;
-        const runtimeWorkspaceWarnings = [
-            ...resolvedWorkspace.warnings,
-            ...executionWorkspace.warnings,
-            ...(runtimeSessionResolution.warning ? [runtimeSessionResolution.warning] : []),
-            ...(resetTaskSession && sessionResetReason
-                ? [
-                    taskKey
-                        ? `Skipping saved session resume for task "${taskKey}" because ${sessionResetReason}.`
-                        : `Skipping saved session resume because ${sessionResetReason}.`,
-                ]
-                : []),
-        ];
-        context.paperclipWorkspace = {
-            cwd: executionWorkspace.cwd,
-            source: executionWorkspace.source,
-            mode: executionWorkspaceMode,
-            strategy: executionWorkspace.strategy,
-            projectId: executionWorkspace.projectId,
-            workspaceId: executionWorkspace.workspaceId,
-            repoUrl: executionWorkspace.repoUrl,
-            repoRef: executionWorkspace.repoRef,
-            branchName: executionWorkspace.branchName,
-            worktreePath: executionWorkspace.worktreePath,
-        };
-        context.paperclipWorkspaces = resolvedWorkspace.workspaceHints;
-        const runtimeServiceIntents = (() => {
-            const runtimeConfig = parseObject(resolvedConfig.workspaceRuntime);
-            return Array.isArray(runtimeConfig.services)
-                ? runtimeConfig.services.filter((value) => typeof value === "object" && value !== null)
-                : [];
-        })();
-        if (runtimeServiceIntents.length > 0) {
-            context.paperclipRuntimeServiceIntents = runtimeServiceIntents;
-        }
-        else {
-            delete context.paperclipRuntimeServiceIntents;
-        }
-        if (executionWorkspace.projectId && !readNonEmptyString(context.projectId)) {
-            context.projectId = executionWorkspace.projectId;
-        }
-        const runtimeSessionFallback = taskKey || resetTaskSession ? null : runtime.sessionId;
-        const previousSessionDisplayId = truncateDisplayId(taskSessionForRun?.sessionDisplayId ??
-            (sessionCodec.getDisplayId ? sessionCodec.getDisplayId(runtimeSessionParams) : null) ??
-            readNonEmptyString(runtimeSessionParams?.sessionId) ??
-            runtimeSessionFallback);
-        const runtimeForAdapter = {
-            sessionId: readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback,
-            sessionParams: runtimeSessionParams,
-            sessionDisplayId: previousSessionDisplayId,
-            taskKey,
-        };
-        let seq = 1;
-        let handle = null;
-        let stdoutExcerpt = "";
-        let stderrExcerpt = "";
+        activeRunExecutions.add(run.id);
         try {
-            const startedAt = run.startedAt ?? new Date();
-            const runningWithSession = await db
-                .update(heartbeatRuns)
-                .set({
-                startedAt,
-                sessionIdBefore: runtimeForAdapter.sessionDisplayId ?? runtimeForAdapter.sessionId,
-                contextSnapshot: context,
-                updatedAt: new Date(),
-            })
-                .where(eq(heartbeatRuns.id, run.id))
-                .returning()
-                .then((rows) => rows[0] ?? null);
-            if (runningWithSession)
-                run = runningWithSession;
-            const runningAgent = await db
-                .update(agents)
-                .set({ status: "running", updatedAt: new Date() })
-                .where(eq(agents.id, agent.id))
-                .returning()
-                .then((rows) => rows[0] ?? null);
-            if (runningAgent) {
-                publishLiveEvent({
-                    companyId: runningAgent.companyId,
-                    type: "agent.status",
-                    payload: {
-                        agentId: runningAgent.id,
-                        status: runningAgent.status,
-                        outcome: "running",
-                    },
+            const agent = await getAgent(run.agentId);
+            if (!agent) {
+                await setRunStatus(runId, "failed", {
+                    error: "Agent not found",
+                    errorCode: "agent_not_found",
+                    finishedAt: new Date(),
+                });
+                await setWakeupStatus(run.wakeupRequestId, "failed", {
+                    finishedAt: new Date(),
+                    error: "Agent not found",
                 });
+                const failedRun = await getRun(runId);
+                if (failedRun)
+                    await releaseIssueExecutionAndPromote(failedRun);
+                return;
             }
-            const currentRun = run;
-            await appendRunEvent(currentRun, seq++, {
-                eventType: "lifecycle",
-                stream: "system",
-                level: "info",
-                message: "run started",
+            const runtime = await ensureRuntimeState(agent);
+            const context = parseObject(run.contextSnapshot);
+            const taskKey = deriveTaskKey(context, null);
+            const sessionCodec = getAdapterSessionCodec(agent.adapterType);
+            const issueId = readNonEmptyString(context.issueId);
+            const issueContext = issueId
+                ? await db
+                    .select({
+                    id: issues.id,
+                    identifier: issues.identifier,
+                    title: issues.title,
+                    projectId: issues.projectId,
+                    projectWorkspaceId: issues.projectWorkspaceId,
+                    executionWorkspaceId: issues.executionWorkspaceId,
+                    executionWorkspacePreference: issues.executionWorkspacePreference,
+                    assigneeAgentId: issues.assigneeAgentId,
+                    assigneeAdapterOverrides: issues.assigneeAdapterOverrides,
+                    executionWorkspaceSettings: issues.executionWorkspaceSettings,
+                })
+                    .from(issues)
+                    .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
+                    .then((rows) => rows[0] ?? null)
+                : null;
+            const issueAssigneeOverrides = issueContext && issueContext.assigneeAgentId === agent.id
+                ? parseIssueAssigneeAdapterOverrides(issueContext.assigneeAdapterOverrides)
+                : null;
+            const isolatedWorkspacesEnabled = (await instanceSettings.getExperimental()).enableIsolatedWorkspaces;
+            const issueExecutionWorkspaceSettings = isolatedWorkspacesEnabled
+                ? parseIssueExecutionWorkspaceSettings(issueContext?.executionWorkspaceSettings)
+                : null;
+            const contextProjectId = readNonEmptyString(context.projectId);
+            const executionProjectId = issueContext?.projectId ?? contextProjectId;
+            const projectExecutionWorkspacePolicy = executionProjectId
+                ? await db
+                    .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
+                    .from(projects)
+                    .where(and(eq(projects.id, executionProjectId), eq(projects.companyId, agent.companyId)))
+                    .then((rows) => gateProjectExecutionWorkspacePolicy(parseProjectExecutionWorkspacePolicy(rows[0]?.executionWorkspacePolicy), isolatedWorkspacesEnabled))
+                : null;
+            const taskSession = taskKey
+                ? await getTaskSession(agent.companyId, agent.id, agent.adapterType, taskKey)
+                : null;
+            const resetTaskSession = shouldResetTaskSessionForWake(context);
+            const sessionResetReason = describeSessionResetReason(context);
+            const taskSessionForRun = resetTaskSession ? null : taskSession;
+            const previousSessionParams = normalizeSessionParams(sessionCodec.deserialize(taskSessionForRun?.sessionParamsJson ?? null));
+            const config = parseObject(agent.adapterConfig);
+            const executionWorkspaceMode = resolveExecutionWorkspaceMode({
+                projectPolicy: projectExecutionWorkspacePolicy,
+                issueSettings: issueExecutionWorkspaceSettings,
+                legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
             });
-            handle = await runLogStore.begin({
-                companyId: run.companyId,
-                agentId: run.agentId,
-                runId,
+            const resolvedWorkspace = await resolveWorkspaceForRun(agent, context, previousSessionParams, { useProjectWorkspace: executionWorkspaceMode !== "agent_default" });
+            const workspaceManagedConfig = buildExecutionWorkspaceAdapterConfig({
+                agentConfig: config,
+                projectPolicy: projectExecutionWorkspacePolicy,
+                issueSettings: issueExecutionWorkspaceSettings,
+                mode: executionWorkspaceMode,
+                legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
             });
-            await db
-                .update(heartbeatRuns)
-                .set({
-                logStore: handle.store,
-                logRef: handle.logRef,
-                updatedAt: new Date(),
-            })
-                .where(eq(heartbeatRuns.id, runId));
-            const onLog = async (stream, chunk) => {
-                const sanitizedChunk = redactCurrentUserText(chunk);
-                if (stream === "stdout")
-                    stdoutExcerpt = appendExcerpt(stdoutExcerpt, sanitizedChunk);
-                if (stream === "stderr")
-                    stderrExcerpt = appendExcerpt(stderrExcerpt, sanitizedChunk);
-                const ts = new Date().toISOString();
-                if (handle) {
-                    await runLogStore.append(handle, {
-                        stream,
-                        chunk: sanitizedChunk,
-                        ts,
-                    });
+            const mergedConfig = issueAssigneeOverrides?.adapterConfig
+                ? { ...workspaceManagedConfig, ...issueAssigneeOverrides.adapterConfig }
+                : workspaceManagedConfig;
+            const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(agent.companyId, mergedConfig);
+            const issueRef = issueContext
+                ? {
+                    id: issueContext.id,
+                    identifier: issueContext.identifier,
+                    title: issueContext.title,
+                    projectId: issueContext.projectId,
+                    projectWorkspaceId: issueContext.projectWorkspaceId,
+                    executionWorkspaceId: issueContext.executionWorkspaceId,
+                    executionWorkspacePreference: issueContext.executionWorkspacePreference,
                 }
-                const payloadChunk = sanitizedChunk.length > MAX_LIVE_LOG_CHUNK_BYTES
-                    ? sanitizedChunk.slice(sanitizedChunk.length - MAX_LIVE_LOG_CHUNK_BYTES)
-                    : sanitizedChunk;
-                publishLiveEvent({
-                    companyId: run.companyId,
-                    type: "heartbeat.run.log",
-                    payload: {
-                        runId: run.id,
-                        agentId: run.agentId,
-                        ts,
-                        stream,
-                        chunk: payloadChunk,
-                        truncated: payloadChunk.length !== sanitizedChunk.length,
-                    },
-                });
-            };
-            for (const warning of runtimeWorkspaceWarnings) {
-                await onLog("stderr", `[paperclip] ${warning}\n`);
-            }
-            const adapterEnv = Object.fromEntries(Object.entries(parseObject(resolvedConfig.env)).filter((entry) => typeof entry[0] === "string" && typeof entry[1] === "string"));
-            const runtimeServices = await ensureRuntimeServicesForRun({
-                db,
-                runId: run.id,
+                : null;
+            const existingExecutionWorkspace = issueRef?.executionWorkspaceId ? await executionWorkspacesSvc.getById(issueRef.executionWorkspaceId) : null;
+            const workspaceOperationRecorder = workspaceOperationsSvc.createRecorder({
+                companyId: agent.companyId,
+                heartbeatRunId: run.id,
+                executionWorkspaceId: existingExecutionWorkspace?.id ?? null,
+            });
+            const executionWorkspace = await realizeExecutionWorkspace({
+                base: {
+                    baseCwd: resolvedWorkspace.cwd,
+                    source: resolvedWorkspace.source,
+                    projectId: resolvedWorkspace.projectId,
+                    workspaceId: resolvedWorkspace.workspaceId,
+                    repoUrl: resolvedWorkspace.repoUrl,
+                    repoRef: resolvedWorkspace.repoRef,
+                },
+                config: resolvedConfig,
+                issue: issueRef,
                 agent: {
                     id: agent.id,
                     name: agent.name,
                     companyId: agent.companyId,
                 },
-                issue: issueRef,
-                workspace: executionWorkspace,
-                config: resolvedConfig,
-                adapterEnv,
-                onLog,
+                recorder: workspaceOperationRecorder,
             });
-            if (runtimeServices.length > 0) {
-                context.paperclipRuntimeServices = runtimeServices;
-                context.paperclipRuntimePrimaryUrl =
-                    runtimeServices.find((service) => readNonEmptyString(service.url))?.url ?? null;
+            const resolvedProjectId = executionWorkspace.projectId ?? issueRef?.projectId ?? executionProjectId ?? null;
+            const resolvedProjectWorkspaceId = issueRef?.projectWorkspaceId ?? resolvedWorkspace.workspaceId ?? null;
+            const shouldReuseExisting = issueRef?.executionWorkspacePreference === "reuse_existing" &&
+                existingExecutionWorkspace &&
+                existingExecutionWorkspace.status !== "archived";
+            let persistedExecutionWorkspace = null;
+            try {
+                persistedExecutionWorkspace = shouldReuseExisting && existingExecutionWorkspace
+                    ? await executionWorkspacesSvc.update(existingExecutionWorkspace.id, {
+                        cwd: executionWorkspace.cwd,
+                        repoUrl: executionWorkspace.repoUrl,
+                        baseRef: executionWorkspace.repoRef,
+                        branchName: executionWorkspace.branchName,
+                        providerType: executionWorkspace.strategy === "git_worktree" ? "git_worktree" : "local_fs",
+                        providerRef: executionWorkspace.worktreePath,
+                        status: "active",
+                        lastUsedAt: new Date(),
+                        metadata: {
+                            ...(existingExecutionWorkspace.metadata ?? {}),
+                            source: executionWorkspace.source,
+                            createdByRuntime: executionWorkspace.created,
+                        },
+                    })
+                    : resolvedProjectId
+                        ? await executionWorkspacesSvc.create({
+                            companyId: agent.companyId,
+                            projectId: resolvedProjectId,
+                            projectWorkspaceId: resolvedProjectWorkspaceId,
+                            sourceIssueId: issueRef?.id ?? null,
+                            mode: executionWorkspaceMode === "isolated_workspace"
+                                ? "isolated_workspace"
+                                : executionWorkspaceMode === "operator_branch"
+                                    ? "operator_branch"
+                                    : executionWorkspaceMode === "agent_default"
+                                        ? "adapter_managed"
+                                        : "shared_workspace",
+                            strategyType: executionWorkspace.strategy === "git_worktree" ? "git_worktree" : "project_primary",
+                            name: executionWorkspace.branchName ?? issueRef?.identifier ?? `workspace-${agent.id.slice(0, 8)}`,
+                            status: "active",
+                            cwd: executionWorkspace.cwd,
+                            repoUrl: executionWorkspace.repoUrl,
+                            baseRef: executionWorkspace.repoRef,
+                            branchName: executionWorkspace.branchName,
+                            providerType: executionWorkspace.strategy === "git_worktree" ? "git_worktree" : "local_fs",
+                            providerRef: executionWorkspace.worktreePath,
+                            lastUsedAt: new Date(),
+                            openedAt: new Date(),
+                            metadata: {
+                                source: executionWorkspace.source,
+                                createdByRuntime: executionWorkspace.created,
+                            },
+                        })
+                        : null;
+            }
+            catch (error) {
+                if (executionWorkspace.created) {
+                    try {
+                        await cleanupExecutionWorkspaceArtifacts({
+                            workspace: {
+                                id: existingExecutionWorkspace?.id ?? `transient-${run.id}`,
+                                cwd: executionWorkspace.cwd,
+                                providerType: executionWorkspace.strategy === "git_worktree" ? "git_worktree" : "local_fs",
+                                providerRef: executionWorkspace.worktreePath,
+                                branchName: executionWorkspace.branchName,
+                                repoUrl: executionWorkspace.repoUrl,
+                                baseRef: executionWorkspace.repoRef,
+                                projectId: resolvedProjectId,
+                                projectWorkspaceId: resolvedProjectWorkspaceId,
+                                sourceIssueId: issueRef?.id ?? null,
+                                metadata: {
+                                    createdByRuntime: true,
+                                    source: executionWorkspace.source,
+                                },
+                            },
+                            projectWorkspace: {
+                                cwd: resolvedWorkspace.cwd,
+                                cleanupCommand: null,
+                            },
+                            teardownCommand: projectExecutionWorkspacePolicy?.workspaceStrategy?.teardownCommand ?? null,
+                            recorder: workspaceOperationRecorder,
+                        });
+                    }
+                    catch (cleanupError) {
+                        logger.warn({
+                            runId: run.id,
+                            issueId,
+                            executionWorkspaceCwd: executionWorkspace.cwd,
+                            cleanupError: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+                        }, "Failed to cleanup realized execution workspace after persistence failure");
+                    }
+                }
+                throw error;
+            }
+            await workspaceOperationRecorder.attachExecutionWorkspaceId(persistedExecutionWorkspace?.id ?? null);
+            if (existingExecutionWorkspace &&
+                persistedExecutionWorkspace &&
+                existingExecutionWorkspace.id !== persistedExecutionWorkspace.id &&
+                existingExecutionWorkspace.status === "active") {
+                await executionWorkspacesSvc.update(existingExecutionWorkspace.id, {
+                    status: "idle",
+                    cleanupReason: null,
+                });
+            }
+            if (issueId && persistedExecutionWorkspace && issueRef?.executionWorkspaceId !== persistedExecutionWorkspace.id) {
+                await issuesSvc.update(issueId, {
+                    executionWorkspaceId: persistedExecutionWorkspace.id,
+                    ...(resolvedProjectWorkspaceId ? { projectWorkspaceId: resolvedProjectWorkspaceId } : {}),
+                });
+            }
+            if (persistedExecutionWorkspace) {
+                context.executionWorkspaceId = persistedExecutionWorkspace.id;
                 await db
                     .update(heartbeatRuns)
                     .set({
@@ -1113,58 +1494,182 @@ export function heartbeatService(db) {
                 })
                     .where(eq(heartbeatRuns.id, run.id));
             }
-            if (issueId && (executionWorkspace.created || runtimeServices.some((service) => !service.reused))) {
-                try {
-                    await issuesSvc.addComment(issueId, buildWorkspaceReadyComment({
-                        workspace: executionWorkspace,
-                        runtimeServices,
-                    }), { agentId: agent.id });
-                }
-                catch (err) {
-                    await onLog("stderr", `[paperclip] Failed to post workspace-ready comment: ${err instanceof Error ? err.message : String(err)}\n`);
+            const runtimeSessionResolution = resolveRuntimeSessionParamsForWorkspace({
+                agentId: agent.id,
+                previousSessionParams,
+                resolvedWorkspace: {
+                    ...resolvedWorkspace,
+                    cwd: executionWorkspace.cwd,
+                },
+            });
+            const runtimeSessionParams = runtimeSessionResolution.sessionParams;
+            const runtimeWorkspaceWarnings = [
+                ...resolvedWorkspace.warnings,
+                ...executionWorkspace.warnings,
+                ...(runtimeSessionResolution.warning ? [runtimeSessionResolution.warning] : []),
+                ...(resetTaskSession && sessionResetReason
+                    ? [
+                        taskKey
+                            ? `Skipping saved session resume for task "${taskKey}" because ${sessionResetReason}.`
+                            : `Skipping saved session resume because ${sessionResetReason}.`,
+                    ]
+                    : []),
+            ];
+            context.paperclipWorkspace = {
+                cwd: executionWorkspace.cwd,
+                source: executionWorkspace.source,
+                mode: executionWorkspaceMode,
+                strategy: executionWorkspace.strategy,
+                projectId: executionWorkspace.projectId,
+                workspaceId: executionWorkspace.workspaceId,
+                repoUrl: executionWorkspace.repoUrl,
+                repoRef: executionWorkspace.repoRef,
+                branchName: executionWorkspace.branchName,
+                worktreePath: executionWorkspace.worktreePath,
+                agentHome: resolveDefaultAgentWorkspaceDir(agent.id),
+            };
+            context.paperclipWorkspaces = resolvedWorkspace.workspaceHints;
+            const runtimeServiceIntents = (() => {
+                const runtimeConfig = parseObject(resolvedConfig.workspaceRuntime);
+                return Array.isArray(runtimeConfig.services)
+                    ? runtimeConfig.services.filter((value) => typeof value === "object" && value !== null)
+                    : [];
+            })();
+            if (runtimeServiceIntents.length > 0) {
+                context.paperclipRuntimeServiceIntents = runtimeServiceIntents;
+            }
+            else {
+                delete context.paperclipRuntimeServiceIntents;
+            }
+            if (executionWorkspace.projectId && !readNonEmptyString(context.projectId)) {
+                context.projectId = executionWorkspace.projectId;
+            }
+            const runtimeSessionFallback = taskKey || resetTaskSession ? null : runtime.sessionId;
+            let previousSessionDisplayId = truncateDisplayId(taskSessionForRun?.sessionDisplayId ??
+                (sessionCodec.getDisplayId ? sessionCodec.getDisplayId(runtimeSessionParams) : null) ??
+                readNonEmptyString(runtimeSessionParams?.sessionId) ??
+                runtimeSessionFallback);
+            let runtimeSessionIdForAdapter = readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback;
+            let runtimeSessionParamsForAdapter = runtimeSessionParams;
+            const sessionCompaction = await evaluateSessionCompaction({
+                agent,
+                sessionId: previousSessionDisplayId ?? runtimeSessionIdForAdapter,
+                issueId,
+            });
+            if (sessionCompaction.rotate) {
+                context.paperclipSessionHandoffMarkdown = sessionCompaction.handoffMarkdown;
+                context.paperclipSessionRotationReason = sessionCompaction.reason;
+                context.paperclipPreviousSessionId = previousSessionDisplayId ?? runtimeSessionIdForAdapter;
+                runtimeSessionIdForAdapter = null;
+                runtimeSessionParamsForAdapter = null;
+                previousSessionDisplayId = null;
+                if (sessionCompaction.reason) {
+                    runtimeWorkspaceWarnings.push(`Starting a fresh session because ${sessionCompaction.reason}.`);
                 }
             }
-            const onAdapterMeta = async (meta) => {
-                if (meta.env && secretKeys.size > 0) {
-                    for (const key of secretKeys) {
-                        if (key in meta.env)
-                            meta.env[key] = "***REDACTED***";
-                    }
+            else {
+                delete context.paperclipSessionHandoffMarkdown;
+                delete context.paperclipSessionRotationReason;
+                delete context.paperclipPreviousSessionId;
+            }
+            const runtimeForAdapter = {
+                sessionId: runtimeSessionIdForAdapter,
+                sessionParams: runtimeSessionParamsForAdapter,
+                sessionDisplayId: previousSessionDisplayId,
+                taskKey,
+            };
+            let seq = 1;
+            let handle = null;
+            let stdoutExcerpt = "";
+            let stderrExcerpt = "";
+            try {
+                const startedAt = run.startedAt ?? new Date();
+                const runningWithSession = await db
+                    .update(heartbeatRuns)
+                    .set({
+                    startedAt,
+                    sessionIdBefore: runtimeForAdapter.sessionDisplayId ?? runtimeForAdapter.sessionId,
+                    contextSnapshot: context,
+                    updatedAt: new Date(),
+                })
+                    .where(eq(heartbeatRuns.id, run.id))
+                    .returning()
+                    .then((rows) => rows[0] ?? null);
+                if (runningWithSession)
+                    run = runningWithSession;
+                const runningAgent = await db
+                    .update(agents)
+                    .set({ status: "running", updatedAt: new Date() })
+                    .where(eq(agents.id, agent.id))
+                    .returning()
+                    .then((rows) => rows[0] ?? null);
+                if (runningAgent) {
+                    publishLiveEvent({
+                        companyId: runningAgent.companyId,
+                        type: "agent.status",
+                        payload: {
+                            agentId: runningAgent.id,
+                            status: runningAgent.status,
+                            outcome: "running",
+                        },
+                    });
                 }
+                const currentRun = run;
                 await appendRunEvent(currentRun, seq++, {
-                    eventType: "adapter.invoke",
+                    eventType: "lifecycle",
                     stream: "system",
                     level: "info",
-                    message: "adapter invocation",
-                    payload: meta,
+                    message: "run started",
                 });
-            };
-            const adapter = getServerAdapter(agent.adapterType);
-            const authToken = adapter.supportsLocalAgentJwt
-                ? createLocalAgentJwt(agent.id, agent.companyId, agent.adapterType, run.id)
-                : null;
-            if (adapter.supportsLocalAgentJwt && !authToken) {
-                logger.warn({
-                    companyId: agent.companyId,
-                    agentId: agent.id,
-                    runId: run.id,
-                    adapterType: agent.adapterType,
-                }, "local agent jwt secret missing or invalid; running without injected PAPERCLIP_API_KEY");
-            }
-            const adapterResult = await adapter.execute({
-                runId: run.id,
-                agent,
-                runtime: runtimeForAdapter,
-                config: resolvedConfig,
-                context,
-                onLog,
-                onMeta: onAdapterMeta,
-                authToken: authToken ?? undefined,
-            });
-            const adapterManagedRuntimeServices = adapterResult.runtimeServices
-                ? await persistAdapterManagedRuntimeServices({
+                handle = await runLogStore.begin({
+                    companyId: run.companyId,
+                    agentId: run.agentId,
+                    runId,
+                });
+                await db
+                    .update(heartbeatRuns)
+                    .set({
+                    logStore: handle.store,
+                    logRef: handle.logRef,
+                    updatedAt: new Date(),
+                })
+                    .where(eq(heartbeatRuns.id, runId));
+                const onLog = async (stream, chunk) => {
+                    const sanitizedChunk = redactCurrentUserText(chunk);
+                    if (stream === "stdout")
+                        stdoutExcerpt = appendExcerpt(stdoutExcerpt, sanitizedChunk);
+                    if (stream === "stderr")
+                        stderrExcerpt = appendExcerpt(stderrExcerpt, sanitizedChunk);
+                    const ts = new Date().toISOString();
+                    if (handle) {
+                        await runLogStore.append(handle, {
+                            stream,
+                            chunk: sanitizedChunk,
+                            ts,
+                        });
+                    }
+                    const payloadChunk = sanitizedChunk.length > MAX_LIVE_LOG_CHUNK_BYTES
+                        ? sanitizedChunk.slice(sanitizedChunk.length - MAX_LIVE_LOG_CHUNK_BYTES)
+                        : sanitizedChunk;
+                    publishLiveEvent({
+                        companyId: run.companyId,
+                        type: "heartbeat.run.log",
+                        payload: {
+                            runId: run.id,
+                            agentId: run.agentId,
+                            ts,
+                            stream,
+                            chunk: payloadChunk,
+                            truncated: payloadChunk.length !== sanitizedChunk.length,
+                        },
+                    });
+                };
+                for (const warning of runtimeWorkspaceWarnings) {
+                    await onLog("stderr", `[paperclip] ${warning}\n`);
+                }
+                const adapterEnv = Object.fromEntries(Object.entries(parseObject(resolvedConfig.env)).filter((entry) => typeof entry[0] === "string" && typeof entry[1] === "string"));
+                const runtimeServices = await ensureRuntimeServicesForRun({
                     db,
-                    adapterType: agent.adapterType,
                     runId: run.id,
                     agent: {
                         id: agent.id,
@@ -1173,203 +1678,337 @@ export function heartbeatService(db) {
                     },
                     issue: issueRef,
                     workspace: executionWorkspace,
-                    reports: adapterResult.runtimeServices,
-                })
-                : [];
-            if (adapterManagedRuntimeServices.length > 0) {
-                const combinedRuntimeServices = [
-                    ...runtimeServices,
-                    ...adapterManagedRuntimeServices,
-                ];
-                context.paperclipRuntimeServices = combinedRuntimeServices;
-                context.paperclipRuntimePrimaryUrl =
-                    combinedRuntimeServices.find((service) => readNonEmptyString(service.url))?.url ?? null;
-                await db
-                    .update(heartbeatRuns)
-                    .set({
-                    contextSnapshot: context,
-                    updatedAt: new Date(),
-                })
-                    .where(eq(heartbeatRuns.id, run.id));
-                if (issueId) {
+                    executionWorkspaceId: persistedExecutionWorkspace?.id ?? issueRef?.executionWorkspaceId ?? null,
+                    config: resolvedConfig,
+                    adapterEnv,
+                    onLog,
+                });
+                if (runtimeServices.length > 0) {
+                    context.paperclipRuntimeServices = runtimeServices;
+                    context.paperclipRuntimePrimaryUrl =
+                        runtimeServices.find((service) => readNonEmptyString(service.url))?.url ?? null;
+                    await db
+                        .update(heartbeatRuns)
+                        .set({
+                        contextSnapshot: context,
+                        updatedAt: new Date(),
+                    })
+                        .where(eq(heartbeatRuns.id, run.id));
+                }
+                if (issueId && (executionWorkspace.created || runtimeServices.some((service) => !service.reused))) {
                     try {
                         await issuesSvc.addComment(issueId, buildWorkspaceReadyComment({
                             workspace: executionWorkspace,
-                            runtimeServices: adapterManagedRuntimeServices,
+                            runtimeServices,
                         }), { agentId: agent.id });
                     }
                     catch (err) {
-                        await onLog("stderr", `[paperclip] Failed to post adapter-managed runtime comment: ${err instanceof Error ? err.message : String(err)}\n`);
+                        await onLog("stderr", `[paperclip] Failed to post workspace-ready comment: ${err instanceof Error ? err.message : String(err)}\n`);
                     }
                 }
-            }
-            const nextSessionState = resolveNextSessionState({
-                codec: sessionCodec,
-                adapterResult,
-                previousParams: previousSessionParams,
-                previousDisplayId: runtimeForAdapter.sessionDisplayId,
-                previousLegacySessionId: runtimeForAdapter.sessionId,
-            });
-            let outcome;
-            const latestRun = await getRun(run.id);
-            if (latestRun?.status === "cancelled") {
-                outcome = "cancelled";
-            }
-            else if (adapterResult.timedOut) {
-                outcome = "timed_out";
-            }
-            else if ((adapterResult.exitCode ?? 0) === 0 && !adapterResult.errorMessage) {
-                outcome = "succeeded";
-            }
-            else {
-                outcome = "failed";
-            }
-            let logSummary = null;
-            if (handle) {
-                logSummary = await runLogStore.finalize(handle);
-            }
-            const status = outcome === "succeeded"
-                ? "succeeded"
-                : outcome === "cancelled"
-                    ? "cancelled"
-                    : outcome === "timed_out"
-                        ? "timed_out"
-                        : "failed";
-            const usageJson = adapterResult.usage || adapterResult.costUsd != null
-                ? {
-                    ...(adapterResult.usage ?? {}),
-                    ...(adapterResult.costUsd != null ? { costUsd: adapterResult.costUsd } : {}),
-                    ...(adapterResult.billingType ? { billingType: adapterResult.billingType } : {}),
+                const onAdapterMeta = async (meta) => {
+                    if (meta.env && secretKeys.size > 0) {
+                        for (const key of secretKeys) {
+                            if (key in meta.env)
+                                meta.env[key] = "***REDACTED***";
+                        }
+                    }
+                    await appendRunEvent(currentRun, seq++, {
+                        eventType: "adapter.invoke",
+                        stream: "system",
+                        level: "info",
+                        message: "adapter invocation",
+                        payload: meta,
+                    });
+                };
+                const adapter = getServerAdapter(agent.adapterType);
+                const authToken = adapter.supportsLocalAgentJwt
+                    ? createLocalAgentJwt(agent.id, agent.companyId, agent.adapterType, run.id)
+                    : null;
+                if (adapter.supportsLocalAgentJwt && !authToken) {
+                    logger.warn({
+                        companyId: agent.companyId,
+                        agentId: agent.id,
+                        runId: run.id,
+                        adapterType: agent.adapterType,
+                    }, "local agent jwt secret missing or invalid; running without injected PAPERCLIP_API_KEY");
                 }
-                : null;
-            await setRunStatus(run.id, status, {
-                finishedAt: new Date(),
-                error: outcome === "succeeded"
-                    ? null
-                    : redactCurrentUserText(adapterResult.errorMessage ?? (outcome === "timed_out" ? "Timed out" : "Adapter failed")),
-                errorCode: outcome === "timed_out"
-                    ? "timeout"
+                const adapterResult = await adapter.execute({
+                    runId: run.id,
+                    agent,
+                    runtime: runtimeForAdapter,
+                    config: resolvedConfig,
+                    context,
+                    onLog,
+                    onMeta: onAdapterMeta,
+                    authToken: authToken ?? undefined,
+                });
+                const adapterManagedRuntimeServices = adapterResult.runtimeServices
+                    ? await persistAdapterManagedRuntimeServices({
+                        db,
+                        adapterType: agent.adapterType,
+                        runId: run.id,
+                        agent: {
+                            id: agent.id,
+                            name: agent.name,
+                            companyId: agent.companyId,
+                        },
+                        issue: issueRef,
+                        workspace: executionWorkspace,
+                        reports: adapterResult.runtimeServices,
+                    })
+                    : [];
+                if (adapterManagedRuntimeServices.length > 0) {
+                    const combinedRuntimeServices = [
+                        ...runtimeServices,
+                        ...adapterManagedRuntimeServices,
+                    ];
+                    context.paperclipRuntimeServices = combinedRuntimeServices;
+                    context.paperclipRuntimePrimaryUrl =
+                        combinedRuntimeServices.find((service) => readNonEmptyString(service.url))?.url ?? null;
+                    await db
+                        .update(heartbeatRuns)
+                        .set({
+                        contextSnapshot: context,
+                        updatedAt: new Date(),
+                    })
+                        .where(eq(heartbeatRuns.id, run.id));
+                    if (issueId) {
+                        try {
+                            await issuesSvc.addComment(issueId, buildWorkspaceReadyComment({
+                                workspace: executionWorkspace,
+                                runtimeServices: adapterManagedRuntimeServices,
+                            }), { agentId: agent.id });
+                        }
+                        catch (err) {
+                            await onLog("stderr", `[paperclip] Failed to post adapter-managed runtime comment: ${err instanceof Error ? err.message : String(err)}\n`);
+                        }
+                    }
+                }
+                const nextSessionState = resolveNextSessionState({
+                    codec: sessionCodec,
+                    adapterResult,
+                    previousParams: previousSessionParams,
+                    previousDisplayId: runtimeForAdapter.sessionDisplayId,
+                    previousLegacySessionId: runtimeForAdapter.sessionId,
+                });
+                const rawUsage = normalizeUsageTotals(adapterResult.usage);
+                const sessionUsageResolution = await resolveNormalizedUsageForSession({
+                    agentId: agent.id,
+                    runId: run.id,
+                    sessionId: nextSessionState.displayId ?? nextSessionState.legacySessionId,
+                    rawUsage,
+                });
+                const normalizedUsage = sessionUsageResolution.normalizedUsage;
+                let outcome;
+                const latestRun = await getRun(run.id);
+                if (latestRun?.status === "cancelled") {
+                    outcome = "cancelled";
+                }
+                else if (adapterResult.timedOut) {
+                    outcome = "timed_out";
+                }
+                else if ((adapterResult.exitCode ?? 0) === 0 && !adapterResult.errorMessage) {
+                    outcome = "succeeded";
+                }
+                else {
+                    outcome = "failed";
+                }
+                let logSummary = null;
+                if (handle) {
+                    logSummary = await runLogStore.finalize(handle);
+                }
+                const status = outcome === "succeeded"
+                    ? "succeeded"
                     : outcome === "cancelled"
                         ? "cancelled"
-                        : outcome === "failed"
-                            ? (adapterResult.errorCode ?? "adapter_failed")
-                            : null,
-                exitCode: adapterResult.exitCode,
-                signal: adapterResult.signal,
-                usageJson,
-                resultJson: adapterResult.resultJson ?? null,
-                sessionIdAfter: nextSessionState.displayId ?? nextSessionState.legacySessionId,
-                stdoutExcerpt,
-                stderrExcerpt,
-                logBytes: logSummary?.bytes,
-                logSha256: logSummary?.sha256,
-                logCompressed: logSummary?.compressed ?? false,
-            });
-            await setWakeupStatus(run.wakeupRequestId, outcome === "succeeded" ? "completed" : status, {
-                finishedAt: new Date(),
-                error: adapterResult.errorMessage ?? null,
-            });
-            const finalizedRun = await getRun(run.id);
-            if (finalizedRun) {
-                await appendRunEvent(finalizedRun, seq++, {
-                    eventType: "lifecycle",
-                    stream: "system",
-                    level: outcome === "succeeded" ? "info" : "error",
-                    message: `run ${outcome}`,
-                    payload: {
-                        status,
-                        exitCode: adapterResult.exitCode,
-                    },
+                        : outcome === "timed_out"
+                            ? "timed_out"
+                            : "failed";
+                const usageJson = normalizedUsage || adapterResult.costUsd != null
+                    ? {
+                        ...(normalizedUsage ?? {}),
+                        ...(rawUsage ? {
+                            rawInputTokens: rawUsage.inputTokens,
+                            rawCachedInputTokens: rawUsage.cachedInputTokens,
+                            rawOutputTokens: rawUsage.outputTokens,
+                        } : {}),
+                        ...(sessionUsageResolution.derivedFromSessionTotals ? { usageSource: "session_delta" } : {}),
+                        ...((nextSessionState.displayId ?? nextSessionState.legacySessionId)
+                            ? { persistedSessionId: nextSessionState.displayId ?? nextSessionState.legacySessionId }
+                            : {}),
+                        sessionReused: runtimeForAdapter.sessionId != null || runtimeForAdapter.sessionDisplayId != null,
+                        taskSessionReused: taskSessionForRun != null,
+                        freshSession: runtimeForAdapter.sessionId == null && runtimeForAdapter.sessionDisplayId == null,
+                        sessionRotated: sessionCompaction.rotate,
+                        sessionRotationReason: sessionCompaction.reason,
+                        provider: readNonEmptyString(adapterResult.provider) ?? "unknown",
+                        biller: resolveLedgerBiller(adapterResult),
+                        model: readNonEmptyString(adapterResult.model) ?? "unknown",
+                        ...(adapterResult.costUsd != null ? { costUsd: adapterResult.costUsd } : {}),
+                        billingType: normalizeLedgerBillingType(adapterResult.billingType),
+                    }
+                    : null;
+                await setRunStatus(run.id, status, {
+                    finishedAt: new Date(),
+                    error: outcome === "succeeded"
+                        ? null
+                        : redactCurrentUserText(adapterResult.errorMessage ?? (outcome === "timed_out" ? "Timed out" : "Adapter failed")),
+                    errorCode: outcome === "timed_out"
+                        ? "timeout"
+                        : outcome === "cancelled"
+                            ? "cancelled"
+                            : outcome === "failed"
+                                ? (adapterResult.errorCode ?? "adapter_failed")
+                                : null,
+                    exitCode: adapterResult.exitCode,
+                    signal: adapterResult.signal,
+                    usageJson,
+                    resultJson: adapterResult.resultJson ?? null,
+                    sessionIdAfter: nextSessionState.displayId ?? nextSessionState.legacySessionId,
+                    stdoutExcerpt,
+                    stderrExcerpt,
+                    logBytes: logSummary?.bytes,
+                    logSha256: logSummary?.sha256,
+                    logCompressed: logSummary?.compressed ?? false,
                 });
-                await releaseIssueExecutionAndPromote(finalizedRun);
-            }
-            if (finalizedRun) {
-                await updateRuntimeState(agent, finalizedRun, adapterResult, {
-                    legacySessionId: nextSessionState.legacySessionId,
+                await setWakeupStatus(run.wakeupRequestId, outcome === "succeeded" ? "completed" : status, {
+                    finishedAt: new Date(),
+                    error: adapterResult.errorMessage ?? null,
                 });
-                if (taskKey) {
-                    if (adapterResult.clearSession || (!nextSessionState.params && !nextSessionState.displayId)) {
-                        await clearTaskSessions(agent.companyId, agent.id, {
-                            taskKey,
-                            adapterType: agent.adapterType,
-                        });
+                const finalizedRun = await getRun(run.id);
+                if (finalizedRun) {
+                    await appendRunEvent(finalizedRun, seq++, {
+                        eventType: "lifecycle",
+                        stream: "system",
+                        level: outcome === "succeeded" ? "info" : "error",
+                        message: `run ${outcome}`,
+                        payload: {
+                            status,
+                            exitCode: adapterResult.exitCode,
+                        },
+                    });
+                    await releaseIssueExecutionAndPromote(finalizedRun);
+                }
+                if (finalizedRun) {
+                    await updateRuntimeState(agent, finalizedRun, adapterResult, {
+                        legacySessionId: nextSessionState.legacySessionId,
+                    }, normalizedUsage);
+                    if (taskKey) {
+                        if (adapterResult.clearSession || (!nextSessionState.params && !nextSessionState.displayId)) {
+                            await clearTaskSessions(agent.companyId, agent.id, {
+                                taskKey,
+                                adapterType: agent.adapterType,
+                            });
+                        }
+                        else {
+                            await upsertTaskSession({
+                                companyId: agent.companyId,
+                                agentId: agent.id,
+                                adapterType: agent.adapterType,
+                                taskKey,
+                                sessionParamsJson: nextSessionState.params,
+                                sessionDisplayId: nextSessionState.displayId,
+                                lastRunId: finalizedRun.id,
+                                lastError: outcome === "succeeded" ? null : (adapterResult.errorMessage ?? "run_failed"),
+                            });
+                        }
                     }
-                    else {
+                }
+                await finalizeAgentStatus(agent.id, outcome);
+            }
+            catch (err) {
+                const message = redactCurrentUserText(err instanceof Error ? err.message : "Unknown adapter failure");
+                logger.error({ err, runId }, "heartbeat execution failed");
+                let logSummary = null;
+                if (handle) {
+                    try {
+                        logSummary = await runLogStore.finalize(handle);
+                    }
+                    catch (finalizeErr) {
+                        logger.warn({ err: finalizeErr, runId }, "failed to finalize run log after error");
+                    }
+                }
+                const failedRun = await setRunStatus(run.id, "failed", {
+                    error: message,
+                    errorCode: "adapter_failed",
+                    finishedAt: new Date(),
+                    stdoutExcerpt,
+                    stderrExcerpt,
+                    logBytes: logSummary?.bytes,
+                    logSha256: logSummary?.sha256,
+                    logCompressed: logSummary?.compressed ?? false,
+                });
+                await setWakeupStatus(run.wakeupRequestId, "failed", {
+                    finishedAt: new Date(),
+                    error: message,
+                });
+                if (failedRun) {
+                    await appendRunEvent(failedRun, seq++, {
+                        eventType: "error",
+                        stream: "system",
+                        level: "error",
+                        message,
+                    });
+                    await releaseIssueExecutionAndPromote(failedRun);
+                    await updateRuntimeState(agent, failedRun, {
+                        exitCode: null,
+                        signal: null,
+                        timedOut: false,
+                        errorMessage: message,
+                    }, {
+                        legacySessionId: runtimeForAdapter.sessionId,
+                    });
+                    if (taskKey && (previousSessionParams || previousSessionDisplayId || taskSession)) {
                         await upsertTaskSession({
                             companyId: agent.companyId,
                             agentId: agent.id,
                             adapterType: agent.adapterType,
                             taskKey,
-                            sessionParamsJson: nextSessionState.params,
-                            sessionDisplayId: nextSessionState.displayId,
-                            lastRunId: finalizedRun.id,
-                            lastError: outcome === "succeeded" ? null : (adapterResult.errorMessage ?? "run_failed"),
+                            sessionParamsJson: previousSessionParams,
+                            sessionDisplayId: previousSessionDisplayId,
+                            lastRunId: failedRun.id,
+                            lastError: message,
                         });
                     }
                 }
+                await finalizeAgentStatus(agent.id, "failed");
             }
-            await finalizeAgentStatus(agent.id, outcome);
         }
-        catch (err) {
-            const message = redactCurrentUserText(err instanceof Error ? err.message : "Unknown adapter failure");
-            logger.error({ err, runId }, "heartbeat execution failed");
-            let logSummary = null;
-            if (handle) {
-                try {
-                    logSummary = await runLogStore.finalize(handle);
-                }
-                catch (finalizeErr) {
-                    logger.warn({ err: finalizeErr, runId }, "failed to finalize run log after error");
-                }
-            }
-            const failedRun = await setRunStatus(run.id, "failed", {
+        catch (outerErr) {
+            // Setup code before adapter.execute threw (e.g. ensureRuntimeState, resolveWorkspaceForRun).
+            // The inner catch did not fire, so we must record the failure here.
+            const message = outerErr instanceof Error ? outerErr.message : "Unknown setup failure";
+            logger.error({ err: outerErr, runId }, "heartbeat execution setup failed");
+            await setRunStatus(runId, "failed", {
                 error: message,
                 errorCode: "adapter_failed",
                 finishedAt: new Date(),
-                stdoutExcerpt,
-                stderrExcerpt,
-                logBytes: logSummary?.bytes,
-                logSha256: logSummary?.sha256,
-                logCompressed: logSummary?.compressed ?? false,
-            });
+            }).catch(() => undefined);
             await setWakeupStatus(run.wakeupRequestId, "failed", {
                 finishedAt: new Date(),
                 error: message,
-            });
+            }).catch(() => undefined);
+            const failedRun = await getRun(runId).catch(() => null);
             if (failedRun) {
-                await appendRunEvent(failedRun, seq++, {
+                // Emit a run-log event so the failure is visible in the run timeline,
+                // consistent with what the inner catch block does for adapter failures.
+                await appendRunEvent(failedRun, 1, {
                     eventType: "error",
                     stream: "system",
                     level: "error",
                     message,
-                });
-                await releaseIssueExecutionAndPromote(failedRun);
-                await updateRuntimeState(agent, failedRun, {
-                    exitCode: null,
-                    signal: null,
-                    timedOut: false,
-                    errorMessage: message,
-                }, {
-                    legacySessionId: runtimeForAdapter.sessionId,
-                });
-                if (taskKey && (previousSessionParams || previousSessionDisplayId || taskSession)) {
-                    await upsertTaskSession({
-                        companyId: agent.companyId,
-                        agentId: agent.id,
-                        adapterType: agent.adapterType,
-                        taskKey,
-                        sessionParamsJson: previousSessionParams,
-                        sessionDisplayId: previousSessionDisplayId,
-                        lastRunId: failedRun.id,
-                        lastError: message,
-                    });
-                }
+                }).catch(() => undefined);
+                await releaseIssueExecutionAndPromote(failedRun).catch(() => undefined);
             }
-            await finalizeAgentStatus(agent.id, "failed");
+            // Ensure the agent is not left stuck in "running" if the inner catch handler's
+            // DB calls threw (e.g. a transient DB error in finalizeAgentStatus).
+            await finalizeAgentStatus(run.agentId, "failed").catch(() => undefined);
         }
         finally {
-            await releaseRuntimeServicesForRun(run.id);
-            await startNextQueuedRunForAgent(agent.id);
+            await releaseRuntimeServicesForRun(run.id).catch(() => undefined);
+            activeRunExecutions.delete(run.id);
+            await startNextQueuedRunForAgent(run.agentId);
         }
     }
     async function releaseIssueExecutionAndPromote(run) {
@@ -1512,19 +2151,13 @@ export function heartbeatService(db) {
         const agent = await getAgent(agentId);
         if (!agent)
             throw notFound("Agent not found");
-        if (agent.status === "paused" ||
-            agent.status === "terminated" ||
-            agent.status === "pending_approval") {
-            throw conflict("Agent is not invokable in its current state", { status: agent.status });
-        }
-        const policy = parseHeartbeatPolicy(agent);
-        const writeSkippedRequest = async (reason) => {
+        const writeSkippedRequest = async (skipReason) => {
             await db.insert(agentWakeupRequests).values({
                 companyId: agent.companyId,
                 agentId,
                 source,
                 triggerDetail,
-                reason,
+                reason: skipReason,
                 payload,
                 status: "skipped",
                 requestedByActorType: opts.requestedByActorType ?? null,
@@ -1533,6 +2166,31 @@ export function heartbeatService(db) {
                 finishedAt: new Date(),
             });
         };
+        let projectId = readNonEmptyString(enrichedContextSnapshot.projectId);
+        if (!projectId && issueId) {
+            projectId = await db
+                .select({ projectId: issues.projectId })
+                .from(issues)
+                .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
+                .then((rows) => rows[0]?.projectId ?? null);
+        }
+        const budgetBlock = await budgets.getInvocationBlock(agent.companyId, agentId, {
+            issueId,
+            projectId,
+        });
+        if (budgetBlock) {
+            await writeSkippedRequest("budget.blocked");
+            throw conflict(budgetBlock.reason, {
+                scopeType: budgetBlock.scopeType,
+                scopeId: budgetBlock.scopeId,
+            });
+        }
+        if (agent.status === "paused" ||
+            agent.status === "terminated" ||
+            agent.status === "pending_approval") {
+            throw conflict("Agent is not invokable in its current state", { status: agent.status });
+        }
+        const policy = parseHeartbeatPolicy(agent);
         if (source === "timer" && !policy.enabled) {
             await writeSkippedRequest("heartbeat.disabled");
             return null;
@@ -1864,6 +2522,140 @@ export function heartbeatService(db) {
         await startNextQueuedRunForAgent(agent.id);
         return newRun;
     }
+    async function listProjectScopedRunIds(companyId, projectId) {
+        const runIssueId = sql `${heartbeatRuns.contextSnapshot} ->> 'issueId'`;
+        const effectiveProjectId = sql `coalesce(${heartbeatRuns.contextSnapshot} ->> 'projectId', ${issues.projectId}::text)`;
+        const rows = await db
+            .selectDistinctOn([heartbeatRuns.id], { id: heartbeatRuns.id })
+            .from(heartbeatRuns)
+            .leftJoin(issues, and(eq(issues.companyId, companyId), sql `${issues.id}::text = ${runIssueId}`))
+            .where(and(eq(heartbeatRuns.companyId, companyId), inArray(heartbeatRuns.status, ["queued", "running"]), sql `${effectiveProjectId} = ${projectId}`));
+        return rows.map((row) => row.id);
+    }
+    async function listProjectScopedWakeupIds(companyId, projectId) {
+        const wakeIssueId = sql `${agentWakeupRequests.payload} ->> 'issueId'`;
+        const effectiveProjectId = sql `coalesce(${agentWakeupRequests.payload} ->> 'projectId', ${issues.projectId}::text)`;
+        const rows = await db
+            .selectDistinctOn([agentWakeupRequests.id], { id: agentWakeupRequests.id })
+            .from(agentWakeupRequests)
+            .leftJoin(issues, and(eq(issues.companyId, companyId), sql `${issues.id}::text = ${wakeIssueId}`))
+            .where(and(eq(agentWakeupRequests.companyId, companyId), inArray(agentWakeupRequests.status, ["queued", "deferred_issue_execution"]), sql `${agentWakeupRequests.runId} is null`, sql `${effectiveProjectId} = ${projectId}`));
+        return rows.map((row) => row.id);
+    }
+    async function cancelPendingWakeupsForBudgetScope(scope) {
+        const now = new Date();
+        let wakeupIds = [];
+        if (scope.scopeType === "company") {
+            wakeupIds = await db
+                .select({ id: agentWakeupRequests.id })
+                .from(agentWakeupRequests)
+                .where(and(eq(agentWakeupRequests.companyId, scope.companyId), inArray(agentWakeupRequests.status, ["queued", "deferred_issue_execution"]), sql `${agentWakeupRequests.runId} is null`))
+                .then((rows) => rows.map((row) => row.id));
+        }
+        else if (scope.scopeType === "agent") {
+            wakeupIds = await db
+                .select({ id: agentWakeupRequests.id })
+                .from(agentWakeupRequests)
+                .where(and(eq(agentWakeupRequests.companyId, scope.companyId), eq(agentWakeupRequests.agentId, scope.scopeId), inArray(agentWakeupRequests.status, ["queued", "deferred_issue_execution"]), sql `${agentWakeupRequests.runId} is null`))
+                .then((rows) => rows.map((row) => row.id));
+        }
+        else {
+            wakeupIds = await listProjectScopedWakeupIds(scope.companyId, scope.scopeId);
+        }
+        if (wakeupIds.length === 0)
+            return 0;
+        await db
+            .update(agentWakeupRequests)
+            .set({
+            status: "cancelled",
+            finishedAt: now,
+            error: "Cancelled due to budget pause",
+            updatedAt: now,
+        })
+            .where(inArray(agentWakeupRequests.id, wakeupIds));
+        return wakeupIds.length;
+    }
+    async function cancelRunInternal(runId, reason = "Cancelled by control plane") {
+        const run = await getRun(runId);
+        if (!run)
+            throw notFound("Heartbeat run not found");
+        if (run.status !== "running" && run.status !== "queued")
+            return run;
+        const running = runningProcesses.get(run.id);
+        if (running) {
+            running.child.kill("SIGTERM");
+            const graceMs = Math.max(1, running.graceSec) * 1000;
+            setTimeout(() => {
+                if (!running.child.killed) {
+                    running.child.kill("SIGKILL");
+                }
+            }, graceMs);
+        }
+        const cancelled = await setRunStatus(run.id, "cancelled", {
+            finishedAt: new Date(),
+            error: reason,
+            errorCode: "cancelled",
+        });
+        await setWakeupStatus(run.wakeupRequestId, "cancelled", {
+            finishedAt: new Date(),
+            error: reason,
+        });
+        if (cancelled) {
+            await appendRunEvent(cancelled, 1, {
+                eventType: "lifecycle",
+                stream: "system",
+                level: "warn",
+                message: "run cancelled",
+            });
+            await releaseIssueExecutionAndPromote(cancelled);
+        }
+        runningProcesses.delete(run.id);
+        await finalizeAgentStatus(run.agentId, "cancelled");
+        await startNextQueuedRunForAgent(run.agentId);
+        return cancelled;
+    }
+    async function cancelActiveForAgentInternal(agentId, reason = "Cancelled due to agent pause") {
+        const runs = await db
+            .select()
+            .from(heartbeatRuns)
+            .where(and(eq(heartbeatRuns.agentId, agentId), inArray(heartbeatRuns.status, ["queued", "running"])));
+        for (const run of runs) {
+            await setRunStatus(run.id, "cancelled", {
+                finishedAt: new Date(),
+                error: reason,
+                errorCode: "cancelled",
+            });
+            await setWakeupStatus(run.wakeupRequestId, "cancelled", {
+                finishedAt: new Date(),
+                error: reason,
+            });
+            const running = runningProcesses.get(run.id);
+            if (running) {
+                running.child.kill("SIGTERM");
+                runningProcesses.delete(run.id);
+            }
+            await releaseIssueExecutionAndPromote(run);
+        }
+        return runs.length;
+    }
+    async function cancelBudgetScopeWork(scope) {
+        if (scope.scopeType === "agent") {
+            await cancelActiveForAgentInternal(scope.scopeId, "Cancelled due to budget pause");
+            await cancelPendingWakeupsForBudgetScope(scope);
+            return;
+        }
+        const runIds = scope.scopeType === "company"
+            ? await db
+                .select({ id: heartbeatRuns.id })
+                .from(heartbeatRuns)
+                .where(and(eq(heartbeatRuns.companyId, scope.companyId), inArray(heartbeatRuns.status, ["queued", "running"])))
+                .then((rows) => rows.map((row) => row.id))
+            : await listProjectScopedRunIds(scope.companyId, scope.scopeId);
+        for (const runId of runIds) {
+            await cancelRunInternal(runId, "Cancelled due to budget pause");
+        }
+        await cancelPendingWakeupsForBudgetScope(scope);
+    }
     return {
         list: async (companyId, agentId, limit) => {
             const query = db
@@ -1972,6 +2764,7 @@ export function heartbeatService(db) {
         }),
         wakeup: enqueueWakeup,
         reapOrphanedRuns,
+        resumeQueuedRuns,
         tickTimers: async (now = new Date()) => {
             const allAgents = await db.select().from(agents);
             let checked = 0;
@@ -2007,69 +2800,9 @@ export function heartbeatService(db) {
             }
             return { checked, enqueued, skipped };
         },
-        cancelRun: async (runId) => {
-            const run = await getRun(runId);
-            if (!run)
-                throw notFound("Heartbeat run not found");
-            if (run.status !== "running" && run.status !== "queued")
-                return run;
-            const running = runningProcesses.get(run.id);
-            if (running) {
-                running.child.kill("SIGTERM");
-                const graceMs = Math.max(1, running.graceSec) * 1000;
-                setTimeout(() => {
-                    if (!running.child.killed) {
-                        running.child.kill("SIGKILL");
-                    }
-                }, graceMs);
-            }
-            const cancelled = await setRunStatus(run.id, "cancelled", {
-                finishedAt: new Date(),
-                error: "Cancelled by control plane",
-                errorCode: "cancelled",
-            });
-            await setWakeupStatus(run.wakeupRequestId, "cancelled", {
-                finishedAt: new Date(),
-                error: "Cancelled by control plane",
-            });
-            if (cancelled) {
-                await appendRunEvent(cancelled, 1, {
-                    eventType: "lifecycle",
-                    stream: "system",
-                    level: "warn",
-                    message: "run cancelled",
-                });
-                await releaseIssueExecutionAndPromote(cancelled);
-            }
-            runningProcesses.delete(run.id);
-            await finalizeAgentStatus(run.agentId, "cancelled");
-            await startNextQueuedRunForAgent(run.agentId);
-            return cancelled;
-        },
-        cancelActiveForAgent: async (agentId) => {
-            const runs = await db
-                .select()
-                .from(heartbeatRuns)
-                .where(and(eq(heartbeatRuns.agentId, agentId), inArray(heartbeatRuns.status, ["queued", "running"])));
-            for (const run of runs) {
-                await setRunStatus(run.id, "cancelled", {
-                    finishedAt: new Date(),
-                    error: "Cancelled due to agent pause",
-                    errorCode: "cancelled",
-                });
-                await setWakeupStatus(run.wakeupRequestId, "cancelled", {
-                    finishedAt: new Date(),
-                    error: "Cancelled due to agent pause",
-                });
-                const running = runningProcesses.get(run.id);
-                if (running) {
-                    running.child.kill("SIGTERM");
-                    runningProcesses.delete(run.id);
-                }
-                await releaseIssueExecutionAndPromote(run);
-            }
-            return runs.length;
-        },
+        cancelRun: (runId) => cancelRunInternal(runId),
+        cancelActiveForAgent: (agentId) => cancelActiveForAgentInternal(agentId),
+        cancelBudgetScopeWork,
         getActiveRunForAgent: async (agentId) => {
             const [run] = await db
                 .select()