@justjoshn/pi-pstack 0.15.36-pi.1 → 0.15.36-pi.7

package/src/subscriptions/index.ts

@@ -1,14 +1,18 @@
 import { randomBytes } from 'node:crypto';
 
-import { StringEnum } from '@earendil-works/pi-ai';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
 import { type Static, Type } from 'typebox';
 import { Value } from 'typebox/value';
 import { isOneShot } from '../modes.ts';
 import { routinesDir } from '../paths.ts';
-import { type CronSchedule, cronMatches, parseCron } from './cron.ts';
-import { defaultGhRunner, fetchPrs, type GhRunner, type PrSnapshot, pollChanges, targetText } from './github.ts';
-import { credentialFile, DEFAULT_ROUTINES_PORT, ensureCredentials, RoutineServer, routineSlug, type WebhookEvent, webhookEventBlock } from './webhook.ts';
+import { parseCron } from './cron.ts';
+import { acquireLease, cancelDesired, canonicalPath, createDesired, deliverOwner, finishFresh, isDesired, isSupervisorLive, type Lease, ownerLockPath, readArm, readRegistry, startFresh, visibleSubscriptions } from './durable-store.ts';
+import type { StoredSubscription } from './durable-types.ts';
+import { defaultEnsureSupervisor, waitForArm, waitForSupervisor } from './ensure-supervisor.ts';
+import { type GhRunner, targetText } from './github.ts';
+import { createSupervisor, type Supervisor } from './supervisor.ts';
+import { credentialFile, routineSlug } from './webhook.ts';
 
 export const SUBSCRIPTIONS_ENTRY = 'pstack/subscriptions';
 export const WAKE_TYPE = 'pstack/subscription';
@@ -16,9 +20,6 @@ export const WAKE_TYPE = 'pstack/subscription';
 const HOUR_MS = 3_600_000;
 const DEFAULT_EXPIRY_MS = 7 * 24 * HOUR_MS;
 const MAX_EXPIRY_HOURS = 30 * 24;
-// setTimeout fires at once past 2^31-1 ms, so long waits are chained in steps of at most this.
-const MAX_STEP_MS = 24 * 24 * HOUR_MS;
-const MINUTE_MS = 60_000;
 
 const TargetSchema = Type.Union([
   Type.Object({ scope: Type.Literal('pr'), prUrl: Type.String() }),
@@ -38,23 +39,6 @@ type Config = Subscription['config'];
 type TimerConfig = Extract<Config, { kind: 'timer' }>;
 type Strategy = TimerConfig['strategy'];
 
-interface Note {
-  at: number;
-  text: string;
-}
-
-interface Live {
-  sub: Subscription;
-  timers: Set<ReturnType<typeof setTimeout>>;
-  lastEvent?: Note;
-  lastError?: Note;
-  baseline?: Map<number, PrSnapshot>;
-  polling?: boolean;
-  url?: string;
-  cron?: CronSchedule;
-  lastCronMinute?: number;
-}
-
 export interface SubscriptionOptions {
   /** Runs a prompt in a fresh background session (a `new_session` timer fire). */
   runFresh: (prompt: string, name: string) => Promise<void> | void;
@@ -63,6 +47,13 @@ export interface SubscriptionOptions {
   /** Routines listener port; defaults to PSTACK_ROUTINES_PORT, else 47913. 0 picks a free port. */
   routinesPort?: number;
   routinesDir?: string;
+  /**
+   * Starts the durable supervisor for this workspace when no live lock exists.
+   * Default spawns `pstack-routines-supervisor` detached so timers and routines survive chat exit.
+   */
+  ensureSupervisor?: (cwd: string) => Promise<void> | void;
+  /** How long create/restore wait for supervisor.lock after ensure (ms). Default 2000. */
+  supervisorReadyMs?: number;
 }
 
 const iso = (ms: number) => new Date(ms).toISOString();
@@ -72,12 +63,6 @@ const oneLine = (text: string, max = 200) => {
 };
 const errorText = (error: unknown) => oneLine(error instanceof Error ? error.message : String(error), 500);
 
-function envPort(): number {
-  const raw = process.env['PSTACK_ROUTINES_PORT'];
-  const port = raw === undefined || raw === '' ? DEFAULT_ROUTINES_PORT : Number(raw);
-  return Number.isInteger(port) && port >= 0 && port < 65536 ? port : DEFAULT_ROUTINES_PORT;
-}
-
 function oneShotError(tool: string): Error {
   return new Error(`${tool} needs an interactive or RPC session: print and JSON runs exit when the agent settles, so nothing could wake this run or fire this subscription later. Do the work now instead.`);
 }
@@ -130,7 +115,7 @@ function timerTarget(config: TimerConfig): string {
 }
 
 const GithubParams = Type.Object({
-  scope: StringEnum(['pr', 'repo', 'author'] as const, { description: 'pr: one pull request (prUrl). repo: every open PR in repo, including PRs opened, closed, or merged. author: open PRs in repo by author.' }),
+  scope: Type.Enum(['pr', 'repo', 'author'] as const, { type: 'string', description: 'pr: one pull request (prUrl). repo: every open PR in repo, including PRs opened, closed, or merged. author: open PRs in repo by author.' }),
   prUrl: Type.Optional(Type.String({ description: 'scope pr: the pull request URL, such as https://github.com/owner/repo/pull/123.' })),
   repo: Type.Optional(Type.String({ description: 'scope repo or author: owner/name.' })),
   author: Type.Optional(Type.String({ description: 'scope author: a GitHub login, or @me.' })),
@@ -145,8 +130,9 @@ const TimerParams = Type.Object({
   delaySeconds: Type.Optional(Type.Integer({ minimum: 1, description: 'Fire this many seconds from now, and again every delaySeconds after that unless once is true.' })),
   once: Type.Optional(Type.Boolean({ description: 'Fire only once, then end the timer. Default false.' })),
   sessionStrategy: Type.Optional(
-    StringEnum(['wake_self', 'new_session'] as const, {
-      description: 'wake_self (default): wake this session with the prompt. new_session: run the prompt in a fresh background subagent each fire; its result arrives as a Task notification.',
+    Type.Enum(['wake_self', 'new_session'] as const, {
+      type: 'string',
+      description: 'wake_self (default) queues the prompt for this owning session. new_session starts fresh work each fire. A live owner gets a background Task notification; offline execution records its outcome in list_subscriptions.',
     }),
   ),
   expiresInHours: Type.Optional(Type.Number({ description: `Hours until the timer ends; default 168 (7 days), at most ${MAX_EXPIRY_HOURS}.` })),
@@ -163,225 +149,217 @@ const UnsubscribeParams = Type.Object({ subscription: Type.String({ description:
 const text = (value: unknown) => ({ content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }], details: value });
 
 export function createSubscriptions(pi: ExtensionAPI, options: SubscriptionOptions) {
-  const live = new Map<string, Live>();
-  const gh = options.gh ?? defaultGhRunner;
-  const pollMs = options.pollIntervalMs ?? MINUTE_MS;
   const dir = options.routinesDir ?? routinesDir();
-  const server = new RoutineServer(options.routinesPort ?? envPort());
-  let active = false;
-
-  const persist = () => pi.appendEntry(SUBSCRIPTIONS_ENTRY, { subscriptions: [...live.values()].map((entry) => entry.sub) });
-
-  const byName = (name: string) => [...live.values()].find((entry) => entry.sub.name === name);
-
-  /** Runs fn at `at`, chaining timeouts so waits past setTimeout's limit stay correct. */
-  const at = (entry: Live, when: number, fn: () => void) => {
-    const handle = setTimeout(
-      () => {
-        entry.timers.delete(handle);
-        if (!active || !owns(entry)) return;
-        if (Date.now() < when) at(entry, when, fn);
-        else fn();
-      },
-      Math.min(Math.max(0, when - Date.now()), MAX_STEP_MS),
-    );
-    handle.unref?.();
-    entry.timers.add(handle);
-  };
-
-  const owns = (entry: Live) => live.get(entry.sub.id) === entry;
-
-  const disarm = (entry: Live) => {
-    for (const handle of entry.timers) clearTimeout(handle);
-    entry.timers.clear();
-    if (entry.sub.config.kind === 'webhook') {
-      server.routes.delete(entry.sub.config.slug);
-      if (server.routes.size === 0) server.close();
+  let workspaceCwd = canonicalPath(process.cwd());
+  let owner: { id: string; cwd: string; lease: Lease; notify: (message: string) => void } | undefined;
+  let ownerPoll: ReturnType<typeof setInterval> | undefined;
+  let fallback: Supervisor | undefined;
+  let starting: Promise<void> | undefined;
+  let draining = false;
+  let lastDrainError: string | undefined;
+
+  const persist = () => pi.appendEntry(SUBSCRIPTIONS_ENTRY, { subscriptions: readRegistry(workspaceCwd).subscriptions.filter((sub) => isDesired(sub)) });
+
+  const drain = () => {
+    const session = owner;
+    if (session === undefined || draining) return;
+    draining = true;
+    try {
+      const eligible = () => owner === session;
+      const registry = readRegistry(session.cwd);
+      const pending = registry.pending.filter((event) => {
+        if (event.retryAt !== undefined && Date.now() < event.retryAt) return false;
+        return registry.subscriptions.some((sub) => sub.id === event.subscriptionId && sub.ownerSessionId === session.id);
+      });
+      if (pending.length === 0) return;
+      deliverOwner(session.cwd, session.id, eligible, (sub, event) => {
+        pi.sendMessage({ customType: WAKE_TYPE, content: event.content, display: true, details: { id: sub.id, eventId: event.id, kind: sub.config.kind, name: sub.name } }, { triggerTurn: true, deliverAs: 'followUp' });
+      });
+      for (const event of pending) {
+        const claim = startFresh(session.cwd, event.id, session.id, eligible, (sub, pending) => options.runFresh(pending.content, sub.name));
+        if (claim !== undefined)
+          void claim.result
+            .then(
+              () => finishFresh(session.cwd, event.id, claim.token),
+              (cause: unknown) => finishFresh(session.cwd, event.id, claim.token, cause),
+            )
+            .catch((cause: unknown) => session.notify(`Subscription result could not be saved. ${errorText(cause)}`));
+      }
+      lastDrainError = undefined;
+    } catch (cause) {
+      const message = errorText(cause);
+      if (message !== lastDrainError) session.notify(`Subscription owner delivery failed. ${message}`);
+      lastDrainError = message;
+    } finally {
+      draining = false;
     }
   };
 
-  const remove = (entry: Live, save = true) => {
-    disarm(entry);
-    // A restored entry reuses the id. Only that object may drop the subscription.
-    if (!owns(entry)) return;
-    live.delete(entry.sub.id);
-    if (save) persist();
+  const ensureEngine = async () => {
+    if (starting !== undefined) return starting;
+    const cwd = workspaceCwd;
+    const session = owner;
+    const attempt = (async () => {
+      if (fallback !== undefined) {
+        await fallback.reconcile();
+        return;
+      }
+      if (isSupervisorLive(cwd)) return;
+      const canDetach = options.routinesDir === undefined || options.routinesDir === routinesDir();
+      if (canDetach) {
+        const ensure = options.ensureSupervisor ?? ((workspace: string) => defaultEnsureSupervisor(workspace, options.routinesPort === undefined ? {} : { routinesPort: options.routinesPort }));
+        await ensure(cwd);
+        if (owner !== session || session === undefined) return;
+        if (isSupervisorLive(cwd) || (await waitForSupervisor(cwd, options.supervisorReadyMs ?? 2_000))) return;
+      }
+      if (owner !== session || session === undefined) return;
+      const engine = createSupervisor({
+        workspaceCwd: cwd,
+        runFresh: options.runFresh,
+        isDaemon: false,
+        ownerSessionId: session.id,
+        ...(options.gh === undefined ? {} : { gh: options.gh }),
+        ...(options.pollIntervalMs === undefined ? {} : { pollIntervalMs: options.pollIntervalMs }),
+        ...(options.routinesPort === undefined ? {} : { routinesPort: options.routinesPort }),
+        ...(options.routinesDir === undefined ? {} : { routinesDir: options.routinesDir }),
+        onAccepted: drain,
+      });
+      fallback = engine;
+      try {
+        const result = await engine.start();
+        if (owner !== session) engine.stop();
+        if (!result.started && fallback === engine) fallback = undefined;
+      } catch (cause) {
+        engine.stop();
+        if (fallback === engine) fallback = undefined;
+        throw cause;
+      }
+    })().finally(() => {
+      if (starting === attempt) starting = undefined;
+    });
+    starting = attempt;
+    return attempt;
   };
 
-  /** True (and the subscription gone) once it has expired. */
-  const expired = (entry: Live) => {
-    if (Date.now() < entry.sub.expiresAt) return false;
-    remove(entry);
-    return true;
+  const view = (sub: StoredSubscription) => {
+    const config = sub.config;
+    const base = { id: sub.id, name: sub.name, kind: config.kind, createdAt: iso(sub.createdAt), expiresAt: iso(sub.expiresAt) };
+    if (config.kind === 'timer')
+      return { ...base, target: timerTarget(config), prompt: config.prompt, sessionStrategy: config.strategy, ...(config.cron === undefined ? { delaySeconds: config.delaySeconds } : { cron: config.cron }), once: config.once };
+    if (config.kind === 'github') return { ...base, target: targetText(config.target), ...config.target, sessionStrategy: 'wake_self' as Strategy };
+    const arm = readArm(workspaceCwd, sub);
+    const url = arm?.state === 'ready' ? arm.url : undefined;
+    return { ...base, target: url ?? `(not listening) /routines/${config.slug}`, url, credentialFile: credentialFile(dir, config.slug), slug: config.slug, prompt: config.prompt, sessionStrategy: 'wake_self' as Strategy };
   };
 
-  const wake = (entry: Live, content: string, summary: string) => {
-    if (!active) return;
-    entry.lastEvent = { at: Date.now(), text: oneLine(summary) };
-    pi.sendMessage({ customType: WAKE_TYPE, content, display: true, details: { id: entry.sub.id, kind: entry.sub.config.kind, name: entry.sub.name } }, { triggerTurn: true, deliverAs: 'followUp' });
-  };
+  const status = (sub: StoredSubscription) => ({
+    ...(sub.lastEvent === undefined ? {} : { lastEvent: `${iso(sub.lastEvent.at)} ${sub.lastEvent.text}` }),
+    ...(sub.lastError === undefined ? {} : { lastError: `${iso(sub.lastError.at)} ${sub.lastError.text}` }),
+    ...(sub.lastOutcome === undefined ? {} : { lastOutcome: `${iso(sub.lastOutcome.at)} ${sub.lastOutcome.text}` }),
+  });
 
-  const fireTimer = (entry: Live, config: TimerConfig) => {
-    if (config.strategy === 'wake_self') wake(entry, `[timer] ${entry.sub.name}\n\n${config.prompt}`, 'fired');
-    else {
-      entry.lastEvent = { at: Date.now(), text: 'started a fresh session' };
-      Promise.resolve()
-        .then(() => options.runFresh(config.prompt, entry.sub.name))
-        .catch((error: unknown) => {
-          entry.lastError = { at: Date.now(), text: errorText(error) };
-        });
-    }
-    if (config.once) remove(entry);
+  const shutdown = () => {
+    if (ownerPoll !== undefined) clearInterval(ownerPoll);
+    ownerPoll = undefined;
+    starting = undefined;
+    const previous = owner;
+    owner = undefined;
+    previous?.lease.release();
+    fallback?.stop();
+    fallback = undefined;
   };
 
-  const armTimer = (entry: Live, config: TimerConfig) => {
-    if (config.cron !== undefined) {
-      const schedule = parseCron(config.cron);
-      const tick = () => {
-        if (expired(entry)) return;
-        const now = Date.now();
-        const minute = Math.floor(now / MINUTE_MS);
-        if (minute !== entry.lastCronMinute && cronMatches(schedule, new Date(now))) {
-          entry.lastCronMinute = minute;
-          fireTimer(entry, config);
-          if (!owns(entry)) return;
-        }
-        at(entry, (minute + 1) * MINUTE_MS, tick);
-      };
-      at(entry, (Math.floor(Date.now() / MINUTE_MS) + 1) * MINUTE_MS, tick);
+  const restore = (ctx: ExtensionContext) => {
+    if (isOneShot(ctx.mode)) {
+      shutdown();
       return;
     }
-    const period = (config.delaySeconds ?? 1) * 1_000;
-    const next = () => {
-      const { createdAt } = entry.sub;
-      // A once timer that came due while Pi was not running fires on restore; a repeating one resumes its cadence.
-      if (config.once) return createdAt + period;
-      return createdAt + (Math.floor(Math.max(0, Date.now() - createdAt) / period) + 1) * period;
-    };
-    const fire = () => {
-      if (expired(entry)) return;
-      fireTimer(entry, config);
-      if (owns(entry)) at(entry, next(), fire);
-    };
-    at(entry, next(), fire);
-  };
-
-  const poll = async (entry: Live, target: Static<typeof TargetSchema>) => {
-    if (entry.polling === true || !active || expired(entry)) return;
-    entry.polling = true;
-    try {
-      const after = await fetchPrs(gh, target);
-      if (!active || !owns(entry)) return;
-      if (entry.baseline !== undefined) {
-        const blocks = await pollChanges(gh, target, entry.baseline, after);
-        if (blocks.length > 0 && owns(entry))
-          wake(
-            entry,
-            [`[github] ${entry.sub.name}`, ...blocks].join('\n\n'),
-            blocks
-              .map((block) =>
-                block
-                  .replace(/ \(https?:\/\/\S+\)/, '')
-                  .replace(/\n- /g, ': ')
-                  .replace(/\n/g, '; '),
-              )
-              .join(' | '),
-          );
+    const cwd = canonicalPath(ctx.cwd || process.cwd());
+    const id = ctx.sessionManager.getSessionId();
+    if (owner?.id === id && owner.cwd === cwd) {
+      drain();
+      return;
+    }
+    shutdown();
+    workspaceCwd = cwd;
+    const lease = acquireLease(ownerLockPath(cwd, id));
+    if (lease === undefined) {
+      ctx.ui.notify('Subscription owner delivery unavailable. Another live process owns this exact session.', 'error');
+      if (ownerPoll === undefined) {
+        ownerPoll = setInterval(() => {
+          if (owner === undefined) restore(ctx);
+          else drain();
+        }, 250);
+        ownerPoll.unref?.();
       }
-      if (!owns(entry)) return;
-      entry.baseline = after;
-      delete entry.lastError;
-    } catch (error) {
-      entry.lastError = { at: Date.now(), text: errorText(error) };
-    } finally {
-      entry.polling = false;
+      return;
     }
-  };
-
-  const armGithub = async (entry: Live, target: Static<typeof TargetSchema>) => {
-    const loop = () => {
-      void poll(entry, target).then(() => {
-        if (active && owns(entry)) at(entry, Date.now() + pollMs, loop);
-      });
-    };
-    await poll(entry, target);
-    if (active && owns(entry)) at(entry, Date.now() + pollMs, loop);
-  };
-
-  const onWebhook = (entry: Live, prompt: string) => (event: WebhookEvent) => {
-    if (!owns(entry) || expired(entry)) return;
-    wake(entry, [`[routine] ${entry.sub.name}`, prompt, webhookEventBlock(event)].join('\n\n'), `POST, body sha256 ${event.bodyDigest.slice(0, 12)}`);
-  };
-
-  const armWebhook = async (entry: Live, slug: string, prompt: string) => {
-    const credentialFile = ensureCredentials(dir, slug);
-    server.routes.set(slug, { slug, credentialFile, onEvent: onWebhook(entry, prompt) });
-    try {
-      entry.url = await server.url(slug);
-      delete entry.lastError;
-    } catch (error) {
-      server.routes.delete(slug);
-      entry.lastError = { at: Date.now(), text: errorText(error) };
-      throw error;
+    const notify = ctx.ui.notify.bind(ctx.ui);
+    owner = { id, cwd, lease, notify: (message) => notify(message, 'error') };
+    drain();
+    ownerPoll = setInterval(drain, 250);
+    ownerPoll.unref?.();
+    const registry = readRegistry(cwd);
+    if (subscriptionsFromBranch(ctx.sessionManager.getBranch()).some((sub) => !registry.subscriptions.some((stored) => stored.id === sub.id))) {
+      notify('Historical subscription receipts are inactive. Recreate missing subscriptions with the subscribe tools.', 'info');
+    }
+    if (registry.subscriptions.some((sub) => isDesired(sub))) {
+      void ensureEngine().catch((cause: unknown) => notify(`Subscriptions could not start. ${errorText(cause)}`, 'error'));
     }
-  };
-
-  const expiryTimer = (entry: Live) => at(entry, entry.sub.expiresAt, () => expired(entry));
-
-  const arm = async (entry: Live) => {
-    const { config } = entry.sub;
-    expiryTimer(entry);
-    if (config.kind === 'timer') armTimer(entry, config);
-    else if (config.kind === 'github') await armGithub(entry, config.target);
-    else await armWebhook(entry, config.slug, config.prompt);
-  };
-
-  const view = (entry: Live) => {
-    const { sub } = entry;
-    const { config } = sub;
-    const base = { id: sub.id, name: sub.name, kind: config.kind, createdAt: iso(sub.createdAt), expiresAt: iso(sub.expiresAt) };
-    if (config.kind === 'timer')
-      return { ...base, target: timerTarget(config), prompt: config.prompt, sessionStrategy: config.strategy, ...(config.cron === undefined ? { delaySeconds: config.delaySeconds } : { cron: config.cron }), once: config.once };
-    if (config.kind === 'github') return { ...base, target: targetText(config.target), ...config.target, sessionStrategy: 'wake_self' as Strategy };
-    return { ...base, target: entry.url ?? `(not listening) /routines/${config.slug}`, url: entry.url, credentialFile: credentialFile(dir, config.slug), slug: config.slug, prompt: config.prompt, sessionStrategy: 'wake_self' as Strategy };
   };
 
   const create = async (ctx: ExtensionContext, tool: string, name: string, config: Config, hours: number | undefined) => {
     if (isOneShot(ctx.mode)) throw oneShotError(tool);
     if (name.trim() === '') throw new Error('name must not be empty.');
-    const existing = byName(name);
-    if (existing !== undefined) {
-      if (existing.sub.config.kind !== config.kind) throw new Error(`A ${existing.sub.config.kind} subscription is already named "${name}". Pick another name or unsubscribe it first.`);
-      return { created: false, ...view(existing), ...status(existing) };
-    }
-    if (config.kind === 'webhook') {
-      const clash = [...live.values()].find((entry) => entry.sub.config.kind === 'webhook' && entry.sub.config.slug === config.slug);
-      if (clash !== undefined) throw new Error(`Routine "${clash.sub.name}" already uses the slug ${config.slug}.`);
-    }
+    const cwd = canonicalPath(ctx.cwd || process.cwd());
+    const id = ctx.sessionManager.getSessionId();
+    if (owner?.id !== id || owner.cwd !== cwd) restore(ctx);
+    if (owner === undefined) throw new Error('Subscription owner delivery unavailable for this session.');
+    const session = owner;
     const now = Date.now();
-    const entry: Live = { sub: { id: `sub-${randomBytes(4).toString('hex')}`, name, createdAt: now, expiresAt: expiryOf(now, hours), config }, timers: new Set() };
-    live.set(entry.sub.id, entry);
+    const file = ctx.sessionManager.getSessionFile();
+    const result = createDesired(cwd, {
+      id: `sub-${randomBytes(12).toString('hex')}`,
+      name,
+      createdAt: now,
+      expiresAt: expiryOf(now, hours),
+      config,
+      ownerSessionId: id,
+      ...(file === undefined ? {} : { ownerSessionFile: canonicalPath(file) }),
+    });
+    let sub = result.subscription;
+    if (sub.config.kind !== config.kind) throw new Error(`A ${sub.config.kind} subscription is already named "${name}". Pick another name or unsubscribe it first.`);
     try {
-      await arm(entry);
-    } catch (error) {
-      remove(entry, false);
-      throw error;
+      await ensureEngine();
+      if (owner !== session) throw new Error(`Subscription ${sub.id} owner session changed while arming.`);
+      await waitForArm(cwd, sub, options.supervisorReadyMs ?? 2_000);
+      if (owner !== session) throw new Error(`Subscription ${sub.id} owner session changed while arming.`);
+    } catch (cause) {
+      if (result.created) {
+        cancelDesired(cwd, sub.id);
+        if (owner === session) await fallback?.reconcile();
+      }
+      throw cause;
     }
-    persist();
-    return { created: true, ...view(entry), ...status(entry) };
+    sub = readRegistry(cwd).subscriptions.find((entry) => entry.id === sub.id) ?? sub;
+    if (result.created) persist();
+    return {
+      created: result.created,
+      ...view(sub),
+      ...status(sub),
+      ...(fallback === undefined ? {} : { durability: 'in-process; start pstack-routines-supervisor for chat-exit survival' }),
+      ...(sub.ownerSessionFile === undefined && !(sub.config.kind === 'timer' && sub.config.strategy === 'new_session') ? { ownerWarning: 'Owner session is unsaved. Offline owner wakes cannot resume after this process exits.' } : {}),
+    };
   };
 
-  const status = (entry: Live) => ({
-    ...(entry.lastEvent === undefined ? {} : { lastEvent: `${iso(entry.lastEvent.at)} ${entry.lastEvent.text}` }),
-    ...(entry.lastError === undefined ? {} : { lastError: `${iso(entry.lastError.at)} ${entry.lastError.text}` }),
-  });
-
   const listText = () => {
-    if (live.size === 0) return 'No subscriptions.';
-    return [...live.values()]
-      .map((entry) => {
-        const item = view(entry);
-        const state = status(entry);
+    const registry = readRegistry(workspaceCwd);
+    const visible = visibleSubscriptions(registry);
+    if (visible.length === 0) return 'No subscriptions.';
+    return visible
+      .map((sub) => {
+        const item = view(sub);
+        const state = status(sub);
         return [
           `${item.id} ${item.kind} "${item.name}"`,
           `  target: ${item.target}`,
@@ -389,71 +367,49 @@ export function createSubscriptions(pi: ExtensionAPI, options: SubscriptionOptio
           `  created: ${item.createdAt}  expires: ${item.expiresAt}`,
           `  last event: ${state.lastEvent ?? 'none'}`,
           ...(state.lastError === undefined ? [] : [`  last error: ${state.lastError}`]),
+          ...(state.lastOutcome === undefined ? [] : [`  last outcome: ${state.lastOutcome}`]),
+          ...(registry.pending.some((event) => event.subscriptionId === sub.id) ? ['  delivery: pending'] : []),
         ].join('\n');
       })
       .join('\n');
   };
 
   const routinesText = () => {
-    const routines = [...live.values()].filter((entry) => entry.sub.config.kind === 'webhook');
+    const routines = visibleSubscriptions(readRegistry(workspaceCwd)).filter((sub) => sub.config.kind === 'webhook');
     if (routines.length === 0) return 'No webhook routines.';
     return routines
-      .map((entry) => {
-        const item = view(entry) as ReturnType<typeof view> & { url?: string; credentialFile?: string };
-        const enabled = entry.url !== undefined && server.isListening() ? 'enabled' : `disabled${entry.lastError === undefined ? '' : ` (${entry.lastError.text})`}`;
+      .map((sub) => {
+        const item = view(sub) as ReturnType<typeof view> & { url?: string; credentialFile?: string };
+        const arm = readArm(workspaceCwd, sub);
+        const enabled = isDesired(sub) && arm?.state === 'ready' ? 'enabled' : `disabled${sub.lastError === undefined ? '' : ` (${sub.lastError.text})`}`;
         return [`${item.name} [${enabled}]`, `  url: ${item.url ?? 'none'}`, `  credential file: ${item.credentialFile}`, `  expires: ${item.expiresAt}`].join('\n');
       })
       .join('\n');
   };
 
-  const stopAll = () => {
-    for (const entry of live.values()) disarm(entry);
-    live.clear();
-    server.close();
+  const unsubscribe = async (key: string) => {
+    const sub = cancelDesired(workspaceCwd, key);
+    if (sub === undefined) throw new Error(`No subscription has the id or name "${key}". list_subscriptions shows them.`);
+    await fallback?.reconcile();
+    persist();
+    return { removed: true, id: sub.id, name: sub.name, kind: sub.config.kind };
   };
 
-  const restore = (ctx: ExtensionContext) => {
-    const baselines = new Map<string, Map<number, PrSnapshot>>();
-    for (const [id, entry] of live) if (entry.baseline !== undefined) baselines.set(id, new Map(entry.baseline));
-    stopAll();
-    active = true;
-    if (isOneShot(ctx.mode)) return;
-    const stored = subscriptionsFromBranch(ctx.sessionManager.getBranch());
-    const now = Date.now();
-    for (const sub of stored) {
-      if (sub.expiresAt <= now) continue;
-      const baseline = baselines.get(sub.id);
-      live.set(sub.id, { sub, timers: new Set(), ...(baseline === undefined ? {} : { baseline }) });
-    }
-    if (live.size !== stored.length) persist();
-    for (const entry of live.values()) {
-      arm(entry).catch(() => undefined);
-    }
-  };
+  return { create, unsubscribe, listText, routinesText, restore, shutdown };
+}
 
-  const unsubscribe = (key: string) => {
-    const entry = live.get(key) ?? byName(key);
-    if (entry === undefined) throw new Error(`No subscription has the id or name "${key}". list_subscriptions shows them.`);
-    remove(entry);
-    return { removed: true, id: entry.sub.id, name: entry.sub.name, kind: entry.sub.config.kind };
-  };
+const WAKE_COLLAPSED_LINES = 10;
 
-  return {
-    create,
-    unsubscribe,
-    listText,
-    routinesText,
-    restore,
-    shutdown: () => {
-      active = false;
-      stopAll();
-    },
-  };
+export function subscriptionWakeText(message: { content: string | { type: string; text?: string }[] }, expanded: boolean): string {
+  const raw = typeof message.content === 'string' ? message.content : message.content.map((part) => (part.type === 'text' ? (part.text ?? '') : '')).join('\n');
+  const lines = raw.split('\n');
+  return (expanded || lines.length <= WAKE_COLLAPSED_LINES ? lines : [...lines.slice(0, WAKE_COLLAPSED_LINES), `… ${lines.length - WAKE_COLLAPSED_LINES} more lines`]).join('\n');
 }
 
 /** Subscriptions (GitHub PR polls, timers, webhook routines) that wake this session or start fresh ones. */
 export function registerSubscriptions(pi: ExtensionAPI, options: SubscriptionOptions): ReturnType<typeof createSubscriptions> {
   const subs = createSubscriptions(pi, options);
+  pi.registerMessageRenderer?.(WAKE_TYPE, (message, renderOptions) => new Text(subscriptionWakeText(message, renderOptions.expanded), 0, 0));
   pi.on('session_start', (_event, ctx) => subs.restore(ctx));
   pi.on('session_tree', (_event, ctx) => subs.restore(ctx));
   pi.on('session_shutdown', () => subs.shutdown());
@@ -465,6 +421,7 @@ export function registerSubscriptions(pi: ExtensionAPI, options: SubscriptionOpt
       'Watch GitHub pull requests with gh and wake this session when one changes: state (merged, closed, reopened), head SHA, mergeability, review decision, new reviews or comments, or a check concluding. The first poll only records a baseline. Polls every minute until unsubscribed or expired.',
     promptSnippet: 'Wake this session when a GitHub PR changes',
     parameters: GithubParams,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     async execute(_id, params, _signal, _onUpdate, ctx) {
       const target =
         params.scope === 'pr'
@@ -482,9 +439,10 @@ export function registerSubscriptions(pi: ExtensionAPI, options: SubscriptionOpt
     name: 'subscribe_timer',
     label: 'Subscribe: timer',
     description:
-      'Fire a prompt on a 5-field cron schedule (local time) or after delaySeconds (repeating unless once). wake_self wakes this session with the prompt; new_session runs it in a fresh background subagent. Re-subscribing an existing name returns created: false and changes nothing.',
+      'Fire a prompt on a 5-field cron schedule (local time) or after delaySeconds (repeating unless once). wake_self queues the prompt for this owning session, including while offline. new_session uses a background Task while the owner is live, or a detached run with recorded status while offline. Re-subscribing an existing name returns created: false and changes nothing.',
     promptSnippet: 'Schedule a prompt with cron or a delay',
     parameters: TimerParams,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async execute(_id, params, _signal, _onUpdate, ctx) {
       if (isOneShot(ctx.mode)) throw oneShotError('subscribe_timer');
       if ((params.cron === undefined) === (params.delaySeconds === undefined)) throw new Error('Pass exactly one of cron or delaySeconds.');
@@ -507,6 +465,7 @@ export function registerSubscriptions(pi: ExtensionAPI, options: SubscriptionOpt
       'Create a webhook routine: a local URL (http://127.0.0.1:<port>/routines/<slug>) that wakes this session with a [routine] turn when a sender POSTs a JSON object with the routine key in X-Automation-Key or Authorization: Bearer. The result gives the URL and the credential file holding the key (field "key"); the key itself is never shown. Copy it from that file into the sender without printing it.',
     promptSnippet: 'Create a webhook routine that wakes this session',
     parameters: WebhookParams,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async execute(_id, params, _signal, _onUpdate, ctx) {
       if (isOneShot(ctx.mode)) throw oneShotError('subscribe_webhook');
       return text(await subs.create(ctx, 'subscribe_webhook', params.name, { kind: 'webhook', prompt: params.prompt, slug: routineSlug(params.name) }, params.expiresInHours));
@@ -516,7 +475,7 @@ export function registerSubscriptions(pi: ExtensionAPI, options: SubscriptionOpt
   pi.registerTool({
     name: 'list_subscriptions',
     label: 'Subscriptions',
-    description: "List this session's subscriptions (GitHub PR watches, timers, webhook routines) with id, kind, target, strategy, created and expiry times, and the last event or error.",
+    description: "List this workspace's subscriptions (GitHub PR watches, timers, webhook routines) with id, kind, target, strategy, created and expiry times, and the last event or error.",
     promptSnippet: 'List subscriptions',
     parameters: Type.Object({}),
     annotations: { readOnlyHint: true, openWorldHint: false },
@@ -531,8 +490,9 @@ export function registerSubscriptions(pi: ExtensionAPI, options: SubscriptionOpt
     description: 'End a subscription by id or name.',
     promptSnippet: 'End a subscription',
     parameters: UnsubscribeParams,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async execute(_id, params) {
-      return text(subs.unsubscribe(params.subscription));
+      return text(await subs.unsubscribe(params.subscription));
     },
   });