shraga 0.1.66 → 0.1.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "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

@@ -1134,10 +1134,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

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);