@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/core/nudge/policy.js

@@ -0,0 +1,143 @@
+// How many unrequested messages APX may send, and when.
+//
+// Three layers, lowest precedence first:
+//
+//   1. CORE DEFAULTS — permissive, and `enabled: false`. Vanilla APX delivers
+//      exactly what it delivered before this module existed. Turning a budget
+//      on by default would have silently muted push paths people already rely
+//      on, which is a regression dressed as a feature.
+//   2. THE ACTIVE PROFILE — a profile that declares `nudge_budget_per_day` or
+//      `quiet_hours` is stating a criterion, and switches enforcement ON. This
+//      is the split the whole profile subsystem rests on: core owns the
+//      capability (a gate, a ledger, a feedback loop), the profile owns the
+//      judgement (three a day, quiet after ten).
+//   3. THE USER — `config.nudge` in ~/.apx/config.json, written by the panel or
+//      by hand. Always wins. Someone who sets a number should get that number
+//      whatever profile they install later.
+import { readActiveProfile, effectiveProfileConfig } from "#core/profiles/store.js";
+
+/** Permissive on purpose — see the header. */
+export const DEFAULT_POLICY = Object.freeze({
+  enabled: false,
+  daily_max: 0,               // 0 = no ceiling
+  quiet_hours: "",            // "" = never quiet
+  cooldown_minutes: 0,        // between any two nudges
+  project_cooldown_minutes: 0, // between two nudges about the SAME project
+  kind_cooldown_minutes: 0,   // between two nudges of the SAME kind
+  critical_bypasses_budget: true,
+});
+
+/**
+ * Profile config keys this module understands. Deliberately generic names: a
+ * chief-of-staff profile and a study-tutor profile both mean the same thing by
+ * "how often may you interrupt me". A profile that declares neither key leaves
+ * the gate off.
+ */
+const PROFILE_KEYS = Object.freeze({
+  nudge_budget_per_day: "daily_max",
+  quiet_hours: "quiet_hours",
+  nudge_cooldown_minutes: "cooldown_minutes",
+  nudge_project_cooldown_minutes: "project_cooldown_minutes",
+  nudge_kind_cooldown_minutes: "kind_cooldown_minutes",
+});
+
+/**
+ * Resolve the effective policy for the current config.
+ *
+ * @param {object} config  the parsed ~/.apx/config.json
+ * @returns {typeof DEFAULT_POLICY & { source: string[] }}
+ */
+export function resolveNudgePolicy(config = {}) {
+  const policy = { ...DEFAULT_POLICY };
+  const source = ["defaults"];
+
+  // ── layer 2: the active profile ──────────────────────────────────────────
+  let profileConfig = null;
+  try {
+    const active = readActiveProfile(config);
+    if (active) profileConfig = effectiveProfileConfig(active, config);
+  } catch {
+    // A broken or half-installed profile must not take the gate down with it.
+    profileConfig = null;
+  }
+
+  if (profileConfig) {
+    let touched = false;
+    for (const [profileKey, policyKey] of Object.entries(PROFILE_KEYS)) {
+      const v = profileConfig[profileKey];
+      if (v === undefined || v === null || v === "") continue;
+      policy[policyKey] = v;
+      touched = true;
+    }
+    // Declaring a budget IS opting in. A profile that says "three a day" and
+    // then gets ignored because a separate flag was off is worse than useless.
+    if (touched) {
+      policy.enabled = true;
+      source.push("profile");
+    }
+  }
+
+  // ── layer 3: the user ────────────────────────────────────────────────────
+  const user = config?.nudge;
+  if (user && typeof user === "object") {
+    let touched = false;
+    for (const key of Object.keys(DEFAULT_POLICY)) {
+      if (user[key] === undefined || user[key] === null) continue;
+      policy[key] = user[key];
+      touched = true;
+    }
+    if (touched) source.push("user");
+  }
+
+  policy.daily_max = toNonNegativeInt(policy.daily_max);
+  policy.cooldown_minutes = toNonNegativeInt(policy.cooldown_minutes);
+  policy.project_cooldown_minutes = toNonNegativeInt(policy.project_cooldown_minutes);
+  policy.kind_cooldown_minutes = toNonNegativeInt(policy.kind_cooldown_minutes);
+  policy.enabled = policy.enabled === true;
+  policy.critical_bypasses_budget = policy.critical_bypasses_budget !== false;
+  policy.quiet_hours = typeof policy.quiet_hours === "string" ? policy.quiet_hours.trim() : "";
+
+  return { ...policy, source };
+}
+
+function toNonNegativeInt(v) {
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Parse a "HH:MM-HH:MM" window into minutes-from-midnight.
+ * Returns null when the string is absent or unparseable — an unreadable window
+ * must not accidentally mean "always quiet".
+ */
+export function parseQuietHours(spec) {
+  const m = /^\s*(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})\s*$/.exec(String(spec || ""));
+  if (!m) return null;
+  const [h1, m1, h2, m2] = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (h1 > 23 || h2 > 23 || m1 > 59 || m2 > 59) return null;
+  return { start: h1 * 60 + m1, end: h2 * 60 + m2 };
+}
+
+/**
+ * Is `date` inside the quiet window? Handles windows that cross midnight,
+ * which is the normal case for sleep ("22:00-07:30").
+ */
+export function isQuietAt(spec, date = new Date()) {
+  const w = parseQuietHours(spec);
+  if (!w) return false;
+  const mins = date.getHours() * 60 + date.getMinutes();
+  if (w.start === w.end) return false;               // zero-width window
+  if (w.start < w.end) return mins >= w.start && mins < w.end;
+  return mins >= w.start || mins < w.end;            // crosses midnight
+}
+
+/** When does the current quiet window end? Null when not quiet. */
+export function quietEndsAt(spec, date = new Date()) {
+  if (!isQuietAt(spec, date)) return null;
+  const w = parseQuietHours(spec);
+  const end = new Date(date);
+  end.setSeconds(0, 0);
+  end.setHours(Math.floor(w.end / 60), w.end % 60);
+  if (end <= date) end.setDate(end.getDate() + 1);
+  return end;
+}

package/src/core/nudge/store.js

@@ -0,0 +1,141 @@
+// The nudge ledger — every unrequested message APX sent, and what the user
+// thought of it.
+//
+// Path: ~/.apx/nudges.json
+//
+// Two reasons this is written down rather than kept in memory:
+//   - a daily ceiling that resets on every daemon restart is not a ceiling;
+//   - without a record of what was sent, "was that useful?" has nothing to
+//     attach to, and the feedback loop is what stops the initiative from
+//     decaying into noise the user mutes.
+//
+// Bounded on purpose: a file read on every push must not grow without limit.
+import fs from "node:fs";
+import path from "node:path";
+import { NUDGES_PATH } from "#core/config/paths.js";
+
+/** Entries kept. Roughly a year at three a day, minutes at pathological rates. */
+const MAX_ENTRIES = 1000;
+
+// A FUNCTION, not a shared constant: `{ ...EMPTY }` would copy the object but
+// hand every caller the same `entries` array, so appends would accumulate in
+// memory whatever the file said — a daily ceiling that quietly counted across
+// wipes and restarts.
+const empty = () => ({ version: 1, entries: [] });
+
+export function readNudgeLedger() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(NUDGES_PATH, "utf8"));
+    if (!raw || typeof raw !== "object") return empty();
+    return {
+      version: raw.version || 1,
+      entries: Array.isArray(raw.entries) ? raw.entries : [],
+    };
+  } catch {
+    return empty();
+  }
+}
+
+function writeNudgeLedger(ledger) {
+  const entries = ledger.entries.slice(-MAX_ENTRIES);
+  fs.mkdirSync(path.dirname(NUDGES_PATH), { recursive: true });
+  fs.writeFileSync(NUDGES_PATH, JSON.stringify({ ...ledger, entries }, null, 2));
+}
+
+/**
+ * Append a delivered nudge.
+ *
+ * Called AFTER the send succeeds: a message that never reached the user must
+ * not spend their budget for the day.
+ */
+export function appendNudge(entry) {
+  const ledger = readNudgeLedger();
+  ledger.entries.push({
+    id: entry.id,
+    at: entry.at || new Date().toISOString(),
+    kind: entry.kind || "unknown",
+    project_id: entry.project_id ?? null,
+    severity: entry.severity || "normal",
+    channel: entry.channel || "telegram",
+    chat_id: entry.chat_id != null ? String(entry.chat_id) : null,
+    preview: String(entry.preview || "").slice(0, 200),
+    bypassed_budget: entry.bypassed_budget === true,
+    scheduled: entry.scheduled === true,
+    feedback: null,
+  });
+  writeNudgeLedger(ledger);
+  return ledger.entries[ledger.entries.length - 1];
+}
+
+/**
+ * Record what the user thought. Returns the updated entry, or null when the id
+ * is unknown — a button pressed on a message older than the ledger window.
+ */
+export function setNudgeFeedback(nudgeId, { useful, note = "" } = {}) {
+  const ledger = readNudgeLedger();
+  const entry = ledger.entries.find((e) => e.id === nudgeId);
+  if (!entry) return null;
+  entry.feedback = {
+    useful: useful === true,
+    note: String(note || "").slice(0, 500),
+    at: new Date().toISOString(),
+  };
+  writeNudgeLedger(ledger);
+  return entry;
+}
+
+/** Entries sent on the same local calendar day as `date`. */
+export function nudgesOnDay(date = new Date(), ledger = readNudgeLedger()) {
+  const day = localDayKey(date);
+  return ledger.entries.filter((e) => localDayKey(new Date(e.at)) === day);
+}
+
+/** Most recent entry matching a predicate, or null. */
+export function lastNudge(predicate, ledger = readNudgeLedger()) {
+  for (let i = ledger.entries.length - 1; i >= 0; i--) {
+    if (predicate(ledger.entries[i])) return ledger.entries[i];
+  }
+  return null;
+}
+
+/** Newest first, optionally filtered. For the CLI and the panel. */
+export function listNudges({ limit = 50, kind = "", project_id = "", with_feedback = null } = {}) {
+  let rows = readNudgeLedger().entries.slice().reverse();
+  if (kind) rows = rows.filter((e) => e.kind === kind);
+  if (project_id) rows = rows.filter((e) => String(e.project_id) === String(project_id));
+  if (with_feedback === true) rows = rows.filter((e) => e.feedback);
+  if (with_feedback === false) rows = rows.filter((e) => !e.feedback);
+  return rows.slice(0, Math.max(1, Number(limit) || 50));
+}
+
+/**
+ * What the feedback adds up to. The point of collecting it is to be able to
+ * answer "which kinds of interruption are worth sending".
+ */
+export function nudgeStats() {
+  const entries = readNudgeLedger().entries;
+  const byKind = {};
+  for (const e of entries) {
+    const k = (byKind[e.kind] ||= { kind: e.kind, sent: 0, useful: 0, noise: 0 });
+    k.sent += 1;
+    if (e.feedback?.useful === true) k.useful += 1;
+    if (e.feedback?.useful === false) k.noise += 1;
+  }
+  return {
+    total: entries.length,
+    today: nudgesOnDay().length,
+    rated: entries.filter((e) => e.feedback).length,
+    by_kind: Object.values(byKind).sort((a, b) => b.sent - a.sent),
+  };
+}
+
+/** Local calendar day — the user's day, not UTC's. */
+function localDayKey(d) {
+  if (Number.isNaN(d?.getTime?.())) return "";
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+/** Test-only: wipe the ledger. */
+export function _resetNudgeLedger() {
+  try { fs.rmSync(NUDGES_PATH, { force: true }); } catch { /* nothing to remove */ }
+}

package/src/core/profiles/bundled/secretary/PROFILE.md

@@ -20,26 +20,25 @@ through you is anchored to a project registered in APX.
 ## How you work
 
 **Capture by default, ask rarely.** When a task surfaces, record it yourself. Infer the
-project when you can and say in one line what you filed and where. When you genuinely
-cannot tell, ask with buttons, never an open question. The system dies the day recording
+project when you can and say in one line what you filed and where. When you cannot tell,
+ask with buttons, never an open question. The system dies the day recording
 something costs more than not recording it.
 
 **Tasks and commitments are different.** A task is work to be done. A commitment was
-promised to a specific person, with a date; breaking it has a relational cost. Commitments
-outrank tasks and get warned about earlier.
+promised to a specific person, with a date; breaking it has a relational cost. Use `record_commitment`, not
+`create_task`. Commitments outrank tasks and are warned about earlier.
 
 **Never invent state.** If you do not know how a project is doing, say "no activity
-recorded on X since Y". That is useful. A fabricated summary destroys trust in the whole
-system and it does not come back. Always prefer the explicit gap over the tidy assumption.
+recorded on X since Y". That is useful. A fabricated summary destroys trust in the
+system and it does not come back. Prefer the explicit gap over the tidy assumption.
 
 **Write like someone who knows the subject.** Short sentences. No decorative headers, no
 greeting rituals, no six bullets where two sentences do. What matters goes first. These
 instructions are in English; write to {{owner_name}} in their language.
 
-**Delegate domain work.** You coordinate; you do not do it. Anything involving code goes
-through the development agent. When several specialists report back, you consolidate —
+**Delegate domain work.** You coordinate; you do not do it. Code goes through the development agent. When several specialists report back, you consolidate —
 never pass raw subagent output through.
 
 **Permissions.** Recording, reorganising, preparing and researching: go ahead. Writing
 outward — sending, publishing, changing something in a third-party system: confirm first,
-but arrive with it already prepared so confirming is one button.
+but arrive with it prepared so confirming is one button.

package/src/core/profiles/bundled/secretary/config.schema.json

@@ -17,19 +17,49 @@
       "type": "integer",
       "default": 3,
       "title": "Unrequested messages per day",
-      "description": "The ceiling outside the anchors. Lower is usually better."
+      "description": "The ceiling outside the anchors. Lower is usually better. Declaring this switches the interruption budget on."
     },
     "quiet_hours": {
       "type": "string",
       "default": "22:00-07:30",
       "title": "Quiet hours",
-      "description": "No unrequested messages in this window."
+      "description": "No unrequested messages in this window. Replies are never held back."
+    },
+    "nudge_project_cooldown_minutes": {
+      "type": "integer",
+      "default": 180,
+      "title": "Minimum gap per project (minutes)",
+      "description": "Three separate thoughts about the same project in one hour is one interruption too many."
+    },
+    "nudge_kind_cooldown_minutes": {
+      "type": "integer",
+      "default": 120,
+      "title": "Minimum gap per kind (minutes)",
+      "description": "Stops one repeating condition from filling the day's budget on its own."
+    },
+    "watch_schedule": {
+      "type": "string",
+      "default": "0 */2 * * *",
+      "title": "Watch runs (cron)",
+      "description": "How often to sweep for things worth noticing between the anchors. Cheap: with nothing to report it never wakes the model."
     },
     "stale_project_days": {
       "type": "integer",
       "default": 7,
       "title": "A project is stale after (days)",
-      "description": "Days without recorded activity before it is worth mentioning."
+      "description": "Days without recorded task or commitment activity before it is worth mentioning."
+    },
+    "blocked_task_hours": {
+      "type": "integer",
+      "default": 48,
+      "title": "A blocked task is stuck after (hours)",
+      "description": "Blocked this morning is a normal working state, not a problem."
+    },
+    "commitment_lead_hours": {
+      "type": "integer",
+      "default": 48,
+      "title": "Warn about a promise this early (hours)",
+      "description": "How far ahead of its date to raise a commitment, while there is still time to keep it."
     },
     "primary_channel": {
       "type": "string",

package/src/core/profiles/bundled/secretary/routines/day-close.json

@@ -2,9 +2,13 @@
   "name": "day-close",
   "kind": "super_agent",
   "schedule": "{{day_close_schedule}}",
-  "permission_mode": "automatico",
+  "permission_mode": "permiso",
   "enabled_by_default": true,
   "spec": {
-    "prompt": "Close the day. Across every registered project, review what moved today, what is still stuck, and what carries over to tomorrow. Send ONE short message covering those three. Note anything that has now gone quiet longer than the staleness threshold. If the day was quiet, say that plainly and keep it to a line or two. Record in your routine memory anything durable you learned about how this person works."
-  }
+    "prompt": "Close the day. Review what moved today, what is still stuck, and what carries over to tomorrow, across every registered project. Call list_tasks and list_commitments ONCE each, with no project argument — both search every project in a single call. Do not loop over projects. If a commitment came due today, ask whether it was kept — do not mark it yourself.\n\nSend ONE short message covering those, keeping promises to people separate from ordinary tasks. Note anything that has gone quiet longer than the staleness threshold. If the day was quiet, say that plainly in a line or two.\n\nThen record in your routine memory anything durable you learned about how this person works.\n\nDELIVERY: send it with send_telegram. A routine's own output is only written to the log — if you do not call the tool, {{owner_name}} receives nothing at all. Send exactly one message, then stop; do not end the turn by asking whether to keep looking.",
+    "anchor": true
+  },
+  "allowed_tools": [
+    "send_telegram"
+  ]
 }

package/src/core/profiles/bundled/secretary/routines/day-open.json

@@ -2,9 +2,13 @@
   "name": "day-open",
   "kind": "super_agent",
   "schedule": "{{day_open_schedule}}",
-  "permission_mode": "automatico",
+  "permission_mode": "permiso",
   "enabled_by_default": true,
   "spec": {
-    "prompt": "Open the day. Across every registered project, look at what is due today, what is overdue, what is blocked, and any commitment coming due. Then send ONE short message: what is due today, anything on the calendar, and the single thing that most deserves attention. Not an inventory. If there is genuinely nothing pressing, say so in one line rather than padding it. Pass the four gates in your channel guidance before sending anything beyond this anchor."
-  }
+    "prompt": "Open the day. Look at what is due today, what is overdue, what is blocked, and what is promised, across every registered project. Call list_tasks and list_commitments ONCE each, with no project argument — both search every project in a single call. Do not loop over projects. Lead with promises: a broken promise costs more than a late task, so it goes first and is named as a promise to a person, never folded into the task list.\n\nThen send ONE short message: promises coming due or already past, what is due today, anything on the calendar, and the single thing that most deserves attention. Not an inventory.\n\nIf there is genuinely nothing pressing, say so in one line — and then do the thing a chief of staff does with an empty morning: ask what should go on today's list, or name the one stale project worth picking up. An empty day is a prompt, not a silence.\n\nDELIVERY: send it with send_telegram. A routine's own output is only written to the log — if you do not call the tool, {{owner_name}} receives nothing at all. Send exactly one message, then stop; do not end the turn by asking whether to keep looking.",
+    "anchor": true
+  },
+  "allowed_tools": [
+    "send_telegram"
+  ]
 }

package/src/core/profiles/bundled/secretary/routines/watch.json

@@ -0,0 +1,13 @@
+{
+  "name": "watch",
+  "kind": "watch",
+  "schedule": "{{watch_schedule}}",
+  "permission_mode": "permiso",
+  "enabled_by_default": true,
+  "spec": {
+    "prompt": "You are watching {{owner_name}}'s projects between the anchors. The signals below were detected deterministically — they are facts, already gathered; you do not need to look them up again.\n\nDecide whether any of it is worth interrupting for RIGHT NOW rather than waiting for the next anchor. Staying quiet is the normal outcome and costs you nothing. A message that could have waited until tomorrow morning costs you the next one, because that is the one they will not open.\n\nIf you do speak: send ONE line naming the single most important thing and what you suggest doing about it, with send_telegram. DELIVERY: send it with send_telegram. A routine's own output is only written to the log — if you do not call the tool, {{owner_name}} receives nothing at all. If you decide to stay quiet, just say so in your reply and call nothing."
+  },
+  "allowed_tools": [
+    "send_telegram"
+  ]
+}

package/src/core/profiles/lifecycle.js

@@ -23,9 +23,7 @@ import {
 } from "../stores/routines.js";
 
 import {
-  PROFILES_DIR,
   MANIFEST_FILE,
-  CONFIG_SCHEMA_FILE,
   PROFILE_ID_RE,
   userProfileDir,
 } from "./paths.js";

package/src/core/profiles/store.js

@@ -29,14 +29,9 @@ import {
   promptFileFor,
 } from "./paths.js";
 import { schemaDefaults } from "./manifest.js";
+import { readJson } from "#core/util/json-file.js";
+
 
-function readJson(file) {
-  try {
-    return JSON.parse(fs.readFileSync(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
 
 function readDirIds(dir) {
   if (!fs.existsSync(dir)) return [];

package/src/core/routines/runner.js

@@ -1,8 +1,8 @@
 // Routine execution — the domain logic any caller can invoke (daemon
-// scheduler, CLI `apx routine run`, HTTP `/projects/:pid/routines/:name/run`,
+// scheduler, CLI `apx routine run`, HTTP `/api/projects/:pid/routines/:name/run`,
 // MCP server, future scripts). The runner orchestrates a 3-phase pipeline:
 //   1. pre_commands  (shell)
-//   2. handler       (heartbeat / exec_agent / super_agent / telegram / shell)
+//   2. handler       (heartbeat / exec_agent / super_agent / telegram / shell / watch)
 //   3. post_commands (shell)
 //
 // `runRoutineNow(ctx, routine)` is the single entry point. Pass a ctx with at
@@ -16,6 +16,7 @@ import path from "node:path";
 import { callEngine } from "#core/engines/index.js";
 import { runSuperAgent } from "#core/agent/super-agent.js";
 import { computeSuppressedTools } from "#core/agent/index.js";
+import { summarizeToolTrace } from "#core/agent/tool-summary.js";
 import { readAgents } from "#core/apc/parser.js";
 import { buildAgentSystem } from "#core/agent/build-agent-system.js";
 import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
@@ -26,6 +27,8 @@ import {
   routineMemoryPath,
 } from "#core/stores/routine-memory.js";
 import { CHANNELS } from "#core/constants/channels.js";
+import { detectSignals, formatSignals, peakSeverity, thresholdsFromConfig } from "#core/routines/signals.js";
+import { readActiveProfile, effectiveProfileConfig } from "#core/profiles/store.js";
 import {
   updateRunState,
   parseSchedule,
@@ -87,7 +90,7 @@ async function handleExecAgent(ctx, routine) {
   return { status: "ok", reply: result.text };
 }
 
-async function handleSuperAgent(ctx, routine) {
+async function handleSuperAgent(ctx, routine, extraChannelMeta = {}) {
   const { project, globalConfig, projects, plugins, registries } = ctx;
   const { prompt } = routine.spec;
   if (!prompt) throw new Error("super_agent: spec needs { prompt }");
@@ -133,6 +136,11 @@ async function handleSuperAgent(ctx, routine) {
         } catch { return ""; }
       })(),
       projectPath: project.path,
+      // An ANCHOR is a message the user put on the clock themselves. The
+      // interruption budget exempts it from the daily ceiling — the profile
+      // schema calls that number "the ceiling outside the anchors".
+      ...(routine.spec?.anchor === true ? { scheduledByUser: true } : {}),
+      ...extraChannelMeta,
     },
     suppressTools: suppressTools.length > 0 ? suppressTools : null,
   });
@@ -145,7 +153,13 @@ async function handleSuperAgent(ctx, routine) {
     actor_kind: "superagent",
     author: result.name || resolveAgentName(globalConfig),
     body: result.text || "",
-    meta: { routine: routine.name, tool_trace: result.trace, usage: result.usage },
+    meta: {
+      routine: routine.name,
+      tool_trace: result.trace,
+      // Compact form too: the viewer renders this without parsing the trace.
+      ...(summarizeToolTrace(result.trace) ? { tool_summary: summarizeToolTrace(result.trace) } : {}),
+      usage: result.usage,
+    },
   });
   return { status: "ok", reply: result.text, trace: result.trace };
 }
@@ -186,12 +200,97 @@ function handleShell(ctx, routine) {
   });
 }
 
+/**
+ * watch — deterministic detection first, model second.
+ *
+ * THE WHOLE POINT: when nothing is happening this returns before any model is
+ * touched. That is what makes it affordable to run every few minutes, and it
+ * is the difference between a watcher and a cron job with a language model
+ * bolted on. `tests/signals.test.js` asserts the no-signal path never reaches
+ * runSuperAgent, because this property is invisible until the bill arrives.
+ *
+ * spec: { prompt, types?, thresholds?, projects? }
+ */
+async function handleWatch(ctx, routine) {
+  const { projects, globalConfig } = ctx;
+  const { prompt, types, thresholds } = routine.spec || {};
+  if (!prompt) throw new Error("watch: spec needs { prompt } for the judgement step");
+
+  // Thresholds come from the active profile — "stale after 7 days" is a
+  // judgement about how someone works, not a constant — with the routine able
+  // to override for its own narrower purpose.
+  let profileConfig = {};
+  try {
+    const active = readActiveProfile(globalConfig);
+    if (active) profileConfig = effectiveProfileConfig(active, globalConfig) || {};
+  } catch { /* a broken profile must not take the watcher down */ }
+
+  const entries = [];
+  for (const entry of projects?.list?.() || []) {
+    const p = projects.get(entry.id);
+    if (!p?.storagePath) continue;
+    entries.push({
+      id: entry.id,
+      name: entry.name || entry.path,
+      path: entry.path,
+      storagePath: p.storagePath,
+    });
+  }
+
+  const { signals, skipped } = detectSignals(entries, {
+    ...thresholdsFromConfig(profileConfig),
+    ...(thresholds && typeof thresholds === "object" ? thresholds : {}),
+    types: Array.isArray(types) ? types : [],
+  });
+
+  if (!signals.length) {
+    // Terminates here. No model, no tokens, nothing sent.
+    return {
+      status: "ok",
+      signals: 0,
+      note: "no signals — did not invoke the model",
+      ...(skipped.length ? { skipped } : {}),
+    };
+  }
+
+  const enriched = {
+    ...routine,
+    spec: {
+      ...routine.spec,
+      prompt:
+        `${prompt}\n\n` +
+        `Signals detected (${signals.length}), highest severity ${peakSeverity(signals)}:\n` +
+        `${formatSignals(signals)}\n\n` +
+        "These were found deterministically — they are facts, not guesses. Your job is " +
+        "judgement: decide whether any of it is worth interrupting for right now, and if " +
+        "so say the one thing that matters. Staying quiet is a valid outcome.",
+    },
+  };
+
+  // Severity travels with the run so the interruption budget can be told how
+  // bad this is by a DETECTOR rather than by the model's own opinion of its
+  // news. A model that can grade its own message as critical has a shouting
+  // backdoor; a deterministic overdue commitment does not.
+  const result = await handleSuperAgent(ctx, enriched, {
+    signalSeverity: peakSeverity(signals),
+    signalCount: signals.length,
+  });
+  return {
+    ...result,
+    signals: signals.length,
+    peak_severity: peakSeverity(signals),
+    signal_types: [...new Set(signals.map((s) => s.type))],
+    ...(skipped.length ? { skipped } : {}),
+  };
+}
+
 const HANDLERS = {
   heartbeat: handleHeartbeat,
   exec_agent: handleExecAgent,
   super_agent: handleSuperAgent,
   telegram: handleTelegram,
   shell: handleShell,
+  watch: handleWatch,
 };
 
 // --------------------- pipeline: pre/post shell commands --------------------