@saadnvd1/agent-os 0.3.514 → 0.3.517

package/lib/notify/push-types.ts

@@ -0,0 +1,79 @@
+/**
+ * Push notification types. Pure: no imports from the app, so the mobile app
+ * can sync this file as is.
+ *
+ * The payload is a versioned envelope. v1 is generic and content-free (a fixed
+ * title, a category word, a deep link). v2 is reserved for encrypted rich
+ * text; an app that doesn't know a version shows the outer alert and opens
+ * the fallback link, so v2 can ship without breaking older apps.
+ */
+
+export const PUSH_CATEGORIES = [
+  "asks",
+  "needs-you",
+  "review",
+  "ci",
+  "merged",
+  "agents",
+  "digest",
+  "system",
+] as const;
+export type PushCategory = (typeof PUSH_CATEGORIES)[number];
+
+/** Maps onto the APNs interruption level. */
+export type PushLevel = "time-sensitive" | "active" | "passive";
+
+export const PUSH_PLATFORMS = ["ios", "android"] as const;
+export type PushPlatform = (typeof PUSH_PLATFORMS)[number];
+
+export const PUSH_ENVIRONMENTS = ["production", "sandbox"] as const;
+export type PushEnvironment = (typeof PUSH_ENVIRONMENTS)[number];
+
+export const PUSH_TITLE = "AgentOS";
+
+/** Plain, content-free alert. */
+export interface PushEnvelopeV1 {
+  v: 1;
+  /** Category, so the app can group and filter. */
+  c: PushCategory;
+  /** Fixed title. */
+  t: typeof PUSH_TITLE;
+  /** Category word from the registry, never event text. */
+  b: string;
+  /** Deep link, an app path like `/session/abc`. */
+  l: string;
+  /** Replaces an earlier alert with the same key. Opaque. */
+  k: string;
+  /** Interruption level. */
+  p: PushLevel;
+}
+
+/** Reserved: encrypted rich text. Not produced yet. */
+export interface PushEnvelopeV2 {
+  v: 2;
+  c: PushCategory;
+  t: typeof PUSH_TITLE;
+  /** Generic fallback body shown if the app can't decrypt. */
+  b: string;
+  l: string;
+  k: string;
+  p: PushLevel;
+  /** Device id the key belongs to. */
+  d: string;
+  /** Base64url nonce and ciphertext. */
+  n: string;
+  x: string;
+}
+
+export type PushEnvelope = PushEnvelopeV1 | PushEnvelopeV2;
+
+/** What a sender needs to say about an event. Ids only, never text. */
+export interface PushEvent {
+  category: PushCategory;
+  /** Session, task or workspace id the link opens, when the category has one. */
+  id?: string | null;
+  /** Dedupe key, e.g. `ask:<id>` or `review:<task>:<sha>`. */
+  key?: string | null;
+  /** Events sharing this replace each other on the phone. Defaults to key. */
+  collapse?: string | null;
+}

package/lib/notify/redact.ts

@@ -0,0 +1,68 @@
+/**
+ * Keeps free text and secret-looking strings out of push payloads. Pure, so
+ * the mobile app can sync it.
+ */
+
+const MAX_ID = 64;
+const SAFE_ID = /^[A-Za-z0-9_-]+$/;
+
+/** Hex or base64 runs this long are treated as keys. */
+const LONG_RUN = /[A-Za-z0-9+/_=-]{24,}/g;
+const SECRET_PATTERNS: RegExp[] = [
+  /\baosd_[A-Za-z0-9_-]+/g,
+  /\bsk-[A-Za-z0-9_-]{8,}/g,
+  /\bgh[pousr]_[A-Za-z0-9]{8,}/g,
+  /\bAKIA[0-9A-Z]{8,}/g,
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g,
+];
+
+/**
+ * An id or key made by the app: no known token shape, and no single
+ * segment (split on - _ : .) that is a long hex or base64 run. A uuid or a
+ * timestamped id passes; a pasted key or a 40-character sha does not.
+ */
+function plainIdent(text: string): boolean {
+  if (SECRET_PATTERNS.some((re) => ((re.lastIndex = 0), re.test(text))))
+    return false;
+  return !text.split(/[-_:.]/).some((seg) => seg.length >= 24);
+}
+
+/** True when the string looks like a token, key or JWT. */
+export function looksSecret(text: string): boolean {
+  return [...SECRET_PATTERNS, LONG_RUN].some((re) => {
+    re.lastIndex = 0;
+    return re.test(text);
+  });
+}
+
+/**
+ * First line only, collapsed whitespace, no backticks, secrets replaced by
+ * `…`, clipped. For the rich text of a later envelope version.
+ */
+export function scrubText(text: string | null | undefined, max = 120): string {
+  let s = (text ?? "").split(/\r?\n/).find((l) => l.trim()) ?? "";
+  s = s.replace(/`+/g, "");
+  for (const re of SECRET_PATTERNS) s = s.replace(re, "…");
+  s = s.replace(LONG_RUN, "…");
+  s = s.replace(/\s+/g, " ").trim();
+  return s.length > max ? s.slice(0, max - 1).trimEnd() + "…" : s;
+}
+
+/** An id fit for a link or key: short and plain. Null if it isn't. */
+export function safeId(id: unknown): string | null {
+  if (typeof id !== "string" || id.length === 0 || id.length > MAX_ID)
+    return null;
+  if (!SAFE_ID.test(id)) return null;
+  return plainIdent(id) ? id : null;
+}
+
+/**
+ * A collapse key: opaque and bounded. Anything with characters outside the
+ * plain set, or secret-looking, is dropped rather than cleaned.
+ */
+export function safeKey(key: unknown): string | null {
+  if (typeof key !== "string" || key.length === 0 || key.length > 128)
+    return null;
+  if (!/^[A-Za-z0-9_:.-]+$/.test(key)) return null;
+  return plainIdent(key) ? key : null;
+}

package/lib/orchestrator/asks.ts

@@ -6,6 +6,7 @@
  * gate or brake ask is spent on that one item: never standing permission.
  */
 
+import { pushAskRaised } from "../notify/push/events";
 import { db } from "../db";
 import { answerKey, queueEvent } from "./events";
 import { addNote } from "./notes";
@@ -167,7 +168,7 @@ export function raiseAsk(input: {
   const sha = input.sha ?? null;
   const brakeKey = input.brakeKey ?? null;
   const raisedBy = input.raisedBy ?? null;
-  return db.transaction(() => {
+  const result = db.transaction(() => {
     const open = openBySubject(input.workspaceId, input.subject);
     if (open) {
       db.prepare(
@@ -209,6 +210,9 @@ export function raiseAsk(input: {
       created: true,
     };
   })();
+  // A new ask buzzes the phone; a refresh of an open one doesn't.
+  if (result.created) pushAskRaised(result.ask.id, input.workspaceId);
+  return result;
 }
 
 export function openAsks(workspaceId: string): AskRow[] {

package/lib/orchestrator/review.ts

@@ -10,6 +10,7 @@
  * the orchestrator hears the verdict as an event.
  */
 
+import { pushReviewBlocked, pushReviewReady } from "../notify/push/events";
 import { db, type Session } from "../db";
 import { amendmentsOf } from "./amendments";
 import type { TaskPR } from "../tasks/state";
@@ -275,6 +276,8 @@ export async function reviewAt(
     .then((done) => {
       if (done.status === "pass" && target.task)
         noteQuickReview(target.task, sha);
+      if (done.status === "pass") pushReviewReady(target.id, sha);
+      else if (done.status === "block") pushReviewBlocked(target.id, sha);
       const said =
         done.status === "pass"
           ? "passed"

package/lib/program-status/tap.ts

@@ -24,7 +24,9 @@ import {
   applyProgramReport,
   dropProgramTransient,
   programSessions,
+  programSummary,
 } from "./store";
+import { noteWaiting } from "../notify/push/waiting";
 
 const execFileAsync = promisify(execFile);
 const tmux = (args: string[]) =>
@@ -85,7 +87,15 @@ async function handle(name: string, event: OscEvent): Promise<void> {
             ? await foreground(name)
             : undefined
         );
-  if (changed) notifyStatusChanged();
+  if (changed) {
+    notifyStatusChanged();
+    const id = (
+      getDb()
+        .prepare(`SELECT id FROM sessions WHERE tmux_name = ?`)
+        .get(name) as { id: string } | undefined
+    )?.id;
+    if (id) noteWaiting(id, programSummary(name)?.state === "blocked");
+  }
 }
 
 // What one pane has said but isn't applied yet: the latest report per

package/lib/schedules/start.ts

@@ -237,7 +237,11 @@ function notify(schedule: Schedule, why: string, paused?: boolean): void {
     const text = `Schedule "${schedule.name}" is paused: ${why}. Point it at another session or delete it.`;
     console.error(`[schedules] ${text}`);
     addNote(schedule.workspace_id, text, "pause");
-    notifyPhone(`schedule:${schedule.id}`, text);
+    notifyPhone(`schedule:${schedule.id}`, text, {
+      category: "system",
+      key: `system:schedule:${schedule.id}:${Date.now()}`,
+      collapse: `system:schedule:${schedule.id}`,
+    });
     return;
   }
   console.error(`[schedules] ${schedule.name} failed: ${why}`);
@@ -248,7 +252,12 @@ function notify(schedule: Schedule, why: string, paused?: boolean): void {
   );
   notifyPhone(
     `schedule:${schedule.id}`,
-    `Schedule "${schedule.name}" failed: ${why}`
+    `Schedule "${schedule.name}" failed: ${why}`,
+    {
+      category: "system",
+      key: `system:schedule:${schedule.id}:${Date.now()}`,
+      collapse: `system:schedule:${schedule.id}`,
+    }
   );
 }
 

package/lib/security/demo.ts

@@ -59,6 +59,7 @@ export const STATIC_SIBLINGS = [
   "import",
   "init",
   "init-script",
+  "me",
   "items",
   "network",
   "queue",

package/lib/security/device-me.ts

@@ -0,0 +1,12 @@
+import { NextRequest, NextResponse } from "next/server";
+import { DEVICE_HEADER } from "./auth";
+
+/**
+ * The calling device, from the gate's header (never the body). Null when the
+ * request wasn't made with a device token, e.g. from this machine's browser.
+ */
+export const callingDevice = (request: NextRequest): string | null =>
+  request.headers.get(DEVICE_HEADER);
+
+export const needsDevice = () =>
+  NextResponse.json({ error: "Needs a paired device token." }, { status: 403 });

package/lib/security/devices.ts

@@ -5,6 +5,12 @@
 
 import crypto from "crypto";
 import { getDb } from "@/lib/db";
+import { enabledCategories } from "@/lib/notify/copy";
+import type {
+  PushCategory,
+  PushEnvironment,
+  PushPlatform,
+} from "@/lib/notify/push-types";
 
 export interface Device {
   id: string;
@@ -80,13 +86,52 @@ export function touchDevice(id: string, address?: string): boolean {
   return true;
 }
 
-export function listDevices(): Device[] {
-  return getDb()
+/** What the Devices page shows of a device's push: never the token. */
+export interface DevicePushView {
+  enabled: boolean;
+  categories: PushCategory[];
+  lastError: string | null;
+  updatedAt: string | null;
+}
+
+export type ListedDevice = Device & { push: DevicePushView };
+
+export function listDevices(): ListedDevice[] {
+  const rows = getDb()
     .prepare(
-      `SELECT id, name, user_agent, created_at, last_seen_at, last_address, revoked_at, can_approve
+      `SELECT id, name, user_agent, created_at, last_seen_at, last_address, revoked_at, can_approve,
+         ${PUSH_COLS}
        FROM devices WHERE revoked_at IS NULL ORDER BY created_at DESC`
     )
-    .all() as Device[];
+    .all() as (Device & PushRow)[];
+  return rows.map((r) => {
+    const {
+      push_token,
+      push_platform,
+      push_environment,
+      push_categories,
+      push_updated_at,
+      push_last_error,
+      ...device
+    } = r;
+    const push = pushOf({
+      push_token,
+      push_platform,
+      push_environment,
+      push_categories,
+      push_updated_at,
+      push_last_error,
+    });
+    return {
+      ...device,
+      push: {
+        enabled: !!push,
+        categories: push?.categories ?? [],
+        lastError: push_last_error,
+        updatedAt: push?.updatedAt ?? null,
+      },
+    };
+  });
 }
 
 export function renameDevice(id: string, name: string): boolean {
@@ -115,13 +160,162 @@ export function revokeDevice(id: string): boolean {
   const changed =
     getDb()
       .prepare(
-        `UPDATE devices SET revoked_at = datetime('now') WHERE id = ? AND revoked_at IS NULL`
+        `UPDATE devices SET revoked_at = datetime('now'),
+           push_token = NULL, push_platform = NULL, push_environment = NULL,
+           push_categories = NULL, push_updated_at = NULL, push_last_error = NULL
+         WHERE id = ? AND revoked_at IS NULL`
       )
       .run(id).changes > 0;
   if (changed) dropDeviceSockets(id);
   return changed;
 }
 
+export interface DevicePush {
+  token: string;
+  platform: PushPlatform;
+  environment: PushEnvironment;
+  /** What it receives: its saved list, or the defaults. */
+  categories: PushCategory[];
+  updatedAt: string;
+  lastError: string | null;
+}
+
+interface PushRow {
+  push_token: string | null;
+  push_platform: PushPlatform;
+  push_environment: PushEnvironment;
+  push_categories: string | null;
+  push_updated_at: string;
+  push_last_error: string | null;
+}
+
+// A corrupt saved list reads as "none saved", so the defaults apply.
+function parseCategories(raw: string | null): unknown[] | null {
+  if (!raw) return null;
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+const pushOf = (r: PushRow | undefined): DevicePush | null =>
+  r?.push_token
+    ? {
+        token: r.push_token,
+        platform: r.push_platform,
+        environment: r.push_environment,
+        categories: enabledCategories(parseCategories(r.push_categories)),
+        updatedAt: r.push_updated_at,
+        lastError: r.push_last_error,
+      }
+    : null;
+
+const PUSH_COLS = `push_token, push_platform, push_environment, push_categories,
+  push_updated_at, push_last_error`;
+
+export function getDevicePush(id: string): DevicePush | null {
+  return pushOf(
+    getDb()
+      .prepare(
+        `SELECT ${PUSH_COLS} FROM devices WHERE id = ? AND revoked_at IS NULL`
+      )
+      .get(id) as PushRow | undefined
+  );
+}
+
+/** Every live device that can be sent a push, for the sender. */
+export function listPushDevices(): { id: string; push: DevicePush }[] {
+  const rows = getDb()
+    .prepare(
+      `SELECT id, ${PUSH_COLS} FROM devices
+       WHERE revoked_at IS NULL AND push_token IS NOT NULL`
+    )
+    .all() as (PushRow & { id: string })[];
+  return rows.flatMap((r) => {
+    const push = pushOf(r);
+    return push ? [{ id: r.id, push }] : [];
+  });
+}
+
+/**
+ * Registers or refreshes a device's push token. Idempotent. Saved categories
+ * are kept unless new ones are given. A token belongs to one device: if
+ * another row held it (a re-pair on the same phone), that row loses it so
+ * nothing is sent twice.
+ */
+export function setDevicePush(
+  id: string,
+  p: {
+    token: string;
+    platform: PushPlatform;
+    environment: PushEnvironment;
+    categories?: PushCategory[];
+  }
+): boolean {
+  const db = getDb();
+  return db.transaction(() => {
+    db.prepare(
+      `UPDATE devices SET push_token = NULL, push_platform = NULL,
+         push_environment = NULL, push_categories = NULL,
+         push_updated_at = NULL, push_last_error = NULL
+       WHERE push_token = ? AND id != ?`
+    ).run(p.token, id);
+    return (
+      db
+        .prepare(
+          `UPDATE devices SET push_token = ?, push_platform = ?, push_environment = ?,
+             push_categories = COALESCE(?, push_categories),
+             push_updated_at = datetime('now'), push_last_error = NULL
+           WHERE id = ? AND revoked_at IS NULL`
+        )
+        .run(
+          p.token,
+          p.platform,
+          p.environment,
+          p.categories ? JSON.stringify(p.categories) : null,
+          id
+        ).changes > 0
+    );
+  })();
+}
+
+/** False when the device has no push registered. */
+export function setDevicePushCategories(
+  id: string,
+  categories: PushCategory[]
+): boolean {
+  return (
+    getDb()
+      .prepare(
+        `UPDATE devices SET push_categories = ?, push_updated_at = datetime('now')
+         WHERE id = ? AND revoked_at IS NULL AND push_token IS NOT NULL`
+      )
+      .run(JSON.stringify(categories), id).changes > 0
+  );
+}
+
+/** The sender records why a send failed, so the Devices page can say. */
+export function setDevicePushError(id: string, error: string | null): void {
+  getDb()
+    .prepare(`UPDATE devices SET push_last_error = ? WHERE id = ?`)
+    .run(error ? error.slice(0, 200) : null, id);
+}
+
+export function clearDevicePush(id: string): boolean {
+  return (
+    getDb()
+      .prepare(
+        `UPDATE devices SET push_token = NULL, push_platform = NULL,
+           push_environment = NULL, push_categories = NULL,
+           push_updated_at = NULL, push_last_error = NULL
+         WHERE id = ? AND push_token IS NOT NULL`
+      )
+      .run(id).changes > 0
+  );
+}
+
 // Open WebSockets per device, so revoking one cuts its live terminal too.
 // On globalThis because server.ts and Next's route bundles load this module
 // separately.
@@ -146,3 +340,17 @@ function dropDeviceSockets(id: string): void {
   for (const s of sockets.get(id) ?? []) s.destroy();
   sockets.delete(id);
 }
+
+/**
+ * The relay said this token is dead: forget it, keep the chosen categories,
+ * say why. The app registers a fresh token on its next launch.
+ */
+export function pruneDevicePush(id: string, reason: string): void {
+  getDb()
+    .prepare(
+      `UPDATE devices SET push_token = NULL, push_platform = NULL,
+         push_environment = NULL, push_last_error = ?
+       WHERE id = ?`
+    )
+    .run(reason.slice(0, 200), id);
+}

package/lib/security/net.ts

@@ -5,6 +5,7 @@
  * another site's page (drive-by requests from any website the user visits).
  */
 
+import { isIP } from "net";
 import os from "os";
 
 const TAILSCALE_V4 = /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./; // 100.64.0.0/10
@@ -72,6 +73,8 @@ export function bindAddresses(
 export interface AccessPolicy {
   bound: string[];
   extraHosts: string[];
+  /** This machine's Connect address (connect.json), when it has one. */
+  machineHost?: () => string | null;
 }
 
 const LOCAL_NAMES = new Set(["localhost", "127.0.0.1", "::1"]);
@@ -82,6 +85,23 @@ function hostname(hostOrUrlHost: string): string {
   return h.replace(/:\d+$/, "");
 }
 
+// Every Connect machine is m-<16 hex>.runagentos.com, so all of them are
+// the same site: another machine's page is never one of ours.
+const MACHINE_HOST = /^m-[0-9a-f]{16}\.runagentos\.com$/;
+
+const machineHostOf = (policy: AccessPolicy) =>
+  policy.machineHost?.()?.toLowerCase() || null;
+
+/** Names that are this machine whatever it's bound to. */
+function ownHost(h: string, policy: AccessPolicy): boolean {
+  return (
+    LOCAL_NAMES.has(h) ||
+    (h !== "0.0.0.0" && policy.bound.includes(h)) ||
+    policy.extraHosts.includes(h) ||
+    machineHostOf(policy) === h
+  );
+}
+
 export function hostAllowed(
   host: string | undefined,
   policy: AccessPolicy
@@ -89,25 +109,39 @@ export function hostAllowed(
   if (!host) return false;
   if (policy.bound.includes("0.0.0.0")) return true;
   const h = hostname(host);
-  return (
-    LOCAL_NAMES.has(h) ||
-    policy.bound.includes(h) ||
-    h.endsWith(".ts.net") ||
-    policy.extraHosts.includes(h)
-  );
+  return ownHost(h, policy) || h.endsWith(".ts.net");
 }
 
+/**
+ * A page may talk to this machine only from one of this machine's own
+ * origins, whatever AGENTOS_BIND says: its loopback, bound and configured
+ * names, its own Connect address, or the host the request itself names when
+ * that is one of its addresses (a page served here on any of its ports; the
+ * mobile app's native socket sends that one). A wildcard bind widens the
+ * Host check, never this one: not another machine's m- address, not a name
+ * rebound to this machine's address.
+ */
 export function originAllowed(
   origin: string | undefined,
-  policy: AccessPolicy
+  policy: AccessPolicy,
+  requestHost?: string
 ): boolean {
-  if (!origin) return true; // not a browser page: curl, aos, server-side
+  if (!origin) return true; // not a browser page: curl, aos, peers, the app
   if (origin === "null") return false;
+  let h: string;
   try {
-    return hostAllowed(new URL(origin).host, policy);
+    h = hostname(new URL(origin).host);
   } catch {
     return false;
   }
+  if (!h) return false;
+  if (MACHINE_HOST.test(h)) return h === machineHostOf(policy);
+  if (ownHost(h, policy)) return true;
+  return (
+    !!requestHost &&
+    h === hostname(requestHost) &&
+    (h.endsWith(".ts.net") || isIP(h) !== 0)
+  );
 }
 
 const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
@@ -145,7 +179,7 @@ export function requestAllowed(
   if (!req.url?.startsWith("/api/")) return true;
   if (req.fetchSite === "cross-site") return crossSiteNavigationAllowed(req);
   if (!SAFE_METHODS.has((req.method ?? "GET").toUpperCase())) {
-    return originAllowed(req.origin, policy);
+    return originAllowed(req.origin, policy, req.host);
   }
   return true;
 }
@@ -154,5 +188,7 @@ export function upgradeAllowed(
   req: { host?: string; origin?: string },
   policy: AccessPolicy
 ): boolean {
-  return hostAllowed(req.host, policy) && originAllowed(req.origin, policy);
+  return (
+    hostAllowed(req.host, policy) && originAllowed(req.origin, policy, req.host)
+  );
 }

package/lib/tasks/finish.ts

@@ -12,6 +12,7 @@ import { itemName, liveChildren, signOffRefusal } from "../stacks/guard";
 import { resolveMergedTaskAsks } from "../orchestrator/ask-settle";
 import { endSessionAgent } from "../sessions/end";
 import { run } from "./gh";
+import { pushMerged } from "../notify/push/events";
 import { gitFetch, gitPush } from "../git-exec";
 import {
   mergePolicy,
@@ -155,6 +156,7 @@ export async function signOffTask(
     signingOff.delete(id);
   }
   syncTaskCardInBackground(session, "merged", pr);
+  pushMerged(id);
   // Reads the plan file now: cleanup below removes the worktree.
   void captureMergedTask(id, { head: opts.head ?? pr!.head ?? null });
   const head = opts.head ?? pr!.head;

package/lib/tasks/session.ts

@@ -16,6 +16,12 @@ import { findPRStrict } from "./gh";
 import { currentBranch, git } from "../git-exec";
 import { lookupPR } from "./pr-poll";
 import { captureMergedTask } from "../session-logs";
+import { getOrchestrator } from "../orchestrator/home";
+import {
+  pushCiFailed,
+  pushMerged,
+  pushReviewReady,
+} from "../notify/push/events";
 import { notifyStatusChanged } from "../status/hub";
 import type { TaskPR } from "./state";
 import { markStatusDirty } from "../status/dirty";
@@ -193,14 +199,19 @@ export async function prFor(
   prCache.set(session.id, { at: Date.now(), pr });
   markStatusDirty(session.id);
   // A PR whose stage inputs moved is news for the sidebar's badge.
-  if (prSignature(before) !== prSignature(pr)) notifyStatusChanged();
+  if (prSignature(before) !== prSignature(pr)) {
+    notifyStatusChanged();
+    if (pr) pushPrChange(session, pr);
+  }
   if (pr) {
     db.prepare(
       `UPDATE sessions SET pr_url = ?, pr_number = ?, pr_status = ? WHERE id = ?`
     ).run(pr.url, pr.number, pr.state.toLowerCase(), session.id);
     // Merged on GitHub rather than through AgentOS: its log is due too.
-    if (pr.state === "MERGED")
+    if (pr.state === "MERGED") {
+      if (session.pr_status !== "merged") pushMerged(session.id);
       void captureMergedTask(session.id, { head: pr.head });
+    }
   }
   // Only an answer just read from GitHub: a cached one may predate a
   // retarget AgentOS made itself (a restack).
@@ -283,3 +294,16 @@ export function forgetPR(sessionId: string): void {
   prCache.delete(sessionId);
   markStatusDirty(sessionId);
 }
+
+// CI failing is news for the phone in any workspace. Green is "ready for
+// review" only where no orchestrator runs a review of its own (its verdict is
+// the signal there). Each head is pushed once: the event key holds the sha.
+export function pushPrChange(session: Session, pr: TaskPR): void {
+  if (pr.state !== "OPEN" || !pr.head) return;
+  if (pr.checks === "fail") pushCiFailed(session.id, pr.head);
+  else if (
+    pr.checks === "pass" &&
+    !(session.workspace_id && getOrchestrator(session.workspace_id))
+  )
+    pushReviewReady(session.id, pr.head);
+}