@sapiom/harness 0.1.6 → 0.2.0

package/dist/server/index.js

@@ -15,7 +15,6 @@ import { WebSocketServer } from "ws";
 import open from "open";
 import { JSON_BODY_LIMIT_BYTES } from "../shared/types.js";
 import { resolveStatePaths } from "../core/paths.js";
-import { seedExampleProject } from "../core/example-seed.js";
 import { SessionManager, } from "../core/session-manager.js";
 import { TaskManager } from "../core/task-manager.js";
 import { createClaudeCodeAdapter } from "../core/adapters/claude-code.js";
@@ -23,6 +22,10 @@ import { createCodexAdapter } from "../core/adapters/codex.js";
 import { WorkflowRegistry, createWorkflowsRouter, } from "../core/workflow-registry.js";
 import { DEFAULT_MACROS } from "../core/macros.js";
 import { createEventStore } from "../core/collector/store.js";
+import { createClaudeTranscriptEnricher, createSessionRecordReader, } from "../core/session-record.js";
+import { buildRehydrationBrief, systemPromptDeliveryFor, } from "../core/rehydration.js";
+import { createRollingSummarizer, readRollingSummary, } from "../core/rolling-summary.js";
+import { backfillSessionRecords, createRecordArchive, } from "../core/record-archive.js";
 import { createHarnessEmitter } from "../core/collector/analytics-emitter.js";
 import { migrateHarnessIdentity } from "../core/collector/identity-migration.js";
 import { normalizeHookEvent } from "../core/collector/normalizer.js";
@@ -30,7 +33,7 @@ import { enrichTurnCompleted } from "../core/collector/transcript.js";
 import { createSeqCounter } from "../core/collector/seq.js";
 import { findRolloutFile, tailCodexRollout, } from "../core/collector/codex-tailer.js";
 import { getOrCreateMachineId } from "../cli/machine-id.js";
-import { pruneDeadRecentDirs } from "../cli/settings.js";
+import { loadSettings, pruneDeadRecentDirs } from "../cli/settings.js";
 import { generateClaudeSettings } from "../core/inject/claude-settings.js";
 import { generateMcpConfig } from "../core/inject/mcp-config.js";
 import { generateSystemPromptFile } from "../core/inject/system-prompt.js";
@@ -43,8 +46,8 @@ import { PortDetector, portFromUrl } from "../core/port-detector.js";
 import { EventBus } from "../core/event-bus.js";
 import { writeHarnessContext, harnessContextFileExists, } from "../core/workspace-context.js";
 import { ensureCanvasTemplate } from "../core/canvas-template.js";
-import { renderCanvasForSession, renderWorkflowRenderFile, } from "../core/canvas-render.js";
-import { CanvasEnrichmentCoordinator } from "../core/canvas-enrich.js";
+import { renderCanvasForSession } from "../core/canvas-render.js";
+import { invalidateExtractionCache } from "../core/canvas-cache.js";
 import { sweepNdjson } from "../core/collector/store-retention.js";
 import { createDefinitionSlugResolver, resolveAgentsBaseUrl, } from "../core/definition-slug-resolver.js";
 import { createBootTokenMiddleware } from "./auth.js";
@@ -60,6 +63,7 @@ import { createCanvasRenderRouter } from "./canvas-render.js";
 import { createMacrosRouter } from "./macros.js";
 import { createFsRouter } from "./fs.js";
 import { createRunsRouter } from "./runs.js";
+import { createTemplatesRouter } from "./templates.js";
 import { createActionsRouter } from "./actions.js";
 import { createAuthRouter, createMutableAuthState, } from "./auth-routes.js";
 // resolveAgentsBaseUrl is imported above from definition-slug-resolver.js
@@ -100,6 +104,9 @@ function packageRoot() {
 function workflowListsEqual(a, b) {
     if (a.length !== b.length)
         return false;
+    // NUL separates the fields because it can't occur in any of them. Keep it
+    // written as the escape `\u0000` — a literal NUL byte in the source makes
+    // grep and ripgrep classify this whole file as binary and silently skip it.
     const key = (w) => `${w.path}\u0000${w.name}\u0000${w.definitionId ?? ""}\u0000${w.source}`;
     const setA = new Set(a.map(key));
     return b.every((w) => setA.has(key(w)));
@@ -123,8 +130,29 @@ function readVersion() {
  * so the remote `sapiom` MCP is actually authenticated — a factory rather
  * than a plain function since it's per-server-instance state.
  */
-function createDefaultBuildLaunchOpts(apiKey, generatedRoot) {
-    return async (harnessSessionId) => {
+function createDefaultBuildLaunchOpts(apiKey, generatedRoot, rehydration) {
+    return async (harnessSessionId, req) => {
+        // Portable continue (SAP-2059). Resolved before the prompt file is
+        // written, because for a `launch-flag` harness the brief IS part of that
+        // file. Best-effort throughout: a brief that can't be assembled leaves
+        // `rehydratedFrom` unset and the session launches as an ordinary fresh
+        // one rather than failing — see CreateSessionRequest.rehydrateFrom.
+        //
+        // Only ever set on create(): resume() calls this builder with the persisted
+        // HarnessSession, which carries no `rehydrateFrom`, so a rehydrated session
+        // that is later resumed does not get the brief a second time (the agent's
+        // own conversation already holds it).
+        const rehydrateFrom = req.rehydrateFrom;
+        const brief = rehydrateFrom && rehydration
+            ? await rehydration.buildBrief(rehydrateFrom).catch((err) => {
+                console.error("[harness] rehydration brief failed:", err);
+                return null;
+            })
+            : null;
+        // The other channel (post-ready injection, for a harness with no prompt
+        // flag) is driven from the session status handler in startServer — the
+        // brief must not go into a file that adapter never reads.
+        const viaSystemPrompt = brief !== null && rehydration?.deliveryFor(req.harness) === "launch-flag";
         const [settings, mcpConfigFile, systemPromptFile, pluginDir] = await Promise.all([
             generateClaudeSettings({ harnessSessionId, generatedRoot }),
             generateMcpConfig(harnessSessionId, {
@@ -132,7 +160,10 @@ function createDefaultBuildLaunchOpts(apiKey, generatedRoot) {
                 apiKey,
                 generatedRoot,
             }),
-            generateSystemPromptFile(harnessSessionId, { generatedRoot }),
+            generateSystemPromptFile(harnessSessionId, {
+                generatedRoot,
+                ...(viaSystemPrompt ? { appendix: brief } : {}),
+            }),
             generateSkillsPlugin(harnessSessionId, { generatedRoot }),
         ]);
         return {
@@ -140,6 +171,9 @@ function createDefaultBuildLaunchOpts(apiKey, generatedRoot) {
             mcpConfigFile,
             systemPromptFile,
             ...(pluginDir ? { pluginDir } : {}),
+            // Set on BOTH channels: the post-ready path hasn't delivered yet, but a
+            // brief exists and will, and this is the flag that tells it to.
+            ...(brief !== null && rehydrateFrom ? { rehydratedFrom: rehydrateFrom } : {}),
         };
     };
 }
@@ -202,6 +236,19 @@ export const startServer = async (options) => {
     const bus = new EventBus();
     const canvasWatcher = new CanvasWatcherManager({
         onChange: (harnessSessionId) => bus.publish({ type: "canvas.reload", harnessSessionId }),
+        // A workflow SOURCE edit auto re-renders the bound workflow — deterministic
+        // and free, so there's nothing to wait for and no button to press. Uses the
+        // preserve-on-failure path: while an agent is mid-edit the sources are
+        // transiently un-buildable, and flashing an extraction-error panel over a
+        // perfectly good diagram reads as broken. So keep the last good render until
+        // the edit builds cleanly, then swap it in (the write flows back through
+        // onChange above as the iframe reload, with its loading skeleton). Only a
+        // workflow that has never rendered shows the honest error.
+        onSourceChange: (harnessSessionId) => {
+            const session = sessionManager.get(harnessSessionId);
+            if (session)
+                void autoRenderCanvas(session).catch(() => { });
+        },
     });
     // The harness's own infrastructure shouldn't ever show up as a "discovered"
     // dev server in the Preview pane — a mention of our own listening port (in
@@ -293,6 +340,54 @@ export const startServer = async (options) => {
             : null;
         await writeHarnessContext(session, boundWorkflow, workflowsCache);
     };
+    // Declared before the launch-opts builder (rather than beside the ingest
+    // pipeline, where the rest of the event wiring lives) because portable
+    // continue resolves a rehydration brief from this reader at session-create
+    // time — see createDefaultBuildLaunchOpts below.
+    const eventStorePath = options.eventStorePath ?? statePaths.events;
+    const eventStore = createEventStore(eventStorePath);
+    // Archived session records — the copies that survive events.ndjson's 50 MB /
+    // 30-day retention (core/record-archive.ts). Declared here, above the session
+    // manager, because the "exited" handler archives through it.
+    const recordsRoot = options.recordsRoot ?? statePaths.records;
+    const recordArchive = createRecordArchive({ root: recordsRoot });
+    // Past-session transcripts, rebuilt from the events above rather than from
+    // any vendor's history file — the same code path for claude-code and codex.
+    // The claude enricher is a pure bonus on top: when that transcript happens
+    // to still exist, the final turn gains its model/usage; when it doesn't, the
+    // record renders unchanged.
+    const sessionRecordReader = createSessionRecordReader(eventStore, {
+        enrichFinalTurn: createClaudeTranscriptEnricher(),
+        archive: recordArchive,
+    });
+    /**
+     * Fold a session's record from the events and archive it — the write that
+     * makes its history outlive the log. Idempotent (it replaces any earlier
+     * archive of the same conversation), detached, and silent about nothing: a
+     * failure is logged and never propagated, because a session's exit must not
+     * fail over its bookkeeping.
+     *
+     * Folded via `readFromEvents`, deliberately not `read`: re-archiving whatever
+     * `read` returned would compact an already-compacted excerpt and re-stamp it
+     * with a fresh `archivedAt`, making a stale copy look current.
+     *
+     * The sweep runs right after a write because a write is the only thing that
+     * grows the store — enforcing the caps at the moment they can be exceeded
+     * beats waiting for the next boot.
+     */
+    const archiveSessionRecord = async (harnessSessionId) => {
+        const record = await sessionRecordReader.readFromEvents(harnessSessionId);
+        if (!record)
+            return;
+        if (!(await recordArchive.write(record)))
+            return;
+        await recordArchive.sweep();
+    };
+    const archiveSessionRecordDetached = (harnessSessionId) => {
+        void archiveSessionRecord(harnessSessionId).catch((err) => {
+            console.error("[harness] session record archive failed:", err);
+        });
+    };
     // Exit-time deletion of generated/<id> (see the onStatusChange handler
     // below) can race a fast resume(): resume regenerates the dir via
     // buildLaunchOpts, and the rm scheduled at the previous exit could still
@@ -300,8 +395,65 @@ export const startServer = async (options) => {
     // before (re)generating its files.
     const generatedRoot = options.generatedRoot ?? statePaths.generated;
     const pendingGeneratedRemovals = new Map();
+    /**
+     * The git branch the PRIOR session was last on, from whichever adapter
+     * recorded it — our own events never carry one. One adapter history scan per
+     * rehydrate, which is a user-initiated "continue this session" click rather
+     * than a hot path (the reason `GET /sessions/history` avoids per-row probes
+     * doesn't apply to a single deliberate action). Null for a harness whose
+     * transcript doesn't record a branch, and never throws.
+     */
+    const priorGitBranch = async (record) => {
+        if (!record.cwd || !record.agentSessionId)
+            return null;
+        const adapter = adapters[record.harness];
+        if (!adapter)
+            return null;
+        try {
+            const rows = await adapter.listPastSessions(record.cwd);
+            return rows.find((row) => row.agentSessionId === record.agentSessionId)?.gitBranch ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+    /**
+     * Portable continue: the brief text for a `rehydrateFrom` id, or null when
+     * our event log holds nothing for it.
+     *
+     * Closes over `sessionManager` (declared just below, since it consumes the
+     * builder this feeds) for the prior session's title and workflow binding —
+     * safe because nothing can create a session before the manager that creates
+     * them exists.
+     */
+    const resolveRehydrationBrief = (rehydrateFrom) => buildRehydrationBrief(rehydrateFrom, {
+        readRecord: (id) => sessionRecordReader.read(id),
+        readSummary: (harnessSessionId) => readRollingSummary(generatedRoot, harnessSessionId),
+        resolveContext: async (record) => {
+            // The earliest merged session the registry still knows — the record's
+            // own primary id first, so a conversation that spans a resume reports
+            // where it began rather than whichever segment happens to be indexed.
+            const prior = record.mergedSessionIds
+                .map((id) => sessionManager.get(id))
+                .find((session) => session !== undefined);
+            const workflowPath = prior?.boundWorkflowPath ?? null;
+            const workflow = workflowPath
+                ? (workflowsCache.find((w) => w.path === workflowPath) ?? null)
+                : null;
+            return {
+                title: prior?.title ?? null,
+                gitBranch: await priorGitBranch(record),
+                workflow: workflow
+                    ? { name: workflow.name, path: workflow.path, definitionId: workflow.definitionId }
+                    : null,
+            };
+        },
+    });
     const innerBuildLaunchOpts = options.buildLaunchOpts ??
-        createDefaultBuildLaunchOpts(identity?.apiKey ?? null, generatedRoot);
+        createDefaultBuildLaunchOpts(identity?.apiKey ?? null, generatedRoot, {
+            buildBrief: resolveRehydrationBrief,
+            deliveryFor: (harness) => systemPromptDeliveryFor(adapters[harness]),
+        });
     const buildLaunchOpts = async (harnessSessionId, req) => {
         await pendingGeneratedRemovals.get(harnessSessionId);
         return innerBuildLaunchOpts(harnessSessionId, req);
@@ -322,6 +474,41 @@ export const startServer = async (options) => {
     await sessionManager.init();
     const sessionSweepTimer = setInterval(() => sessionManager.sweepDeadSessions(), SESSION_LIVENESS_SWEEP_MS);
     sessionSweepTimer.unref?.();
+    // Portable continue, second channel: for a harness whose adapter never puts
+    // `systemPromptFile` in front of the agent, the brief is injected once the
+    // session reports `ready` — not merely "running", which for a TUI sitting on
+    // a "trust this directory?" prompt would feed the brief to the prompt. No
+    // adapter shipped today needs this (both declare `launch-flag`), so it is
+    // dormant rather than dead: a new harness with no prompt flag gets working
+    // rehydration from one line in its adapter.
+    const briefsDelivered = new Set();
+    sessionManager.onStatusChange((session) => {
+        if (session.status === "exited") {
+            briefsDelivered.delete(session.id);
+            return;
+        }
+        const rehydratedFrom = session.rehydratedFrom;
+        if (!session.ready || !rehydratedFrom)
+            return;
+        if (systemPromptDeliveryFor(adapters[session.harness]) !== "post-ready-injection")
+            return;
+        if (briefsDelivered.has(session.id))
+            return;
+        // Claimed before the await so a burst of status frames can't double-inject.
+        briefsDelivered.add(session.id);
+        void (async () => {
+            const brief = await resolveRehydrationBrief(rehydratedFrom);
+            if (!brief)
+                return;
+            // submit:true — the brief has to enter the conversation to be context at
+            // all; left unsubmitted it would just sit in the composer as a wall of
+            // text the user has to deal with before they can type.
+            await sessionManager.submitInput(session.id, brief, true);
+        })().catch((err) => {
+            briefsDelivered.delete(session.id);
+            console.error("[harness] post-ready rehydration injection failed:", err);
+        });
+    });
     // Background tasks (canvas enrichment today): headless one-shot agent
     // runs that never touch a user's interactive session. They
     // reuse the exact same per-id config generation as sessions — a task's
@@ -343,6 +530,24 @@ export const startServer = async (options) => {
     taskManager.onStatusChange((task) => {
         bus.publish({ type: "task.status", task });
     });
+    // Rolling summary (opt-in, `HarnessSettings.rollingSummary`): folds a live
+    // session's record into a ≤500-word summary.md that a later portable
+    // continue reads. Everything about it is detached from the session's own
+    // path — `noteEvent` is synchronous and the fold is a separate headless
+    // process — so a turn is never slower or riskier for it being on. A codex
+    // session produces none (no `launchTask`); its briefs degrade to
+    // last-N-turns, which is also the default for everyone with the setting off.
+    const rollingSummarizer = createRollingSummarizer({
+        generatedRoot,
+        enabled: async () => (await loadSettings(statePaths.settings)).rollingSummary === true,
+        readRecord: (harnessSessionId) => sessionRecordReader.read(harnessSessionId),
+        getSession: (harnessSessionId) => {
+            const session = sessionManager.get(harnessSessionId);
+            return session ? { harness: session.harness, cwd: session.cwd } : undefined;
+        },
+        runTask: (req) => taskManager.run(req),
+    });
+    taskManager.onStatusChange((task) => rollingSummarizer.noteTaskStatus(task));
     // One boot-time sweep for generated dirs the exit-time cleanup below never
     // reached (crashes, force-kills, accumulation from before retention
     // existed). Age-gated (GENERATED_SWEEP_MAX_AGE_MS) and skips live
@@ -436,6 +641,15 @@ export const startServer = async (options) => {
                 void rescanWorkspaceForSession(session.id).catch((err) => {
                     console.error("[harness] initial workspace rescan failed:", err);
                 });
+                // A resumed/already-bound session skips the rescan's auto-bind render
+                // (guarded by !boundWorkflowPath), so render it here — a reopened
+                // workflow shows its diagram on start without any manual trigger, now
+                // that the empty-state render button is gone.
+                if (session.boundWorkflowPath) {
+                    void autoRenderCanvas(session).catch((err) => {
+                        console.error("[harness] on-start canvas render failed:", err);
+                    });
+                }
             }
         }
         else if (session.status === "exited") {
@@ -445,6 +659,13 @@ export const startServer = async (options) => {
             executionDetector.reset(session.id);
             // Let a resumed session get a fresh on-start rescan.
             rescannedOnStart.delete(session.id);
+            // Archive the record now the session is over, so its history survives
+            // events.ndjson's retention. This path is what covers a session that
+            // exited WITHOUT a SessionEnd hook (killed pty, crashed agent) and so
+            // never produced the `session.end` event the ingest path archives on;
+            // when both fire, the second write simply replaces the first with the
+            // fuller record.
+            archiveSessionRecordDetached(session.id);
             // The generated config dir is dead once the pty is: every file in it
             // is regenerated by buildLaunchOpts on resume, and the agent's last
             // emit.cjs execution (SessionEnd) happens before its process exits.
@@ -495,43 +716,26 @@ export const startServer = async (options) => {
         bus.publish({ type: "workflows.changed" });
         return found;
     };
-    // The AI enrichment layer over the deterministic renders: one bounded
-    // headless task per workflow (spawned on bind when no fresh cache exists,
-    // or by the visualize macro's force refresh), whose validated JSON output
-    // is persisted per-workflow and merged into the render on completion —
-    // the render write alone hot-reloads any open pane via the canvas watcher.
-    const enrichment = new CanvasEnrichmentCoordinator({
-        tasks: taskManager,
-        rerender: async (cwd, workflow) => {
-            await renderWorkflowRenderFile(cwd, workflow);
-        },
-    });
-    // Renders a session's bound workflow via the deterministic pipeline —
-    // always against the live workflowsCache, never an LLM in the render
-    // itself; a cheap no-op for an unbound session (the canvas router serves
-    // the empty state on its own). Never throws (see core/canvas-render.ts);
-    // best-effort, like every other canvas write here. The bind path
-    // (PATCH /sessions/:id/workflow → rest.ts) and the UNPROMPTED call sites
-    // (session-create/boot auto-render, via autoRenderCanvas — which won't
-    // replace a workflow's existing render with an error panel when its
-    // extraction fails) also kick the enrichment freshness check afterwards:
-    // instant base diagram now, annotations merged in when the task lands.
+    // Renders a session's bound workflow via the fully deterministic pipeline —
+    // always against the live workflowsCache; structure + derived annotations,
+    // no LLM, no user token. A cheap no-op for an unbound session (the canvas
+    // router serves the empty state on its own). Never throws (see
+    // core/canvas-render.ts); best-effort, like every other canvas write here.
+    // autoRenderCanvas is the UNPROMPTED variant (session-create/boot) that
+    // won't replace a workflow's existing render with an error panel when its
+    // extraction fails.
     const renderCanvas = async (session) => {
         await renderCanvasForSession(session, workflowsCache);
-        await enrichment.ensureFresh(session, workflowsCache);
     };
     const autoRenderCanvas = async (session) => {
         await renderCanvasForSession(session, workflowsCache, {
             preserveExistingOnFailure: true,
         });
-        await enrichment.ensureFresh(session, workflowsCache);
     };
     const initialWorkflowScan = scanWorkflowsAndBroadcast(launchDir).catch((err) => {
         console.error("[harness] initial workflow scan failed:", err);
         return [];
     });
-    const eventStorePath = options.eventStorePath ?? statePaths.events;
-    const eventStore = createEventStore(eventStorePath);
     // Boot-time retention sweep: keeps events.ndjson within the 50 MB / 30-day
     // caps even on long-lived installs. Runs through the store's exclusive queue
     // so the sweep's read→filter→rename window never races a concurrent append.
@@ -546,6 +750,37 @@ export const startServer = async (options) => {
     runNdjsonSweep();
     const ndjsonRetentionTimer = setInterval(runNdjsonSweep, NDJSON_RETENTION_SWEEP_MS);
     ndjsonRetentionTimer.unref?.();
+    // One boot-time pass that archives conversations the log still holds but the
+    // archive doesn't, then sweeps the archive's own caps. This is what covers the
+    // two cases archiving-at-exit can't: a harness that was force-killed (no exit
+    // transition, no session.end), and every session that ended before this
+    // existed — whose history would otherwise vanish at its 30-day mark.
+    //
+    // It races the ndjson sweep queued above, and deliberately doesn't wait for
+    // it: reads run outside the store's exclusive queue by design (see store.ts),
+    // and either order is correct here — win the race and the record is archived
+    // from bytes retention was about to delete, lose it and the record is archived
+    // from what survived. Both beat not archiving it.
+    //
+    // Fire-and-forget: boot must not wait on it. The cost is one full index build
+    // (~130 ms against a 50 MB log), which the first history open would have paid
+    // anyway.
+    void backfillSessionRecords({
+        conversationIds: () => sessionRecordReader.conversationIds(),
+        readFromEvents: (id) => sessionRecordReader.readFromEvents(id),
+        archive: recordArchive,
+        isLiveSession: (harnessSessionId) => {
+            const session = sessionManager.get(harnessSessionId);
+            return session !== undefined && session.status !== "exited";
+        },
+        onCapped: (remaining) => {
+            console.error(`[harness] session record backfill hit its per-boot cap; ${remaining} conversation(s) left for the next boot`);
+        },
+    })
+        .then(() => recordArchive.sweep())
+        .catch((err) => {
+        console.error("[harness] session record backfill failed:", err);
+    });
     const harnessVersion = readVersion();
     const batcher = createHarnessEmitter({
         telemetryOptIn: options.telemetryOptIn,
@@ -622,12 +857,14 @@ export const startServer = async (options) => {
             });
         },
         launchDir,
+        defaultProjectRoot: options.projectRoot ?? launchDir,
         agentsBaseUrl: resolveAgentsBaseUrl(),
         availableHarnesses: options.availableHarnesses,
         listTasks: () => taskManager.list(),
         firstRun: options.firstRun,
         consentSource: options.consentSource,
         consentEnvReason: options.consentEnvReason,
+        sessionRecords: sessionRecordReader,
         uiTrack: {
             store: eventStore,
             batcher,
@@ -636,12 +873,6 @@ export const startServer = async (options) => {
             userId: identity?.userId ?? null,
             tenantId: identity?.tenantId ?? null,
         },
-        seedSampleProject: async () => {
-            const { root, projectDir, created } = await seedExampleProject({
-                targetRoot: options.sampleProjectRoot ?? statePaths.sampleProject,
-            });
-            return { root, projectDir, created };
-        },
         settingsPath: statePaths.settings,
     }));
     app.use("/api", createCanvasRenderRouter({
@@ -663,6 +894,12 @@ export const startServer = async (options) => {
         apiKey: apiKeyProvider,
         baseUrl: resolveAgentsBaseUrl(),
     }));
+    // The template gallery, relayed from CORE (not the agents surface) so the
+    // Studio's picker and the dashboard's Template library read one catalog.
+    // baseUrl omitted: the router self-defaults via resolveCoreBaseUrl().
+    app.use(createTemplatesRouter({
+        apiKey: apiKeyProvider,
+    }));
     // Direct action macros (Deploy / Prod-run) — server-side, key never reaches
     // the browser, no Claude Code. Resolves a workflow :id (its path) against the
     // same live cache the rest router's findWorkflow uses.
@@ -680,15 +917,17 @@ export const startServer = async (options) => {
         findWorkflow: (workflowPath) => workflowsCache.find((w) => w.path === workflowPath) ?? null,
         getSessionCwd: (harnessSessionId) => sessionManager.get(harnessSessionId)?.cwd ?? null,
         getBoundWorkflowPath: (harnessSessionId) => sessionManager.get(harnessSessionId)?.boundWorkflowPath ?? null,
-        // The visualize macro is a FORCE refresh, not a plain re-render:
-        // invalidate the extraction + enrichment caches, re-render the base
-        // instantly, re-spawn the enrichment task. Its refusals map to the
-        // router's existing error handling (already running → 409, codex
-        // session → 400).
+        // The visualize/refresh macro forces a fresh deterministic re-render:
+        // drop the bound workflow's extraction cache so a source change (new or
+        // removed steps) is picked up, then re-render. Fully deterministic and
+        // instant — no task, no user token, nothing to already-be-running.
         renderCanvas: async (harnessSessionId) => {
             const session = sessionManager.get(harnessSessionId);
-            if (session)
-                await enrichment.forceRefresh(session, workflowsCache);
+            if (!session)
+                return;
+            if (session.boundWorkflowPath)
+                invalidateExtractionCache(session.boundWorkflowPath);
+            await renderCanvas(session);
         },
         injectInput: async (harnessSessionId, text, submit) => {
             // Two-phase write: a combined text+\r lands in Claude Code as a
@@ -745,6 +984,9 @@ export const startServer = async (options) => {
         batcher,
         enrichFromTranscript: enrichTurnCompleted,
         onNormalizedEvent: (event) => {
+            // Synchronous and total — it counts turns and detaches any fold it
+            // decides to start, so the ingest path never waits on a summary.
+            rollingSummarizer.noteEvent(event);
             if (event.type !== "tool.call")
                 return;
             const { toolInput, toolResponseSummary } = event.payload;
@@ -765,6 +1007,14 @@ export const startServer = async (options) => {
                 executionDetector.flush(event.harnessSessionId);
             }
         },
+        onEventPersisted: (event) => {
+            // The normal end of a session: the SessionEnd hook's event is in the
+            // store, so the archived record carries the whole conversation including
+            // its `endedAt`. (The "exited" status handler archives too, for sessions
+            // that never get here.)
+            if (event.type === "session.end")
+                archiveSessionRecordDetached(event.harnessSessionId);
+        },
         onError: (err) => console.error("[harness] ingest processing error:", err),
         seqCounter,
     };
@@ -969,14 +1219,35 @@ export const startServer = async (options) => {
             if (shutdownTimerHandle !== undefined)
                 clearTimeout(shutdownTimerHandle);
             void batcher.close();
+            // wss.close() stops NEW upgrades but never terminates the connections
+            // already open — and httpServer.close() then waits indefinitely for those
+            // sockets to drain. The main window's live /ws/events and /ws/terminal
+            // connections (plus any keep-alive HTTP socket) would therefore hang
+            // close() forever, so Electron's before-quit never reaches app.quit() and
+            // the process lingers as a zombie still holding the single-instance lock —
+            // which blocks the next launch (it hangs on "Starting Sapiom…"). Force
+            // each client shut, drop keep-alive HTTP conns, and bound the final wait
+            // so shutdown always completes.
+            for (const client of terminalWss.clients)
+                client.terminate();
+            for (const client of eventsWss.clients)
+                client.terminate();
             terminalWss.close();
             eventsWss.close();
-            await new Promise((resolve, reject) => {
+            httpServer.closeAllConnections?.();
+            const HTTP_CLOSE_TIMEOUT_MS = 3000;
+            await new Promise((resolve) => {
+                let httpCloseTimer = setTimeout(() => {
+                    httpCloseTimer = undefined;
+                    resolve();
+                }, HTTP_CLOSE_TIMEOUT_MS);
+                httpCloseTimer.unref?.();
                 httpServer.close((err) => {
                     if (err)
-                        reject(err);
-                    else
-                        resolve();
+                        console.error("[harness] httpServer.close error:", err);
+                    if (httpCloseTimer !== undefined)
+                        clearTimeout(httpCloseTimer);
+                    resolve();
                 });
             });
         },