@agentprojectcontext/apx 1.78.0 → 1.79.0

package/src/core/routines/signals.js

@@ -0,0 +1,270 @@
+// Signals — deterministic detection of things worth noticing.
+//
+// THE SPLIT THIS FILE EXISTS FOR: detection is cheap and mechanical; judgement
+// is expensive and contextual. Mixing them means paying a language model every
+// five minutes to conclude that nothing is happening. Everything here is a
+// pure function over stored state — no model, no network, no clock beyond the
+// `now` you pass in — so a watch routine that finds nothing costs nothing, and
+// every rule below is testable with synthetic state.
+//
+// Thresholds are PARAMETERS, never constants. "Stale after 7 days" is a
+// judgement about how someone works, and judgements belong to the profile.
+//
+// A signal is:
+//   { type, project_id, project_name, severity, subject, detected_at, payload }
+//
+// `subject` is a one-line human phrasing — the detector already knows exactly
+// what it found, and making the model re-derive it from payload fields is how
+// summaries drift from the data they claim to describe.
+import { listTasks } from "#core/stores/tasks.js";
+import { listCommitments } from "#core/stores/commitments.js";
+import { nowIso } from "#core/util/time.js";
+
+/** Every detector, keyed by the type it emits. */
+export const SIGNAL_TYPES = Object.freeze([
+  "overdue_task",
+  "blocked_task",
+  "stale_project",
+  "commitment_due",
+  "overdue_commitment",
+]);
+
+/** Defaults chosen to be quiet. A watcher that cries on day one gets turned off. */
+export const DEFAULT_THRESHOLDS = Object.freeze({
+  blocked_hours: 48,
+  stale_project_days: 7,
+  commitment_lead_hours: 48,
+  /** Detectors to run. Empty = all of them. */
+  types: [],
+});
+
+// ---------------------------------------------------------------------------
+// detectors — each takes (project, opts) and returns Signal[]
+// ---------------------------------------------------------------------------
+
+/** A task whose due date has passed and which nobody closed. */
+function detectOverdueTasks(project, { now }) {
+  const today = now.slice(0, 10);
+  return listTasks(project.storagePath, { state: "open" })
+    .filter((t) => t.due && t.due < today)
+    .map((t) =>
+      signal(project, {
+        type: "overdue_task",
+        // A task one day late and one three weeks late are not the same event.
+        severity: daysBetween(t.due, today) >= 7 ? "high" : "normal",
+        subject: `"${t.title}" was due ${t.due}`,
+        payload: { task_id: t.id, title: t.title, due: t.due, days_late: daysBetween(t.due, today) },
+      }),
+    );
+}
+
+/**
+ * A task sitting in `blocked` long enough that nobody is coming back to it.
+ *
+ * Uses updated_at, not created_at: a task blocked this morning is a normal
+ * working state, and flagging it would train the user to ignore the watcher.
+ */
+function detectBlockedTasks(project, { now, blocked_hours }) {
+  const cutoff = new Date(Date.parse(now) - blocked_hours * 3_600_000).toISOString();
+  return listTasks(project.storagePath, { state: "open", status: "blocked" })
+    .filter((t) => (t.updated_at || t.created_at || "") < cutoff)
+    .map((t) =>
+      signal(project, {
+        type: "blocked_task",
+        severity: "normal",
+        subject: `"${t.title}" has been blocked since ${(t.updated_at || t.created_at || "").slice(0, 10)}`,
+        payload: { task_id: t.id, title: t.title, since: t.updated_at || t.created_at },
+      }),
+    );
+}
+
+/**
+ * A project nobody has touched.
+ *
+ * WHAT "ACTIVITY" MEANS HERE: the newest task or commitment event in the
+ * project's store. APX has no single per-project activity timestamp, and
+ * folding every conversation on a five-minute tick would defeat the point of a
+ * cheap detector. So this measures what it can actually see, and the phrasing
+ * says so — "no task or commitment activity", not "nothing happened". A caller
+ * with a better timestamp can pass `last_activity_at` and it wins.
+ *
+ * Claiming more than the data supports is the failure mode that kills trust in
+ * a watcher: one confident "you have abandoned this" about a project the user
+ * worked on all week, and they stop believing the rest.
+ *
+ * Deliberately ONE signal per project rather than per silent item — the point
+ * is "you have forgotten about this", and saying it once is the whole message.
+ *
+ * A project with nothing recorded at all is skipped: a freshly registered
+ * project is not neglected, and greeting someone with "this is stale" the day
+ * they add it is exactly what gets a watcher muted.
+ */
+function detectStaleProject(project, { now, stale_project_days }) {
+  const last = project.last_activity_at || lastRecordedActivity(project.storagePath);
+  if (!last) return [];
+  const days = daysBetween(last.slice(0, 10), now.slice(0, 10));
+  if (days < stale_project_days) return [];
+  const measured = project.last_activity_at ? "activity" : "task or commitment activity";
+  return [
+    signal(project, {
+      type: "stale_project",
+      severity: days >= stale_project_days * 3 ? "normal" : "low",
+      subject: `no ${measured} on ${project.name || project.path || "this project"} for ${days} days`,
+      payload: { days, last_activity_at: last, measured },
+    }),
+  ];
+}
+
+/** Newest task or commitment timestamp in a project store, or "" when empty. */
+function lastRecordedActivity(storagePath) {
+  let newest = "";
+  const bump = (v) => { if (v && v > newest) newest = v; };
+  try {
+    for (const t of listTasks(storagePath, { state: "all" })) bump(t.updated_at || t.created_at);
+  } catch { /* unreadable → treated as no evidence, not as staleness */ }
+  try {
+    for (const c of listCommitments(storagePath, { state: "all" })) bump(c.updated_at || c.created_at);
+  } catch { /* same */ }
+  return newest;
+}
+
+/** A promise coming due inside the lead window — still time to keep it. */
+function detectCommitmentsDue(project, { now, commitment_lead_hours }) {
+  const horizon = new Date(Date.parse(now) + commitment_lead_hours * 3_600_000).toISOString();
+  return listCommitments(project.storagePath, { state: "open" })
+    .filter((c) => c.due && c.due >= now && c.due <= horizon)
+    .map((c) =>
+      signal(project, {
+        type: "commitment_due",
+        // Higher than an equivalent task on purpose: someone is waiting, and a
+        // warning that arrives in time is worth more than one that arrives after.
+        severity: "high",
+        subject: `you promised ${c.counterparty}: ${c.body} — due ${c.due.slice(0, 10)}`,
+        payload: { commitment_id: c.id, counterparty: c.counterparty, due: c.due, body: c.body },
+      }),
+    );
+}
+
+/** A promise already past its date and still open. The costliest thing here. */
+function detectOverdueCommitments(project, { now }) {
+  return listCommitments(project.storagePath, { state: "open", overdue: true, now })
+    .map((c) =>
+      signal(project, {
+        type: "overdue_commitment",
+        severity: "critical",
+        subject: `you owe ${c.counterparty}: ${c.body} — was due ${c.due.slice(0, 10)}`,
+        payload: {
+          commitment_id: c.id, counterparty: c.counterparty, due: c.due, body: c.body,
+          days_late: daysBetween(c.due.slice(0, 10), now.slice(0, 10)),
+        },
+      }),
+    );
+}
+
+const DETECTORS = {
+  overdue_task: detectOverdueTasks,
+  blocked_task: detectBlockedTasks,
+  stale_project: detectStaleProject,
+  commitment_due: detectCommitmentsDue,
+  overdue_commitment: detectOverdueCommitments,
+};
+
+// ---------------------------------------------------------------------------
+// public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the configured detectors over the given projects.
+ *
+ * @param {{id, name?, path?, storagePath, last_activity_at?}[]} projects
+ * @param {object} opts  thresholds + `types` + `now` (ISO, injectable for tests)
+ * @returns {{ signals: object[], skipped: {id, error}[] }}
+ */
+export function detectSignals(projects, opts = {}) {
+  const cfg = { ...DEFAULT_THRESHOLDS, ...opts, now: opts.now || nowIso() };
+  const wanted = Array.isArray(cfg.types) && cfg.types.length
+    ? cfg.types.filter((t) => t in DETECTORS)
+    : SIGNAL_TYPES;
+
+  const signals = [];
+  const skipped = [];
+
+  for (const project of projects || []) {
+    if (!project?.storagePath) continue;
+    for (const type of wanted) {
+      try {
+        signals.push(...DETECTORS[type](project, cfg));
+      } catch (e) {
+        // One unreadable log must not blank the whole sweep — and must not be
+        // silent either, or the watcher reports "all clear" when it is blind.
+        skipped.push({ id: project.id, type, error: e?.message || String(e) });
+      }
+    }
+  }
+
+  signals.sort(bySeverityThenDate);
+  return { signals, skipped };
+}
+
+const SEVERITY_RANK = { critical: 0, high: 1, normal: 2, low: 3 };
+
+function bySeverityThenDate(a, b) {
+  const s = (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9);
+  if (s !== 0) return s;
+  return String(a.subject).localeCompare(String(b.subject));
+}
+
+/**
+ * Render signals as the block a routine hands the model.
+ *
+ * Pre-rendered rather than passed as JSON because the model's job here is
+ * judgement — "is any of this worth interrupting for?" — not parsing.
+ */
+export function formatSignals(signals) {
+  if (!signals?.length) return "";
+  const lines = signals.map(
+    (s) => `- [${s.severity}] ${s.project_name ? `${s.project_name}: ` : ""}${s.subject}`,
+  );
+  return lines.join("\n");
+}
+
+/** The highest severity present, for the interruption budget. */
+export function peakSeverity(signals) {
+  let best = "low";
+  for (const s of signals || []) {
+    if ((SEVERITY_RANK[s.severity] ?? 9) < (SEVERITY_RANK[best] ?? 9)) best = s.severity;
+  }
+  return signals?.length ? best : "low";
+}
+
+/** Thresholds from a profile's config, falling back to the defaults. */
+export function thresholdsFromConfig(profileConfig = {}) {
+  const pick = (key, fallback) => {
+    const v = Number.parseInt(profileConfig[key], 10);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+  };
+  return {
+    blocked_hours: pick("blocked_task_hours", DEFAULT_THRESHOLDS.blocked_hours),
+    stale_project_days: pick("stale_project_days", DEFAULT_THRESHOLDS.stale_project_days),
+    commitment_lead_hours: pick("commitment_lead_hours", DEFAULT_THRESHOLDS.commitment_lead_hours),
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+function signal(project, fields) {
+  return {
+    project_id: project.id ?? null,
+    project_name: project.name || project.path || "",
+    detected_at: nowIso(),
+    ...fields,
+  };
+}
+
+/** Whole days between two YYYY-MM-DD strings. Negative when `to` precedes `from`. */
+function daysBetween(from, to) {
+  const a = Date.parse(`${String(from).slice(0, 10)}T00:00:00Z`);
+  const b = Date.parse(`${String(to).slice(0, 10)}T00:00:00Z`);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return 0;
+  return Math.round((b - a) / 86_400_000);
+}

package/src/core/stores/commitments.js

@@ -0,0 +1,331 @@
+// Commitments per project.
+//
+// Append-only JSONL event log, one file per month under
+//   ~/.apx/projects/<apxId>/commitments/YYYY-MM.jsonl
+//
+// A TASK is something to do. A COMMITMENT is something PROMISED TO A PERSON:
+// it has a counterparty, a date you gave them, and the channel you said it on.
+// Breaking one costs trust, not just throughput, and that is why it is a type
+// and not a tag.
+//
+// The tag version is tempting and wrong. The day you want "everything I owe
+// Ana" you would be substring-matching your way through task titles, and
+// "kept" versus "renegotiated" — the distinction that tells you whether a
+// relationship is fine — has nowhere to live at all.
+//
+// Events:
+//   create        — the promise (counterparty, body, due, origin_channel, …)
+//   update        — shallow-merge patch
+//   kept          — delivered
+//   missed        — the date passed without delivery. Recorded, not hidden:
+//                   a system that quietly drops what you failed to do cannot
+//                   tell you that you keep failing the same person.
+//   renegotiate   — a NEW date, agreed with them. Distinct from missing:
+//                   moving a date with someone is not the same as letting it
+//                   slide, and the history keeps both.
+//
+// State: "open" → "kept" | "missed" | "renegotiated" → (renegotiated reopens
+// as "open" with a new due, keeping the previous date in `history`).
+import fs from "node:fs";
+import path from "node:path";
+import { nowIso } from "../util/time.js";
+import { shortId as makeShortId } from "../util/ids.js";
+
+export const COMMITMENT_STATES = Object.freeze(["open", "kept", "missed", "renegotiated"]);
+
+function commitmentsDir(storagePath) {
+  return path.join(storagePath, "commitments");
+}
+
+function monthlyFile(storagePath, date = new Date()) {
+  const ym = date.toISOString().slice(0, 7); // YYYY-MM
+  return path.join(commitmentsDir(storagePath), `${ym}.jsonl`);
+}
+
+function shortId() {
+  return makeShortId("c");
+}
+
+function appendEvent(storagePath, event) {
+  const file = monthlyFile(storagePath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(event) + "\n");
+}
+
+function readAllEvents(storagePath) {
+  const dir = commitmentsDir(storagePath);
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort();
+  const events = [];
+  for (const f of files) {
+    const text = fs.readFileSync(path.join(dir, f), "utf8");
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const ev = JSON.parse(line);
+        if (ev && ev.id && ev.op) events.push(ev);
+      } catch {
+        // One bad write must not blank the projection.
+      }
+    }
+  }
+  events.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+  return events;
+}
+
+function projectState(events) {
+  const rows = new Map();
+  for (const ev of events) {
+    const existing = rows.get(ev.id);
+    switch (ev.op) {
+      case "create": {
+        if (existing) break; // duplicate create — keep the first
+        rows.set(ev.id, {
+          id: ev.id,
+          created_at: ev.ts,
+          updated_at: ev.ts,
+          state: "open",
+          counterparty: ev.counterparty || "",
+          body: ev.body || "",
+          promised_at: ev.promised_at || ev.ts,
+          due: ev.due || null,
+          origin_channel: ev.origin_channel || null,
+          origin_message_ref: ev.origin_message_ref || null,
+          created_by: ev.created_by || null,
+          // Every date this promise has ever had. Renegotiating twice is a
+          // fact about the relationship, and it is only visible if kept.
+          history: [],
+          meta: ev.meta && typeof ev.meta === "object" ? { ...ev.meta } : {},
+        });
+        break;
+      }
+      case "update": {
+        if (!existing) break;
+        const patch = ev.patch && typeof ev.patch === "object" ? ev.patch : {};
+        for (const k of Object.keys(patch)) {
+          if (k === "id" || k === "state" || k === "created_at" || k === "history") continue;
+          existing[k] = patch[k];
+        }
+        existing.updated_at = ev.ts;
+        break;
+      }
+      case "kept": {
+        if (!existing) break;
+        existing.state = "kept";
+        existing.closed_at = ev.ts;
+        existing.note = ev.note || existing.note || null;
+        existing.updated_at = ev.ts;
+        break;
+      }
+      case "missed": {
+        if (!existing) break;
+        existing.state = "missed";
+        existing.closed_at = ev.ts;
+        existing.note = ev.note || existing.note || null;
+        existing.updated_at = ev.ts;
+        break;
+      }
+      case "renegotiate": {
+        if (!existing) break;
+        existing.history.push({
+          due: existing.due,
+          moved_at: ev.ts,
+          note: ev.note || null,
+        });
+        existing.due = ev.due || existing.due;
+        // Back to open: a renegotiated promise is a live promise with a new
+        // date, not a closed one. "renegotiated" as a resting state would hide
+        // it from every "what do I owe people" view.
+        existing.state = "open";
+        existing.renegotiated_count = (existing.renegotiated_count || 0) + 1;
+        existing.updated_at = ev.ts;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return rows;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Record a promise.
+ * fields: { counterparty (required), body (required), due?, promised_at?,
+ *           origin_channel?, origin_message_ref?, created_by?, meta? }
+ */
+export function createCommitment(storagePath, fields) {
+  if (!fields || typeof fields !== "object") throw new Error("createCommitment: fields required");
+  if (!fields.counterparty || typeof fields.counterparty !== "string") {
+    // The counterparty IS the type. Without it this is a task.
+    throw new Error("createCommitment: counterparty required");
+  }
+  if (!fields.body || typeof fields.body !== "string") {
+    throw new Error("createCommitment: body required");
+  }
+  const id = shortId();
+  appendEvent(storagePath, {
+    id,
+    ts: nowIso(),
+    op: "create",
+    counterparty: fields.counterparty.trim(),
+    body: fields.body.trim(),
+    promised_at: fields.promised_at || nowIso(),
+    due: fields.due || null,
+    origin_channel: fields.origin_channel || null,
+    origin_message_ref: fields.origin_message_ref || null,
+    created_by: fields.created_by || null,
+    meta: fields.meta && typeof fields.meta === "object" ? fields.meta : {},
+  });
+  return getCommitment(storagePath, id);
+}
+
+/** Newest first, id as tiebreak — same reasoning as tasks.js byNewest. */
+function byNewest(a, b) {
+  const t = (b.created_at || "").localeCompare(a.created_at || "");
+  return t !== 0 ? t : String(b.id || "").localeCompare(String(a.id || ""));
+}
+
+/** Soonest deadline first; undated last. The order the anchors want. */
+function byDue(a, b) {
+  if (!a.due && !b.due) return byNewest(a, b);
+  if (!a.due) return 1;
+  if (!b.due) return -1;
+  const d = a.due.localeCompare(b.due);
+  return d !== 0 ? d : byNewest(a, b);
+}
+
+/**
+ * List commitments.
+ *
+ * opts: { state, counterparty, due_before, due_after, overdue, updated_since,
+ *         sort: "due"|"newest", limit }
+ * Default state is "open" — the useful question is what you still owe.
+ */
+export function listCommitments(storagePath, opts = {}) {
+  let out = [...projectState(readAllEvents(storagePath)).values()];
+
+  if (opts.state && opts.state !== "all") {
+    out = out.filter((c) => c.state === opts.state);
+  } else if (!opts.state) {
+    out = out.filter((c) => c.state === "open");
+  }
+  if (opts.counterparty) {
+    // Case-insensitive substring: counterparty is free text, not a CRM key,
+    // so "ana" must find "Ana Pérez" or the field is unusable.
+    const needle = String(opts.counterparty).toLowerCase();
+    out = out.filter((c) => String(c.counterparty).toLowerCase().includes(needle));
+  }
+  if (opts.due_before) out = out.filter((c) => c.due && c.due <= opts.due_before);
+  if (opts.due_after) out = out.filter((c) => c.due && c.due >= opts.due_after);
+  if (opts.overdue) {
+    const now = opts.now || nowIso();
+    out = out.filter((c) => c.state === "open" && c.due && c.due < now);
+  }
+  if (opts.updated_since) {
+    out = out.filter((c) => (c.updated_at || c.created_at || "") >= opts.updated_since);
+  }
+
+  out.sort(opts.sort === "newest" ? byNewest : byDue);
+  if (opts.limit && Number.isFinite(opts.limit)) out = out.slice(0, opts.limit);
+  return out;
+}
+
+/**
+ * The same query folded across registered projects. Mirrors
+ * listTasksAcrossProjects — a chief of staff lives in the cross-project layer,
+ * and a promise made in a meeting rarely knows which repo it belongs to.
+ *
+ * A project whose log is unreadable is SKIPPED, not fatal.
+ */
+export function listCommitmentsAcrossProjects(projects, opts = {}) {
+  const { limit, ...perProject } = opts || {};
+  const commitments = [];
+  const skipped = [];
+
+  for (const entry of projects || []) {
+    if (!entry?.storagePath) continue;
+    try {
+      for (const c of listCommitments(entry.storagePath, perProject)) {
+        commitments.push({
+          ...c,
+          project_id: entry.id,
+          project_name: entry.name || entry.path || String(entry.id),
+        });
+      }
+    } catch (e) {
+      skipped.push({ id: entry.id, error: e?.message || String(e) });
+    }
+  }
+
+  commitments.sort(opts.sort === "newest" ? byNewest : byDue);
+  return {
+    commitments: Number.isFinite(limit) && limit > 0 ? commitments.slice(0, limit) : commitments,
+    skipped,
+  };
+}
+
+/** Get one by id or unique id prefix (≥ 3 chars). */
+export function getCommitment(storagePath, idOrPrefix) {
+  if (!idOrPrefix || typeof idOrPrefix !== "string") return null;
+  const rows = projectState(readAllEvents(storagePath));
+  if (rows.has(idOrPrefix)) return rows.get(idOrPrefix);
+  if (idOrPrefix.length < 3) return null;
+  const matches = [...rows.values()].filter((c) => c.id.startsWith(idOrPrefix));
+  return matches.length === 1 ? matches[0] : null;
+}
+
+export function patchCommitment(storagePath, idOrPrefix, patch) {
+  const existing = getCommitment(storagePath, idOrPrefix);
+  if (!existing) return null;
+  if (!patch || typeof patch !== "object") return existing;
+  appendEvent(storagePath, { id: existing.id, ts: nowIso(), op: "update", patch });
+  return getCommitment(storagePath, existing.id);
+}
+
+/** Delivered. */
+export function keepCommitment(storagePath, idOrPrefix, note = null) {
+  return close(storagePath, idOrPrefix, "kept", note);
+}
+
+/** The date passed and it did not happen. */
+export function missCommitment(storagePath, idOrPrefix, note = null) {
+  return close(storagePath, idOrPrefix, "missed", note);
+}
+
+function close(storagePath, idOrPrefix, op, note) {
+  const existing = getCommitment(storagePath, idOrPrefix);
+  if (!existing) return null;
+  appendEvent(storagePath, { id: existing.id, ts: nowIso(), op, note: note || null });
+  return getCommitment(storagePath, existing.id);
+}
+
+/**
+ * A new date, agreed with them. Requires the new date: "renegotiated, no idea
+ * until when" is how a promise disappears.
+ */
+export function renegotiateCommitment(storagePath, idOrPrefix, due, note = null) {
+  if (!due) throw new Error("renegotiateCommitment: a new due date is required");
+  const existing = getCommitment(storagePath, idOrPrefix);
+  if (!existing) return null;
+  appendEvent(storagePath, {
+    id: existing.id, ts: nowIso(), op: "renegotiate", due, note: note || null,
+  });
+  return getCommitment(storagePath, existing.id);
+}
+
+/** Counts for status displays and anchors. */
+export function countCommitments(storagePath, now = nowIso()) {
+  const rows = [...projectState(readAllEvents(storagePath)).values()];
+  const open = rows.filter((c) => c.state === "open");
+  return {
+    open: open.length,
+    kept: rows.filter((c) => c.state === "kept").length,
+    missed: rows.filter((c) => c.state === "missed").length,
+    overdue: open.filter((c) => c.due && c.due < now).length,
+    total: rows.length,
+  };
+}

package/src/core/stores/messages.js

@@ -684,6 +684,10 @@ export function readGlobalThread({ channel, date, _globalMessagesDir } = {}) {
         ...(r.actor_kind ? { actor_kind: r.actor_kind } : {}),
         ...(r.meta?.model ? { model: r.meta.model } : {}),
         ...(usage && typeof usage === "object" ? { usage } : {}),
+        // What the turn actually did. Recorded compactly at write time
+        // (core/agent/tool-summary.js) because the live tool events are gone
+        // by the time anyone reads the thread back.
+        ...(r.meta?.tool_summary ? { tool_summary: r.meta.tool_summary } : {}),
       };
     });
   return { id: date, channel, messages };

package/src/core/stores/routines.js

@@ -27,6 +27,17 @@ function writeFile(projectPath, routines) {
 
 export function parseSchedule(s, baseMs = Date.now()) {
   if (!s || typeof s !== "string") return { kind: "invalid" };
+
+  // "manual" — runs only when someone runs it. It USED to work by accident:
+  // the string failed cron parsing, came back "invalid", and an invalid
+  // schedule never becomes due. Correct outcome, wrong reason, and it meant
+  // every surface reported a deliberate choice as a broken expression.
+  if (s.trim().toLowerCase() === "manual") return { kind: "manual" };
+
+  // Tolerate a leading "cron " label. The web editor's own presets wrote
+  // `cron 0 9 * * *`, which cron-parser rejects — so picking "daily at 9am"
+  // in the panel produced a routine that never ran, with nothing to show why.
+  const labelled = s.trim().replace(/^cron\s+/i, "");
   
   if (s.startsWith("every:")) {
     const spec = s.slice(6).trim();
@@ -46,7 +57,7 @@ export function parseSchedule(s, baseMs = Date.now()) {
 
   // Fallback: Try parsing as standard cron expression using cron-parser
   try {
-    const interval = CronExpressionParser.parse(s, { currentDate: new Date(baseMs) });
+    const interval = CronExpressionParser.parse(labelled, { currentDate: new Date(baseMs) });
     return { kind: "cron", parser: interval };
   } catch (err) {
     return { kind: "invalid" };
@@ -55,7 +66,7 @@ export function parseSchedule(s, baseMs = Date.now()) {
 
 export function computeNextRun(routine, baseMs = Date.now()) {
   const sched = parseSchedule(routine.schedule, baseMs);
-  if (sched.kind === "invalid") return null;
+  if (sched.kind === "invalid" || sched.kind === "manual") return null;
   if (sched.kind === "once") {
     return sched.atMs > baseMs
       ? new Date(sched.atMs).toISOString().replace(/\.\d{3}Z$/, "Z")
@@ -227,7 +238,10 @@ export function getDueRoutines(projectPath, nowStr) {
     // CRITICAL: If the schedule cannot be parsed, NEVER run it.
     // Otherwise, an invalid schedule (like a cron string) sets next_run_at to null,
     // which previously caused it to be considered ALWAYS due and spam execution every 5 seconds!
-    if (parseSchedule(r.schedule).kind === "invalid") return false;
+    const kind = parseSchedule(r.schedule).kind;
+    // "manual" is a deliberate never-on-a-clock, not a broken expression —
+    // both are skipped here, but only one of them is a problem to report.
+    if (kind === "invalid" || kind === "manual") return false;
     return (!r.next_run_at || r.next_run_at <= nowStr);
   });
 }