@hyperdrive.bot/fleet-server 0.3.147 → 0.3.149

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

@@ -1,10 +1,10 @@
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WorkflowNotFoundError } from "../workflow/workflow-manager.js";
-import { WorkflowAgentPresetSchema, WorkflowSnapshotSchema, WorkflowStatusSchema, WorkflowTaskGraphSchema, SessionDigestSchema, } from "../messages.js";
+import { WorkflowAgentPresetSchema, WorkflowSnapshotSchema, WorkflowStatusSchema, WorkflowTaskGraphSchema, SessionDigestSchema, PendingDecisionSchema, } from "../messages.js";
 import { normalizeSecretForStorage } from "@hyperdrive.bot/fleet-protocol/session-secrets";
 import { isTagColorName } from "@hyperdrive.bot/fleet-protocol/tag-color";
-import { mergePendingDecisions } from "./session-digest.js";
+import { answerPendingDecision, applyDecisionExpiry, mergePendingDecisions, } from "./session-digest.js";
 import { AgentStatusEnum } from "./mcp-shared.js";
 import { expandUserPath } from "../path-utils.js";
 import { ensureValidJson } from "../json-utils.js";
@@ -605,6 +605,7 @@ export async function createAgentMcpServer(options) {
                     askedAt,
             })), resolvedMode);
         }
+        applyDecisionExpiry(next, existing);
         next.selfReportedAt = new Date().toISOString();
         await agentManager.updateAgentMetadata(callerAgentId, { digest: next });
         return {
@@ -612,6 +613,67 @@ export async function createAgentMcpServer(options) {
             structuredContent: ensureValidJson({ ok: true, digest: next }),
         };
     });
+    server.registerTool("resolve_decision", {
+        title: "Resolve a decision you already settled yourself",
+        description: "Close one of YOUR OWN pendingDecisions that no longer needs the user, because you " +
+            'resolved it in the work itself. Recorded as answeredBy: "agent", which is a ' +
+            "different fact from the user answering and stays visibly different forever. " +
+            "REQUIRES a note saying how it was settled: the user is being told they no longer " +
+            "have to decide, so they are owed the reason. Pass optionId when what you did " +
+            "matches one of the options you listed; omit it when the work went another way and " +
+            "let the note carry it. Refuses a decision the USER already answered - their answer " +
+            "stands and you read it with get_session_digest. Use this the moment a question " +
+            "stops being open, not at the end of the session.",
+        inputSchema: {
+            decisionId: z.string().min(1).max(80),
+            note: z.string().min(1).max(400),
+            optionId: z.string().min(1).max(80).optional(),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            decision: PendingDecisionSchema.optional(),
+            error: z.string().optional(),
+        },
+    }, async ({ decisionId, note, optionId }) => {
+        if (!callerAgentId) {
+            throw new Error("resolve_decision is only available to agent-scoped MCP sessions");
+        }
+        const existing = agentManager.getAgent(callerAgentId)?.digest;
+        const result = answerPendingDecision(existing?.pendingDecisions, {
+            decisionId,
+            optionId: optionId ?? null,
+            note,
+            at: new Date().toISOString(),
+            by: "agent",
+        });
+        if (!result.ok) {
+            /*
+             * Returned, not thrown. "Already answered" and "no such decision" are
+             * both ordinary outcomes of an agent sweeping its own open questions,
+             * and a thrown error reads to the model as a broken tool worth
+             * retrying. It is not: it is the answer.
+             */
+            return {
+                content: [],
+                structuredContent: ensureValidJson({ ok: false, error: result.error }),
+            };
+        }
+        const next = { ...existing, pendingDecisions: result.decisions };
+        /*
+         * This writer ages decisions too. It is the third digest write path and
+         * was the only one not doing it, which quietly broke the invariant
+         * `applyDecisionExpiry`'s own docblock states. An agent sweeping its open
+         * list is exactly when a sibling decision is most likely to be past the
+         * TTL, so skipping it here costs a whole idle cycle for no reason.
+         */
+        applyDecisionExpiry(next, existing);
+        next.selfReportedAt = new Date().toISOString();
+        await agentManager.updateAgentMetadata(callerAgentId, { digest: next });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ ok: true, decision: result.decision }),
+        };
+    });
     return server;
 }
 function unionStrings(existing, incoming) {

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

@@ -1,7 +1,7 @@
 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";
+import { applyDecisionExpiry, buildDigestSourceText, deriveKeyFilesFromTimeline, mergeDigest, } from "./session-digest.js";
 const SUMMARY_MAX_CHARS = 600;
 const ACCOMPLISHMENT_MAX = 10;
 const NEXT_STEP_MAX_CHARS = 240;
@@ -200,7 +200,6 @@ export async function generateAndApplySessionDigest(options) {
     }
     // 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) {
@@ -263,11 +262,43 @@ export async function generateAndApplySessionDigest(options) {
             // Fall through — still persist the deterministic keyFiles + timestamp.
         }
     }
+    /*
+     * Read the digest HERE, after the await above, not before it.
+     *
+     * It used to be read alongside `keyFiles`, then survive an LLM call capped at
+     * `DIGEST_GENERATION_TIMEOUT_MS` (120s), and `setDigest` replaces the digest
+     * wholesale, so this is a read-modify-write across a two-minute window. A user
+     * answering a decision inside that window had their answer written straight
+     * back out.
+     *
+     * On master that showed up as the entry reverting to unanswered: visibly
+     * wrong, and the user just answers again. With decision expiry it stops being
+     * recoverable, because the stale entry is still unanswered and a decision past
+     * the TTL gets stamped `answeredBy: "timeout"` - a terminal state
+     * `answerPendingDecision` refuses to overwrite. The card would then say
+     * "Expired unanswered" about a question they had answered, permanently.
+     *
+     * Nothing between the two points needs the old value: `existing` had exactly
+     * two uses, both below.
+     */
+    const existing = agentManager.getAgent(agentId)?.digest;
     const next = mergeDigest(existing, {
         keyFiles,
         generatedAt: new Date().toISOString(),
         ...summaryPatch,
     });
+    /*
+     * The idle sweep is where a QUIET agent's decisions age out.
+     *
+     * `set_session_digest` expires them too, but an agent that has stopped
+     * self-reporting never calls it, and stopping is the failing case: the
+     * decision this whole mechanism exists for was one the agent answered in its
+     * own code and then never mentioned again. This runs on every running->idle
+     * transition, which that agent still makes, and it rewrites the record the
+     * reel actually reads - so without it a 72h-old question stays on the card
+     * forever no matter what the TTL says.
+     */
+    applyDecisionExpiry(next, existing);
     await agentManager.updateAgentMetadata(agentId, { digest: next });
 }
 /**

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

@@ -38,6 +38,77 @@ export declare function isDigestEmpty(digest: SessionDigest | undefined): boolea
  * silently drops something still waiting on the user.
  */
 export declare const MAX_PENDING_DECISIONS = 20;
+/**
+ * How long an UNANSWERED decision stays open before it expires.
+ *
+ * Three hooks write decisions onto a digest (the protocol injector, the Stop
+ * capture net, the per-turn nudge) and, until this existed, nothing ever took
+ * one off. `capDecisions` reasons about answered-vs-unanswered and has no time
+ * dimension at all, and it protects unanswered entries hardest, so a `blocking`
+ * question the agent then answered ITSELF in code stayed on the digest until 20
+ * newer decisions pushed it out. Measured: `reel-tail-depth` was asked, built,
+ * shipped twice and released, and was still presented to the user as open 31
+ * hours later.
+ *
+ * 72h rather than 24h on purpose. Expiring a question the user is still
+ * thinking about is worse than carrying a dead one an extra day: the first
+ * loses a real decision, the second costs a row.
+ */
+export declare const DECISION_STALE_AFTER_MS: number;
+/**
+ * Close out unanswered decisions older than the TTL, as `answeredBy: "timeout"`.
+ *
+ * NOT deleted. `answeredBy` already carried `"timeout"` as a value that nothing
+ * had ever written, which is the affordance this needs: the entry stays
+ * readable with no `chosenOptionId`, so "nobody ever answered" stays
+ * distinguishable from "answered, and this is the choice". Deleting would make
+ * a dropped question indistinguishable from one that never existed, which is
+ * the same class of silent loss the answer-stripping guard above prevents.
+ *
+ * Marking them answered also hands them to `capDecisions`, which already prunes
+ * answered entries oldest-first, so expiry needs no second eviction path.
+ *
+ * Daemon-side and after the merge, never on the incoming payload: `stripAnswer`
+ * means an agent cannot fake a timeout on its own question to make it go away.
+ *
+ * Deliberately NOT called from `mergePendingDecisions`. Wiring it in there made
+ * that pure, deterministic function depend on the wall clock, and five existing
+ * tests went red on fixtures whose `askedAt` was simply in the past. They were
+ * right: a merge that silently rewrites entries based on when it happens to run
+ * is not a merge. The write path owns the clock; the merge owns the data.
+ */
+export declare function expireStaleDecisions(decisions: readonly PendingDecision[], now?: number, staleAfterMs?: number): PendingDecision[];
+/**
+ * Age out decisions nobody answered, on EVERY digest write, from either writer.
+ *
+ * Not only when the agent sent `pendingDecisions`, which is the distinction the
+ * whole fix turns on: a decision goes stale precisely because the agent STOPPED
+ * mentioning it. `reel-tail-depth` was asked, answered by the agent in its own
+ * code, shipped and released, and never appeared in a payload again, so
+ * anything hanging off the merge would have run zero times on it. It was still
+ * shown to the user as an open blocking question 31 hours later.
+ *
+ * Reads the carried list when this write did not touch decisions, so a digest
+ * that only refreshes `nextStep` still ages them.
+ *
+ * Called from BOTH digest writers, because either one alone leaves the hole
+ * open at its own end:
+ *   - `set_session_digest` (mcp-server.ts) is the agent reporting. An agent
+ *     that has gone quiet does not call it, and quiet is the failing case.
+ *   - `generateAndApplySessionDigest` (session-digest-generator.ts) runs on
+ *     every running->idle transition, which is exactly what a quiet agent still
+ *     does. Without it an agent that stops self-reporting keeps its stale
+ *     decision on the card forever, TTL or no TTL, because nothing rewrites the
+ *     record the reel reads.
+ *
+ * A helper rather than two inline blocks: the MCP handler was already at
+ * oxlint's complexity ceiling and one `if` tipped it to 21.
+ */
+export declare function applyDecisionExpiry(next: {
+    pendingDecisions?: PendingDecision[];
+}, existing: {
+    pendingDecisions?: PendingDecision[];
+} | undefined): void;
 /**
  * Merge agent-reported decisions onto the stored list, upserting by `id`.
  *

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

@@ -128,6 +128,98 @@ function carryAnswerForward(incoming, existing) {
         ...(existing.answeredBy !== undefined ? { answeredBy: existing.answeredBy } : {}),
     };
 }
+/**
+ * How long an UNANSWERED decision stays open before it expires.
+ *
+ * Three hooks write decisions onto a digest (the protocol injector, the Stop
+ * capture net, the per-turn nudge) and, until this existed, nothing ever took
+ * one off. `capDecisions` reasons about answered-vs-unanswered and has no time
+ * dimension at all, and it protects unanswered entries hardest, so a `blocking`
+ * question the agent then answered ITSELF in code stayed on the digest until 20
+ * newer decisions pushed it out. Measured: `reel-tail-depth` was asked, built,
+ * shipped twice and released, and was still presented to the user as open 31
+ * hours later.
+ *
+ * 72h rather than 24h on purpose. Expiring a question the user is still
+ * thinking about is worse than carrying a dead one an extra day: the first
+ * loses a real decision, the second costs a row.
+ */
+export const DECISION_STALE_AFTER_MS = 72 * 60 * 60 * 1000;
+/**
+ * Close out unanswered decisions older than the TTL, as `answeredBy: "timeout"`.
+ *
+ * NOT deleted. `answeredBy` already carried `"timeout"` as a value that nothing
+ * had ever written, which is the affordance this needs: the entry stays
+ * readable with no `chosenOptionId`, so "nobody ever answered" stays
+ * distinguishable from "answered, and this is the choice". Deleting would make
+ * a dropped question indistinguishable from one that never existed, which is
+ * the same class of silent loss the answer-stripping guard above prevents.
+ *
+ * Marking them answered also hands them to `capDecisions`, which already prunes
+ * answered entries oldest-first, so expiry needs no second eviction path.
+ *
+ * Daemon-side and after the merge, never on the incoming payload: `stripAnswer`
+ * means an agent cannot fake a timeout on its own question to make it go away.
+ *
+ * Deliberately NOT called from `mergePendingDecisions`. Wiring it in there made
+ * that pure, deterministic function depend on the wall clock, and five existing
+ * tests went red on fixtures whose `askedAt` was simply in the past. They were
+ * right: a merge that silently rewrites entries based on when it happens to run
+ * is not a merge. The write path owns the clock; the merge owns the data.
+ */
+export function expireStaleDecisions(decisions, now = Date.now(), staleAfterMs = DECISION_STALE_AFTER_MS) {
+    return decisions.map((decision) => {
+        if (decision.answeredAt) {
+            return decision;
+        }
+        const askedAt = Date.parse(decision.askedAt);
+        /*
+         * An unparseable `askedAt` is left alone rather than treated as epoch 0,
+         * which would expire it instantly. A question with a broken timestamp is
+         * still a question.
+         */
+        if (Number.isNaN(askedAt) || now - askedAt < staleAfterMs) {
+            return decision;
+        }
+        return {
+            ...decision,
+            answeredAt: new Date(now).toISOString(),
+            answeredBy: "timeout",
+        };
+    });
+}
+/**
+ * Age out decisions nobody answered, on EVERY digest write, from either writer.
+ *
+ * Not only when the agent sent `pendingDecisions`, which is the distinction the
+ * whole fix turns on: a decision goes stale precisely because the agent STOPPED
+ * mentioning it. `reel-tail-depth` was asked, answered by the agent in its own
+ * code, shipped and released, and never appeared in a payload again, so
+ * anything hanging off the merge would have run zero times on it. It was still
+ * shown to the user as an open blocking question 31 hours later.
+ *
+ * Reads the carried list when this write did not touch decisions, so a digest
+ * that only refreshes `nextStep` still ages them.
+ *
+ * Called from BOTH digest writers, because either one alone leaves the hole
+ * open at its own end:
+ *   - `set_session_digest` (mcp-server.ts) is the agent reporting. An agent
+ *     that has gone quiet does not call it, and quiet is the failing case.
+ *   - `generateAndApplySessionDigest` (session-digest-generator.ts) runs on
+ *     every running->idle transition, which is exactly what a quiet agent still
+ *     does. Without it an agent that stops self-reporting keeps its stale
+ *     decision on the card forever, TTL or no TTL, because nothing rewrites the
+ *     record the reel reads.
+ *
+ * A helper rather than two inline blocks: the MCP handler was already at
+ * oxlint's complexity ceiling and one `if` tipped it to 21.
+ */
+export function applyDecisionExpiry(next, existing) {
+    const carried = next.pendingDecisions ?? existing?.pendingDecisions;
+    if (carried?.length) {
+        next.pendingDecisions = expireStaleDecisions(carried);
+    }
+}
 /**
  * Trim to MAX_PENDING_DECISIONS, dropping ANSWERED entries oldest-first. An
  * unanswered decision is only dropped when the list is entirely unanswered and
@@ -168,7 +260,31 @@ export function mergePendingDecisions(existing, incoming, mode = "merge") {
     for (const decision of existing ?? []) {
         byId.set(decision.id, decision);
     }
-    const out = mode === "replace" ? [] : [...(existing ?? [])];
+    /*
+     * `replace` replaces the agent's OPEN questions, never the user's answers.
+     *
+     * It used to start from `[]`, so an answered entry simply left out of the
+     * payload was dropped with its `chosenOptionId`, `answerNote` and
+     * `answeredBy` - the only place that choice lives. On its own that was
+     * "merely" erasure, and the question came back visibly open.
+     *
+     * `resolve_decision` turns it into forgery in three calls. Drop the answered
+     * entry with a `replace` that omits it; re-report the same id, which now has
+     * no stored `previous`, so `carryAnswerForward` never runs and it is stored
+     * unanswered; then `resolve_decision` sees no `answeredAt`, its guard does not
+     * fire, and the agent writes its OWN choice where the user's had been. The
+     * feed then shows a different answer, attributed to the agent, with no record
+     * that the user ever decided.
+     *
+     * Keeping answered entries unconditionally closes that at the source, for
+     * both tools at once. It costs nothing: `capDecisions` already evicts answered
+     * entries oldest-first, so they still age out, and an incoming id that matches
+     * one is found by the `findIndex` below and runs through `carryAnswerForward`
+     * exactly as in merge mode.
+     */
+    const out = mode === "replace"
+        ? (existing ?? []).filter((decision) => decision.answeredAt)
+        : [...(existing ?? [])];
     for (const raw of incoming) {
         const sanitized = stripAnswer(raw);
         const previous = byId.get(raw.id);

package/dist/server/server/agent/tools/paseo-tools.d.ts

@@ -8,6 +8,7 @@ import type { TerminalManager } from "../../../terminal/terminal-manager.js";
 import type { CreatePaseoWorktreeWorkflowFn } from "../../worktree-session.js";
 import type { JudgeRelayGate } from "../judge-relay-gate.js";
 import type { ScheduleService } from "../../schedule/service.js";
+import type { SubscriptionReader } from "../../ingestion/subscriptions/reader.js";
 import type { ProviderSnapshotManager } from "../provider-snapshot-manager.js";
 import type { GitHubService } from "../../../services/github-service.js";
 import type { WorkspaceGitService } from "../../workspace-git-service.js";
@@ -20,6 +21,14 @@ export interface PaseoToolHostDependencies {
     terminalManager?: TerminalManager | null;
     getDaemonTcpPort?: () => number | null;
     scheduleService?: ScheduleService | null;
+    /**
+     * Read access to session subscriptions and the items they have announced.
+     *
+     * Supplied as two narrow stores rather than a service: these tools only ever
+     * READ, and handing the catalog something that could arm or notify would put
+     * the delivery policy inside a model's reach.
+     */
+    subscriptionReader?: SubscriptionReader | null;
     providerSnapshotManager: ProviderSnapshotManager;
     github?: GitHubService;
     workspaceGitService?: Pick<WorkspaceGitService, "getSnapshot" | "listWorktrees" | "resolveRepoRoot">;

package/dist/server/server/agent/tools/paseo-tools.js

@@ -257,7 +257,7 @@ function resolveTerminalKeyToken(key, literal) {
     }
 }
 export function createPaseoToolCatalog(options) {
-    const { agentManager, agentStorage, terminalManager, scheduleService, providerSnapshotManager, callerAgentId, resolveSpeakHandler, resolveCallerContext, logger, } = options;
+    const { agentManager, agentStorage, terminalManager, scheduleService, subscriptionReader, providerSnapshotManager, callerAgentId, resolveSpeakHandler, resolveCallerContext, logger, } = options;
     const childLogger = logger.child({ module: "agent", component: "paseo-tool-catalog" });
     const waitTracker = new WaitForAgentTracker(logger);
     const callerContext = callerAgentId ? (resolveCallerContext?.(callerAgentId) ?? null) : null;
@@ -2060,6 +2060,81 @@ export function createPaseoToolCatalog(options) {
             structuredContent: ensureValidJson(schedule),
         };
     });
+    registerTool("list_subscriptions", {
+        title: "List subscriptions",
+        description: "List this daemon's source subscriptions: which filter each one listens to, which agent it notifies, and when it last did.",
+        inputSchema: {},
+        outputSchema: {
+            subscriptions: z.array(z.object({
+                id: z.string(),
+                filterId: z.string(),
+                agentId: z.string(),
+                label: z.string().nullable(),
+                status: z.string(),
+                debounceMs: z.number(),
+                lastNotifiedAt: z.string().nullable(),
+            })),
+        },
+    }, async () => {
+        if (!subscriptionReader) {
+            throw new Error("Subscriptions are not configured on this daemon");
+        }
+        const subscriptions = (await subscriptionReader.list(callerAgentId)).map((subscription) => ({
+            id: subscription.id,
+            filterId: subscription.filterId,
+            agentId: subscription.agentId,
+            label: subscription.label,
+            status: subscription.status,
+            debounceMs: subscription.debounceMs,
+            lastNotifiedAt: subscription.lastNotifiedAt,
+        }));
+        return { content: [], structuredContent: ensureValidJson({ subscriptions }) };
+    });
+    registerTool("get_subscription_items", {
+        title: "Get subscription items",
+        description: "Full content of items a subscription notification announced. Pass the subscription id and the item keys from the notice. Keys that are no longer held come back absent rather than as an error.",
+        inputSchema: {
+            subscriptionId: z.string().min(1),
+            itemKeys: z.array(z.string().min(1)).min(1).max(50),
+        },
+        outputSchema: {
+            items: z.array(z.object({
+                itemKey: z.string(),
+                contentHash: z.string(),
+                title: z.string(),
+                subtitle: z.string(),
+                timestampMs: z.number(),
+                notifiedAt: z.string().nullable(),
+                payload: z.unknown(),
+            })),
+            missingKeys: z.array(z.string()),
+        },
+    }, async (input) => {
+        if (!subscriptionReader) {
+            throw new Error("Subscriptions are not configured on this daemon");
+        }
+        const items = await subscriptionReader.resolveItems(input.subscriptionId, input.itemKeys, callerAgentId);
+        const found = new Set(items.map((item) => item.itemKey));
+        // Named, not silent. A key that is gone is an ordinary consequence of the
+        // TTL sweep, and saying which ones went is what stops a caller reading a
+        // short list as the whole answer.
+        const missingKeys = input.itemKeys.filter((key) => !found.has(key));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                items: items.map((item) => ({
+                    itemKey: item.itemKey,
+                    contentHash: item.contentHash,
+                    title: item.title,
+                    subtitle: item.subtitle,
+                    timestampMs: item.timestampMs,
+                    notifiedAt: item.notifiedAt,
+                    payload: item.payload,
+                })),
+                missingKeys,
+            }),
+        };
+    });
     registerTool("list_schedules", {
         title: "List schedules",
         description: "List all schedules managed by the daemon.",

package/dist/server/server/agent/tools/read-only-surface.d.ts

@@ -45,6 +45,13 @@
  * - `run_schedule_once`      fires a schedule now, which starts or prompts an agent.
  * - `rename_workspace`       mutates.
  * - `speak`                  an outward side effect, and voice is out of v1 scope.
+ * - `get_subscription_items`  a FETCHER, not a passive read: it pulls fresh
+ *                            untrusted bytes (raw aggregator event bodies) into
+ *                            the judge's context on demand, widening the very
+ *                            input surface this allowlist bounds. The judge is
+ *                            also the one identity holding an outbound relay
+ *                            channel, and read-only stops mutation, not
+ *                            exfiltration through a channel granted on purpose.
  * - `wait_for_agent`         not mutating, but it BLOCKS. An event-woken judge
  *                            that blocks holds its run open indefinitely.
  */

package/dist/server/server/agent/tools/read-only-surface.js

@@ -45,6 +45,13 @@
  * - `run_schedule_once`      fires a schedule now, which starts or prompts an agent.
  * - `rename_workspace`       mutates.
  * - `speak`                  an outward side effect, and voice is out of v1 scope.
+ * - `get_subscription_items`  a FETCHER, not a passive read: it pulls fresh
+ *                            untrusted bytes (raw aggregator event bodies) into
+ *                            the judge's context on demand, widening the very
+ *                            input surface this allowlist bounds. The judge is
+ *                            also the one identity holding an outbound relay
+ *                            channel, and read-only stops mutation, not
+ *                            exfiltration through a channel granted on purpose.
  * - `wait_for_agent`         not mutating, but it BLOCKS. An event-woken judge
  *                            that blocks holds its run open indefinitely.
  */
@@ -59,6 +66,7 @@ export const READ_ONLY_PASEO_TOOLS = new Set([
     "list_pending_permissions",
     "list_providers",
     "list_schedules",
+    "list_subscriptions",
     "list_terminals",
     "list_worktrees",
     "schedule_logs",

package/dist/server/server/bootstrap.js

@@ -119,6 +119,12 @@ import { ScheduleService } from "./schedule/service.js";
 import { IngestionService } from "./ingestion/service.js";
 import { FilterStore, filtersDir } from "./ingestion/filters/store.js";
 import { SourceStore } from "./ingestion/sources/store.js";
+import { formatSystemNotificationPrompt, sendPromptToAgent } from "./agent/agent-prompt.js";
+import { SubscriptionStore } from "./ingestion/subscriptions/store.js";
+import { PendingItemStore } from "./ingestion/subscriptions/pending-store.js";
+import { SubscriptionNotifier } from "./ingestion/subscriptions/notifier.js";
+import { SubscriptionPoller } from "./ingestion/subscriptions/poller.js";
+import { createSubscriptionReader } from "./ingestion/subscriptions/reader.js";
 import { resolveSourceGateway } from "./ingestion/adapters.js";
 import { CapLimiter } from "./ingestion/cap-limiter.js";
 import { IngestionLedger } from "./ingestion/ledger.js";
@@ -443,6 +449,11 @@ function buildIngestionCollaborators(config, ingestionLedger) {
     const ingestionFilterStore = new FilterStore(filtersDir(config.paseoHome));
     const ingestionSourceStore = new SourceStore(path.join(config.paseoHome, "sources"));
     const ingestionGatewayResolver = resolveIngestionGatewayResolver(config, ingestionConfig);
+    // Session subscriptions. Declared beside the other ingestion stores so the
+    // schedule service below can be handed a live filter resolver rather than the
+    // thrower it has been defaulting to since the source cadence was added.
+    const ingestionSubscriptionStore = new SubscriptionStore(path.join(config.paseoHome, "subscriptions"));
+    const ingestionPendingStore = new PendingItemStore(path.join(config.paseoHome, "subscription-items"));
     return {
         capLimiter,
         ingestionCohortStore,
@@ -450,6 +461,8 @@ function buildIngestionCollaborators(config, ingestionLedger) {
         ingestionFilterStore,
         ingestionSourceStore,
         ingestionGatewayResolver,
+        ingestionSubscriptionStore,
+        ingestionPendingStore,
     };
 }
 export async function createPaseoDaemon(config, rootLogger) {
@@ -936,7 +949,7 @@ export async function createPaseoDaemon(config, rootLogger) {
     // from being true (someone caches `used` in a field to save a query). Two
     // guards, one of which fails loudly.
     //
-    const { capLimiter, ingestionCohortStore, ingestionCohorts, ingestionFilterStore, ingestionSourceStore, ingestionGatewayResolver, } = buildIngestionCollaborators(config, ingestionLedger);
+    const { capLimiter, ingestionCohortStore, ingestionCohorts, ingestionFilterStore, ingestionSourceStore, ingestionGatewayResolver, ingestionSubscriptionStore, ingestionPendingStore, } = buildIngestionCollaborators(config, ingestionLedger);
     // Explicit annotation breaks the inference cycle: this options object passes
     // `schedule: () => scheduleService`, so inferring the type from the initializer
     // is circular (TS7022/TS7023). The lazy closure itself is correct and intended.
@@ -992,6 +1005,62 @@ export async function createPaseoDaemon(config, rootLogger) {
     });
     await ingestionService.start();
     logger.info({ elapsed: elapsed() }, "Ingestion service initialized");
+    // Session subscriptions: source change -> thin notice -> one specific session.
+    //
+    // It owns its own timer and never touches the schedule engine. A subscription
+    // has to survive its target being archived, and `sweepOrphanedSchedules`
+    // completes an agent-target schedule terminally at the next boot, which is the
+    // exact opposite of the rule here: sending to a dead session revives it.
+    const subscriptionNotifier = new SubscriptionNotifier({
+        subscriptions: ingestionSubscriptionStore,
+        pending: ingestionPendingStore,
+        agentManager,
+        filterResolver: (filterId) => ingestionFilterStore.get(filterId),
+        // `sendPromptToAgent` is the one entry point where unarchive, reload and
+        // detached-runtime recycling already live, which is what makes "the session
+        // revives" true rather than aspirational. The `route` it returns is READ
+        // here on purpose: the websocket handler discards it and answers
+        // `accepted: true` even for `no-route`, and a subscription that believed
+        // that would mark items announced that nobody ever saw.
+        send: async ({ agentId, body }) => {
+            const result = await sendPromptToAgent({
+                agentManager,
+                agentStorage,
+                agentId,
+                prompt: formatSystemNotificationPrompt(body),
+                // A notice must not resurrect a session the user deliberately archived.
+                unarchive: false,
+                logger,
+            });
+            // Fail CLOSED on a missing route. `sendPromptToAgent` types `route` as
+            // optional and omits it on exactly one branch: an archived agent when
+            // `unarchive` is false (`agent-prompt.ts:291-295`), which is the branch
+            // this caller always takes. Coalescing that to "live" would mark every
+            // waiting item announced, advance `lastNotifiedAt` and log a delivery,
+            // for a prompt that was never written anywhere.
+            return { route: result.route ?? "no-route" };
+        },
+        logger,
+    });
+    const subscriptionPoller = new SubscriptionPoller({
+        subscriptions: ingestionSubscriptionStore,
+        pending: ingestionPendingStore,
+        notifier: subscriptionNotifier,
+        sourceStore: ingestionSourceStore,
+        filterResolver: (filterId) => ingestionFilterStore.get(filterId),
+        gatewayResolver: ingestionGatewayResolver,
+        logger,
+    });
+    const subscriptionReader = createSubscriptionReader({
+        subscriptions: ingestionSubscriptionStore,
+        pending: ingestionPendingStore,
+    });
+    // The retention half of storing payloads at rest. At boot, beside the other
+    // sweeps, rather than on a timer of its own.
+    await subscriptionPoller.sweep().catch((error) => {
+        logger.warn({ err: error }, "Subscription payload sweep failed");
+    });
+    subscriptionPoller.start();
     // The read-only ingestion PREVIEW collaborators (Story 5.1).
     //
     // Wired beside IngestionService rather than through it, because that service
@@ -1164,6 +1233,7 @@ export async function createPaseoDaemon(config, rootLogger) {
         terminalManager,
         getDaemonTcpPort: () => (boundListenTarget?.type === "tcp" ? boundListenTarget.port : null),
         scheduleService,
+        subscriptionReader,
         providerSnapshotManager,
         github,
         workspaceGitService,

package/dist/server/server/exports.d.ts

@@ -1,6 +1,8 @@
 export { createPaseoDaemon, type PaseoDaemon, type PaseoDaemonConfig } from "./bootstrap.js";
 export { loadConfig, type CliConfigOverrides } from "./config.js";
 export { resolvePaseoHome } from "./paseo-home.js";
+export { SubscriptionStore } from "./ingestion/subscriptions/store.js";
+export { PendingItemStore } from "./ingestion/subscriptions/pending-store.js";
 export { getOrCreateServerId } from "./server-id.js";
 export { createRootLogger, type LogLevel, type LogFormat } from "./logger.js";
 export { loadPersistedConfig, savePersistedConfig, type PersistedConfig, } from "./persisted-config.js";

package/dist/server/server/exports.js

@@ -2,6 +2,12 @@
 export { createPaseoDaemon } from "./bootstrap.js";
 export { loadConfig } from "./config.js";
 export { resolvePaseoHome } from "./paseo-home.js";
+// Session subscriptions. Exported for the CLI, which writes the store DIRECTLY
+// rather than through the daemon: both stores re-read from disk on every call
+// and cache nothing, so a file written here is picked up by the poller's next
+// tick with no RPC and no restart.
+export { SubscriptionStore } from "./ingestion/subscriptions/store.js";
+export { PendingItemStore } from "./ingestion/subscriptions/pending-store.js";
 export { getOrCreateServerId } from "./server-id.js";
 export { createRootLogger } from "./logger.js";
 export { loadPersistedConfig, savePersistedConfig, } from "./persisted-config.js";