shraga 0.1.66 → 0.1.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/server/boot.ts

@@ -25,6 +25,7 @@ import { streamChat, consumeStream, getAgentConfig, saveAgentConfig, getClaudeAu
 import { mountFeatures, registerFeature, resumeFeatureSession, collectFeatureFlags, collectSidecarRoutes } from './features.ts';
 import { registerSpaCatchAll } from './spa-catchall.ts';
 import { slackFeature } from './slack/feature.ts';
+import { paraFeature } from './para/feature.ts';
 import { dataPath } from './paths.ts';
 import { getAllSessions, getSession, getSessionHistory, upsertSession, appendMessage, saveConversation, loadConversation, setSessionDirectives, getAutoApprove, setAutoApprove, getSessionsByScheduleId, getSessionsVisibleTo, isSessionVisibleTo, setRunStatus, incrementRetryCount, getRunningSessions, getActiveLockCount, updateScheduledSessionStatus, setShuttingDown, backfillSessionVisibility, writePartial, readPartial, clearPartial, registerLivePartial, unregisterLivePartial, readLivePartial, acquireSessionLock, releaseSessionLock, replaceSessionLock, isSessionLocked, getSessionAbortController, forkSession, generateSessionTitle, type ConvBlock, type ConvMessage, type SessionMeta } from './sessions.ts';
 import { setBroadcaster } from './session-bus.ts';
@@ -1134,10 +1135,41 @@ if (!PASSIVE) {
 // runs in passive too. Otherwise a standby instance reports empty stats and /api/stats is a lie.
 statsSampler.start(broadcast);
 registerEventRoutes(app, requireAuth);
+/** How long an out-of-band wake turn waits for a busy session before giving up (see runTurn). */
+const WAKE_LOCK_WAIT_MS = 5 * 60_000;
 initPolls({
   broadcast,
-  runTurn: ({ prompt, sessionId, uid, userEmail }) =>
-    consumeStream(streamChat({ prompt, sessionId, uid, userEmail, mcpServers: getMcpConfig(uid), abortController: new AbortController(), onPermissionRequest: async () => ({ allow: true }) })),
+  // The out-of-band turn runner (polls + background-job follow-ups). It TAKES THE SESSION LOCK, and
+  // that is load-bearing: `streamChat` never acquires one itself, so before this every guard written
+  // against `isSessionLocked` — including background-jobs.ts's "never start a turn on top of a live
+  // one" — was reading a lock that this path never took. Two jobs finishing minutes apart then ran
+  // two concurrent wake turns in one session, each free to dispatch the next leg of the same
+  // workflow: two writers on one browser instance, which is the failure these workflows are built to
+  // prevent. Waiting (bounded) rather than failing fast, because the whole point of a wake is that
+  // the outcome gets told: a busy session usually means another wake is mid-turn and will be done in
+  // seconds.
+  runTurn: async ({ prompt, sessionId, uid, userEmail }) => {
+    const abortController = new AbortController();
+    const deadline = Date.now() + WAKE_LOCK_WAIT_MS;
+    while (!acquireSessionLock(sessionId, 'api', abortController)) {
+      if (Date.now() >= deadline) {
+        // Give up by returning NOTHING, never by throwing. A throw propagates out of wake.ts's
+        // unguarded `await runTurn` into background-jobs' catch, which records `reported: 'failed'`
+        // — the one delivery path with no raw fallback, so the job's outcome would reach the user in
+        // no form at all, after wake.ts had already appended the trigger prompt (a question with no
+        // answer in the transcript). Empty blocks are the 'no-output' contract callers already
+        // handle: the job store then delivers its raw report instead. Degraded, but never silent.
+        console.warn(`[wake] session ${sessionId} stayed busy for ${Math.round(WAKE_LOCK_WAIT_MS / 1000)}s — skipping the turn; the caller falls back to a raw report`);
+        return [];
+      }
+      await new Promise((r) => setTimeout(r, 2_000));
+    }
+    try {
+      return await consumeStream(streamChat({ prompt, sessionId, uid, userEmail, mcpServers: getMcpConfig(uid), abortController, onPermissionRequest: async () => ({ allow: true }) }));
+    } finally {
+      if (releaseSessionLock(sessionId, abortController)) setRunStatus(sessionId, 'idle');
+    }
+  },
 });
 // Background jobs outlive the turn that started them, so their follow-up must too. Must run AFTER
 // initPolls (which wires wake.ts's turn runner) — boot adoption can report a job that finished
@@ -1172,6 +1204,9 @@ if (process.env.SHRAGA_OVERLAY) {
 // so their routes mount ahead of the SPA fallback, identical to the overlay path.
 for (const f of __reg.features ?? []) registerFeature(f);
 registerFeature(slackFeature);
+// para-li external-agent lane — a second medium alongside Slack; both subscribe the owner-notice
+// bus independently, so neither affects the other.
+registerFeature(paraFeature);
 mountFeatures({ app, requireAuth, broadcast, passive: PASSIVE });
 // Fold in feature-contributed sidecar WS proxy routes (the core names none; each add-on adds its own).
 Object.assign(WS_PROXY_ROUTES, collectSidecarRoutes());

package/src/server/notify-owners.ts

@@ -10,12 +10,29 @@ import { emitEvent } from './events/bus.ts';
 
 export type Owner = { name?: string; slackId: string };
 
+/** The OWNERS env list, lowercased. THE definition of "an owner of this deployment" — every
+ *  medium joins on it, each through whatever identity it happens to hold. */
+export function ownerEmails(): string[] {
+  return (process.env.OWNERS ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+}
+
+/** Is this email address an owner of this deployment?
+ *
+ *  Exported because a medium that is not Slack cannot use `resolveOwners`: that returns Slack ids
+ *  (OWNERS ∩ contacts WITH a Slack id), which is a Slack-shaped answer. The para lane holds a
+ *  shraga uid + the email of the API key that opened the link, so it joins on the email instead.
+ *  An empty/unknown address is NOT an owner — the fail-closed direction, since the alternative is
+ *  fanning a deploy report out to whoever happened to link a para. */
+export function isOwnerEmail(email: string | undefined | null): boolean {
+  const e = String(email ?? '').trim().toLowerCase();
+  return !!e && ownerEmails().includes(e);
+}
+
 /** Owners of THIS deployment (OWNERS env ∩ contacts that have a Slack id). */
 export async function resolveOwners(): Promise<Owner[]> {
   const { getAll } = await import('./contacts.ts');
-  const ownerEmails = (process.env.OWNERS ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
   return getAll()
-    .filter(c => c.slackIds.length > 0 && c.emails.some(e => ownerEmails.includes(e.toLowerCase())))
+    .filter(c => c.slackIds.length > 0 && c.emails.some(e => isOwnerEmail(e)))
     .map(c => ({ name: c.name, slackId: c.slackIds[0] }));
 }
 
@@ -26,16 +43,22 @@ export function senderStamp(): string {
 }
 
 /**
- * DM the owners. `source` is the event-bus source (used for logging/filtering only) — delivery is
- * keyed on the notice `kind`, so a new subsystem needs no change on the Slack side.
- * Returns false when there was nobody to tell.
+ * Publish an owner notice on the bus. `source` is the event-bus source (used for logging/filtering
+ * only) — delivery is keyed on the notice `kind`, so a new subsystem needs no change on the Slack
+ * side.
+ *
+ * Returns NOTHING, on purpose. It used to return "was there anyone to tell", which was a truthful
+ * answer only while Slack was the sole medium: `resolveOwners` filters on a SLACK id, so once para
+ * subscribes the same bus an empty owner list means "no Slack owner", not "nobody was notified".
+ * Rather than keep a boolean whose meaning depends on which features happen to be registered — no
+ * caller reads it (`data-sync.ts`, `self-upgrade/index.ts`) — the notice is emitted unconditionally
+ * and each subscriber decides for itself. The Slack subscriber already no-ops on an empty
+ * `owners`, so Slack behaviour is unchanged.
  */
-export async function notifyOwners(source: string, text: string): Promise<boolean> {
+export async function notifyOwners(source: string, text: string): Promise<void> {
   const owners = await resolveOwners();
+  emitEvent(source as any, { kind: 'deploy', owners, text: `${text}\n\n_from ${senderStamp()}_` });
   if (!owners.length) {
-    console.warn(`[${source}] No owners (OWNERS env) with Slack IDs found, skipping notification`);
-    return false;
+    console.warn(`[${source}] No owners (OWNERS env) with Slack IDs found — notice emitted for non-Slack subscribers only`);
   }
-  emitEvent(source as any, { kind: 'deploy', owners, text: `${text}\n\n_from ${senderStamp()}_` });
-  return true;
 }

package/src/server/para/feature.ts

@@ -0,0 +1,218 @@
+/**
+ * paraFeature — the sender half of the para-li external-agent lane.
+ *
+ * Mirrors `slackFeature` exactly in shape: one `ServerFeature` that (a) mounts an ingress route and
+ * (b) subscribes the owner-notice event bus so deploy / self-upgrade / downtime notices reach the
+ * medium. Slack is untouched and the two coexist — both subscribe the same bus, neither knows about
+ * the other, and a notice is delivered to each independently.
+ *
+ * TRANSPORT. para-li POSTs one turn here and we stream the answer BACK to it over signed webhook
+ * calls (see `streamer.ts`), rather than holding this response open. para-li's caller is a Bodify
+ * trigger whose lifetime is the turn, so a multi-minute agent run held on one response body dies to
+ * a proxy idle timeout with a half-written row. Two independent requests also give the proactive
+ * lane the same transport for free.
+ *
+ * TRUST. The turn request is authenticated with an ordinary shraga API key (`POST /api/api-keys`),
+ * so reaching this route requires a credential the owner minted. The callback URL + secret arrive
+ * IN that authenticated request — para-li tells us where to answer and with what, per turn, which
+ * is what makes a rotated webhook secret take effect on the very next message with no config here.
+ */
+import type { ServerFeature, FeatureContext } from '../features.ts';
+import crypto from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { subscribeEvents } from '../events/bus.ts';
+import { streamChat } from '../claude.ts';
+import { getMcpConfig } from '../mcp.ts';
+import { dataPath } from '../paths.ts';
+import {
+  appendMessage, upsertSession, setRunStatus, acquireSessionLock, releaseSessionLock,
+  type ConvBlock,
+} from '../sessions.ts';
+import { validateApiKey } from '../api-keys.ts';
+import { isOwnerEmail } from '../notify-owners.ts';
+import { ParaStreamer, postProactive, type ParaCallback } from './streamer.ts';
+
+interface DeployNotice { kind: 'deploy'; owners: { name?: string; slackId: string }[]; text: string }
+
+/** Last known para conversation per connection — the proactive lane's destination.
+ *
+ *  Learned from the first turn rather than configured: para-li already tells us the conv and the
+ *  callback on every turn, so a second source of truth would only be a thing to drift. Persisted
+ *  because a deploy notice fires right after a RESTART, which is exactly when an in-memory map is
+ *  empty — the one moment the feature has to work. Lives beside `api-keys.json` in the data dir and
+ *  holds the webhook secret, so it inherits that file's protection, no more and no less. */
+const LINKS_PATH = dataPath('para-links.json');
+/** `uid` is the shraga user whose API key opened this link. It is the OWNER of the entry — see
+ *  `rememberLink`.
+ *
+ *  `email` is that user's address, recorded so the PROACTIVE lane can answer "is this link's user
+ *  an owner of this deployment?" — `OWNERS` is an email list, and a uid does not join to it. It is
+ *  taken from `validateApiKey`, never from the request body. A link written before this field
+ *  existed has no email and is therefore not an owner: it receives no notices until its next turn
+ *  refreshes the entry. */
+type Link = ParaCallback & { convId: string; at: number; uid: string; email?: string };
+
+function loadLinks(): Record<string, Link> {
+  if (!existsSync(LINKS_PATH)) return {};
+  try { return JSON.parse(readFileSync(LINKS_PATH, 'utf-8')); } catch (err) {
+    console.warn('[para] links file unreadable, starting empty:', (err as Error).message);
+    return {};
+  }
+}
+/** Record (or refresh) a connection's callback.
+ *
+ *  ONE USER OWNS A connId. `connId` is chosen by the caller, so without this an API key for user A
+ *  could claim a connId already linked by user B and re-point every future PROACTIVE notice
+ *  (deploy reports, self-upgrade outcomes) at A's URL + secret. An API key is already full agent
+ *  access to its own user, so this is not a privilege boundary being invented — it is the one
+ *  cross-user step that access does not otherwise imply, so it is refused rather than logged. */
+function rememberLink(link: Link): void {
+  try {
+    const all = loadLinks();
+    const prev = all[link.connId];
+    if (prev?.uid && prev.uid !== link.uid) {
+      console.warn(`[para] refusing to re-link ${link.connId}: owned by another user`);
+      return;
+    }
+    all[link.connId] = link;
+    mkdirSync(dataPath(''), { recursive: true });
+    writeFileSync(LINKS_PATH, JSON.stringify(all, null, 2));
+  } catch (err) {
+    console.warn('[para] could not persist link:', (err as Error).message);
+  }
+}
+
+/** Run one turn, streaming into the para row. Errors settle the row visibly — the owner must never
+ *  be left watching a "typing…" placeholder that will never resolve. */
+async function runParaTurn(args: {
+  callback: ParaCallback; convId: string; msgId: string; sessionId: string; prompt: string;
+  uid: string; userEmail: string;
+}): Promise<void> {
+  const { callback, convId, msgId, sessionId, prompt, uid, userEmail } = args;
+  const streamer = new ParaStreamer({ callback, convId, msgId });
+  const abortController = new AbortController();
+
+  // Lock origin is 'api': the union in sessions.ts is a closed set ('web'|'slack'|'scheduler'|
+  // 'api') and this is an authenticated API caller. Widening it just to label the medium would
+  // touch recovery and status code paths for no behavioural gain.
+  if (!acquireSessionLock(sessionId, 'api', abortController)) {
+    // sessionId === convId, so this is genuinely "you sent two messages into the same thread while
+    // the first was still running". Say so rather than dropping it silently.
+    await streamer.fail('That conversation is already processing a message — wait for it to finish.');
+    return;
+  }
+  upsertSession(sessionId, prompt, { uid, email: userEmail });
+  appendMessage(sessionId, { id: crypto.randomUUID(), role: 'user', blocks: [{ type: 'text', text: prompt }], channel: 'para' });
+  setRunStatus(sessionId, 'running', 'web');
+
+  const blocks: ConvBlock[] = [];
+  let text = '';
+  try {
+    for await (const ev of streamChat({
+      prompt, sessionId, uid, userEmail,
+      mcpServers: getMcpConfig(uid),
+      abortController,
+      context: { source: 'para', user: userEmail },
+      onPermissionRequest: async () => ({ allow: true }),
+    })) {
+      if (ev.type === 'text_delta') { text += ev.text; streamer.feed({ type: 'text_delta', text: ev.text }); }
+      else if (ev.type === 'tool_use') {
+        if (text) { blocks.push({ type: 'text', text }); text = ''; }
+        blocks.push({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
+        streamer.feed({ type: 'tool_use', tool: ev.tool });
+      }
+      else if (ev.type === 'tool_result') blocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
+      else if (ev.type === 'done') break;
+      else if (ev.type === 'error') {
+        if (text) { blocks.push({ type: 'text', text }); text = ''; }
+        blocks.push({ type: 'error', text: ev.message });
+        await streamer.fail(ev.message);
+        return;
+      }
+    }
+    if (text) blocks.push({ type: 'text', text });
+    await streamer.finish();
+  } catch (err) {
+    console.error('[para] turn failed:', (err as Error).message);
+    await streamer.fail((err as Error).message || 'agent error');
+  } finally {
+    // The transcript is persisted whatever happened, so the shraga UI and the next turn's context
+    // see the same history para saw.
+    if (blocks.length) appendMessage(sessionId, { id: crypto.randomUUID(), role: 'assistant', blocks });
+    if (releaseSessionLock(sessionId, abortController)) setRunStatus(sessionId, 'idle');
+  }
+}
+
+let mounted = false;
+let busSubscribed = false;
+
+export const paraFeature: ServerFeature = {
+  name: 'para',
+
+  // No capability flag. `flags` is the seam's way to tell the CLIENT a surface exists, and nothing
+  // in the client gates on para — the lane is driven entirely by para.li calling in. Declaring one
+  // would be dead public surface on /api/features (slackFeature declares none for the same reason).
+
+  register(ctx: FeatureContext): void {
+    // Owner notices → the linked para conversations OF THIS DEPLOYMENT'S OWNERS. Keyed on the
+    // notice KIND, not the source, for the reason spelled out in slackFeature: self-upgrade emits
+    // under its own source and a source-gated subscriber silently dropped every one of them.
+    //
+    // WHY NOT `payload.owners`. That field is `{name?, slackId}[]` — the SLACK join, computed by
+    // `resolveOwners` as OWNERS ∩ contacts-that-have-a-Slack-id. A para link carries no Slack id,
+    // so the field is unmatchable here. Unfiltered, this loop posted every deploy / self-upgrade /
+    // data-sync report to EVERY entry in para-links.json — and any shraga user with an API key
+    // gets an entry on their first turn (`rememberLink`). The `uid` guard does not help: it stops
+    // STEALING another user's connId, not adding your own.
+    // The join that works is the one OWNERS is actually expressed in — the email of the API key
+    // that opened the link — checked with the same `isOwnerEmail` that backs `resolveOwners`.
+    if (!ctx.passive && !busSubscribed) {
+      busSubscribed = true;
+      subscribeEvents((evt) => {
+        const payload = evt.payload as DeployNotice;
+        if (payload?.kind !== 'deploy' || !payload.text) return;
+        for (const link of Object.values(loadLinks())) {
+          if (!isOwnerEmail(link.email)) continue;
+          postProactive({ url: link.url, secret: link.secret, connId: link.connId }, link.convId, payload.text)
+            .then((ok) => console.log(`[para] owner notice ${ok ? 'delivered' : 'FAILED'} → ${link.convId}`))
+            .catch((err) => console.warn('[para] owner notice failed:', (err as Error).message));
+        }
+      });
+    }
+
+    if (ctx.passive || mounted) return;
+    mounted = true;
+
+    ctx.app.post('/api/para/turn', (req, res) => {
+      const bearer = /^Bearer\s+(.+)$/i.exec(req.get('authorization') ?? '')?.[1];
+      const caller = bearer ? validateApiKey(bearer) : null;
+      if (!caller) return void res.status(401).json({ error: 'unauthorized' });
+
+      const { connId, convId, sessionId, msgId, prompt, callback } = req.body as {
+        connId?: string; convId?: string; sessionId?: string; msgId?: string; prompt?: string;
+        callback?: { url?: string; secret?: string };
+      };
+      if (!connId || !convId || !msgId || !prompt) return void res.status(400).json({ error: 'connId, convId, msgId and prompt are required' });
+      if (!callback?.url || !callback?.secret) return void res.status(400).json({ error: 'callback.url and callback.secret are required' });
+      try {
+        const u = new URL(callback.url);
+        // We hold the owner's credential and will POST to whatever this says, so it is validated
+        // here too rather than trusted because the request authenticated.
+        if (u.protocol !== 'https:' && u.hostname !== 'localhost' && u.hostname !== '127.0.0.1') throw new Error('https required');
+      } catch { return void res.status(400).json({ error: 'callback.url must be a valid HTTPS URL' }); }
+
+      const cb: ParaCallback = { url: callback.url, secret: callback.secret, connId };
+      rememberLink({ ...cb, convId, at: Date.now(), uid: caller.uid, email: caller.email });
+
+      // ACCEPT, then run. The answer arrives on the callback, so holding this response open would
+      // only give para-li's trigger a socket to time out on.
+      res.json({ status: 'accepted', sessionId: sessionId || convId });
+      void runParaTurn({
+        callback: cb, convId, msgId, sessionId: sessionId || convId, prompt,
+        uid: caller.uid, userEmail: caller.email,
+      });
+    });
+
+    console.log('[para] turn ingress mounted at POST /api/para/turn');
+  },
+};

package/src/server/para/streamer.ts

@@ -0,0 +1,175 @@
+/**
+ * ParaStreamer — progressive delivery of one agent turn into a para-li conversation row.
+ *
+ * WHY NOT `SlackStreamer`. The brief said to reuse `mcp-slack-use/src/streamer.ts` rather than
+ * write a second streamer. Its throttling contract IS reused — buffer, `flushInterval` (300ms),
+ * `flushThreshold` (30 chars), and a serialized `flushChain` so sends never overtake each other,
+ * all mirrored here deliberately and with the same defaults. Its *transport* cannot be: every
+ * send in that class is a `slackApi(token, 'chat.appendStream'|'chat.startStream'|'chat.update')`
+ * call against Slack's three-call streaming protocol, and it lives in a vendored package in a
+ * different repo. Para's transport is one signed POST per flush carrying the accumulated text —
+ * there is no start/append/stop handshake and no ts to thread. Forking that package to
+ * parameterize the transport would be a larger, riskier change to Slack's live path than these
+ * ~60 lines, so the shared thing is the CONTRACT, not the code, and this comment is the seam.
+ *
+ * ACCUMULATE, DON'T APPEND: each flush sends the full text so far. para-li patches the message row
+ * with a whole-row `set` (its existing partial-update convention), so a dropped or reordered delta
+ * self-heals on the next flush instead of leaving a hole. That is worth more than the bytes.
+ */
+import { createHmac, randomUUID } from 'node:crypto';
+
+export interface ParaCallback {
+  /** Absolute webhook URL, handed to us per-turn by para-li (never configured here). */
+  url: string;
+  /** HMAC key for THIS connection, handed over per-turn so a rotation lands on the next message. */
+  secret: string;
+  /** Connection id — inside the signed material, so a delivery is bound to its connection. */
+  connId: string;
+}
+
+export interface ParaStreamerOptions {
+  callback: ParaCallback;
+  convId: string;
+  /** The row to patch. Omit for a PROACTIVE post (no preceding user turn) — see `post()`. */
+  msgId?: string;
+  flushInterval?: number;
+  flushThreshold?: number;
+  /** Show a transient inline marker per tool call, as the Slack streamer does. Default on. */
+  toolMarkers?: boolean;
+}
+
+/** Signature contract, mirrored byte-for-byte in para-li's `lib/agent-conn.ts#signPayload`.
+ *  The two repos are separately published, so this is duplicated on purpose; if you change one,
+ *  change both — a drift here presents as a silent 401 on every delta.
+ *
+ *  The DELIVERY id is in the material because para-li's replay guard dedupes on that header alone;
+ *  unsigned, it would be the one field an attacker could vary freely to replay a captured delivery
+ *  inside the signature window.
+ *
+ *  UNESCAPED `.` — why the field boundaries cannot be shifted. There are no length prefixes, so in
+ *  general `a.b.c` is ambiguous. It holds here because the receiver PINS every field but the last
+ *  before it verifies: `connId` must be exactly 24 lowercase hex chars (`isConnId`, checked before
+ *  the signature) and `ts` is `Number(header)` re-stringified, so it is a canonical, dot-free digit
+ *  run that must also land within 300s of now. `rawBody` is trailing and can absorb nothing. That
+ *  leaves `deliveryId` as the only free field, and it sits between two fixed-shape neighbours, so
+ *  no (deliveryId, ts) pair can be re-cut into a different one. If either check is ever relaxed,
+ *  length-prefix the material instead of relying on this. */
+export function signPara(secret: string, connId: string, deliveryId: string, ts: number, rawBody: string): string {
+  return 'v1=' + createHmac('sha256', secret).update(`${connId}.${deliveryId}.${ts}.${rawBody}`).digest('hex');
+}
+
+/** One signed POST. Returns false on any non-2xx or network error, having logged it — the caller
+ *  keeps streaming rather than aborting the agent's turn over a transport hiccup. */
+export async function postPara(cb: ParaCallback, payload: object): Promise<boolean> {
+  const raw = JSON.stringify(payload);
+  const ts = Date.now();
+  // Per-DELIVERY id, not per-turn: para-li's replay guard dedupes on this, so a shared id across
+  // the deltas of one turn would drop every delta after the first. Minted here so the exact same
+  // value goes into the header AND the signature — they must not be able to diverge.
+  const delivery = randomUUID();
+  try {
+    const res = await fetch(cb.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-agent-conn': cb.connId,
+        'x-agent-timestamp': String(ts),
+        'x-agent-signature': signPara(cb.secret, cb.connId, delivery, ts, raw),
+        'x-agent-delivery': delivery,
+      },
+      body: raw,
+    });
+    if (!res.ok) {
+      console.warn(`[para-streamer] ${(payload as any).type} rejected: ${res.status} ${await res.text().catch(() => '')}`.slice(0, 300));
+      return false;
+    }
+    return true;
+  } catch (err) {
+    console.warn('[para-streamer] delivery failed:', (err as Error).message);
+    return false;
+  }
+}
+
+export class ParaStreamer {
+  private buffer = '';
+  private fullText = '';
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private flushChain: Promise<void> = Promise.resolve();
+  private aborted = false;
+  private afterTool = false;
+
+  private readonly flushInterval: number;
+  private readonly flushThreshold: number;
+  private readonly toolMarkers: boolean;
+
+  constructor(private readonly opts: ParaStreamerOptions) {
+    this.flushInterval = opts.flushInterval ?? 300;
+    this.flushThreshold = opts.flushThreshold ?? 30;
+    this.toolMarkers = opts.toolMarkers ?? true;
+  }
+
+  feed(ev: { type: string; text?: string; tool?: string }): void {
+    if (this.aborted || !this.opts.msgId) return;
+
+    if (ev.type === 'text_delta' && ev.text) {
+      if (this.afterTool) { this.fullText += '\n'; this.afterTool = false; }
+      this.buffer += ev.text;
+      this.fullText += ev.text;
+      if (this.buffer.length >= this.flushThreshold) this.enqueueFlush();
+      else this.scheduleTimer();
+    } else if (ev.type === 'tool_use' && ev.tool && this.toolMarkers) {
+      // In-band, transient: `finish()` sends the clean final text, which replaces the row wholesale
+      // (para-li writes the whole row), so the marker disappears on its own.
+      this.afterTool = true;
+      this.fullText += `\n\n_🔧 ${ev.tool.slice(0, 200)}_\n\n`;
+      this.enqueueFlush();
+    }
+  }
+
+  /** Settle the row with the final text. Returns the text actually sent. */
+  async finish(): Promise<string> {
+    this.clearTimer();
+    this.buffer = '';
+    await this.flushChain;
+    if (this.aborted || !this.opts.msgId) return this.fullText;
+    const text = this.fullText.trim() || '(no output)';
+    await postPara(this.opts.callback, { type: 'final', convId: this.opts.convId, msgId: this.opts.msgId, text });
+    return text;
+  }
+
+  /** Settle the row as a visible failure. The owner sees WHY, in the thread, not only in a log. */
+  async fail(message: string): Promise<void> {
+    this.aborted = true;
+    this.clearTimer();
+    await this.flushChain;
+    if (!this.opts.msgId) return;
+    await postPara(this.opts.callback, { type: 'error', convId: this.opts.convId, msgId: this.opts.msgId, message });
+  }
+
+  private enqueueFlush(): void {
+    this.clearTimer();
+    if (!this.fullText) return;
+    this.buffer = '';
+    const snapshot = this.fullText;
+    // Serialized: a later, longer snapshot must never be overtaken by an earlier one, or the row
+    // visibly rewinds mid-stream.
+    this.flushChain = this.flushChain
+      .then(async () => { await postPara(this.opts.callback, { type: 'delta', convId: this.opts.convId, msgId: this.opts.msgId, text: snapshot }); })
+      .catch((err) => console.warn('[para-streamer] flush error:', (err as Error).message));
+  }
+
+  private scheduleTimer(): void {
+    this.clearTimer();
+    this.timer = setTimeout(() => this.enqueueFlush(), this.flushInterval);
+  }
+
+  private clearTimer(): void {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+  }
+}
+
+/** PROACTIVE post — a scheduled run, a deploy notice, a downtime report. No preceding user turn,
+ *  so there is no row to patch: para-li mints one. Same signed transport, same fence. */
+export function postProactive(cb: ParaCallback, convId: string, text: string): Promise<boolean> {
+  return postPara(cb, { type: 'post', convId, text });
+}

package/src/server/polls.ts

@@ -9,7 +9,7 @@ import path from 'node:path';
 import { dataPath } from './paths.ts';
 import { getSession } from './sessions.ts';
 import { slackPost, getUserName, buildPollBlocks, type PollSpec } from './slack/api.ts';
-import { initWake, wakeSession, type TurnRunner } from './wake.ts';
+import { initWake, wakeSession, deliverToSession, type TurnRunner } from './wake.ts';
 
 const PREFIX = '[polls]';
 
@@ -155,5 +155,18 @@ async function wakeAgent(p: PollRecord, reason: string): Promise<void> {
   const headline = p.kind === 'question' ? 'Your question was answered' : `Your poll closed (${reason})`;
   const prompt = `[Poll result] ${headline}. Title: "${p.title}". ${voterCount(p)} participant(s).\n${lines}\n\nFollow up appropriately (summarize, take the next action, or notify the relevant people). Do not re-post the poll.`;
 
-  await wakeSession({ sessionId: p.sessionId, uid: p.uid, userEmail: p.userEmail, prompt, channel: 'poll', title: p.title, unreadFallback: 'Poll closed' });
+  // The return value is NOT decoration: a wake that could not run a turn ('no-output' — no runner
+  // wired, or the session stayed busy past the wake lock's wait) leaves this poll CLOSED, already
+  // re-rendered as closed in Slack, and the transcript holding a `[Poll result]` prompt with no
+  // answer. The tally would then be lost for good (the record is pruned after 7 days). So when no
+  // turn ran, deliver the lines we already built — the same raw-report fallback the background-job
+  // caller makes. `unreadFallback` above cannot cover this: wake.ts returns before it consults it.
+  const outcome = await wakeSession({ sessionId: p.sessionId, uid: p.uid, userEmail: p.userEmail, prompt, channel: 'poll', title: p.title, unreadFallback: 'Poll closed' });
+  if (outcome !== 'woke') {
+    console.warn(`${PREFIX} wake for ${p.pollId} returned '${outcome}' — delivering the tally as plain text instead`);
+    await deliverToSession({
+      sessionId: p.sessionId, uid: p.uid, title: p.title,
+      text: `${headline} — "${p.title}" (${voterCount(p)} participant(s)).\n${lines}`,
+    }).catch((e) => console.error(`${PREFIX} raw tally deliver failed:`, (e as Error)?.message));
+  }
 }

package/src/server/scheduler/outcome.ts

@@ -0,0 +1,92 @@
+// A scheduled run's DECLARED outcome — the run saying what actually happened, instead of the
+// scheduler inferring success from "the agent's turn returned".
+//
+// The bug this exists for: a prompt run whose real work failed (or never started) still records
+// `ok`, because the only thing measured was that the turn came back. On 2026-08-28 the 15:30 social
+// run's scout died, nothing was delivered, the run stored `ok`, and the (enabled) failure notifier
+// stayed silent all day — it is event-driven on `status: 'error'` and was never given one.
+//
+// It gets worse with background jobs (server/background-jobs.ts): there, ending the turn early is
+// the CORRECT behaviour — the work outlives it and the job store wakes the session when it exits.
+// So "the turn returned" stops being even a weak proxy for the run's outcome.
+//
+// Shape: one JSON file per run session, written by the run itself (any tool that can write a file —
+// no new tool surface, nothing to plumb through the engine), read by runner.ts when the turn ends.
+//   { "status": "ok" }                                  → the run delivered
+//   { "status": "error", "error": "…" }                 → it did not; this fires the notifier
+//   { "status": "pending", "deadline": <epoch ms|ISO> }  → work is still in flight; the run stays
+//                                                          open until a terminal declaration lands,
+//                                                          and FAILS if the deadline passes first
+// Absent file ⇒ unchanged legacy behaviour (turn returned = ok), so no existing schedule changes.
+// Deliberately domain-free: it knows nothing about what the run was doing.
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { dataPath } from '../paths.ts';
+
+/** Cap on how long a `pending` run may hold the window open, whatever deadline it asked for. */
+export const MAX_PENDING_MS = 6 * 60 * 60_000;
+/** Used when a `pending` declaration names no deadline. */
+export const DEFAULT_PENDING_MS = 60 * 60_000;
+
+export interface DeclaredOutcome {
+  status: 'ok' | 'error' | 'pending';
+  error?: string;
+  /** For `pending`: when the run gives up and is recorded as failed. Epoch ms or ISO-8601. */
+  deadline?: number | string;
+}
+
+const dir = (): string => { const d = dataPath('scheduler', 'outcomes'); mkdirSync(d, { recursive: true }); return d; };
+/** Session ids are server-minted (`sched-<id>-<ts>`), but this value reaches `path.join` and `rmSync`
+ *  — so it is validated rather than trusted. A `../` in there would delete outside the outcomes dir. */
+const safeId = (sessionId: string): string => {
+  if (!/^[A-Za-z0-9._-]+$/.test(sessionId) || sessionId.startsWith('.')) throw new Error(`unsafe session id for an outcome file: ${sessionId}`);
+  return sessionId;
+};
+export const outcomeFile = (sessionId: string): string => path.join(dir(), `${safeId(sessionId)}.json`);
+
+export function readOutcome(sessionId: string): DeclaredOutcome | null {
+  let raw: string;
+  try { raw = readFileSync(outcomeFile(sessionId), 'utf-8'); } catch { return null; }
+  let o: DeclaredOutcome;
+  // A malformed declaration is not "no declaration": the run tried to say something. Surfacing it
+  // as an error beats silently falling back to the optimistic default this module exists to remove.
+  // But a plain `Write` is not atomic, so a read can also land MID-write — that is a torn read, not
+  // a malformed declaration, and failing a run for it would be the same class of lie in reverse.
+  // Re-read once after a beat before believing it (the prompt also asks for write-temp-then-rename).
+  try { o = JSON.parse(raw) as DeclaredOutcome; }
+  catch {
+    try { raw = readFileSync(outcomeFile(sessionId), 'utf-8'); o = JSON.parse(raw) as DeclaredOutcome; }
+    catch { return { status: 'error', error: `run outcome file is not valid JSON: ${raw.slice(0, 200)}` }; }
+  }
+  if (o?.status !== 'ok' && o?.status !== 'error' && o?.status !== 'pending')
+    return { status: 'error', error: `run outcome file has an invalid status: ${JSON.stringify(o?.status)}` };
+  return o;
+}
+
+export function clearOutcome(sessionId: string): void {
+  try { rmSync(outcomeFile(sessionId)); } catch { /* nothing to clear */ }
+}
+
+/** Test/host seam — writes a declaration the way a run's own file write would. */
+export function writeOutcome(sessionId: string, o: DeclaredOutcome): void {
+  writeFileSync(outcomeFile(sessionId), JSON.stringify(o));
+}
+
+/** Absolute epoch ms a `pending` run expires at, clamped to MAX_PENDING_MS. */
+export function pendingDeadline(o: DeclaredOutcome, now: number): number {
+  const raw = typeof o.deadline === 'string' ? Date.parse(o.deadline) : o.deadline;
+  const asked = Number.isFinite(raw) ? (raw as number) : now + DEFAULT_PENDING_MS;
+  return Math.min(Math.max(asked, now), now + MAX_PENDING_MS);
+}
+
+/** The contract, appended to a scheduled prompt run so a run can report itself truthfully. */
+export function outcomePrompt(sessionId: string): string {
+  return `# Reporting this run's outcome
+This is a scheduled run. Unless you say otherwise, it is recorded as SUCCESSFUL the moment your turn returns — which is a lie whenever the work failed, was skipped, or is still in flight. Correct that by writing this file:
+\`${outcomeFile(sessionId)}\`
+- \`{"status":"ok"}\` — the run delivered what it was for.
+- \`{"status":"error","error":"<what went wrong>"}\` — it did not. This is what raises the failure alert; write it for a leg that never ran, a worker that died, or work you could not finish.
+- \`{"status":"pending","deadline":"<ISO-8601>"}\` — work you started outlives this turn (e.g. a background job). The run stays open and NOT successful until you write a terminal status from a later turn; if the deadline passes with no terminal status, the run is recorded as failed automatically.
+Write it atomically — write a temp file next to it and \`mv\` it into place — so a reader can never catch it half-written.
+Declare \`pending\` BEFORE you end a turn that leaves work running, and re-declare \`ok\`/\`error\` from the turn that sees it finish. Never declare \`ok\` for a run that did not deliver.`;
+}

package/src/server/scheduler/runner.ts

@@ -6,7 +6,8 @@ import { streamChat, type PermissionHandler } from '../claude.ts';
 import { getMcpConfig } from '../mcp.ts';
 import { appendMessage, createScheduledSession, updateScheduledSessionStatus, setRunStatus, registerLivePartial, unregisterLivePartial, writePartial, clearPartial, acquireSessionLock, releaseSessionLock, type ConvBlock } from '../sessions.ts';
 import type { Schedule, ScheduleRunSummary } from './types.ts';
-import { updateRunLockPid, clearRunningMarker } from './storage.ts';
+import { updateRunLockPid, clearRunningMarker, loadSchedules } from './storage.ts';
+import { readOutcome, clearOutcome, pendingDeadline, outcomePrompt, MAX_PENDING_MS } from './outcome.ts';
 import { addUnread } from '../unread.ts';
 
 export interface RunContext {
@@ -87,6 +88,70 @@ const sleep = (ms: number, signal?: AbortSignal) => new Promise<void>((resolve)
   signal?.addEventListener('abort', done, { once: true });
 });
 
+/** How often a `pending` run is re-checked while it waits for its terminal declaration. */
+const OUTCOME_POLL_MS = 10_000;
+
+/**
+ * Resolve what the run itself declared, once its turn has ended.
+ *
+ * Returns null when the run declared nothing — that is the legacy path and stays exactly as it was
+ * (turn returned ⇒ ok). A `pending` declaration keeps the run open until a terminal one lands; each
+ * fresh `pending` extends the wait (leg 2 re-declaring after leg 1 finished), bounded absolutely by
+ * MAX_PENDING_MS from the first one so an agent cannot extend forever. Silence past the deadline is
+ * a FAILURE — that is the whole point: a run that never came back must alert, not read as success.
+ */
+/**
+ * The schedule's CURRENT next fire time, read live from disk each time it is needed.
+ *
+ * Deliberately not the caller's snapshot: `fireDue()` starts the run in its first loop and only
+ * advances `nextRun` in its second, and `startRun` deep-copies the schedule BEFORE that advance —
+ * so the snapshot this run was handed still carries the window it is running FOR (already in the
+ * past), which would make the ceiling below `Infinity` and inert. The engine persists the advanced
+ * value (`saveSchedules` at the end of `fireDue`), so disk is the source of truth here. Reading it
+ * per poll also picks up an edit made while the run waits.
+ */
+function liveNextWindow(scheduleId: string): number | undefined {
+  try { return loadSchedules().find((s) => s.id === scheduleId)?.nextRun; }
+  catch { return undefined; }
+}
+
+async function resolveDeclaredOutcome(
+  sessionId: string,
+  ac: AbortController,
+  /** Schedule whose next window caps the wait — looked up live, never from the run's snapshot. */
+  scheduleId: string,
+): Promise<{ status: Exclude<ScheduleRunSummary['status'], 'running'>; error?: string } | null> {
+  let declared = readOutcome(sessionId);
+  if (!declared) return null;
+  // Waiting happens INSIDE the run promise, and engine.startRun only does `state.running.delete()`
+  // when that promise settles — so a pending run keeps its schedule marked running, and the next
+  // fire of the same schedule is QUEUED behind it rather than run on time. Verified in
+  // engine.ts (`state.running.delete` sits in `.finally`, and `fire()` queues when `state.running`
+  // has the id). For a 3×-daily schedule a multi-hour pending wait would therefore eat the next
+  // slot. So the wait ends at the next window at the latest: the run is then recorded as failed
+  // (the notifier fires) and the new window starts clean and on time.
+  const windowStop = (): number => {
+    const next = liveNextWindow(scheduleId);
+    return next && next > Date.now() ? next - 60_000 : Infinity;
+  };
+  const absoluteStop = Date.now() + MAX_PENDING_MS;
+  while (declared?.status === 'pending' && !ac.signal.aborted) {
+    const stop = windowStop();
+    const deadline = Math.min(pendingDeadline(declared, Date.now()), absoluteStop, stop);
+    if (Date.now() >= deadline) {
+      const why = deadline === stop ? 'its next scheduled window arrived first' : `deadline ${new Date(deadline).toISOString()}`;
+      return { status: 'error', error: `Run declared itself still in flight and never reported a terminal outcome (${why}).` };
+    }
+    await sleep(Math.min(OUTCOME_POLL_MS, deadline - Date.now()), ac.signal);
+    declared = readOutcome(sessionId);
+  }
+  if (ac.signal.aborted) return { status: 'aborted' };
+  if (!declared) return { status: 'error', error: 'Run outcome declaration disappeared before it reported a terminal state.' };
+  return declared.status === 'error'
+    ? { status: 'error', error: declared.error ? `Run reported failure: ${declared.error}` : 'Run reported failure with no detail.' }
+    : { status: 'ok' };
+}
+
 function formatEventBlock(e: EventContext): string {
   let body: string;
   try { body = JSON.stringify(e.payload, null, 2); } catch { body = String(e.payload); }
@@ -140,6 +205,17 @@ export async function runSchedule(
     if (eventCtx) base = `${base}\n\n---\n${formatEventBlock(eventCtx)}`;
     prompt = base;
   }
+  // Tell the run how to report its own truthful outcome (scheduler/outcome.ts). Prompt tasks only:
+  // a `bash` task's permission handler allows nothing but the task's own command, so such a run
+  // could not write the file even if it wanted to — its exit code is already the truth there.
+  if (task.kind === 'prompt') {
+    // Cleared on RESUME too: a resume reuses the interrupted run's session id, so a declaration left
+    // by the attempt that crashed would be adopted as this attempt's verdict. The contract is
+    // re-stated for the same reason — the resumed turn must be able to declare for itself.
+    clearOutcome(sessionId);
+    prompt = `${prompt}\n\n---\n${outcomePrompt(sessionId)}`;
+  }
+
   // task.engine/task.model ride the same prompt-directive channel users type by hand —
   // parseDirectives strips them and resolves aliases. Prepending (vs new plumbing) also persists the
   // choice into the saved prompt, so the session UI shows what the schedule actually requested.
@@ -322,6 +398,27 @@ export async function runSchedule(
     updateScheduledSessionStatus(sessionId, status);
   }
 
+  // The run's OWN verdict beats "the turn returned" — see scheduler/outcome.ts. Deliberately after
+  // the finally: the session lock is released by now, so a run that declared `pending` can be closed
+  // by a later turn in this session (a background job's wake, a follow-up message) while we wait.
+  if (status === 'ok' && task.kind === 'prompt') {
+    const declared = await resolveDeclaredOutcome(sessionId, abortController, schedule.id);
+    if (declared) {
+      status = declared.status;
+      error = declared.error;
+      updateScheduledSessionStatus(sessionId, status);
+      if (status !== 'ok') {
+        appendMessage(sessionId, {
+          id: crypto.randomUUID(),
+          role: 'assistant',
+          blocks: [{ type: 'error', text: error ?? `Run reported status ${status}` }],
+        });
+        onEvent({ type: 'session_messages_changed', sessionId });
+      }
+    }
+    clearOutcome(sessionId);
+  }
+
   const preview = assistantText.slice(0, 120) || (status === 'ok' ? 'Schedule completed' : `Schedule ${status}`);
   addUnread(schedule.createdBy.uid, sessionId, preview, 'schedule', schedule.name);