@kendoo.agentdesk/agentdesk 0.31.1 → 0.32.0

package/CHANGELOG.md

@@ -8,6 +8,14 @@ All user-facing changes to AgentDesk. Each entry is tagged:
 
 Internal refactors, infrastructure changes, and architectural notes are not listed here.
 
+## [0.32.0] — 2026-09-21
+
+### Changed
+- `[CLI]` Publishing is verified on the spot. When the team runs `git push` or `gh pr create`, the engine runs the project's `test`/`build`/`lint` at the commit being published and refuses with the failing output until a new commit passes; the review that follows reuses a passing run instead of running everything twice. Reviewers can no longer push or change history either.
+- `[CLI]` A phase that ends without its structured handoff is run again once; if it misses again the session ends for human review instead of letting the next phase start from nothing.
+- `[UI]` A Delivery strip above the conversation shows the engine's verification results (each command, pass/fail, failing output), the open items carried between phases, and the phase-by-phase handoff timeline with commit changes — live, and after a restart.
+- `[UI]` The conversation defaults to a product view: the lead's narrative stays inline, the team's reports fold into one expandable row, and tool calls and status notes are hidden. Switch to Full in the session row to see everything; the choice is remembered.
+
 ## [0.31.1] — 2026-09-21
 
 ### Fixed

package/README.md

@@ -265,7 +265,7 @@ Valid values: `"default"`, `"opus"`, `"sonnet"`, `"haiku"`. `"default"` resolves
 
 The `REVIEW` phase is a read-only completeness check (no code changes) — it verifies the implementation meets requirements, flags missed documentation updates or silently-deferred scope. If gaps are found, the orchestrator loops back to `EXECUTION` once before moving on. The `SUMMARY` phase writes the final tracker comments and session protocol.
 
-Before the reviewers are asked, the engine runs the project's own checks itself — `commands.test`, `commands.build` and `commands.lint` from project settings, or the `test`/`build`/`lint` scripts in `package.json` when those are unset — inside the session sandbox, at the current commit. A failing check goes straight back to `EXECUTION` with the real output as findings; the reviewers are only asked once the checks pass. An approval is pinned to that commit: if the code changes afterwards, the approval no longer counts and the session ends for human review instead of reporting success. In a session worktree, uncommitted changes block review too — an approval refers to a committed revision. `SUMMARY` cannot commit, move `HEAD`, or push; it writes messages only.
+Before the reviewers are asked, the engine runs the project's own checks itself — `commands.test`, `commands.build` and `commands.lint` from project settings, or the `test`/`build`/`lint` scripts in `package.json` when those are unset — inside the session sandbox, at the current commit. A failing check goes straight back to `EXECUTION` with the real output as findings; the reviewers are only asked once the checks pass. An approval is pinned to that commit: if the code changes afterwards, the approval no longer counts and the session ends for human review instead of reporting success. In a session worktree, uncommitted changes block review too — an approval refers to a committed revision. Publishing is verified the same way, on the spot: when the team runs `git push` or `gh pr create`, the engine runs the checks at the revision being published and refuses with the failing output until a new commit passes (a passing run is reused by the review that follows). `REVIEW` and `SUMMARY` cannot commit, move `HEAD`, or push; they read and write messages only.
 
 The team follows the task. `INTAKE` assesses the scope — `small` or `standard`, and which areas the change touches (`ui`, `copy`, `docs`, `api`, `data`). A small task skips `PLAN` (Dennis states the approach at the start of `EXECUTION`) and is reviewed by Bart and Vera; Sam's architecture audit still gates the PR inside `EXECUTION`. Luna, Mark and Nora join only when the task touches UI, user-facing copy or docs respectively. Set `"teamProfile": "small"` or `"standard"` in `.agentdesk.json` to force it (`"auto"`, the default, lets `INTAKE` decide).
 

package/cli/engine/hooks.mjs

@@ -69,6 +69,9 @@ export function decidePreToolUse({ phase, input, state = {} }) {
   if (phase === "REVIEW" && MUTATING_TOOLS.has(tool)) {
     return { decision: "deny", reason: "REVIEW is read-only: report findings; fixes happen back in EXECUTION." };
   }
+  if (phase === "REVIEW" && tool === "Bash" && (isPublishCommand(input?.tool_input?.command) || isHistoryCommand(input?.tool_input?.command))) {
+    return { decision: "deny", reason: "REVIEW is read-only: it cannot commit, move HEAD, or publish — the verdict refers to the revision as it is." };
+  }
 
   // The approval refers to one revision. SUMMARY may read it and talk about
   // it; it may not edit, commit, move HEAD, or publish.
@@ -108,17 +111,28 @@ function denyOutput(reason) {
 }
 
 // Build the SDK `hooks` option for one phase.
-//   state         — shared session state (openFindings, ...)
+//   state         — shared session state (openFindings, verifyPublish, ...)
 //   onToolUse     — ({ agentType, tool, input }) for the dashboard
 //   onToolResult  — ({ agentType, tool, response }) for the dashboard
 //   onSubagentStop — ({ agentType }) when a subagent finishes
-export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagentStop } = {}) {
+//   verifyTimeoutSec — hook timeout for PreToolUse; publishing may run the
+//                      project's checks inside the hook (state.verifyPublish)
+export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagentStop, verifyTimeoutSec } = {}) {
   return {
     PreToolUse: [{
+      ...(verifyTimeoutSec > 0 ? { timeout: verifyTimeoutSec } : {}),
       hooks: [async (input) => {
         onToolUse?.({ agentType: input.agent_type || null, tool: input.tool_name, input: input.tool_input });
         const d = decidePreToolUse({ phase, input, state });
-        return d.decision === "deny" ? denyOutput(d.reason) : {};
+        if (d.decision === "deny") return denyOutput(d.reason);
+        // Publishing is the one action the policy cannot judge from state
+        // alone: the engine verifies the revision being published, on the
+        // spot. state.verifyPublish is set by the session loop for EXECUTION.
+        if (phase === "EXECUTION" && input.tool_name === "Bash" && isPublishCommand(input.tool_input?.command) && typeof state?.verifyPublish === "function") {
+          const verdict = await state.verifyPublish();
+          if (!verdict?.ok) return denyOutput(verdict?.reason || "Cannot publish: verification did not pass.");
+        }
+        return {};
       }],
     }],
     PostToolUse: [{

package/cli/engine/prompts.mjs

@@ -136,7 +136,7 @@ function createTaskSection({ tracker, config, description }) {
 export function renderPhasePrompt({
   phase, taskId, taskLink, description, createTask, tracker, config = {}, project = {},
   sessionUrl, cwd, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
-  roster = null, profile = null,
+  roster = null, profile = null, handoffRetry = false,
 }) {
   const vars = {
     TASK_ID: taskId,
@@ -180,6 +180,9 @@ export function renderPhasePrompt({
     body += `\n\n## ENGINE VERIFICATION\n\nThe engine ran the project's own checks before this phase. Build on these observations; do not re-run the whole suite blind.\n\n${formatEvidenceForPrompt(evidence)}`;
   }
   if (openItems.length) body += `\n\n${renderOpenItems(openItems)}`;
+  if (handoffRetry) {
+    body += "\n\n## PREVIOUS RUN ENDED WITHOUT ITS HANDOFF\n\nThe last run of this phase did not produce the structured output the schema requires, so nothing was handed forward. Keep this run focused and shorter, and finish while turns remain so the structured summary is captured.";
+  }
   if (sessionMemory) {
     body += `\n\n## SESSION MEMORY (previous phases)\n\n${sessionMemory}`;
   }

package/cli/engine/query.mjs

@@ -35,6 +35,7 @@ export function buildQueryOptions({
   phase, cwd, env, model, agents, allowedTools, lead, state, config = {},
   abortController, sandbox, onChild, onIsolation, hookCallbacks = {},
   extraWritePaths = [],
+  verifyTimeoutSec,
   claudePath = process.env.AGENTDESK_CLAUDE_PATH,
 }) {
   const options = {
@@ -50,7 +51,7 @@ export function buildQueryOptions({
     abortController,
     forwardSubagentText: true,
     outputFormat: { type: "json_schema", schema: PHASE_OUTPUT_SCHEMAS[phase] },
-    hooks: hooksForPhase({ phase, state, ...hookCallbacks }),
+    hooks: hooksForPhase({ phase, state, verifyTimeoutSec, ...hookCallbacks }),
     spawnClaudeCodeProcess: createSandboxedSpawn({ sandbox, onChild, onIsolation, extraWritePaths }),
   };
   if (model) options.model = model;

package/cli/engine/session.mjs

@@ -17,7 +17,7 @@ import { fileURLToPath } from "url";
 import { createScratchHome } from "../session-sandbox.mjs";
 import { resolveGitHubCreds, assertPushable, PreflightError } from "../session-preflight.mjs";
 import {
-  MAX_REVIEW_RETRIES, MAX_PHASE_RUNS, phaseFailed, finalStatus, archiveStaleMemory,
+  MAX_REVIEW_RETRIES, MAX_HANDOFF_RETRIES, MAX_PHASE_RUNS, phaseFailed, finalStatus, archiveStaleMemory,
 } from "../phase-loop.mjs";
 import { buildChildEnv } from "./env.mjs";
 import { loadDotEnv } from "../dotenv.mjs";
@@ -235,6 +235,7 @@ async function executeSession({
   let handoff = false, aborted = false, reviewResolved = !!solo; // solo has no review gate
   let reviewRetries = 0, phaseRuns = 0, lastVerdict = null, lastPhase = null;
   let isolationLogged = false;
+  const handoffRetries = new Map(); // phase → runs that ended without a structured handoff
 
   // --- evidence (engine-owned) ---------------------------------------------
   // The engine runs the project's checks itself before every REVIEW and pins
@@ -250,14 +251,45 @@ async function executeSession({
   });
   const headNow = () => gitState(cwd, workspaceGitEnv).revision;
   let approvedRevision = null;
+  const verify = () => runChecks({ checks, cwd, env: buildChildEnv({ dotenv, sandboxEnv: sandbox.env, extra: workspaceGitEnv }),
+    gitEnv: workspaceGitEnv, runCheck: runOneCheck, timeoutMs: checkTimeoutMs(config), signal: abortController.signal, requireClean });
+  // Generous: every configured check may run to its own timeout inside the hook.
+  const verifyTimeoutSec = Math.ceil((checkTimeoutMs(config) * Math.max(1, checks.length)) / 1000) + 60;
+
+  // Publishing (git push / gh pr create) is verified on the spot: the engine
+  // runs the checks at the revision being published and refuses with the
+  // failing output when they do not pass. A pass is cached per revision, so
+  // REVIEW reuses it at the same HEAD instead of running everything twice; a
+  // failure is never cached — the next attempt gets a fresh run.
+  let verified = null; // { revision, evidence, verdict } from the latest publish verification
+  const verifyPublish = async () => {
+    const head = headNow();
+    if (verified && head && verified.revision === head && verified.evidence.passed) return verified.verdict;
+    const evidence = await verify();
+    if (abortController.signal.aborted) return { ok: false, reason: "Session is being cancelled." };
+    let verdict;
+    if (!evidence.checked && evidence.clean !== false) verdict = { ok: true };
+    else {
+      reportEvidence(evidence, "EXECUTION");
+      appendMemory(renderEvidenceSection(evidence));
+      if (evidence.passed) verdict = { ok: true };
+      else {
+        const lines = evidenceFindings(evidence).map(f => `- ${f.title}\n  ${String(f.detail || "").split("\n").slice(-8).join("\n  ")}`);
+        verdict = { ok: false, reason: `Cannot publish: verification did not pass at ${shortRev(head)}.\n${lines.join("\n")}\nFix it, commit, and publish again — the engine re-runs the checks for the new revision.` };
+      }
+    }
+    verified = { revision: evidence.revision, evidence, verdict };
+    return verdict;
+  };
+  state.verifyPublish = verifyPublish;
 
   // --- handoff ledger (engine-owned) ---------------------------------------
   // One entry per phase run; the open-items list travels into the next prompt.
   const ledger = createLedger(ledgerPath);
   let openItems = [];
 
-  const reportEvidence = evidence => {
-    emit({ type: "session:evidence", phase: "REVIEW", revision: evidence.revision, clean: evidence.clean,
+  const reportEvidence = (evidence, evidencePhase = "REVIEW") => {
+    emit({ type: "session:evidence", phase: evidencePhase, revision: evidence.revision, clean: evidence.clean,
       passed: evidence.passed, checked: evidence.checked, results: evidence.results });
     const at = evidence.revision ? ` at ${shortRev(evidence.revision)}` : "";
     if (!evidence.checked) {
@@ -341,11 +373,17 @@ async function executeSession({
       // to EXECUTION as findings, through the same retry path.
       let evidence = null;
       if (phase === "REVIEW") {
-        evidence = await runChecks({ checks, cwd, env: buildChildEnv({ dotenv, sandboxEnv: sandbox.env, extra: workspaceGitEnv }),
-          gitEnv: workspaceGitEnv, runCheck: runOneCheck, timeoutMs: checkTimeoutMs(config), signal: abortController.signal, requireClean });
+        const head = headNow();
+        const reusable = verified && head && verified.revision === head && verified.evidence.passed && verified.evidence.checked;
+        evidence = reusable ? verified.evidence : await verify();
         if (abortController.signal.aborted) { aborted = true; break; }
-        reportEvidence(evidence);
-        appendMemory(renderEvidenceSection(evidence));
+        if (reusable) {
+          emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Verification at ${shortRev(head)} already passed when the work was published — reusing it for review.` });
+          emit({ type: "session:evidence", phase: "REVIEW", revision: evidence.revision, clean: evidence.clean, passed: evidence.passed, checked: evidence.checked, results: evidence.results });
+        } else {
+          reportEvidence(evidence);
+          appendMemory(renderEvidenceSection(evidence));
+        }
         if (!evidence.passed) {
           settleReview({ outcome: "NEEDS_MORE_WORK", findings: evidenceFindings(evidence), deferred: [], unverifiedClaims: [], reason: null,
             revision: evidence.revision, headNow: evidence.revision, evidence, approved: false, approvalReason: "engine checks did not pass", engineOnly: true });
@@ -374,6 +412,7 @@ async function executeSession({
           openItems: phase === "EXECUTION" && lastVerdict && !lastVerdict.approved ? [] : openItems,
           roster: Object.keys(agents).filter(name => name !== lead),
           profile,
+          handoffRetry: (handoffRetries.get(phase) || 0) > 0,
         });
       if (workspaceRecord) {
         prompt += `\n\n## SESSION WORKSPACE\nAll file reads, writes, shell commands and Git operations must use ${cwd}.\nThe session branch ${workspaceRecord.branch} is already checked out; use it instead of creating or switching branches. The starting branch is ${workspaceRecord.baseRef}. Keep this branch until the session ends. Runtime session memory lives at ${memoryPath}.\n`;
@@ -391,6 +430,7 @@ async function executeSession({
         phase, cwd, env: buildChildEnv({ dotenv, sandboxEnv: sandbox.env, extra: workspaceGitEnv }), model,
         agents, allowedTools, lead, state, config, abortController, sandbox, onChild,
         extraWritePaths: workspaceStateDir ? [workspaceStateDir, workspaceRecord.tree || cwd] : [],
+        verifyTimeoutSec,
         hookCallbacks: {
           onToolResult: result => {
             const outcome = captureOutcome({ ...result, phase, sessionId, taskId, repo: outcomeRepo,
@@ -449,7 +489,23 @@ async function executeSession({
         continue;
       }
 
-      // Other phases: the structured output is the handoff.
+      // Other phases: the structured output IS the handoff. Without it the
+      // next phase would start from nothing — run the phase again once, then
+      // fail closed. Solo mode keeps its single-run behaviour.
+      if (!summary.structuredOutput && phase !== "SOLO") {
+        const attempt = (handoffRetries.get(phase) || 0) + 1;
+        handoffRetries.set(phase, attempt);
+        finishRun({ status: "missing-output" });
+        if (attempt <= MAX_HANDOFF_RETRIES) {
+          emit({ type: "session:error", code: "PHASE_OUTPUT_MISSING", message: `${phase} ended without its structured handoff — running it again (retry ${attempt}/${MAX_HANDOFF_RETRIES}).` });
+          queue.unshift(phase);
+          continue;
+        }
+        emit({ type: "session:error", code: "HANDOFF_INVALID", message: `${phase} ended without its structured handoff again — ending session for human review.` });
+        handoff = true;
+        writeResumeFile({ cwd, taskId, sessionUrl, phase, duration: seconds(startedAt), steps: totals.steps, workspaceId: workspaceRecord?.id });
+        break;
+      }
       if (!summary.structuredOutput) {
         emit({ type: "session:error", code: "PHASE_OUTPUT_MISSING", message: `${phase} produced no structured summary — later phases will have less context.` });
       }

package/cli/phase-loop.mjs

@@ -12,10 +12,17 @@ export const PHASES = ["INTAKE", "PLAN", "EXECUTION", "REVIEW", "SUMMARY"];
 // One execution redo after a failed review, then the session ends unresolved.
 export const MAX_REVIEW_RETRIES = 1;
 
-// Absolute ceiling on phase runs. The review loop re-enqueues phases, so a bug
-// in verdict parsing must not be able to spin forever burning tokens. With
-// MAX_REVIEW_RETRIES=1 a legitimate run tops out at 7 (5 + EXECUTION + REVIEW).
-export const MAX_PHASE_RUNS = 10;
+// A phase that ends without its structured handoff is run again once; a
+// second miss ends the session for human review rather than letting the next
+// phase start from nothing.
+export const MAX_HANDOFF_RETRIES = 1;
+
+// Absolute ceiling on phase runs. The review and handoff loops re-enqueue
+// phases, so a bug in verdict or output parsing must not be able to spin
+// forever burning tokens. With MAX_REVIEW_RETRIES=1 and MAX_HANDOFF_RETRIES=1
+// a legitimate run tops out at 12 (5 + EXECUTION + REVIEW + one handoff
+// retry for each of the five non-review runs).
+export const MAX_PHASE_RUNS = 14;
 
 // Classify the first line of `.agentdesk/review-verdict.md`.
 //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
     "server": "node server/index.mjs",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs tests/worktrees.test.mjs tests/workspaces-api.test.mjs tests/engine-outcome.test.mjs tests/session-outcomes.test.mjs tests/outcome-hydration.test.mjs tests/mobile-outcomes.test.mjs tests/session-queue.test.mjs tests/useFollowScroll.test.mjs tests/session-usage.test.mjs tests/task-lookup.test.mjs tests/engine-evidence.test.mjs tests/engine-handoff.test.mjs tests/engine-team-profile.test.mjs tests/project-settings.test.mjs",
+    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs tests/worktrees.test.mjs tests/workspaces-api.test.mjs tests/engine-outcome.test.mjs tests/session-outcomes.test.mjs tests/outcome-hydration.test.mjs tests/mobile-outcomes.test.mjs tests/session-queue.test.mjs tests/useFollowScroll.test.mjs tests/session-usage.test.mjs tests/task-lookup.test.mjs tests/engine-evidence.test.mjs tests/engine-handoff.test.mjs tests/engine-team-profile.test.mjs tests/project-settings.test.mjs tests/delivery.test.mjs tests/feed-view.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='cli/**' --test-coverage-include='server/**' --test-coverage-lines=60 --test-coverage-branches=62 tests/*.test.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/shared/delivery.mjs

@@ -0,0 +1,70 @@
+// Delivery record shared by server and dashboard: the engine's verification
+// evidence, the open items carried between phases, and the handoff ledger.
+// Events arrive from the daemon (untrusted shape); everything is validated
+// and bounded here, once, before it is stored or rendered.
+
+const PHASES = new Set(["INTAKE", "PLAN", "EXECUTION", "REVIEW", "SUMMARY", "SOLO"]);
+const STATUSES = new Set(["ok", "not-approved", "checks-failed", "failed", "missing-output"]);
+const SOURCES = new Set(["review", "engine", "deferred"]);
+const MAX_RESULTS = 10, MAX_OUTPUT = 1000, MAX_ITEMS = 50, MAX_TEXT = 300, MAX_DETAIL = 1000, MAX_HANDOFFS = 20;
+
+const str = (v, max) => (typeof v === "string" ? v.slice(0, max) : "");
+const revision = v => (typeof v === "string" && /^[a-f0-9]{7,64}$/.test(v) ? v : null);
+
+export function emptyDelivery() {
+  return { evidence: null, openItems: [], handoffs: [] };
+}
+
+export function normalizeEvidence(event) {
+  if (!event || typeof event !== "object" || !Array.isArray(event.results)) return null;
+  const results = event.results.slice(0, MAX_RESULTS).flatMap(r => {
+    if (!r || typeof r !== "object" || typeof r.command !== "string") return [];
+    return [{
+      name: str(r.name, 40), command: str(r.command, MAX_TEXT),
+      exitCode: Number.isInteger(r.exitCode) ? r.exitCode : null,
+      durationMs: Number.isFinite(r.durationMs) && r.durationMs >= 0 ? Math.round(r.durationMs) : 0,
+      timedOut: r.timedOut === true, output: str(r.output, MAX_OUTPUT).slice(-MAX_OUTPUT),
+    }];
+  });
+  return {
+    revision: revision(event.revision), clean: typeof event.clean === "boolean" ? event.clean : null,
+    passed: event.passed === true, checked: event.checked === true, results,
+  };
+}
+
+export function normalizeOpenItems(items) {
+  if (!Array.isArray(items)) return [];
+  return items.slice(0, MAX_ITEMS).flatMap(i => {
+    if (!i || typeof i !== "object" || !SOURCES.has(i.source) || typeof i.title !== "string" || !i.title) return [];
+    return [{ source: i.source, title: str(i.title, MAX_TEXT), detail: str(i.detail, MAX_DETAIL) }];
+  });
+}
+
+export function normalizeHandoff(event) {
+  if (!event || typeof event !== "object" || !PHASES.has(event.phase) || !Number.isInteger(event.run) || event.run < 1) return null;
+  return {
+    phase: event.phase, run: event.run,
+    status: STATUSES.has(event.status) ? event.status : "ok",
+    durationMs: Number.isFinite(event.durationMs) && event.durationMs >= 0 ? Math.round(event.durationMs) : 0,
+    revisionBefore: revision(event.revisionBefore), revisionAfter: revision(event.revisionAfter),
+    openItems: normalizeOpenItems(event.openItems),
+  };
+}
+
+// Applies one session:evidence or session:handoff event to a delivery record.
+// Returns the same object when the event is not one of ours or is malformed.
+export function mergeDelivery(delivery, event) {
+  const base = delivery && typeof delivery === "object" ? delivery : emptyDelivery();
+  if (event?.type === "session:evidence") {
+    const evidence = normalizeEvidence(event);
+    return evidence ? { ...base, evidence } : base;
+  }
+  if (event?.type === "session:handoff") {
+    const handoff = normalizeHandoff(event);
+    if (!handoff) return base;
+    const handoffs = [...(base.handoffs || []).filter(h => h.run !== handoff.run), handoff]
+      .sort((a, b) => a.run - b.run).slice(-MAX_HANDOFFS);
+    return { ...base, openItems: handoff.openItems, handoffs };
+  }
+  return base;
+}