@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/runner/channelDiscipline.js

@@ -0,0 +1,425 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { channelFiles, normRole, parsePosts } from '../hub/lib/channels.mjs';
+import { isTerminal } from '../hub/lib/closure.mjs';
+
+/**
+ * Pulse 1.1.2: the delivery-discipline rules as checks in the runner, from the Cursor hook and a sweep.
+ * - E2: on `sessionEnd`, a channel whose newest post by that session is not terminal gets an automatic STOPPED.
+ * - E3: a channel whose newest post is not terminal gets `STATUS?` to its owner at 30 min, and an escalation to its
+ *   architect and to you at 60 min, once per stale episode.
+ * - E4: a header stamped more than 5 min ahead of the clock is flagged back to the session that wrote it.
+ * - E5: `preToolUse` on Task is denied unless the brief names a `.agents/<task>/channel.md` that holds a KICKOFF.
+ * - E6: `preToolUse` on Shell with `required_permissions` posts a BLOCKER to the session's channel and to you, and the
+ *   call's end clears it. The call itself is never blocked.
+ * Which posts a session wrote is learned from its own postToolUse hooks (the channel it named and the header lines it
+ * wrote). These tables are runner.db's own: no capture trigger, never sent to the cloud.
+ */
+
+/** E3: a channel whose newest post is not terminal is asked for a STATUS after this long, and escalated after twice that. */
+export const STALE_ASK_MS = 30 * 60e3;
+export const STALE_ESCALATE_MS = 60 * 60e3;
+/** E3 watches channels written this recently; older ones are history, not stale work. */
+export const STALE_WATCH_MS = 12 * 3600e3;
+/** E4: a header this far ahead of the writer's clock is future-dated. */
+export const FUTURE_MS = 5 * 60e3;
+export const BLOCKER_HEAD = 'BLOCKER — waiting on the user to approve a permission prompt';
+/**
+ * E5 (architect's 11:56:47 ruling): read-only subagents own no deliverable, so they need no channel of their own; their
+ * work is reported in the parent's. A Task with `readonly: true` is exempt too. Anything that can write is gated.
+ */
+export const READ_ONLY_SUBAGENTS = Object.freeze(new Set([
+  'explore', 'cursor-guide', 'ci-investigator', 'researcher', 'innerloop-expert', 'innerloop-code-reviewer', 'innerloop-domain-reviewer',
+  'innerloop-security-reviewer',
+]));
+const STOPPED_HEAD = 'STOPPED — session ended without a terminal post (auto)';
+const CLEARED_HEAD = 'STATUS — permission prompt answered, carrying on (auto)';
+const CHANNEL_MAX_BYTES = 4e6;
+const DAY_S = 86400;
+const HALF_DAY_S = DAY_S / 2;
+/** A header line as an agent writes it into a tool call: the time may still be a shell variable (`$T`). */
+const HEADER_LINE = /^## \[([A-Z][A-Z0-9 -]*?)\] (\S+) (?:(?:IST|UTC|GMT) )?([^\n]*)$/;
+const CLOCK = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;
+const NAME = '[A-Za-z0-9._-]+';
+const CHANNEL_REF = new RegExp(`\\.agents/(${NAME})/channel\\.md`, 'g');
+/** A tool call that writes a channel may name only its folder (`cd <repo>/.agents/<task> && cat >> channel.md`). */
+const CHANNEL_DIR = new RegExp(`\\.agents/(${NAME})(?=/channel\\.md|/?["'\\s;&|)]|/?$)`, 'gm');
+
+const SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS pulse_posts (
+     session TEXT NOT NULL, key TEXT NOT NULL, file TEXT NOT NULL, role TEXT NOT NULL, head TEXT NOT NULL, at INTEGER NOT NULL,
+     terminal INTEGER NOT NULL, auto INTEGER NOT NULL DEFAULT 0, seen_at INTEGER NOT NULL, PRIMARY KEY (session, key, role, head, at))`,
+  'CREATE INDEX IF NOT EXISTS pulse_posts_key ON pulse_posts (key, seen_at)',
+  `CREATE TABLE IF NOT EXISTS pulse_prompts (
+     session TEXT PRIMARY KEY, tool_use_id TEXT, key TEXT, file TEXT, role TEXT, message_id TEXT, at INTEGER NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS pulse_stale (
+     key TEXT PRIMARY KEY, file TEXT NOT NULL, sig TEXT NOT NULL, first_seen INTEGER NOT NULL, owner TEXT, asked_at INTEGER, escalated_at INTEGER)`,
+];
+
+export function installChannelDiscipline(db) {
+  for (const sql of SCHEMA) db.prepare(sql).run();
+}
+
+const two = (n) => String(n).padStart(2, '0');
+const clockOf = (at) => { const d = new Date(at); return `${two(d.getHours())}:${two(d.getMinutes())}:${two(d.getSeconds())}`; };
+const autoPost = (role, head, body, at) => `\n## [${role}] ${clockOf(at)} ${head}\n${body}\n`;
+const strings = (value) => (Array.isArray(value) ? value : [value]).filter((v) => typeof v === 'string');
+
+/** The header lines a tool call wrote, as `{ role, clock, head }`; the clock may be a shell variable. */
+export function headerLines(lines) {
+  const out = [];
+  for (const line of strings(lines)) {
+    const m = line.trim().match(HEADER_LINE);
+    if (m) out.push({ role: normRole(m[1]), clock: m[2], head: m[3].trim() });
+  }
+  return out;
+}
+
+/**
+ * E4: how far a header's `HH:MM[:SS]` runs ahead of the writer's clock at `at`, in ms, across midnight within
+ * (-12 h, +12 h]; null when the time is not a literal clock (a shell variable). A `UTC` or `GMT` header is converted first.
+ */
+export function headerSkewMs(line, at) {
+  const m = String(line || '').trim().match(/^## \[[A-Z][A-Z0-9 -]*?\] (\S+)(?: (IST|UTC|GMT))? /);
+  const c = m && m[1].match(CLOCK);
+  if (!c) return null;
+  const d = new Date(at);
+  let header = +c[1] * 3600 + +c[2] * 60 + +(c[3] || 0);
+  if (m[2] === 'UTC' || m[2] === 'GMT') header -= d.getTimezoneOffset() * 60;
+  let skew = header - (d.getHours() * 3600 + d.getMinutes() * 60 + d.getSeconds());
+  skew = ((skew % DAY_S) + DAY_S) % DAY_S;
+  if (skew > HALF_DAY_S) skew -= DAY_S;
+  return skew * 1000;
+}
+
+/**
+ * Every `.agents/<task>/channel.md` a text names (with `folders`, also a bare `.agents/<task>` folder):
+ * `{ named, repo, task, absolute }`. `repo` is the folder before `.agents` when it is a plain name; `absolute` lists
+ * the absolute paths it could be, since a path may hold spaces.
+ */
+export function channelRefs(text, { folders = false } = {}) {
+  const out = [];
+  const s = String(text || '');
+  for (const m of s.matchAll(folders ? CHANNEL_DIR : CHANNEL_REF)) {
+    const lineStart = s.lastIndexOf('\n', m.index) + 1;
+    const before = s.slice(lineStart, m.index);
+    const repo = (before.match(new RegExp(`(?:^|[^A-Za-z0-9._-])(${NAME})/$`)) || [])[1] || null;
+    const absolute = [];
+    for (let j = 0; j < before.length; j++) {
+      if (before[j] === '/' && (j === 0 || /[\s`'"(\[<:=]/.test(before[j - 1]))) absolute.push(`${before.slice(j)}.agents/${m[1]}/channel.md`);
+    }
+    const named = absolute[absolute.length - 1] || `${repo ? `${repo}/` : ''}.agents/${m[1]}/channel.md`;
+    if (!out.some((r) => r.named === named)) out.push({ named, repo, task: m[1], absolute });
+  }
+  return out;
+}
+
+/** A regular file (never a symlink) at `file`, or null. */
+function regularFile(file) {
+  try { return fs.lstatSync(file).isFile() ? file : null; } catch { return null; }
+}
+
+function readPosts(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.size > CHANNEL_MAX_BYTES) return null;
+    return { posts: parsePosts(fs.readFileSync(fd, 'utf8'), st.mtimeMs), mtime: st.mtimeMs };
+  } catch { return null; } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+const keyOf = (file) => {
+  const m = file.match(new RegExp(`(?:^|/)(${NAME})/\\.agents/(${NAME})/channel\\.md$`));
+  return m ? `${m[1]}/${m[2]}` : null;
+};
+
+export function createChannelDiscipline(hub, {
+  channelRoots = [], workspaceRoot = null, append, publish, now: clock = Date.now, warn = (message) => console.error(message),
+  staleAskMs = STALE_ASK_MS, staleEscalateMs = STALE_ESCALATE_MS,
+} = {}) {
+  const { db, registry } = hub;
+  installChannelDiscipline(db);
+  const started = clock();
+  const q = {
+    record: db.prepare(`INSERT INTO pulse_posts (session, key, file, role, head, at, terminal, auto, seen_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (session, key, role, head, at) DO UPDATE SET seen_at = excluded.seen_at`),
+    channelsOf: db.prepare('SELECT DISTINCT key FROM pulse_posts WHERE session = ?'),
+    lastOf: db.prepare('SELECT * FROM pulse_posts WHERE session = ? AND key = ? ORDER BY seen_at DESC, rowid DESC LIMIT 1'),
+    latestChannel: db.prepare('SELECT * FROM pulse_posts WHERE session = ? ORDER BY seen_at DESC, rowid DESC LIMIT 1'),
+    author: db.prepare('SELECT session FROM pulse_posts WHERE key = ? AND role = ? AND head = ? ORDER BY seen_at DESC LIMIT 1'),
+    prompt: db.prepare('SELECT * FROM pulse_prompts WHERE session = ?'),
+    openPrompt: db.prepare('INSERT INTO pulse_prompts (session, tool_use_id, key, file, role, message_id, at) VALUES (?, ?, ?, ?, ?, ?, ?)'),
+    closePrompt: db.prepare('DELETE FROM pulse_prompts WHERE session = ?'),
+    stale: db.prepare('SELECT * FROM pulse_stale WHERE key = ?'),
+    staleAll: db.prepare('SELECT key FROM pulse_stale'),
+    staleSet: db.prepare(`INSERT INTO pulse_stale (key, file, sig, first_seen, owner, asked_at, escalated_at) VALUES (?, ?, ?, ?, NULL, NULL, NULL)
+      ON CONFLICT (key) DO UPDATE SET file = excluded.file, sig = excluded.sig, first_seen = excluded.first_seen, owner = NULL, asked_at = NULL, escalated_at = NULL`),
+    staleAsked: db.prepare('UPDATE pulse_stale SET asked_at = ?, owner = ? WHERE key = ?'),
+    staleEscalated: db.prepare('UPDATE pulse_stale SET escalated_at = ? WHERE key = ?'),
+    staleDrop: db.prepare('DELETE FROM pulse_stale WHERE key = ?'),
+  };
+
+  /** E5, E6 apply only to sessions in this workspace: `~/.cursor/hooks.json` is global, other projects have no channels. */
+  const inWorkspace = (input) => !!workspaceRoot && (Array.isArray(input.workspace_roots) ? input.workspace_roots : [])
+    .some((r) => typeof r === 'string' && (r === workspaceRoot || r.startsWith(`${workspaceRoot}/`)));
+
+  /** The roots a channel named in a tool call is looked for under: the channel roots, the session's folders, its cwd. */
+  const rootsFor = (input) => {
+    const tool = input.tool_input && typeof input.tool_input === 'object' ? input.tool_input : {};
+    return [...new Set([...channelRoots, ...strings(input.workspace_roots), ...strings([tool.cwd, tool.working_directory, input.cwd])].filter((r) => path.isAbsolute(r)))];
+  };
+
+  /** The channel file a reference names, if it exists. */
+  function resolve(ref, roots) {
+    for (const p of ref.absolute) if (path.isAbsolute(p) && regularFile(p)) return p;
+    for (const root of roots) {
+      const candidates = ref.repo
+        ? [path.join(root, ref.repo, '.agents', ref.task, 'channel.md'), path.basename(root) === ref.repo ? path.join(root, '.agents', ref.task, 'channel.md') : null]
+        : [path.join(root, '.agents', ref.task, 'channel.md')];
+      for (const c of candidates) if (c && regularFile(c)) return c;
+    }
+    return null;
+  }
+
+  const roleOf = (session) => { const a = registry.get(session); return a && a.role ? normRole(a.role) : null; };
+
+  /** E5: a Task launch whose brief names no channel with a KICKOFF is denied; anything else, or too little to tell, is allowed (null). */
+  function taskGate(input) {
+    if (!inWorkspace(input)) return null;
+    const tool = input.tool_input;
+    if (!tool || typeof tool !== 'object' || (!('prompt' in tool) && !('description' in tool))) {
+      warn(`E5 channel gate skipped for ${input.conversation_id}: the hook sent no Task brief (a hook client older than 1.1.2?)`);
+      return null;
+    }
+    if (typeof tool.resume === 'string' && tool.resume.trim()) return null;
+    if (tool.readonly === true || (typeof tool.subagent_type === 'string' && READ_ONLY_SUBAGENTS.has(tool.subagent_type))) return null;
+    const refs = channelRefs(strings([tool.prompt, tool.description]).join('\n'));
+    const roots = rootsFor(input);
+    const checked = refs.map((ref) => {
+      const file = resolve(ref, roots);
+      const read = file ? readPosts(file) : null;
+      return { ref, file, kickoff: !!read && read.posts.some((p) => /^KICKOFF\b/.test(p.type.toUpperCase())) };
+    });
+    if (checked.some((c) => c.kickoff)) return null;
+    const why = checked.length
+      ? checked.map((c) => (c.file ? `\`${c.ref.named}\` has no KICKOFF post` : `\`${c.ref.named}\` does not exist`)).join('; ')
+      : 'the brief names no `.agents/<task>/channel.md`';
+    return {
+      permission: 'deny',
+      user_message: `Pulse stopped a subagent launch: ${why}.`,
+      agent_message: `Pulse denied this subagent launch: ${why}. Every agent you start needs its own task channel with a KICKOFF before it starts work. `
+        + 'Create `<repo>/.agents/<task>/channel.md`, append `## [ARCHITECT] HH:MM:SS KICKOFF — <task>` with the goal, scope, repos, acceptance and reviewer, '
+        + 'then launch again with that path in the brief. Resuming an existing agent is not gated.',
+    };
+  }
+
+  /** The channel a session works in: the one it posted to last, else its registered stream's. */
+  function channelOf(session) {
+    const last = q.latestChannel.get(session);
+    if (last && regularFile(last.file)) return { key: last.key, file: last.file, role: last.role };
+    const actor = registry.get(session);
+    const key = actor && actor.stream_key;
+    if (!key || !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(key)) return null;
+    const [repo, task] = key.split('/');
+    const file = resolve({ absolute: [], repo, task }, channelRoots);
+    return file ? { key, file, role: roleOf(session) } : null;
+  }
+
+  /** E6: a Shell call asking for permissions: one BLOCKER per session, to its channel and to you. Never blocks the call. */
+  function promptOpened(input, at) {
+    const tool = input.tool_input;
+    const asked = tool && Array.isArray(tool.required_permissions) ? tool.required_permissions.filter((p) => typeof p === 'string' && p) : [];
+    if (!asked.length || !inWorkspace(input)) return;
+    const session = input.conversation_id;
+    if (q.prompt.get(session)) return;
+    const channel = channelOf(session);
+    const role = (channel && channel.role) || roleOf(session) || 'AGENT';
+    const perms = asked.slice(0, 10).map((p) => `\`${p.slice(0, 40)}\``).join(', ');
+    if (channel) {
+      append(channel.file, autoPost(role, BLOCKER_HEAD, `Pulse posted this for session \`${session}\`: a Shell call asked for ${perms} and waits for you to approve the prompt in Cursor. The session's next step clears it.`, at));
+      record(session, channel.key, channel.file, { role, head: BLOCKER_HEAD, at, terminal: false, auto: true }, at);
+    }
+    const env = publish({
+      from: 'manager', fromName: 'Pulse', topic: 'user', type: 'BLOCKER',
+      body: `Session \`${session}\`${channel ? ` (${channel.key})` : ''} is waiting on you to approve a permission prompt in Cursor: a Shell call asked for ${perms}.`,
+      meta: { session, channel: channel ? channel.key : null, prompt: true },
+    });
+    q.openPrompt.run(session, typeof input.tool_use_id === 'string' ? input.tool_use_id : null, channel ? channel.key : null, channel ? channel.file : null, role, env && !env.error ? env.id : null, at);
+  }
+
+  /** E6: the prompt's call ended (or the turn or session did): the channel's BLOCKER is answered, unless the agent already posted since. */
+  function promptClosed(input, at) {
+    const session = input.conversation_id;
+    const open = q.prompt.get(session);
+    if (!open) return;
+    const event = input.hook_event_name;
+    if (event === 'postToolUse' || event === 'postToolUseFailure') {
+      const id = typeof input.tool_use_id === 'string' ? input.tool_use_id : null;
+      if (open.tool_use_id && id ? open.tool_use_id !== id : input.tool_name !== 'Shell') return;
+    } else if (event !== 'stop' && event !== 'sessionEnd') return;
+    q.closePrompt.run(session);
+    if (open.file && regularFile(open.file)) {
+      const read = readPosts(open.file);
+      const last = read && read.posts[read.posts.length - 1];
+      if (last && last.role === open.role && last.head === BLOCKER_HEAD) {
+        append(open.file, autoPost(open.role, CLEARED_HEAD, `Pulse posted this for session \`${session}\`: the permission prompt was answered.`, at));
+        record(session, open.key, open.file, { role: open.role, head: CLEARED_HEAD, at, terminal: false, auto: true }, at);
+      }
+    }
+    publish({
+      from: 'manager', fromName: 'Pulse', topic: 'user', type: 'STATUS',
+      body: `Session \`${session}\` is past its permission prompt.`, meta: { session, ...(open.message_id ? { supersedes: open.message_id } : {}) },
+    });
+  }
+
+  function record(session, key, file, post, at) {
+    q.record.run(session, key, file, post.role, post.head, Math.round(post.at), post.terminal ? 1 : 0, post.auto ? 1 : 0, at);
+  }
+
+  /**
+   * The posts a postToolUse shows the session wrote: each header line of the call, found in a channel the call named,
+   * recorded as that session's. Returns E4's receipts for headers stamped ahead of the clock.
+   */
+  function sawPosts(input, at) {
+    const tool = input.tool_input;
+    if (!tool || typeof tool !== 'object') return [];
+    const headers = strings(tool.headers);
+    const wrote = headerLines(headers);
+    if (!wrote.length) return [];
+    const roots = rootsFor(input);
+    const files = new Map();
+    for (const ref of strings(tool.channels).flatMap((c) => channelRefs(c, { folders: true }))) {
+      const file = resolve(ref, roots);
+      if (file) files.set(file, keyOf(file) || ref.task);
+    }
+    const receipts = [];
+    for (const [file, key] of files) {
+      const read = readPosts(file);
+      if (!read) continue;
+      for (const w of wrote) {
+        const mine = read.posts.filter((p) => p.role === w.role);
+        const post = mine.filter((p) => p.head === w.head).pop() || mine.pop();
+        if (post) record(input.conversation_id, key, file, { role: post.role, head: post.head, at: post.at, terminal: isTerminal(post), auto: false }, at);
+      }
+    }
+    if (files.size) {
+      for (const line of headers) {
+        const skew = headerSkewMs(line, at);
+        if (skew !== null && skew > FUTURE_MS) {
+          receipts.push(`Pulse: your post \`${line.trim().slice(0, 120)}\` is stamped ${Math.round(skew / 60e3)} min ahead of this machine's clock (${clockOf(at)}). Write header times with \`date +%H:%M:%S\` when you post.`);
+        }
+      }
+    }
+    return receipts;
+  }
+
+  /** E2: the session ended; each channel where its own newest post is not terminal gets an automatic STOPPED. */
+  function sessionEnded(session, reason, at) {
+    let n = 0;
+    for (const { key } of q.channelsOf.all(session)) {
+      const own = q.lastOf.get(session, key);
+      if (!own || own.terminal || !regularFile(own.file)) continue;
+      const read = readPosts(own.file);
+      if (!read) continue;
+      const at0 = read.posts.findLastIndex((p) => p.role === own.role && p.head === own.head);
+      if (read.posts.slice(at0 + 1).some((p) => p.role === own.role && isTerminal(p))) continue;
+      append(own.file, autoPost(own.role, STOPPED_HEAD, `Pulse appended this when session \`${session}\` ended${reason ? ` (${String(reason).slice(0, 40)})` : ''}. Its last post here was \`${own.head.slice(0, 160)}\`.`, at));
+      record(session, key, own.file, { role: own.role, head: STOPPED_HEAD, at, terminal: true, auto: true }, at);
+      n++;
+    }
+    return n;
+  }
+
+  /**
+   * One hook event. A `preToolUse` answer is the permission decision only (E5's deny, else nothing); a postToolUse
+   * gets E4's receipts as `notices`. The other effects are side effects: E2 on sessionEnd, E6 on Shell calls.
+   */
+  function onHook(input, at = clock()) {
+    const event = input.hook_event_name;
+    if (event === 'preToolUse') {
+      if (input.tool_name === 'Task') return { deny: taskGate(input), notices: [] };
+      if (input.tool_name === 'Shell') promptOpened(input, at);
+      return { deny: null, notices: [] };
+    }
+    promptClosed(input, at);
+    if (event === 'sessionEnd') {
+      sessionEnded(input.conversation_id, input.reason, at);
+      return { deny: null, notices: [] };
+    }
+    if (event === 'postToolUse' || event === 'postToolUseFailure') return { deny: null, notices: sawPosts(input, at) };
+    return { deny: null, notices: [] };
+  }
+
+  /** E3's owner of a channel's newest post: the session that wrote it, else the agent of that stream and role, else its architect. */
+  function ownerOf(key, last) {
+    const wrote = q.author.get(key, last.role, last.head);
+    if (wrote) return wrote.session;
+    const dir = registry.directory();
+    const crew = dir.filter((a) => a.streamKey === key && normRole(a.role) === last.role).sort((a, b) => (b.seenAt || 0) - (a.seenAt || 0));
+    if (crew.length) return crew[0].id;
+    const arch = dir.find((a) => a.isArchitect && (a.streams || []).includes(key));
+    return last.role === 'ARCHITECT' && arch ? arch.id : null;
+  }
+
+  function architectOf(key, owner) {
+    const dir = registry.directory();
+    const a = owner ? dir.find((d) => d.id === owner) : null;
+    if (a && a.deliveryId) return a.deliveryId;
+    const arch = dir.find((d) => d.isArchitect && (d.streams || []).includes(key));
+    return arch ? arch.deliveryId || arch.id : null;
+  }
+
+  /**
+   * E3, from the lease holder's sweep: each channel written in the last STALE_WATCH_MS whose newest post is not
+   * terminal. Its age counts from when this runner first saw that post (never before the runner started), not from
+   * the header, whose zone and date are unknown. Returns the messages it sent.
+   */
+  function sweep(now = clock()) {
+    const sent = [];
+    const live = new Set();
+    for (const c of channelFiles(channelRoots, now - STALE_WATCH_MS)) {
+      const read = readPosts(c.file);
+      const last = read && read.posts[read.posts.length - 1];
+      if (!last) continue;
+      live.add(c.key);
+      if (isTerminal(last)) { q.staleDrop.run(c.key); continue; }
+      const sig = `${last.role}\0${last.head}\0${read.posts.length}`;
+      let row = q.stale.get(c.key);
+      if (!row || row.sig !== sig) {
+        q.staleSet.run(c.key, c.file, sig, Math.max(started, Math.min(now, read.mtime)));
+        row = q.stale.get(c.key);
+      }
+      const age = now - row.first_seen;
+      const quiet = `${Math.floor(age / 60e3)} min`;
+      const lastLine = `\`## [${last.role}] … ${last.head.slice(0, 120)}\``;
+      if (age >= staleAskMs && !row.asked_at) {
+        const owner = ownerOf(c.key, last);
+        q.staleAsked.run(now, owner, c.key);
+        row.owner = owner;
+        if (owner) {
+          // A bus type is [A-Z0-9 _-] only, so `STATUS?` goes as a NUDGE that says it, as the manager's own check-ins do.
+          const env = publish({
+            from: 'manager', fromName: 'Pulse', topic: `agent/${owner}`, type: 'NUDGE', needsAck: true,
+            body: `STATUS? Your channel \`${c.key}\` has had no post for ${quiet}, and its last post ${lastLine} is not terminal. Post STATUS (what you are doing, or what you wait for and from whom), BLOCKER, or your terminal post.`,
+            meta: { stale: c.key },
+          });
+          if (env && !env.error) sent.push({ key: c.key, to: owner, type: 'STATUS?' });
+        }
+      }
+      if (age >= staleEscalateMs && !row.escalated_at) {
+        q.staleEscalated.run(now, c.key);
+        const body = `\`${c.key}\` has had no post for ${quiet}; its last post ${lastLine} is not terminal.${row.owner ? ` STATUS? went to \`${row.owner}\` with no post since.` : ' Pulse found no owner to ask.'}`;
+        const architect = architectOf(c.key, row.owner);
+        for (const topic of [...(architect && architect !== row.owner ? [`delivery/${architect}`] : []), 'user']) {
+          const env = publish({ from: 'manager', fromName: 'Pulse', topic, type: 'STALE', body, meta: { stale: c.key } });
+          if (env && !env.error) sent.push({ key: c.key, to: topic, type: 'STALE' });
+        }
+      }
+    }
+    for (const { key } of q.staleAll.all()) if (!live.has(key)) q.staleDrop.run(key);
+    return sent;
+  }
+
+  return { onHook, sweep };
+}

package/src/runner/deliveryStates.js

@@ -0,0 +1,220 @@
+import { DEFAULT_TTL_MS, MESSAGE_ID } from '../hub/core/ids.mjs';
+import { edgeId } from '../hub/core/edgeIds.mjs';
+import { parseJson } from '../hub/core/db.mjs';
+
+/**
+ * Pulse 1.1.1 honest delivery (F2, F2+, F8). Each recipient of a message is `undeliverable`, `queued`, `delivered`,
+ * `read`, `skipped`, `acked` or `expired`. The hub's own deliveries rows keep their 6b2fb0b states; `read` (a reader
+ * saw it) and `skipped` (settled with no reader) are recorded beside them in runner.db and never sent up: the cloud
+ * keeps delivered, acked and expired (option A), so nothing auto-handled ever shows there as acked.
+ */
+
+/** Mail sent without a delivery report (web, spool, the old backlog) is checked this long after it was sent. */
+export const BOUNCE_GRACE_MS = 2 * 60e3;
+const BOUNCE_BATCH = 200;
+/** The manager records these into its status: read, with no agent run. */
+const RECORDED = new Set(['DONE', 'STATUS']);
+/** Shown to a session by its hook: read at that session's next hook event, when a step has run with it in context. */
+const SHOWN_BY_HOOK = new Set(['postToolUse', 'side', 'stop', 'retried']);
+const REPORTS = 20;
+
+const SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS pulse_reads (
+     message_id TEXT NOT NULL, recipient TEXT NOT NULL, state TEXT NOT NULL CHECK (state IN ('read', 'skipped')), at INTEGER NOT NULL, via TEXT,
+     PRIMARY KEY (message_id, recipient))`,
+  'CREATE TABLE IF NOT EXISTS pulse_reported (message_id TEXT PRIMARY KEY, at INTEGER NOT NULL)',
+  'CREATE TABLE IF NOT EXISTS pulse_bounced (message_id TEXT NOT NULL, recipient TEXT NOT NULL, notice TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (message_id, recipient))',
+];
+
+export function installDeliveryStates(db) {
+  for (const sql of SCHEMA) db.prepare(sql).run();
+}
+
+const topicOf = (sender) => (sender === 'user' ? 'user' : `agent/${sender}`);
+
+export function createDeliveryStates(hub, bus, { now: clock = Date.now } = {}) {
+  const { db, registry, messaging } = hub;
+  installDeliveryStates(db);
+  const q = {
+    record: db.prepare('INSERT OR IGNORE INTO pulse_reads (message_id, recipient, state, at, via) VALUES (?, ?, ?, ?, ?)'),
+    readsOf: db.prepare('SELECT recipient, state, at, via FROM pulse_reads WHERE message_id = ?'),
+    reported: db.prepare('INSERT OR IGNORE INTO pulse_reported (message_id, at) VALUES (?, ?)'),
+    bounced: db.prepare('INSERT OR IGNORE INTO pulse_bounced (message_id, recipient, notice, at) VALUES (?, ?, ?, ?)'),
+    reports: db.prepare(`SELECT m.id, m.created_at AS at, m.sender AS "from", m.from_name AS fromName, m.type, m.topic, m.body, r.at AS readAt
+      FROM pulse_reads r JOIN messages m ON m.id = r.message_id
+      WHERE r.recipient = 'manager' AND r.state = 'read' ORDER BY r.at DESC, m.created_at DESC LIMIT ?`),
+    expire: db.prepare(`UPDATE deliveries SET state = 'expired', lease_token = NULL, lease_until = NULL
+      WHERE message_id = ? AND recipient = ? AND state IN ('queued', 'leased', 'delivered')`),
+    message: db.prepare('SELECT * FROM messages WHERE id = ?'),
+    superseder: db.prepare("SELECT id FROM messages WHERE json_valid(meta) AND json_extract(meta, '$.supersedes') = ? ORDER BY created_at DESC LIMIT 1"),
+  };
+
+  /**
+   * A hook event from a session: what its earlier hooks showed it is now read, since a step ran with it in context. A
+   * `bus listen` delivery needs one hook more: the listen call's own postToolUse fires before the model saw the output.
+   */
+  function readOnHook(addresses, { at = clock(), previousHook = null } = {}) {
+    if (!addresses.length) return 0;
+    const rows = db.prepare(`SELECT d.message_id, d.recipient, d.delivered_at, d.delivered_via FROM deliveries d
+      WHERE d.recipient IN (${addresses.map(() => '?').join(',')}) AND d.state = 'delivered' AND d.delivered_at > ?
+        AND NOT EXISTS (SELECT 1 FROM pulse_reads r WHERE r.message_id = d.message_id AND r.recipient = d.recipient)`).all(...addresses, at - DEFAULT_TTL_MS);
+    let n = 0;
+    for (const r of rows) {
+      const viaListen = r.delivered_via === 'listen';
+      const seen = viaListen ? previousHook !== null && r.delivered_at <= previousHook : SHOWN_BY_HOOK.has(r.delivered_via) && r.delivered_at <= at;
+      if (seen && q.record.run(r.message_id, r.recipient, 'read', at, viaListen ? 'listen' : 'hook').changes) n++;
+    }
+    return n;
+  }
+
+  /**
+   * The manager's FYIs (injected into createManager as `fyi`): taken off its queue with no agent run. A DONE or STATUS
+   * is recorded into its status, so read; anything else (a reply, an ack) is skipped. Never acked.
+   */
+  function managerFyi(m, { at = clock() } = {}) {
+    messaging.markDelivered('manager', [m.id], { via: 'manager', now: at });
+    const state = RECORDED.has(String(m.type || '').toUpperCase()) ? 'read' : 'skipped';
+    q.record.run(m.id, 'manager', state, at, state === 'read' ? 'manager-status' : 'manager');
+    return true;
+  }
+
+  /** The DONE and STATUS posts the manager has read lately, newest first: the `reports` of its status. */
+  const reports = (limit = REPORTS) => q.reports.all(limit).map((r) => ({
+    id: r.id, at: r.at, from: r.from, fromName: r.fromName, type: r.type, topic: r.topic, text: String(r.body || '').slice(0, 300), readAt: r.readAt,
+  }));
+
+  /** A message's recipients with the honest state of each (`delivery`), beside the hub's own fields. */
+  function honest(statuses, messageId, now = clock()) {
+    const reads = new Map(q.readsOf.all(messageId).map((r) => [r.recipient, r]));
+    return statuses.map((s) => {
+      const read = reads.get(s.to);
+      if (s.state === 'acked') return { ...s, delivery: 'acked', ...(read ? { readAt: read.at } : {}) };
+      if (read) return { ...s, delivery: read.state, readAt: read.at, ...(read.via === 'header' ? { reason: 'header-posted' } : {}) };
+      if (s.state === 'delivered' || s.state === 'unacked') return { ...s, delivery: 'delivered' };
+      if (s.state === 'expired') return { ...s, delivery: 'expired' };
+      const { state, ...why } = bus.reach(s.to, now);
+      return { ...s, delivery: state, ...why };
+    });
+  }
+
+  /**
+   * Bus envelopes (messaging.messages) with each recipient's honest state, and `supersededBy` on any message a later one
+   * in the list names in `meta.supersedes` (F7).
+   */
+  function withDelivery(envelopes, now = clock()) {
+    const by = new Map();
+    for (const m of envelopes) if (m.meta && MESSAGE_ID.test(String(m.meta.supersedes || ''))) by.set(m.meta.supersedes, m.id);
+    return envelopes.map((m) => ({ ...m, status: honest(m.status || [], m.id, now), ...(by.has(m.id) ? { supersededBy: by.get(m.id) } : {}) }));
+  }
+
+  /** One message and the honest state of each recipient, for `bus status` (F2+); null when there is no such message. */
+  function status(id, now = clock()) {
+    const m = q.message.get(id);
+    if (!m) return null;
+    const meta = parseJson(m.meta, {});
+    const later = q.superseder.get(id);
+    return {
+      id: m.id, at: m.created_at, from: m.sender, fromName: m.from_name, topic: m.topic, type: m.type, needsAck: !!m.needs_reply,
+      expiresAt: m.expires_at, replyTo: m.reply_to, ...(MESSAGE_ID.test(String(meta.supersedes || '')) ? { supersedes: meta.supersedes } : {}),
+      ...(later ? { supersededBy: later.id } : {}), status: honest(messaging.statusOf(id, now), id, now),
+    };
+  }
+
+  /** Who sent a message, so a reply to it can be checked against the addresses the bus knows (E1); null when there is none. */
+  const senderOf = (id) => (MESSAGE_ID.test(String(id || '')) ? q.message.get(id)?.sender ?? null : null);
+
+  /** The delivery report `bus publish` and `bus ask` print: each recipient, queued or undeliverable, and why. */
+  function report(env, now = clock()) {
+    if (MESSAGE_ID.test(String(env.id || ''))) q.reported.run(env.id, now);
+    return (env.to || []).map((to) => ({ to, ...bus.reach(to, now) }));
+  }
+
+  /**
+   * Mail that never had a delivery report (sent from the web, imported from a spool, or queued before 1.1.1) and has
+   * waited BOUNCE_GRACE_MS for a recipient nobody can read: its sender gets one UNDELIVERABLE notice per recipient,
+   * from the manager, with an id derived from the message and recipient. A notice is never itself bounced.
+   */
+  function bounce(now = clock()) {
+    const rows = db.prepare(`SELECT d.message_id AS id, d.recipient, m.sender, m.type, m.body FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.state = 'queued' AND m.expires_at > ? AND m.created_at <= ? AND m.created_at > ?
+        AND m.sender <> 'manager' AND m.type <> 'UNDELIVERABLE' AND d.recipient NOT IN ('user', 'manager')
+        AND NOT EXISTS (SELECT 1 FROM pulse_reported r WHERE r.message_id = m.id)
+        AND NOT EXISTS (SELECT 1 FROM pulse_bounced b WHERE b.message_id = d.message_id AND b.recipient = d.recipient)
+      ORDER BY m.created_at LIMIT ?`).all(now, now - BOUNCE_GRACE_MS, now - DEFAULT_TTL_MS, BOUNCE_BATCH);
+    const sent = [];
+    let dir = null;
+    for (const r of rows) {
+      const why = bus.reach(r.recipient, now);
+      if (why.state !== 'undeliverable') continue;
+      dir ??= registry.directory(now);
+      const id = edgeId('u', r.id, r.recipient);
+      const reason = why.reason === 'stale' ? `its session ${why.session} has had no activity for ${why.idleMin} min`
+        : why.reason === 'offline' ? `it has been offline since ${new Date(why.offlineSince).toISOString()}` : 'no session has bound it and nobody is listening';
+      const env = messaging.publish({
+        id, from: 'manager', fromName: 'Manager', topic: topicOf(r.sender), type: 'UNDELIVERABLE', replyTo: r.id,
+        body: `Your ${String(r.type).toLowerCase()} \`${r.id}\` to \`${r.recipient}\` is undeliverable: ${reason}. It stays queued until it expires and is delivered if a session binds or listens as \`${r.recipient}\`.`,
+        meta: { about: r.id, to: r.recipient, reason: why.reason },
+      }, dir);
+      q.bounced.run(r.id, r.recipient, env.error ? `error:${env.error}` : id, now);
+      if (!env.error) sent.push({ id: r.id, to: r.recipient, notice: id });
+    }
+    return sent;
+  }
+
+  /**
+   * When each agent last posted a channel header, by the hub's facts: an agent row's own latest post, and for an
+   * architect the newest ARCHITECT post among its delivery's streams.
+   */
+  function headerTimes() {
+    const out = new Map();
+    for (const row of registry.facts('agent-row')) {
+      if (!row.isArchitect && row.doing && Number.isFinite(row.doing.at)) out.set(row.key, row.doing.at);
+    }
+    for (const d of registry.facts('delivery')) {
+      const at = Math.max(0, ...(d.streams || []).map((s) => (s.lastPost && s.lastPost.role === 'ARCHITECT' ? Number(s.lastPost.at) || 0 : 0)));
+      if (at) out.set(d.key, Math.max(out.get(d.key) || 0, at));
+    }
+    return out;
+  }
+
+  /** F8: agents that posted a header since the last scheduled nudge are not silent, so they are not nudged. */
+  function postedSince(last) {
+    if (!Number.isFinite(last)) return [];
+    return [...headerTimes()].filter(([, at]) => at > last).map(([id]) => id);
+  }
+
+  /**
+   * One pending scheduled nudge, answered by a header. Shown: read, and its row stays delivered (the cloud and
+   * reconcile expire only from queued). Never shown: skipped, and off the queue as expired, from queued.
+   */
+  function settleNudge(row, at) {
+    if (row.state === 'delivered') return q.record.run(row.message_id, row.recipient, 'read', at, 'header').changes;
+    q.record.run(row.message_id, row.recipient, 'skipped', at, 'header');
+    return q.expire.run(row.message_id, row.recipient).changes;
+  }
+
+  /** Nudges that ask for an ack and still count as pending in scheduledNudge (wake.mjs), with whether each is settled. */
+  const pendingNudges = (now) => db.prepare(`SELECT d.message_id, d.recipient, d.state, m.created_at, m.meta,
+      EXISTS (SELECT 1 FROM pulse_reads r WHERE r.message_id = d.message_id AND r.recipient = d.recipient) AS settled
+    FROM messages m JOIN deliveries d ON d.message_id = m.id
+    WHERE m.sender = 'manager' AND m.type = 'NUDGE' AND m.needs_reply = 1 AND d.state IN ('queued', 'leased', 'delivered') AND m.expires_at > ?`).all(now);
+
+  /** F8: every pending scheduled nudge whose agent posted a header after it was sent is settled, never acked. */
+  function settleNudges(now = clock()) {
+    const rows = pendingNudges(now).filter((r) => !r.settled && parseJson(r.meta, {}).scheduled);
+    if (!rows.length) return 0;
+    const headers = headerTimes();
+    let n = 0;
+    for (const r of rows) if ((headers.get(r.recipient) || 0) > r.created_at) n += settleNudge(r, now);
+    return n;
+  }
+
+  /** Agents whose every pending nudge is settled: a read nudge must not hold back the next one when they go quiet again. */
+  function settledNudgeRecipients(now = clock()) {
+    const open = new Map();
+    for (const r of pendingNudges(now)) open.set(r.recipient, (open.get(r.recipient) ?? true) && !!r.settled);
+    return [...open].filter(([, settled]) => settled).map(([id]) => id);
+  }
+
+  return { readOnHook, managerFyi, reports, honest, withDelivery, status, senderOf, report, bounce, postedSince, settleNudges, settledNudgeRecipients };
+}