@junctionpanel/server 0.1.83 → 0.1.85

package/dist/server/server/agent/agent-manager.js

@@ -9,6 +9,9 @@ import { buildPermissionRecoveryFingerprint } from "./agent-permission-fingerpri
 import { isCodexPlanModeEnabled, normalizeCodexModeId, setCodexPlanModeEnabled, } from "./codex-config.js";
 import { applyHarnessSystemPrompt, buildHarnessContext, compileHarnessSystemPrompt, getHarnessSessionExtra, mergeRuntimeInfoWithHarness, setHarnessSessionExtra, } from "./harness/context.js";
 import { summarizeTurnFromTimeline, updateSessionState } from "./harness/memory.js";
+import { createHarnessPermissionLedgerEntry, resolveHarnessPermissionLedger, } from "./harness/permission-policy.js";
+import { getActiveHarnessRun, touchHarnessRunProgress, transitionHarnessRunLedger, } from "./harness/run-ledger.js";
+import { accumulateHarnessCostState, createHarnessResumeState, ensureHarnessScratchpadDir, touchHarnessResumeState, } from "./harness/session-bundle.js";
 import { JUNCTION_HARNESS_VERSION } from "./harness/types.js";
 import { getPendingPlanReviewFingerprint, hasPendingPlanReview, } from "./pending-plan-review.js";
 import { extractPermissionQuestionAnswersFromResponse, formatPermissionQuestionAnswers, isInteractiveQuestionPermission, } from "../../shared/permission-questions.js";
@@ -43,6 +46,36 @@ function extractGeminiFallbackPermissionUpdate(response) {
     const persistedSummary = typeof fallback.persistedSummary === "string" ? fallback.persistedSummary.trim() : "";
     return persistedSummary.length > 0 ? { kind, persistedSummary } : { kind };
 }
+function inferHarnessWorkerRole(detail) {
+    const haystack = `${detail.subAgentType ?? ""} ${detail.description ?? ""}`.toLowerCase();
+    if (haystack.includes("explore") || haystack.includes("research")) {
+        return "explore";
+    }
+    if (haystack.includes("plan")) {
+        return "plan";
+    }
+    if (haystack.includes("verify") || haystack.includes("test")) {
+        return "verify";
+    }
+    if (haystack.includes("implement") || haystack.includes("fix")) {
+        return "implement";
+    }
+    return "generic";
+}
+function mapTurnOutcomeToRunLifecycle(outcome) {
+    switch (outcome) {
+        case "provider_error":
+            return "error";
+        case "canceled":
+            return "interrupted";
+        case "completed":
+        case "needs_verification":
+            return "completed";
+        case "blocked_on_permission":
+        case "blocked_on_feedback":
+            return "waiting_permission";
+    }
+}
 function attachPersistenceCwd(handle, cwd) {
     if (!handle) {
         return null;
@@ -225,6 +258,7 @@ export class AgentManager {
                 : null;
         this.idFactory = options?.idFactory ?? (() => randomUUID());
         this.registry = options?.registry;
+        this.checkpointStorage = options?.checkpointStorage;
         this.onAgentAttention = options?.onAgentAttention;
         this.logger = options.logger.child({ module: "agent", component: "agent-manager" });
         if (options?.clients) {
@@ -531,6 +565,7 @@ export class AgentManager {
         return this.registerSession(session, normalizedConfig, resolvedAgentId, {
             labels: options?.labels,
             parentAgentId: options?.parentAgentId ?? null,
+            resumeSource: "new_session",
         });
     }
     // Reconstruct an agent from provider persistence. Callers should explicitly
@@ -549,7 +584,7 @@ export class AgentManager {
             : overrides;
         const client = this.requireClient(handle.provider);
         const session = await client.resumeSession(handle, resumeOverrides);
-        return this.registerSession(session, normalizedConfig, resolvedAgentId, options);
+        return this.registerSession(session, normalizedConfig, resolvedAgentId, { ...options, resumeSource: "provider_resume" });
     }
     // Hot-reload an active agent session with config overrides while preserving
     // in-memory timeline state.
@@ -613,6 +648,7 @@ export class AgentManager {
             activeTurnStartedAt: preservedActiveTurnStartedAt,
             lastError: preservedLastError,
             attention: preservedAttention,
+            resumeSource: handle ? "provider_resume" : "new_session",
         });
     }
     async closeAgent(agentId) {
@@ -1044,13 +1080,15 @@ export class AgentManager {
             }
         }
         await agent.session.respondToPermission(requestId, response);
-        agent.pendingPermissions.delete(requestId);
-        this.clearAttentionForUserEngagement(agent);
-        this.recordPermissionResolutionTimelineItem(agent, requestId, response, {
+        this.resolvePendingPermission(agent, requestId, response, {
             provider: agent.provider,
-            pendingRequest,
+            dispatchEvent: false,
             dispatchTimeline: true,
+            syncHarness: true,
+            dispatchHarnessEvent: false,
+            transitionRunToStreaming: getActiveHarnessRun(getHarnessSessionExtra(agent.config)?.runLedger) !== null,
         });
+        this.clearAttentionForUserEngagement(agent);
         // Update currentModeId - the session may have changed mode internally
         // (e.g., plan approval changes mode from "plan" to "acceptEdits")
         try {
@@ -1122,6 +1160,9 @@ export class AgentManager {
                     provider: agent.provider,
                     dispatchEvent: true,
                     dispatchTimeline: true,
+                    syncHarness: true,
+                    dispatchHarnessEvent: true,
+                    transitionRunToStreaming: false,
                 });
             }
             this.emitState(agent);
@@ -1170,7 +1211,14 @@ export class AgentManager {
         for (const [requestId, request] of agent.pendingPermissions) {
             const fingerprint = buildPermissionRecoveryFingerprint(request);
             if (requestIds.has(request.id) || requestFingerprints.has(fingerprint)) {
-                agent.pendingPermissions.delete(requestId);
+                this.resolvePendingPermission(agent, requestId, { behavior: "deny", message: "Approval request expired while the daemon was offline." }, {
+                    provider: agent.provider,
+                    dispatchEvent: false,
+                    dispatchTimeline: false,
+                    syncHarness: true,
+                    dispatchHarnessEvent: false,
+                    transitionRunToStreaming: false,
+                });
                 removed += 1;
             }
         }
@@ -1407,6 +1455,18 @@ export class AgentManager {
             internal: config.internal ?? false,
             labels: options?.labels ?? {},
         };
+        const registeredAt = (options?.updatedAt ?? options?.createdAt ?? now).toISOString();
+        const existingHarnessExtra = getHarnessSessionExtra(config);
+        setHarnessSessionExtra(config, {
+            scratchpadDir: existingHarnessExtra?.scratchpadDir ?? ensureHarnessScratchpadDir(resolvedAgentId),
+            resumeState: existingHarnessExtra?.resumeState
+                ? touchHarnessResumeState(existingHarnessExtra.resumeState, {
+                    status: existingHarnessExtra.resumeState.status === "checkpoint_restored" ? "checkpoint_restored" : "live",
+                    source: existingHarnessExtra.resumeState.source,
+                    timestamp: registeredAt,
+                })
+                : createHarnessResumeState(options?.resumeSource ?? "new_session", registeredAt),
+        });
         this.agents.set(resolvedAgentId, managed);
         // Initialize previousStatus to track transitions
         this.previousStatuses.set(resolvedAgentId, managed.lifecycle);
@@ -1606,6 +1666,11 @@ export class AgentManager {
                     agent.lastUserMessageAt = new Date();
                     this.emitState(agent);
                 }
+                if (!options?.fromHistory &&
+                    event.item.type !== "permission_request" &&
+                    event.item.type !== "permission_resolution") {
+                    this.touchActiveHarnessRunProgress(agent);
+                }
                 break;
             case "turn_completed":
                 this.pendingUserInterruptAgents.delete(agent.id);
@@ -1615,7 +1680,20 @@ export class AgentManager {
                     let shouldEmitState = pendingRefresh.changed;
                     agent.lastUsage = event.usage;
                     agent.lastError = undefined;
-                    this.finalizeHarnessTurn(agent, "completed");
+                    if (!options?.fromHistory) {
+                        this.finalizeHarnessTurn(agent, "completed");
+                        const timestamp = new Date().toISOString();
+                        const harnessExtra = getHarnessSessionExtra(agent.config);
+                        setHarnessSessionExtra(agent.config, {
+                            costState: accumulateHarnessCostState(harnessExtra?.costState, event.usage, timestamp),
+                            resumeState: touchHarnessResumeState(harnessExtra?.resumeState, {
+                                status: "live",
+                                source: harnessExtra?.resumeState?.source ?? "snapshot",
+                                timestamp,
+                                recoveryHint: null,
+                            }),
+                        });
+                    }
                     if (!options?.fromHistory) {
                         const turnSummaryItem = this.buildTurnSummaryTimelineItem(agent, event.usage, event.modelId, agent.activeTurnStartedAt);
                         if (turnSummaryItem) {
@@ -1647,12 +1725,24 @@ export class AgentManager {
                 }
                 agent.activeTurnStartedAt = null;
                 agent.lastError = event.error;
-                this.finalizeHarnessTurn(agent, "provider_error");
+                if (!options?.fromHistory) {
+                    this.finalizeHarnessTurn(agent, "provider_error");
+                    this.recordHarnessEvent(agent, {
+                        kind: "recovery_hint_emitted",
+                        summary: "The provider run failed. Review the error and retry or resume the task.",
+                        details: {
+                            error: event.error,
+                        },
+                    });
+                }
                 for (const [requestId] of agent.pendingPermissions) {
                     this.resolvePendingPermission(agent, requestId, { behavior: "deny", message: "Turn failed" }, {
                         provider: event.provider,
                         dispatchEvent: !options?.fromHistory,
                         dispatchTimeline: !options?.fromHistory,
+                        syncHarness: !options?.fromHistory,
+                        dispatchHarnessEvent: !options?.fromHistory,
+                        transitionRunToStreaming: false,
                     });
                 }
                 this.emitState(agent);
@@ -1670,13 +1760,28 @@ export class AgentManager {
                     }
                     agent.activeTurnStartedAt = null;
                     agent.lastError = undefined;
-                    this.finalizeHarnessTurn(agent, "canceled");
+                    if (!options?.fromHistory) {
+                        this.finalizeHarnessTurn(agent, "canceled");
+                        const timestamp = new Date().toISOString();
+                        const harnessExtra = getHarnessSessionExtra(agent.config);
+                        setHarnessSessionExtra(agent.config, {
+                            resumeState: touchHarnessResumeState(harnessExtra?.resumeState, {
+                                status: "live",
+                                source: harnessExtra?.resumeState?.source ?? "snapshot",
+                                timestamp,
+                                recoveryHint: "The run was interrupted before completion.",
+                            }),
+                        });
+                    }
                     if (!pendingRefresh.hasPendingPermissions) {
                         for (const requestId of pendingRequestIds) {
                             this.resolvePendingPermission(agent, requestId, { behavior: "deny", message: "Interrupted" }, {
                                 provider: event.provider,
                                 dispatchEvent: !options?.fromHistory,
                                 dispatchTimeline: !options?.fromHistory,
+                                syncHarness: !options?.fromHistory,
+                                dispatchHarnessEvent: !options?.fromHistory,
+                                transitionRunToStreaming: false,
                             });
                         }
                     }
@@ -1700,12 +1805,22 @@ export class AgentManager {
                 if (!agent.pendingRun) {
                     agent.lifecycle = "running";
                 }
+                if (!options?.fromHistory) {
+                    this.transitionHarnessRunState(agent, {
+                        lifecycle: "streaming",
+                        summary: "Run is streaming.",
+                        turnStartSeq: getHarnessSessionExtra(agent.config)?.currentTurn?.turnStartSeq ?? null,
+                    });
+                }
                 this.emitState(agent);
                 shouldPersistSnapshot = true;
                 break;
             case "permission_requested":
                 {
                     agent.pendingPermissions.set(event.request.id, event.request);
+                    if (!options?.fromHistory) {
+                        this.recordHarnessPermissionRequest(agent, event.request, true);
+                    }
                     this.recordPermissionRequestTimelineItem(agent, event.request, {
                         provider: event.provider,
                         dispatchTimeline: !options?.fromHistory,
@@ -1737,6 +1852,9 @@ export class AgentManager {
                     provider: event.provider,
                     dispatchEvent: false,
                     dispatchTimeline: !options?.fromHistory,
+                    syncHarness: !options?.fromHistory,
+                    dispatchHarnessEvent: !options?.fromHistory,
+                    transitionRunToStreaming: !options?.fromHistory,
                 });
                 this.emitState(agent);
                 shouldPersistSnapshot = true;
@@ -1863,6 +1981,12 @@ export class AgentManager {
     }
     resolvePendingPermission(agent, requestId, resolution, options) {
         const pendingRequest = agent.pendingPermissions.get(requestId) ?? null;
+        if (options.syncHarness) {
+            this.recordHarnessPermissionResolution(agent, requestId, resolution, {
+                dispatchEvent: options.dispatchHarnessEvent ?? false,
+                transitionRunToStreaming: options.transitionRunToStreaming ?? false,
+            });
+        }
         agent.pendingPermissions.delete(requestId);
         const row = this.recordPermissionResolutionTimelineItem(agent, requestId, resolution, {
             provider: options.provider,
@@ -2174,6 +2298,261 @@ export class AgentManager {
             },
         };
     }
+    recordHarnessEvent(agent, input) {
+        const item = {
+            type: "harness_event",
+            kind: input.kind,
+            summary: input.summary,
+            ...(input.checkpointId !== undefined ? { checkpointId: input.checkpointId } : {}),
+            ...(input.verificationState !== undefined
+                ? { verificationState: input.verificationState }
+                : {}),
+            ...(input.trustState !== undefined ? { trustState: input.trustState } : {}),
+            ...(input.workerId !== undefined ? { workerId: input.workerId } : {}),
+            ...(input.details ? { details: input.details } : {}),
+        };
+        const row = this.recordTimeline(agent, item);
+        this.dispatchStream(agent.id, { type: "timeline", provider: agent.provider, item }, {
+            seq: row.seq,
+            epoch: this.ensureTimelineState(agent).epoch,
+        });
+    }
+    transitionHarnessRunState(agent, input) {
+        const timestamp = new Date().toISOString();
+        const current = getHarnessSessionExtra(agent.config);
+        const previousRun = getActiveHarnessRun(current?.runLedger);
+        const { ledger, run } = transitionHarnessRunLedger(current?.runLedger, {
+            lifecycle: input.lifecycle,
+            timestamp,
+            idFactory: this.idFactory,
+            owner: agent.internal ? "background" : "foreground",
+            summary: input.summary,
+            turnStartSeq: input.turnStartSeq,
+            turnEndSeq: input.turnEndSeq,
+            permissionRequestId: input.permissionRequestId,
+            correlationId: agent.persistence?.sessionId ?? agent.runtimeInfo?.sessionId ?? null,
+            modelId: agent.runtimeInfo?.model ?? agent.config.model ?? null,
+            progress: input.lifecycle === "streaming",
+        });
+        setHarnessSessionExtra(agent.config, {
+            runLedger: ledger,
+        });
+        if (input.dispatchEvent !== false &&
+            (previousRun?.lifecycle !== run.lifecycle ||
+                previousRun?.permissionRequestId !== run.permissionRequestId)) {
+            this.recordHarnessEvent(agent, {
+                kind: "run_state_changed",
+                summary: input.summary ?? `Run is now ${run.lifecycle}.`,
+                details: {
+                    runId: run.id,
+                    lifecycle: run.lifecycle,
+                    permissionRequestId: run.permissionRequestId,
+                },
+            });
+        }
+    }
+    touchActiveHarnessRunProgress(agent) {
+        const current = getHarnessSessionExtra(agent.config);
+        const nextLedger = touchHarnessRunProgress(current?.runLedger, new Date().toISOString());
+        if (!nextLedger || nextLedger === current?.runLedger) {
+            return;
+        }
+        setHarnessSessionExtra(agent.config, {
+            runLedger: nextLedger,
+        });
+    }
+    recordHarnessPermissionRequest(agent, request, dispatchEvent) {
+        const timestamp = new Date().toISOString();
+        const current = getHarnessSessionExtra(agent.config);
+        const existing = (current?.permissionLedger ?? []).filter((entry) => entry.requestId !== request.id);
+        const nextEntry = createHarnessPermissionLedgerEntry(request, timestamp);
+        setHarnessSessionExtra(agent.config, {
+            permissionLedger: [nextEntry, ...existing].slice(0, 50),
+        });
+        this.transitionHarnessRunState(agent, {
+            lifecycle: "waiting_permission",
+            summary: `Waiting for permission: ${request.name}.`,
+            permissionRequestId: request.id,
+            dispatchEvent,
+        });
+        if (dispatchEvent) {
+            this.recordHarnessEvent(agent, {
+                kind: "permission_enqueued",
+                summary: `Queued ${nextEntry.risk} permission request for ${request.name}.`,
+                details: {
+                    requestId: request.id,
+                    risk: nextEntry.risk,
+                    fingerprint: nextEntry.fingerprint,
+                    kind: request.kind,
+                },
+            });
+        }
+    }
+    recordHarnessPermissionResolution(agent, requestId, resolution, options) {
+        const timestamp = new Date().toISOString();
+        const current = getHarnessSessionExtra(agent.config);
+        const nextLedger = resolveHarnessPermissionLedger(current?.permissionLedger, requestId, resolution, timestamp);
+        const resolvedEntry = nextLedger.find((entry) => entry.requestId === requestId) ?? null;
+        setHarnessSessionExtra(agent.config, {
+            permissionLedger: nextLedger,
+        });
+        if (options.dispatchEvent && resolvedEntry && agent.lifecycle !== "closed") {
+            this.recordHarnessEvent(agent, {
+                kind: "permission_resolved",
+                summary: `Permission ${resolvedEntry.status} for ${resolvedEntry.toolName}.`,
+                details: {
+                    requestId,
+                    risk: resolvedEntry.risk,
+                    status: resolvedEntry.status,
+                },
+            });
+            if (resolvedEntry.recoveryHint && resolvedEntry.status !== "allowed") {
+                this.recordHarnessEvent(agent, {
+                    kind: "recovery_hint_emitted",
+                    summary: resolvedEntry.recoveryHint,
+                    details: {
+                        requestId,
+                        status: resolvedEntry.status,
+                    },
+                });
+            }
+        }
+        if (options.transitionRunToStreaming && agent.lifecycle !== "closed") {
+            this.transitionHarnessRunState(agent, {
+                lifecycle: "streaming",
+                summary: resolvedEntry != null
+                    ? `Permission ${resolvedEntry.status} for ${resolvedEntry.toolName}.`
+                    : "Permission resolved.",
+                permissionRequestId: null,
+                dispatchEvent: false,
+            });
+        }
+    }
+    upsertCheckpointSummary(existing, summary) {
+        return [summary, ...(existing ?? []).filter((entry) => entry.id !== summary.id)].slice(0, 50);
+    }
+    deriveHarnessWorkers(agent, turnRows, objective, timestamp) {
+        const workers = {
+            ...(getHarnessSessionExtra(agent.config)?.workers ?? {}),
+        };
+        for (const row of turnRows) {
+            const item = row.item;
+            if (item.type !== "tool_call" || item.detail.type !== "sub_agent") {
+                continue;
+            }
+            const existing = workers[item.callId];
+            const nextStatus = item.status === "running"
+                ? "running"
+                : item.status === "completed"
+                    ? existing?.status === "integrated"
+                        ? "integrated"
+                        : "completed"
+                    : "failed";
+            workers[item.callId] = {
+                id: item.callId,
+                provider: agent.provider,
+                threadId: null,
+                parentAgentId: agent.id,
+                role: inferHarnessWorkerRole(item.detail),
+                kind: "provider_subagent",
+                purpose: item.detail.description?.trim() ||
+                    item.detail.subAgentType?.trim() ||
+                    "Sub-agent task",
+                owner: objective,
+                status: nextStatus,
+                queueState: nextStatus === "running" ? "active" : "completed",
+                outputSummary: item.detail.actions[item.detail.actions.length - 1]?.summary ??
+                    item.detail.description ??
+                    existing?.outputSummary ??
+                    null,
+                changedFiles: existing?.changedFiles ?? [],
+                verificationState: existing?.verificationState ?? "not_needed",
+                startedAt: existing?.startedAt ?? row.timestamp,
+                integratedAt: existing?.integratedAt ?? null,
+                completedAt: nextStatus === "completed" || nextStatus === "integrated" || nextStatus === "failed"
+                    ? timestamp
+                    : existing?.completedAt ?? null,
+                sessionId: existing?.sessionId ?? null,
+                transcriptPath: existing?.transcriptPath ?? null,
+                outputPath: existing?.outputPath ?? null,
+                rolloutPath: existing?.rolloutPath ?? null,
+                recentActions: item.detail.actions.map((action) => ({ ...action })),
+                permissionState: existing?.permissionState ?? "none",
+                lastPermissionRequestId: existing?.lastPermissionRequestId ?? null,
+                lastPermissionToolName: existing?.lastPermissionToolName ?? null,
+                error: item.status === "failed"
+                    ? typeof item.error === "object" && item.error !== null && "message" in item.error
+                        ? String(item.error.message ?? "Worker failed")
+                        : String(item.error)
+                    : null,
+                progress: {
+                    toolCallCount: item.detail.actions.length,
+                    lastActivityAt: row.timestamp,
+                    latestSummary: item.detail.actions[item.detail.actions.length - 1]?.summary ??
+                        item.detail.description ??
+                        existing?.progress?.latestSummary ??
+                        null,
+                },
+                lastUpdatedAt: timestamp,
+            };
+        }
+        return workers;
+    }
+    async captureCheckpoint(agent, input) {
+        if (!this.checkpointStorage) {
+            return null;
+        }
+        const harness = input.harnessSnapshot ?? getHarnessSessionExtra(agent.config);
+        if (!harness) {
+            return null;
+        }
+        try {
+            return await this.checkpointStorage.capture({
+                agentId: agent.id,
+                provider: agent.provider,
+                cwd: agent.cwd,
+                id: input.id,
+                kind: input.kind,
+                objective: input.objective,
+                summary: input.summary,
+                changedFiles: input.changedFiles,
+                turnStartSeq: input.turnStartSeq,
+                turnEndSeq: input.turnEndSeq,
+                harness,
+            });
+        }
+        catch (error) {
+            this.logger.warn({ err: error, agentId: agent.id, checkpointId: input.id }, "Failed to capture Junction harness checkpoint");
+            return null;
+        }
+    }
+    publishCapturedCheckpoint(agent, summary, input) {
+        const current = getHarnessSessionExtra(agent.config);
+        if (!current) {
+            return;
+        }
+        const extraPatch = input.onSetExtra?.(current);
+        setHarnessSessionExtra(agent.config, {
+            ...extraPatch,
+            checkpoints: this.upsertCheckpointSummary(current.checkpoints, summary),
+            lastCheckpointId: summary.id,
+        });
+        this.recordHarnessEvent(agent, {
+            kind: "checkpoint_created",
+            summary: input.eventSummary,
+            checkpointId: summary.id,
+            details: input.details,
+        });
+        this.touchUpdatedAt(agent);
+        this.emitState(agent);
+        const persistTask = this.persistSnapshot(agent).catch((error) => {
+            this.logger.warn({ err: error, agentId: agent.id, checkpointId: summary.id }, "Failed to persist snapshot after publishing Junction harness checkpoint");
+        });
+        this.trackBackgroundTask(persistTask);
+    }
+    isLiveAgent(agent) {
+        return this.agents.get(agent.id) === agent;
+    }
     async prepareHarnessForRun(agent, prompt) {
         const providerInstructionStrategy = resolveProviderInstructionStrategy(agent.provider);
         try {
@@ -2182,21 +2561,79 @@ export class AgentManager {
                 prompt,
                 providerInstructionStrategy,
             });
+            const previousHarnessExtra = getHarnessSessionExtra(agent.config);
+            const turnStartSeq = this.ensureTimelineState(agent).nextSeq;
             const compiledSystemPrompt = compileHarnessSystemPrompt(context);
             applyHarnessSystemPrompt(agent.config, compiledSystemPrompt);
+            const startedAt = new Date().toISOString();
+            const scratchpadDir = previousHarnessExtra?.scratchpadDir ?? ensureHarnessScratchpadDir(agent.id);
             setHarnessSessionExtra(agent.config, {
                 workspaceSynopsis: context.workspaceSynopsis,
                 trustState: context.trustState,
                 contextLayers: context.promptLayers.map((layer) => layer.id),
                 providerInstructionStrategy,
                 harnessVersion: JUNCTION_HARNESS_VERSION,
+                scratchpadDir,
+                resumeState: previousHarnessExtra?.resumeState
+                    ? touchHarnessResumeState(previousHarnessExtra.resumeState, {
+                        status: "live",
+                        source: previousHarnessExtra.resumeState.source,
+                        timestamp: startedAt,
+                        recoveryHint: null,
+                    })
+                    : createHarnessResumeState("new_session", startedAt),
                 currentTurn: {
                     classification: context.classification,
                     objective: context.objective,
-                    turnStartSeq: this.ensureTimelineState(agent).nextSeq,
-                    startedAt: new Date().toISOString(),
+                    turnStartSeq,
+                    startedAt,
                 },
             });
+            if (previousHarnessExtra?.trustState !== context.trustState) {
+                this.recordHarnessEvent(agent, {
+                    kind: "trust_changed",
+                    summary: `Trust state is now ${context.trustState}.`,
+                    trustState: context.trustState,
+                });
+            }
+            if (this.checkpointStorage &&
+                (context.classification === "implement" ||
+                    context.classification === "debug" ||
+                    context.classification === "review")) {
+                const checkpointId = this.idFactory();
+                const record = await this.captureCheckpoint(agent, {
+                    id: checkpointId,
+                    kind: "pre_mutation",
+                    objective: context.objective,
+                    summary: "Pre-mutation checkpoint",
+                    changedFiles: [],
+                    turnStartSeq,
+                    turnEndSeq: turnStartSeq,
+                });
+                if (record) {
+                    this.publishCapturedCheckpoint(agent, this.checkpointStorage.toSummary(record), {
+                        eventSummary: "Created a pre-mutation checkpoint.",
+                        details: {
+                            checkpointKind: "pre_mutation",
+                            turnStartSeq,
+                        },
+                        onSetExtra: (current) => ({
+                            currentTurn: current?.currentTurn
+                                ? {
+                                    ...current.currentTurn,
+                                    preMutationCheckpointId: checkpointId,
+                                }
+                                : {
+                                    classification: context.classification,
+                                    objective: context.objective,
+                                    turnStartSeq,
+                                    startedAt,
+                                    preMutationCheckpointId: checkpointId,
+                                },
+                        }),
+                    });
+                }
+            }
         }
         catch (error) {
             this.logger.warn({ err: error, agentId: agent.id, provider: agent.provider }, "Failed to prepare Junction harness context; continuing with provider defaults");
@@ -2239,21 +2676,156 @@ export class AgentManager {
                 turnEndSeq: turnRows.length > 0 ? turnRows[turnRows.length - 1].seq : currentTurn.turnStartSeq,
                 timestamp,
             });
+        const nextWorkers = this.deriveHarnessWorkers(agent, turnRows, currentTurn.objective, timestamp);
         const sessionState = updateSessionState(harnessExtra?.sessionState ?? null, turnSummary, {
             modeId: agent.currentModeId ?? null,
             modelId: agent.runtimeInfo?.model ?? agent.config.model ?? null,
             thinkingOptionId: agent.runtimeInfo?.thinkingOptionId ?? agent.config.thinkingOptionId ?? null,
         });
-        setHarnessSessionExtra(agent.config, {
+        const nextExtra = {
             ...harnessExtra,
             sessionState,
+            workers: nextWorkers,
             lastTurnSummary: turnSummary,
             lastValidatedAt: turnSummary.lastSuccessfulValidation?.timestamp ?? harnessExtra?.lastValidatedAt ?? null,
             currentTurn: undefined,
             harnessVersion: JUNCTION_HARNESS_VERSION,
+            runLedger: transitionHarnessRunLedger(harnessExtra?.runLedger, {
+                lifecycle: mapTurnOutcomeToRunLifecycle(resolvedOutcome),
+                timestamp,
+                idFactory: this.idFactory,
+                owner: agent.internal ? "background" : "foreground",
+                summary: turnSummary.uiSummary ?? turnSummary.nextRequiredAction,
+                turnStartSeq: turnSummary.turnStartSeq,
+                turnEndSeq: turnSummary.turnEndSeq,
+                correlationId: agent.persistence?.sessionId ?? agent.runtimeInfo?.sessionId ?? null,
+                modelId: agent.runtimeInfo?.model ?? agent.config.model ?? null,
+            }).ledger,
+            resumeState: touchHarnessResumeState(harnessExtra?.resumeState, {
+                status: "live",
+                source: harnessExtra?.resumeState?.source ?? "snapshot",
+                timestamp,
+                recoveryHint: resolvedOutcome === "provider_error"
+                    ? "The previous run failed before completion."
+                    : resolvedOutcome === "canceled"
+                        ? "The previous run was interrupted."
+                        : null,
+            }),
             providerInstructionStrategy: harnessExtra?.providerInstructionStrategy ??
                 resolveProviderInstructionStrategy(agent.provider),
+        };
+        if (harnessExtra?.sessionState?.verificationState !== sessionState.verificationState) {
+            this.recordHarnessEvent(agent, {
+                kind: "verification_changed",
+                summary: `Verification is now ${sessionState.verificationState}.`,
+                verificationState: sessionState.verificationState,
+                details: {
+                    nextRequiredAction: sessionState.nextRequiredAction,
+                },
+            });
+        }
+        const previousWorkerKeys = Object.keys(harnessExtra?.workers ?? {}).sort();
+        const nextWorkerKeys = Object.keys(nextWorkers).sort();
+        if (!isDeepStrictEqual(previousWorkerKeys, nextWorkerKeys)) {
+            for (const workerId of nextWorkerKeys.filter((workerId) => !previousWorkerKeys.includes(workerId))) {
+                this.recordHarnessEvent(agent, {
+                    kind: "worker_updated",
+                    summary: `Tracked worker ${nextWorkers[workerId]?.purpose ?? workerId}.`,
+                    workerId,
+                    details: {
+                        status: nextWorkers[workerId]?.status ?? null,
+                    },
+                });
+            }
+        }
+        if (this.checkpointStorage && turnSummary.changedFiles.length > 0) {
+            const checkpointId = this.idFactory();
+            const task = this.captureCheckpoint(agent, {
+                id: checkpointId,
+                kind: "turn_final",
+                objective: currentTurn.objective,
+                summary: turnSummary.uiSummary,
+                changedFiles: turnSummary.changedFiles,
+                turnStartSeq: turnSummary.turnStartSeq,
+                turnEndSeq: turnSummary.turnEndSeq,
+                harnessSnapshot: nextExtra,
+            }).then((record) => {
+                if (!record) {
+                    return;
+                }
+                if (!this.isLiveAgent(agent)) {
+                    return;
+                }
+                this.publishCapturedCheckpoint(agent, this.checkpointStorage.toSummary(record), {
+                    eventSummary: "Created a restorable checkpoint for this completed turn.",
+                    details: {
+                        checkpointKind: "turn_final",
+                        turnEndSeq: turnSummary.turnEndSeq,
+                        changedFiles: turnSummary.changedFiles,
+                    },
+                });
+            });
+            this.trackBackgroundTask(task);
+        }
+        setHarnessSessionExtra(agent.config, nextExtra);
+    }
+    async listAgentCheckpoints(agentId) {
+        if (!this.checkpointStorage) {
+            return [];
+        }
+        return (await this.checkpointStorage.list(agentId)).map((record) => this.checkpointStorage.toSummary(record));
+    }
+    async restoreAgentCheckpoint(agentId, checkpointId) {
+        if (!this.checkpointStorage) {
+            throw new Error("Checkpoint storage is not configured.");
+        }
+        const agent = this.requireAgent(agentId);
+        if (agent.lifecycle === "running" || agent.pendingRun) {
+            await this.cancelAgentRun(agentId);
+        }
+        const record = await this.checkpointStorage.get(agentId, checkpointId);
+        if (!record) {
+            throw new Error(`Checkpoint not found: ${checkpointId}`);
+        }
+        await this.checkpointStorage.restore(record);
+        agent.config.systemPrompt = record.harness.baseSystemPrompt?.trim() || undefined;
+        setHarnessSessionExtra(agent.config, {
+            ...record.harness,
+            currentTurn: undefined,
+            checkpoints: this.upsertCheckpointSummary(record.harness.checkpoints, {
+                id: record.id,
+                kind: record.kind,
+                createdAt: record.createdAt,
+                objective: record.objective,
+                summary: record.summary,
+                changedFiles: record.changedFiles,
+                restorable: record.restorable,
+                turnStartSeq: record.turnStartSeq,
+                turnEndSeq: record.turnEndSeq,
+            }),
+            lastCheckpointId: record.id,
+            harnessVersion: JUNCTION_HARNESS_VERSION,
+            resumeState: touchHarnessResumeState(record.harness.resumeState, {
+                status: "checkpoint_restored",
+                source: "checkpoint",
+                timestamp: new Date().toISOString(),
+                recoveryHint: "Workspace restored from a saved checkpoint.",
+            }),
+        });
+        this.recordHarnessEvent(agent, {
+            kind: "checkpoint_restored",
+            summary: "Restored the workspace to the selected checkpoint.",
+            checkpointId: record.id,
+            details: {
+                changedFiles: record.changedFiles,
+                turnEndSeq: record.turnEndSeq,
+            },
         });
+        this.touchUpdatedAt(agent);
+        this.emitState(agent);
+        await this.persistSnapshot(agent);
+        await this.refreshRuntimeInfo(agent);
+        return this.agents.get(agentId) ?? agent;
     }
     requireClient(provider) {
         const client = this.clients.get(provider);