@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/session-digest-generator.d.ts

@@ -0,0 +1,64 @@
+import type { Logger } from "pino";
+import type { AgentManager } from "./agent-manager.js";
+import { generateStructuredAgentResponseWithFallback } from "./agent-response-loop.js";
+import { type StructuredGenerationDaemonConfig } from "./structured-generation-providers.js";
+import type { ProviderSnapshotManager } from "./provider-snapshot-manager.js";
+/**
+ * Daemon-side digest refresh. Triggered on the running→idle transition: derives
+ * keyFiles deterministically and generates summary/accomplishments via the same
+ * borrowed-provider rail that powers auto-title generation (no daemon API key).
+ * Self-reported fields (goal/nextStep/blockers/links) are preserved by the
+ * merge. See docs/session-digest.md §4.3 + §5.
+ */
+export interface SessionDigestGeneratorDeps {
+    generateStructuredAgentResponseWithFallback?: typeof generateStructuredAgentResponseWithFallback;
+}
+export interface SessionDigestRefreshOptions {
+    agentManager: AgentManager;
+    agentId: string;
+    cwd: string;
+    providerSnapshotManager?: Pick<ProviderSnapshotManager, "listProviders">;
+    daemonConfig?: StructuredGenerationDaemonConfig | null;
+    currentSelection?: {
+        provider?: string | null;
+        model?: string | null;
+        thinkingOptionId?: string | null;
+    };
+    logger: Logger;
+    deps?: SessionDigestGeneratorDeps;
+    /**
+     * Called once the derivation has finished, whether it produced a digest,
+     * skipped, or failed (JARVIS-V1-SPEC §4).
+     *
+     * This exists because the Jarvis judge and this refresh both listen to the
+     * SAME `finished` attention event. Run in parallel, the judge always wins the
+     * race and reads a digest that has not been written yet, so every briefing
+     * arrives with no summary, no blockers and no deadline, and the judge
+     * correctly answers "quiet" forever. That failure is silent: no error, no log,
+     * a feature that looks alive and delivers nothing. Chaining the judge off this
+     * callback is what makes the substrate actually reach it.
+     */
+    onSettled?: () => void;
+    /** Test seam. Defaults to DIGEST_GENERATION_TIMEOUT_MS. */
+    timeoutMs?: number;
+}
+/** Observability for a path whose failures are permanent (§3.1, hazard 2). */
+declare const digestCounters: {
+    attempted: number;
+    succeeded: number;
+    failed: number;
+    timedOut: number;
+    skippedUnchanged: number;
+};
+export declare function getSessionDigestCounters(): Readonly<typeof digestCounters>;
+/** Test seam: the maps are module-level, so tests need a way back to a clean slate. */
+export declare function resetSessionDigestStateForTests(): void;
+export declare function generateAndApplySessionDigest(options: SessionDigestRefreshOptions): Promise<void>;
+/**
+ * Fire-and-forget, debounced digest refresh. Safe to call on every running→idle
+ * transition — coalesces concurrent calls and skips if refreshed within the
+ * debounce window.
+ */
+export declare function scheduleSessionDigestRefresh(options: SessionDigestRefreshOptions): void;
+export {};
+//# sourceMappingURL=session-digest-generator.d.ts.map

package/dist/server/server/agent/session-digest-generator.js

@@ -0,0 +1,306 @@
+import { z } from "zod";
+import { StructuredAgentFallbackError, StructuredAgentResponseError, generateStructuredAgentResponseWithFallback, } from "./agent-response-loop.js";
+import { resolveStructuredGenerationProviders, } from "./structured-generation-providers.js";
+import { buildDigestSourceText, deriveKeyFilesFromTimeline, mergeDigest, } from "./session-digest.js";
+const SUMMARY_MAX_CHARS = 600;
+const ACCOMPLISHMENT_MAX = 10;
+const NEXT_STEP_MAX_CHARS = 240;
+const BLOCKER_MAX = 5;
+const DIGEST_SUMMARY_SCHEMA = z.object({
+    summary: z.string().max(SUMMARY_MAX_CHARS),
+    accomplishments: z.array(z.string()).max(ACCOMPLISHMENT_MAX),
+    // Jarvis substrate (JARVIS-V1-SPEC §3.1). These land in `derived*` digest keys,
+    // never in the self-reported `nextStep`/`blockers`.
+    // Nullish rather than required: partial substrate beats a whole generation
+    // failing schema validation and costing the summary too. Cheap insurance, and
+    // unlike a second generation call it costs no extra tokens.
+    nextStep: z.string().max(NEXT_STEP_MAX_CHARS).nullish(),
+    blockers: z.array(z.string()).max(BLOCKER_MAX).nullish(),
+    urgency: z.enum(["low", "normal", "high"]).nullish(),
+    deadline: z.string().nullish(),
+});
+/**
+ * Refresh gating (JARVIS-V1-SPEC §3.1, hazard 1).
+ *
+ * The ORIGINAL gate was a flat 10-minute wall-clock debounce, stamped BEFORE the
+ * work ran. Two consequences made it unsafe once the digest became a one-shot,
+ * unrecoverable derivation rather than a nice-to-have summary:
+ *
+ *   1. Back-to-back idles inside the window were silently dropped, and a dropped
+ *      derivation is not always recoverable (see the readability note below).
+ *   2. Stamping before the attempt meant a FAILED generation still burned the
+ *      window, so the next idle was skipped too. That is "record intent as fact":
+ *      the timestamp meant "we tried", not "we produced a digest".
+ *
+ * CORRECTION (measured 2026-07-31). An earlier version of this comment claimed
+ * the timeline is "destroyed shortly after a session goes cold". That is WRONG,
+ * and it was generalized from two probes at the extremes with nothing in between.
+ * What is actually true:
+ *
+ *   - paseo stores NO timeline of its own. Agent records on disk are ~4 KB of
+ *     pure metadata with no timeline key.
+ *   - `get_agent_activity` reads THROUGH to the provider's own transcript, for
+ *     Claude `~/.claude/projects/<slug>/<sid>.jsonl`. Readability is binary and
+ *     age-independent: a 19.6-day-old session returned 88 activities in full.
+ *   - Content is lost only when that provider file is pruned. For Claude that is
+ *     `cleanupPeriodDays`, default 30, which runs at CLI startup on file mtime.
+ *   - A second gate exists: the read fails outright when the agent's `cwd` no
+ *     longer exists ("Working directory does not exist"), which affects sessions
+ *     from removed worktrees or another machine regardless of file retention.
+ *
+ * So this derivation is NOT primarily insurance against a minutes-later loss.
+ * Its real value is (a) surviving the provider's prune window, (b) surviving the
+ * cwd gate, (c) normalizing across providers whose stores paseo cannot read, and
+ * (d) cost: a few hundred bytes of digest instead of re-reading a transcript that
+ * can exceed 40 MB. Still worth doing on every idle, for different reasons than
+ * originally written.
+ *
+ * The replacement gates on CONTENT and nothing else: skip only when the timeline
+ * has not grown since the last SUCCESSFUL digest. New content is new information
+ * and is always worth deriving.
+ *
+ * There is deliberately NO wall-clock floor. An earlier draft had one, and it
+ * reintroduced exactly the bug being fixed: two idles a minute apart, both with
+ * new content, and the second silently dropped. Any clock-based gate re-creates
+ * that, because "we ran recently" and "nothing new happened" are different
+ * questions and only the second is a safe reason to skip a one-shot derivation.
+ *
+ * Cost note: on a chatty session this derives roughly once per completed turn
+ * instead of once per 10 minutes. That is the intended trade. The spec classifies
+ * a lost derivation as a correctness bug and an extra derivation as a cost line.
+ * If cost needs tuning later, the knob must stay content-based (for example
+ * "only derive when the timeline grew by more than N rows"), never clock-based.
+ */
+/**
+ * Hard ceiling on one generation (found live 2026-07-31).
+ *
+ * `generateStructuredAgentResponseWithFallback` takes no signal and no timeout,
+ * and it CAN hang indefinitely: an internal generator agent spawned at 17:50:42
+ * and never settled, no success and no error, for the rest of the daemon's life.
+ *
+ * That is far worse than a slow digest. The hung promise never leaves `inFlight`,
+ * so the agent can never derive again, AND because the Jarvis judge is chained to
+ * `onSettled`, the judge goes permanently silent for that agent too. One stuck
+ * generation quietly removes a card from Jarvis forever, with nothing in the log.
+ *
+ * Racing a timeout turns that into an ordinary failure: counted, logged, mark not
+ * stamped so the next idle retries, and onSettled still fires so the judge runs
+ * with whatever substrate already exists. The abandoned work may keep running in
+ * the background; that is acceptable, recovering the caller is the point.
+ */
+const DIGEST_GENERATION_TIMEOUT_MS = 120000;
+class DigestGenerationTimeoutError extends Error {
+    constructor(ms) {
+        super(`Session digest generation exceeded ${ms}ms`);
+        this.name = "DigestGenerationTimeoutError";
+    }
+}
+function withTimeout(work, ms) {
+    let timer;
+    const bomb = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new DigestGenerationTimeoutError(ms)), ms);
+        // Never let this timer keep the daemon alive on shutdown.
+        timer.unref?.();
+    });
+    return Promise.race([work, bomb]).finally(() => {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    });
+}
+const lastDigestAt = new Map();
+/** agentId -> `${epoch}:${maxSeq}` of the last SUCCESSFUL digest. */
+const lastDigestMark = new Map();
+const inFlight = new Set();
+/** Observability for a path whose failures are permanent (§3.1, hazard 2). */
+const digestCounters = { attempted: 0, succeeded: 0, failed: 0, timedOut: 0, skippedUnchanged: 0 };
+export function getSessionDigestCounters() {
+    return { ...digestCounters };
+}
+/** Test seam: the maps are module-level, so tests need a way back to a clean slate. */
+export function resetSessionDigestStateForTests() {
+    lastDigestAt.clear();
+    lastDigestMark.clear();
+    inFlight.clear();
+    digestCounters.attempted = 0;
+    digestCounters.succeeded = 0;
+    digestCounters.failed = 0;
+    digestCounters.timedOut = 0;
+    digestCounters.skippedUnchanged = 0;
+}
+function buildDigestPrompt(sourceText, todayIso) {
+    return [
+        "You are summarizing a coding agent session so an orchestrator can understand it",
+        "without reading the full transcript. Return JSON with exactly these fields:",
+        `- summary: one paragraph (<= ${SUMMARY_MAX_CHARS} chars) describing what this session`,
+        "  is doing and its current state.",
+        `- accomplishments: up to ${ACCOMPLISHMENT_MAX} short strings, each a concrete thing done`,
+        "  (file changed, feature added, bug fixed). Be specific and factual; do not invent.",
+        `- nextStep: <= ${NEXT_STEP_MAX_CHARS} chars, the single concrete thing this session was`,
+        "  about to do next, phrased as an action. Null if the work is finished or you cannot tell.",
+        `- blockers: up to ${BLOCKER_MAX} short strings, each something STOPPING progress. If the`,
+        "  session is waiting on a specific person or an external party, name them explicitly",
+        '  (for example "waiting on Marco to sign the contract"). Empty array if nothing blocks it.',
+        "- urgency: one of low, normal, high. Judge from the work itself, not from how recent it is.",
+        "  high = production is broken, a client is affected, or a dated commitment is at risk.",
+        "  normal = ordinary in-flight work. low = exploration, cleanup, or already finished.",
+        `- deadline: a real-world calendar date named in the session as a commitment, in YYYY-MM-DD`,
+        `  form. Today is ${todayIso}, so resolve relative phrases like "Friday" against it. Null if`,
+        "  no date is committed to. Do NOT invent one and do not infer a date from mere urgency.",
+        "",
+        "Session transcript:",
+        sourceText,
+    ].join("\n");
+}
+/**
+ * `${epoch}:${maxSeq}` for the agent's current timeline.
+ *
+ * Row `seq` restarts at 1 whenever the timeline store is re-initialized without
+ * seeded rows, so a seq is ONLY comparable within an epoch. Comparing a bare seq
+ * across epochs makes a fresh timeline look older than the last digest and skips
+ * forever, silently. Found live: turn 2 of a session never re-derived because
+ * its post-resume seq was below the pre-resume high-water mark.
+ */
+function resolveDigestMark(agentManager, agentId, rows) {
+    const maxSeq = rows.length > 0 ? rows[rows.length - 1].seq : 0;
+    try {
+        return `${agentManager.getTimelineEpoch(agentId)}:${maxSeq}`;
+    }
+    catch {
+        // Agent not resident: use a marker that can never match a stored one, so we
+        // derive rather than skip. Skipping is the dangerous direction.
+        return `unknown-${Date.now()}:${maxSeq}`;
+    }
+}
+function isUnchangedSinceLastDigest(agentId, mark) {
+    const seen = lastDigestMark.get(agentId);
+    if (seen === undefined) {
+        return false;
+    }
+    const sep = seen.lastIndexOf(":");
+    const markSep = mark.lastIndexOf(":");
+    const sameEpoch = seen.slice(0, sep) === mark.slice(0, markSep);
+    return sameEpoch && Number(mark.slice(markSep + 1)) <= Number(seen.slice(sep + 1));
+}
+export async function generateAndApplySessionDigest(options) {
+    const { agentManager, agentId, cwd, logger } = options;
+    const rows = await agentManager.getTimelineRows(agentId);
+    if (rows.length === 0) {
+        return;
+    }
+    // Content-based gate (see the lastDigestMark block comment above). Extracted
+    // to a helper to stay under the oxlint complexity ceiling of 20.
+    const mark = resolveDigestMark(agentManager, agentId, rows);
+    if (isUnchangedSinceLastDigest(agentId, mark)) {
+        digestCounters.skippedUnchanged += 1;
+        // INFO, not debug. Every bug in this file has been a silent skip; a skip
+        // nobody can see is how a dead feature looks healthy.
+        logger.info({ agentId, mark }, "Session digest skipped: timeline unchanged");
+        return;
+    }
+    // Deterministic, no LLM — always safe to refresh.
+    const keyFiles = deriveKeyFilesFromTimeline(rows);
+    const existing = agentManager.getAgent(agentId)?.digest;
+    let summaryPatch = {};
+    const sourceText = buildDigestSourceText(rows);
+    if (sourceText.trim().length > 0) {
+        const generator = options.deps?.generateStructuredAgentResponseWithFallback ??
+            generateStructuredAgentResponseWithFallback;
+        try {
+            const providers = options.providerSnapshotManager
+                ? await resolveStructuredGenerationProviders({
+                    cwd,
+                    providerSnapshotManager: options.providerSnapshotManager,
+                    daemonConfig: options.daemonConfig,
+                    currentSelection: options.currentSelection,
+                })
+                : [];
+            digestCounters.attempted += 1;
+            const result = await withTimeout(generator({
+                manager: agentManager,
+                cwd,
+                prompt: buildDigestPrompt(sourceText, new Date().toISOString().slice(0, 10)),
+                schema: DIGEST_SUMMARY_SCHEMA,
+                schemaName: "SessionDigestSummary",
+                maxRetries: 2,
+                providers,
+                persistSession: false,
+                logger,
+                agentConfigOverrides: {
+                    title: "Session digest generator",
+                    internal: true,
+                },
+            }), options.timeoutMs ?? DIGEST_GENERATION_TIMEOUT_MS);
+            summaryPatch = {
+                summary: result.summary,
+                accomplishments: result.accomplishments,
+                // Derived fields go in their own keys. Writing `nextStep`/`blockers`
+                // directly would clobber whatever the session self-reported, because
+                // mergeDigest overwrites any key present in the patch.
+                ...(result.nextStep ? { derivedNextStep: result.nextStep } : {}),
+                ...(result.blockers ? { derivedBlockers: result.blockers } : {}),
+                ...(result.urgency ? { urgency: result.urgency } : {}),
+                ...(result.deadline ? { derivedDeadline: result.deadline } : {}),
+            };
+            // Stamp ONLY on success. A failure must leave the window open so the next
+            // idle retries: there is no catch-up job, and the source transcript is
+            // subject to the provider's own prune window and the cwd gate, so a
+            // derivation missed today may not be reproducible later.
+            lastDigestAt.set(agentId, Date.now());
+            lastDigestMark.set(agentId, mark);
+            digestCounters.succeeded += 1;
+        }
+        catch (error) {
+            digestCounters.failed += 1;
+            if (error instanceof DigestGenerationTimeoutError) {
+                digestCounters.timedOut += 1;
+            }
+            const attempts = error instanceof StructuredAgentFallbackError ? error.attempts : undefined;
+            logger.error({ err: error, agentId, attempts, failedTotal: digestCounters.failed }, error instanceof StructuredAgentResponseError ||
+                error instanceof StructuredAgentFallbackError
+                ? "Session digest summary generation failed (derivation lost for this idle; will retry on next idle)"
+                : "Session digest generation failed (derivation lost for this idle; will retry on next idle)");
+            // Fall through — still persist the deterministic keyFiles + timestamp.
+        }
+    }
+    const next = mergeDigest(existing, {
+        keyFiles,
+        generatedAt: new Date().toISOString(),
+        ...summaryPatch,
+    });
+    await agentManager.updateAgentMetadata(agentId, { digest: next });
+}
+/**
+ * Fire-and-forget, debounced digest refresh. Safe to call on every running→idle
+ * transition — coalesces concurrent calls and skips if refreshed within the
+ * debounce window.
+ */
+export function scheduleSessionDigestRefresh(options) {
+    const { agentId } = options;
+    if (inFlight.has(agentId)) {
+        return;
+    }
+    // The gate itself moved into generateAndApplySessionDigest: it needs the
+    // timeline to tell "nothing new happened" apart from "we ran recently", and
+    // only the former is a safe reason to skip a one-shot derivation.
+    inFlight.add(agentId);
+    queueMicrotask(() => {
+        void generateAndApplySessionDigest(options)
+            .catch((error) => {
+            options.logger.error({ err: error, agentId }, "Session digest refresh crashed");
+        })
+            .finally(() => {
+            inFlight.delete(agentId);
+            // Fires even on skip or failure: a judge that only ran on the happy path
+            // would go silent exactly when something went wrong, which is when the
+            // user most needs to hear about it.
+            try {
+                options.onSettled?.();
+            }
+            catch (error) {
+                options.logger.error({ err: error, agentId }, "Session digest onSettled hook threw");
+            }
+        });
+    });
+}
+//# sourceMappingURL=session-digest-generator.js.map

package/dist/server/server/agent/session-digest.d.ts

@@ -0,0 +1,81 @@
+import type { PendingDecision, SessionDigest } from "../messages.js";
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+/**
+ * Pure helpers for the session digest feature. Kept free of I/O so they are
+ * trivially unit-testable. See docs/session-digest.md.
+ */
+export interface DigestTimelineRow {
+    item: AgentTimelineItem;
+}
+/**
+ * Deterministically derive the touched-files list from an agent's timeline —
+ * the filePath of every edit/write tool call, most-recently-touched first,
+ * de-duplicated, capped. No LLM, cannot drift from what the agent actually did.
+ * See docs/session-digest.md §4.2.
+ */
+export declare function deriveKeyFilesFromTimeline(rows: readonly DigestTimelineRow[], max?: number): string[];
+/**
+ * Assemble a compact transcript from the timeline for the digest summary LLM
+ * pass — user/assistant messages plus a one-line note per notable tool call.
+ * Keeps the most-recent tail within maxChars so the prompt stays bounded.
+ */
+export declare function buildDigestSourceText(rows: readonly DigestTimelineRow[], maxChars?: number): string;
+/**
+ * Merge a digest patch onto an existing digest, dropping undefined keys so a
+ * partial update never clobbers fields it doesn't set. Self-reported fields
+ * (goal/nextStep/blockers/links) and daemon-derived fields (keyFiles/summary/
+ * accomplishments) own disjoint keys, so the merge is conflict-free.
+ */
+export declare function mergeDigest(existing: SessionDigest | undefined, patch: Partial<SessionDigest>): SessionDigest;
+/**
+ * True when a digest carries no meaningful content (all fields empty/absent).
+ * Used to avoid emitting empty digest objects.
+ */
+export declare function isDigestEmpty(digest: SessionDigest | undefined): boolean;
+/**
+ * Cap on decisions carried on a digest. Answered entries are pruned first —
+ * they only exist so the agent can read the answer back — so a full list never
+ * silently drops something still waiting on the user.
+ */
+export declare const MAX_PENDING_DECISIONS = 20;
+/**
+ * Merge agent-reported decisions onto the stored list, upserting by `id`.
+ *
+ * The agent never writes the answer fields — they are stripped off the incoming
+ * entry and carried forward from the stored one. Without that, an agent that
+ * re-reports its open questions on a later turn would wipe a choice the user
+ * made in between, and the answer would be lost with no trace. Same principle
+ * that keeps `keyFiles`/`summary` daemon-owned: whoever is not the authority on
+ * a field cannot overwrite it.
+ *
+ * `replace` mode replaces the SET of decisions (ids absent from `incoming` are
+ * dropped); it still cannot fabricate or erase an answer for an id it keeps.
+ */
+export declare function mergePendingDecisions(existing: readonly PendingDecision[] | undefined, incoming: readonly PendingDecision[], mode?: "merge" | "replace"): PendingDecision[];
+export interface AnswerPendingDecisionInput {
+    decisionId: string;
+    optionId: string | null;
+    note: string | null;
+    at: string;
+    by: NonNullable<PendingDecision["answeredBy"]>;
+}
+export type AnswerPendingDecisionResult = {
+    ok: true;
+    decisions: PendingDecision[];
+    decision: PendingDecision;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Record the user's choice on one pending decision. Pure — the caller persists.
+ *
+ * Rejects an unknown decision id and an option id that is not on that decision,
+ * rather than storing a dangling reference the agent would later read as a
+ * choice nobody made. Answering with `optionId: null` requires a note, so an
+ * answer always carries content.
+ */
+export declare function answerPendingDecision(existing: readonly PendingDecision[] | undefined, input: AnswerPendingDecisionInput): AnswerPendingDecisionResult;
+/** Decisions still waiting on a human — the read the whole feature exists for. */
+export declare function decisionsAwaitingUser(digest: SessionDigest | undefined): PendingDecision[];
+//# sourceMappingURL=session-digest.d.ts.map

package/dist/server/server/agent/session-digest.js

@@ -0,0 +1,226 @@
+const MAX_KEY_FILES = 20;
+const DEFAULT_TRANSCRIPT_MAX_CHARS = 6000;
+/**
+ * Deterministically derive the touched-files list from an agent's timeline —
+ * the filePath of every edit/write tool call, most-recently-touched first,
+ * de-duplicated, capped. No LLM, cannot drift from what the agent actually did.
+ * See docs/session-digest.md §4.2.
+ */
+export function deriveKeyFilesFromTimeline(rows, max = MAX_KEY_FILES) {
+    const seen = new Set();
+    const ordered = [];
+    for (let i = rows.length - 1; i >= 0; i--) {
+        const item = rows[i].item;
+        if (item.type !== "tool_call") {
+            continue;
+        }
+        const detail = item.detail;
+        if (detail.type !== "edit" && detail.type !== "write") {
+            continue;
+        }
+        const filePath = detail.filePath;
+        if (filePath.length === 0 || seen.has(filePath)) {
+            continue;
+        }
+        seen.add(filePath);
+        ordered.push(filePath);
+        if (ordered.length >= max) {
+            break;
+        }
+    }
+    return ordered;
+}
+/**
+ * Assemble a compact transcript from the timeline for the digest summary LLM
+ * pass — user/assistant messages plus a one-line note per notable tool call.
+ * Keeps the most-recent tail within maxChars so the prompt stays bounded.
+ */
+export function buildDigestSourceText(rows, maxChars = DEFAULT_TRANSCRIPT_MAX_CHARS) {
+    const lines = [];
+    for (const { item } of rows) {
+        if (item.type === "user_message") {
+            const text = item.text.trim();
+            if (text) {
+                lines.push(`User: ${text}`);
+            }
+        }
+        else if (item.type === "assistant_message") {
+            const text = item.text.trim();
+            if (text) {
+                lines.push(`Assistant: ${text}`);
+            }
+        }
+        else if (item.type === "tool_call") {
+            const detail = item.detail;
+            if (detail.type === "edit") {
+                lines.push(`[edited ${detail.filePath}]`);
+            }
+            else if (detail.type === "write") {
+                lines.push(`[wrote ${detail.filePath}]`);
+            }
+            else if (detail.type === "shell") {
+                lines.push(`[ran: ${detail.command}]`);
+            }
+        }
+    }
+    const joined = lines.join("\n");
+    if (joined.length <= maxChars) {
+        return joined;
+    }
+    // Keep the most-recent tail — that's where the current state lives.
+    return joined.slice(joined.length - maxChars);
+}
+/**
+ * Merge a digest patch onto an existing digest, dropping undefined keys so a
+ * partial update never clobbers fields it doesn't set. Self-reported fields
+ * (goal/nextStep/blockers/links) and daemon-derived fields (keyFiles/summary/
+ * accomplishments) own disjoint keys, so the merge is conflict-free.
+ */
+export function mergeDigest(existing, patch) {
+    const merged = { ...existing };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * True when a digest carries no meaningful content (all fields empty/absent).
+ * Used to avoid emitting empty digest objects.
+ */
+export function isDigestEmpty(digest) {
+    if (!digest) {
+        return true;
+    }
+    return (!digest.goal &&
+        !digest.nextStep &&
+        !digest.summary &&
+        (digest.blockers?.length ?? 0) === 0 &&
+        (digest.links?.length ?? 0) === 0 &&
+        (digest.keyFiles?.length ?? 0) === 0 &&
+        (digest.accomplishments?.length ?? 0) === 0);
+}
+/**
+ * Cap on decisions carried on a digest. Answered entries are pruned first —
+ * they only exist so the agent can read the answer back — so a full list never
+ * silently drops something still waiting on the user.
+ */
+export const MAX_PENDING_DECISIONS = 20;
+/** The four fields only the USER (never the agent) may write on a decision. */
+const ANSWER_KEYS = ["answeredAt", "chosenOptionId", "answerNote", "answeredBy"];
+function stripAnswer(decision) {
+    const next = { ...decision };
+    for (const key of ANSWER_KEYS) {
+        delete next[key];
+    }
+    return next;
+}
+function carryAnswerForward(incoming, existing) {
+    if (!existing.answeredAt) {
+        return incoming;
+    }
+    return {
+        ...incoming,
+        answeredAt: existing.answeredAt,
+        ...(existing.chosenOptionId !== undefined ? { chosenOptionId: existing.chosenOptionId } : {}),
+        ...(existing.answerNote !== undefined ? { answerNote: existing.answerNote } : {}),
+        ...(existing.answeredBy !== undefined ? { answeredBy: existing.answeredBy } : {}),
+    };
+}
+/**
+ * Trim to MAX_PENDING_DECISIONS, dropping ANSWERED entries oldest-first. An
+ * unanswered decision is only dropped when the list is entirely unanswered and
+ * over cap — the alternative (dropping by position regardless of state) would
+ * quietly delete a question the user never saw.
+ */
+function capDecisions(decisions) {
+    if (decisions.length <= MAX_PENDING_DECISIONS) {
+        return decisions;
+    }
+    const overflow = decisions.length - MAX_PENDING_DECISIONS;
+    const answeredOldestFirst = decisions
+        .map((decision, index) => ({ decision, index }))
+        .filter((row) => Boolean(row.decision.answeredAt))
+        .sort((a, b) => (a.decision.answeredAt ?? "").localeCompare(b.decision.answeredAt ?? ""));
+    const drop = new Set(answeredOldestFirst.slice(0, overflow).map((row) => row.index));
+    const kept = decisions.filter((_, index) => !drop.has(index));
+    // Still over cap → every remaining entry is unanswered; keep the newest.
+    return kept.length <= MAX_PENDING_DECISIONS
+        ? kept
+        : kept.slice(kept.length - MAX_PENDING_DECISIONS);
+}
+/**
+ * Merge agent-reported decisions onto the stored list, upserting by `id`.
+ *
+ * The agent never writes the answer fields — they are stripped off the incoming
+ * entry and carried forward from the stored one. Without that, an agent that
+ * re-reports its open questions on a later turn would wipe a choice the user
+ * made in between, and the answer would be lost with no trace. Same principle
+ * that keeps `keyFiles`/`summary` daemon-owned: whoever is not the authority on
+ * a field cannot overwrite it.
+ *
+ * `replace` mode replaces the SET of decisions (ids absent from `incoming` are
+ * dropped); it still cannot fabricate or erase an answer for an id it keeps.
+ */
+export function mergePendingDecisions(existing, incoming, mode = "merge") {
+    const byId = new Map();
+    for (const decision of existing ?? []) {
+        byId.set(decision.id, decision);
+    }
+    const out = mode === "replace" ? [] : [...(existing ?? [])];
+    for (const raw of incoming) {
+        const sanitized = stripAnswer(raw);
+        const previous = byId.get(raw.id);
+        const next = previous ? carryAnswerForward(sanitized, previous) : sanitized;
+        const at = out.findIndex((decision) => decision.id === raw.id);
+        if (at >= 0) {
+            out[at] = next;
+        }
+        else {
+            out.push(next);
+        }
+    }
+    return capDecisions(out);
+}
+/**
+ * Record the user's choice on one pending decision. Pure — the caller persists.
+ *
+ * Rejects an unknown decision id and an option id that is not on that decision,
+ * rather than storing a dangling reference the agent would later read as a
+ * choice nobody made. Answering with `optionId: null` requires a note, so an
+ * answer always carries content.
+ */
+export function answerPendingDecision(existing, input) {
+    const decisions = [...(existing ?? [])];
+    const index = decisions.findIndex((decision) => decision.id === input.decisionId);
+    if (index < 0) {
+        return { ok: false, error: `No pending decision with id "${input.decisionId}"` };
+    }
+    const target = decisions[index];
+    const note = input.note?.trim() ?? "";
+    if (input.optionId === null && note.length === 0) {
+        return { ok: false, error: "Answer needs an optionId or a note" };
+    }
+    if (input.optionId !== null && !target.options.some((option) => option.id === input.optionId)) {
+        const available = target.options.map((option) => option.id).join(", ");
+        return {
+            ok: false,
+            error: `Option "${input.optionId}" is not on decision "${input.decisionId}" (options: ${available})`,
+        };
+    }
+    const answered = {
+        ...target,
+        answeredAt: input.at,
+        answeredBy: input.by,
+        ...(input.optionId !== null ? { chosenOptionId: input.optionId } : {}),
+        ...(note.length > 0 ? { answerNote: note } : {}),
+    };
+    decisions[index] = answered;
+    return { ok: true, decisions, decision: answered };
+}
+/** Decisions still waiting on a human — the read the whole feature exists for. */
+export function decisionsAwaitingUser(digest) {
+    return (digest?.pendingDecisions ?? []).filter((decision) => !decision.answeredAt);
+}
+//# sourceMappingURL=session-digest.js.map