@inetafrica/open-claudia 3.4.23 → 3.5.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 3.5.0
+
+Security fixes for the permission system: phase 0 of the redesign in the owner's 25 Sep review. The owner's own chat turns work as before. Staff and external turns lose the ways around the checks. First shipped as a canary on two bots.
+
+- **Who a process acts for is now decided by the running bot.** The runner registers every run with the person it acts for, resolved from the inbound message, and stamps an attestation bound to that run. Tools, the keyring, notes and scheduling ask the bot through the loopback's new `whoami`. The following are all *unattributed*, and unattributed is never the owner:
+  - a shell that unsets or rewrites its environment;
+  - a process that outlives its turn;
+  - anything started outside a chat turn.
+  Before this release, the CLIs read the speaker from `OC_CHANNEL_*` variables that the agent's own shell could change, and an unset speaker counted as the owner.
+- **Staff turns never see the AI service credentials.** Non-owner runs set `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1`.
+- **A staff write or destructive tool run is decided inside the bot.** The mandate check runs there. If the owner must approve, the bot posts the card itself. Requests raised from inside a tool used to die with "could not post to owner" or "no reachable owner" (18 dropped fleet-wide in 14 days).
+- **A verb that a tool's manifest does not declare is refused for everyone,** and the refusal lists the declared verbs. Before, a staff turn's undeclared verb was classed as a write and sent to the owner.
+- **An owner approval carries exactly the tier approved.** Redeeming any token used to export "destructive", so approving a write unlocked destructive for that run.
+- **Changing tools, notes, the keyring and sub-agents is owner-only:**
+  - tool add, set, edit, note, remove and lib;
+  - entity, pack, lessons and ideas writes;
+  - every keyring verb, including `list`;
+  - `open-claudia agent`.
+  From a plain terminal, these now need an owner approval token.
+- **Follow-ups set in a staff turn run at that person's level, in that room.** This covers wakeups, crons and watches. The job's creator is the attested run. Before, it came from fields the run's own shell could forge, with a fallback to the owner. Watch checks run without the bot's secrets, as their creator.
+- **People notes and tasks are owner-only through the bot's commands.**
+- **History stays in the caller's room.** For a non-owner, `recent`, `transcript-search` and `transcript-window` return only the caller's room. `recent-fetch`'s channel filter, which matched nothing, is fixed.
+- **File reads are screened on staff turns.**
+  - Read, Grep, Glob, NotebookRead and LS cannot reach:
+    - the bot's config (keyring, transcripts, approvals, people);
+    - Claude and Codex credentials;
+    - SSH, cloud and kube credentials;
+    - other processes' environments.
+  - Paths are resolved through symlinks.
+  - The shell refuses the obvious equivalents.
+  - A permission hook that cannot run now refuses on a staff turn instead of letting the tool through.
+- **Destructive is never a standing permission.**
+  - "Always" on a destructive card is refused.
+  - A destructive grant already on disk counts as act.
+  - Grants for anonymous or unverifiable senders (Telegram anonymous admins, channel posts, the bot itself) are refused.
+  - When an exact-room grant and an all-rooms grant both match, the stronger one applies.
+- **Releases can be canaried.**
+  - A `canary-vX.Y.Z` tag publishes npm under `next` and pushes docker `:X.Y.Z` only.
+  - Pushing `vX.Y.Z` on the same commit later promotes that exact build (`latest`, no rebuild).
+
+## 3.4.24
+
+- A repeating watch keeps polling while its triggered delivery waits for a busy room, waits to retry after a failed or `/stop`-killed run, or runs. A new hit folds into that one pending delivery instead of queueing another, and the delivered prompt says how many more times the check passed and whether its latest run had cleared. On 24 Sep the event-bus watch went unpolled for 7.5 h behind a busy room, and after a killed delivery attempt its polling never resumed. One-shot watches are unchanged, and the 15-minute "⏳ Watch … waiting" line still goes out once per occurrence.
+- A watch whose check times out 3 times in a row now wakes the agent once, marked "Watch check timing out", and keeps polling; any completed check resets the count. A hanging health check used to be logged `idle (check timed out)` and never alarm. The alarm does not use up a one-shot watch.
+- Wakeups more than ~24.8 days out no longer fire at once. `setTimeout` overflows past 2^31-1 ms, which fired a 2028 reminder 61 s after it was set (17 Sep); far wakeups now sleep in chunks and re-plan until due, then fire once. `schedule-wakeup` refuses a `<when>` more than 10 years out, in the CLI and in the loopback route.
+- A queued delivery is no longer stranded when a jobs-store write throws (a full disk, a torn journal). Those paths returned without a retry timer, so the alarm was never tried again; they now keep the retry armed and say so in watch.log. This matches the watch alarms that triggered during long turns on 21 and 23 Sep and were never delivered. A regression test also pins that a delivery queued behind a long turn survives the turn's compaction and runs once at the next idle moment, on the compacted session; that path already worked.
+- `cron-list` and `watch-list` say where a fired job stands (delivery waiting, running, retrying or dead) instead of listing it as still to come. A triggered watch whose delivery was queued read "EXPIRED (fires on next poll)" (21 Sep), and a fired 2028 reminder still read "fires 2028-08-01" (17 Sep).
+- `open-claudia say` and the send-file/voice/photo routes now say which step failed when the channel adapter refuses the upload, instead of a bare `loopback 500: {"ok":false}` (10 Sep). The adapter's own error stays in bot.log.
+- Release gate: `test-provider-pack-review.js` gives each probe child 120 s instead of 30 s and reports a timeout as a timeout rather than "failed (null)" (v3.4.19, job 43703). The parity suite's cap for it rises to 8 minutes so it cannot undercut its children.
+
 ## 3.4.23
 
 - Watch, wakeup and cron turns now stream their progress (interim narration, and thinking under `/verbose`) like chat turns. The live preview was gated to chat turns only, so a watch-woken turn showed the bell notice and "thinking…" and then nothing until its final answer, however long it worked.

package/bin/agent.js

@@ -58,6 +58,10 @@ async function run(args) {
   if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
     console.log(HELP); process.exit(args[0] === "--help" || args[0] === "help" ? 0 : 2);
   }
+  // A sub-agent is an unguarded agent with a shell: only the owner's own run
+  // may start one. Decided by the running bot from the run's attestation
+  // (bin/owner-gate), never from this process's env.
+  if (!(await require("./owner-gate").requireOwner("starting a sub-agent"))) return;
   let parsed;
   try { parsed = parseAgentArgs(args); }
   catch (error) { console.error(error.message); process.exit(2); return; }

package/bin/cli.js

@@ -146,7 +146,16 @@ switch (command) {
       const res = runHook(payload);
       if (res.stderr) console.error(res.stderr);
       code = res.exit;
-    } catch (e) { code = 0; }
+    } catch (e) {
+      // The guard itself failed (it would not load, or stdin was unreadable).
+      // On a non-owner's turn that must not wave the tool through: the runner
+      // marks such runs OC_GUARDED_RUN=1 in the agent's env, which the hook
+      // inherits from Claude Code and the agent's own shell cannot change.
+      if (process.env.OC_GUARDED_RUN === "1") {
+        console.error("⛔ The permission check could not run, so this is refused on a non-owner's turn.");
+        code = 2;
+      } else code = 0;
+    }
     process.exit(code);
     break;
   }

package/bin/entity.js

@@ -6,15 +6,26 @@
 //   open-claudia entity persona <name> [--relationship owner|trusted|external] [--role ..] [--style ..] [--knows ..] [--mandate ..]
 //   open-claudia entity remove <slug-or-name>
 //   open-claudia entity reindex
+//
+// note/persona/remove/reindex change the notes (and persona mandates) the bot
+// acts on: owner-only, decided by the running bot from the run's attestation
+// (bin/owner-gate), never from OC_CHANNEL_* env. list/show/match are reads.
 
 const fs = require("fs");
 const path = require("path");
 const entities = require("../core/entities");
 
-function run(args) {
+const OWNER_ONLY_VERBS = new Set(["note", "persona", "remove", "reindex"]);
+
+async function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 
+  if (OWNER_ONLY_VERBS.has(cmd)) {
+    const what = cmd === "persona" ? "setting a persona/mandate" : `"entity ${cmd}" changes the bot's notes`;
+    if (!(await require("./owner-gate").requireOwner(what))) return;
+  }
+
   switch (cmd) {
     case "list": {
       const all = entities.listEntities();
@@ -73,20 +84,11 @@ function run(args) {
       // is cleared to do/discuss with that person. Each flag replaces its section
       // wholesale; omit a flag to leave it unchanged.
       //
-      // OWNER-ONLY: setting a mandate/relationship is a privilege operation, so
-      // an external speaker must never reach it (self-escalation). No guarded
-      // speaker (owner turn, CLI, or cron) may proceed. Note: relationship
-      // "owner" set here is still coerced to "external" at runtime for a non-
-      // owner person (R1) — a note can never confer owner powers.
-      try {
-        const relationship = require("../core/relationship");
-        const sp = relationship.speakerFor(process.env.OC_CHANNEL_ADAPTER, process.env.OC_CHANNEL_ID, process.env.OC_CHANNEL_USER_ID);
-        if (relationship.guardActive(sp)) {
-          console.error("⛔ Only the owner can set a persona/mandate.");
-          process.exitCode = 3; return;
-        }
-      } catch (e) { /* no context → owner-equivalent, allowed */ }
-
+      // OWNER-ONLY (gated above): setting a mandate/relationship is a privilege
+      // operation, so nobody but the owner may reach it (self-escalation) — a
+      // guarded turn and an unattributed process alike are refused. Note:
+      // relationship "owner" set here is still coerced to "external" at runtime
+      // for a non-owner person (R1) — a note can never confer owner powers.
       const takeFlag = (flag) => {
         const i = rest.indexOf(flag);
         if (i === -1) return null;

package/bin/ideas.js

@@ -4,14 +4,23 @@
 //   open-claudia ideas remove <id|text>            — remove one
 //   open-claudia ideas show                         — raw file
 //   open-claudia ideas path                         — print the file path
+//
+// add/remove change the backlog the nightly dream works from: owner-only,
+// decided by the running bot from the run's attestation (bin/owner-gate).
 
 const fs = require("fs");
 const ideas = require("../core/ideas");
 
-function run(args) {
+const OWNER_ONLY_VERBS = new Set(["add", "remove", "rm"]);
+
+async function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 
+  if (OWNER_ONLY_VERBS.has(cmd)) {
+    if (!(await require("./owner-gate").requireOwner(`"ideas ${cmd}" changes the bot's ideas backlog`))) return;
+  }
+
   switch (cmd) {
     case "list": {
       const all = ideas.listIdeas();

package/bin/keyring.js

@@ -15,29 +15,30 @@
 //
 // For genuine personal secrets the bot should NOT use unattended, use the
 // vault (/vault) instead — it stays encrypted and locked.
+//
+// Owner only, every verb (exec and list included): the caller must be a live
+// run the bot attributes to the owner.
 
 const keyring = require("../core/keyring");
 
-function run(args) {
+async function run(args) {
   // The keyring is owner infrastructure wholesale: exec runs an arbitrary
   // command with every credential in env, get prints raw values, set/remove
-  // mutate them. No external request ever needs any of it — and the Bash
-  // control-plane gate exempts `keyring exec` as an authorised channel, so
-  // the speaker gate must live here, on the authorised side. Same fail
-  // directions as the file gate: dormant without channel env (owner-local),
-  // denied when resolution fails.
-  const speaker = require("../core/tool-guard").guardedSpeakerFromEnv();
-  if (speaker) {
-    try {
-      require("../core/tool-guard").logGuardEvent({
-        kind: "deny", rule: "external-keyring", command: `keyring ${args.join(" ")}`.slice(0, 300),
-      });
-    } catch (e) { /* logging is best-effort */ }
-    console.error(`⛔ External-speaker guard: the keyring is owner-only — this turn's speaker${speaker.name ? ` (${speaker.name})` : ""} is not the owner.`);
-    console.error("Describe what you need instead; write-tier tool runs escalate to the owner for approval.");
-    process.exitCode = 1;
-    return;
-  }
+  // mutate them, and even list/path map what exists. No other request ever
+  // needs any of it — and the Bash control-plane gate exempts `keyring exec`
+  // as an authorised channel, so the gate must live here, on the authorised
+  // side. EVERY verb needs an attributed owner: whether this process acts for
+  // the owner is answered by the running bot from the run's attestation
+  // (bin/owner-gate), never from OC_CHANNEL_* env — a stripped or rewritten
+  // env, and a process with no live run behind it, are refused.
+  const owner = await require("./owner-gate").requireOwner("the keyring", {
+    exitCode: 1,
+    onRefuse: (caller) => require("../core/tool-guard").logGuardEvent({
+      kind: "deny", rule: "external-keyring", caller: caller && caller.attributed ? "guarded" : "unattributed",
+      command: `keyring ${args.join(" ")}`.slice(0, 300),
+    }),
+  });
+  if (!owner) return;
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 

package/bin/lessons.js

@@ -4,14 +4,23 @@
 //   open-claudia lessons remove <id|text>           — remove one
 //   open-claudia lessons show                        — raw file + injected block
 //   open-claudia lessons path                        — print the file path
+//
+// add/remove change rules loaded into EVERY conversation: owner-only, decided
+// by the running bot from the run's attestation (bin/owner-gate).
 
 const fs = require("fs");
 const lessons = require("../core/lessons");
 
-function run(args) {
+const OWNER_ONLY_VERBS = new Set(["add", "remove", "rm"]);
+
+async function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 
+  if (OWNER_ONLY_VERBS.has(cmd)) {
+    if (!(await require("./owner-gate").requireOwner(`"lessons ${cmd}" changes the bot's always-loaded rules`))) return;
+  }
+
   switch (cmd) {
     case "list": {
       const all = lessons.listLessons();

package/bin/loopback-client.js

@@ -46,6 +46,9 @@ function context() {
     // Runner-minted HMAC binding canonicalUserId to what the bot stamped for
     // this turn; the loopback's owner gates verify it (see core/speaker-attest).
     speakerAttest: process.env.OC_SPEAKER_ATTEST || null,
+    // Runner-minted attest for THIS run; the bot answers who the run acts
+    // for only while the run is live (see core/speaker-attest registerRun).
+    runAttest: process.env.OC_RUN_ATTEST || null,
     provider: process.env.OC_PROVIDER || null,
     providerSettings,
     project: process.env.OC_PROJECT || null,
@@ -81,6 +84,7 @@ function postJson(kind, body) {
     userId: ctx.userId,
     canonicalUserId: ctx.canonicalUserId,
     speakerAttest: ctx.speakerAttest,
+    runAttest: ctx.runAttest,
     provider: ctx.provider,
     providerSettings: ctx.providerSettings,
     project: requestedProject,
@@ -127,4 +131,45 @@ function postJson(kind, body) {
   });
 }
 
-module.exports = { context, requireContext, postJson, readLoopbackInfo };
+// Who this process acts for, as the RUNNING BOT decides it. Needs no chat
+// context: a process with no live run behind it (stripped env, detached from
+// a finished turn, started outside the bot) comes back unattributed, and so
+// does every failure to ask. Unattributed is never the owner.
+const UNATTRIBUTED = Object.freeze({ attributed: false, owner: false, guarded: true, kind: "unattributed" });
+
+function whoami({ timeoutMs = 5000 } = {}) {
+  const ctx = context();
+  if (!ctx.runId || !ctx.runAttest || !ctx.sendUrl || !ctx.sendToken) return Promise.resolve(UNATTRIBUTED);
+  let u;
+  try { u = new URL(ctx.sendUrl); } catch (_) { return Promise.resolve(UNATTRIBUTED); }
+  const payload = JSON.stringify({ runId: ctx.runId, originRunId: ctx.runId, runAttest: ctx.runAttest });
+  return new Promise((resolve) => {
+    const req = http.request({
+      method: "POST",
+      hostname: u.hostname,
+      port: u.port,
+      path: "/whoami",
+      timeout: timeoutMs,
+      headers: {
+        Authorization: `Bearer ${ctx.sendToken}`,
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload),
+      },
+    }, (res) => {
+      let out = "";
+      res.on("data", (c) => { out += c; });
+      res.on("end", () => {
+        try {
+          const caller = res.statusCode === 200 ? JSON.parse(out).caller : null;
+          resolve(caller && caller.attributed === true ? caller : UNATTRIBUTED);
+        } catch (_) { resolve(UNATTRIBUTED); }
+      });
+    });
+    req.on("timeout", () => { req.destroy(); resolve(UNATTRIBUTED); });
+    req.on("error", () => resolve(UNATTRIBUTED));
+    req.write(payload);
+    req.end();
+  });
+}
+
+module.exports = { context, requireContext, postJson, readLoopbackInfo, whoami, UNATTRIBUTED };

package/bin/owner-gate.js

@@ -0,0 +1,38 @@
+// Owner-only CLI verbs (permission Phase 0). Whether a process acts for the
+// owner is decided by the RUNNING BOT (loopback whoami over OC_RUN_ID +
+// OC_RUN_ATTEST), never by this process's own env: OC_CHANNEL_* and
+// OC_CANONICAL_USER_ID are ignored, and a process with no live run behind it
+// (a stripped env, a detached leftover, a plain terminal) is unattributed —
+// which is never the owner.
+
+const { whoami } = require("./loopback-client");
+
+function hasRunAttest(env = process.env) {
+  return !!(env.OC_RUN_ID && env.OC_RUN_ATTEST);
+}
+
+function refusal(what, caller) {
+  const why = !(caller && caller.attributed) ? "this process is not attributed to an owner chat turn"
+    : caller.name ? `this turn acts for ${caller.name}, not the owner`
+      : "this turn does not act for the owner";
+  return `⛔ Owner only: ${what} — ${why}.`;
+}
+
+// Resolves the caller when it is an attributed owner, else prints one refusal
+// line, sets process.exitCode and resolves null. With no run attestation at
+// all the refusal happens synchronously (before the first await), so callers
+// that do not await still see the exit code at once.
+async function requireOwner(what, { exitCode = 3, onRefuse = null } = {}) {
+  const refuse = (caller) => {
+    if (typeof onRefuse === "function") { try { onRefuse(caller); } catch (_) { /* best-effort */ } }
+    console.error(refusal(what, caller));
+    process.exitCode = exitCode;
+    return null;
+  };
+  if (!hasRunAttest()) return refuse({ attributed: false });
+  const caller = await whoami();
+  if (caller && caller.attributed === true && caller.owner === true) return caller;
+  return refuse(caller);
+}
+
+module.exports = { requireOwner, hasRunAttest, refusal };

package/bin/pack.js

@@ -6,15 +6,25 @@
 //   open-claudia pack migrate               — fold ~/.claude/skills into packs
 //   open-claudia pack remove <dir>
 //   open-claudia pack reindex
+//
+// skill/kind/archive/restore/remove/reindex/migrate change the packs the bot
+// works from: owner-only, decided by the running bot from the run's
+// attestation (bin/owner-gate). The listing/show/match/search verbs are reads.
 
 const fs = require("fs");
 const path = require("path");
 const packs = require("../core/packs");
 
-function run(args) {
+const OWNER_ONLY_VERBS = new Set(["skill", "kind", "archive", "restore", "remove", "reindex", "migrate"]);
+
+async function run(args) {
   const cmd = (args[0] || "list").toLowerCase();
   const rest = args.slice(1);
 
+  if (OWNER_ONLY_VERBS.has(cmd)) {
+    if (!(await require("./owner-gate").requireOwner(`"pack ${cmd}" changes the bot's packs`))) return;
+  }
+
   switch (cmd) {
     case "list": {
       const all = packs.listPacks();

package/bin/schedule.js

@@ -8,7 +8,8 @@ Background scheduling — manage wakeups and crons.
 
 Wakeups (one-shot, resumes the same conversation):
   open-claudia schedule-wakeup <when> "<prompt>" [--label "<label>"]
-    <when>: duration (e.g. 30s, 5m, 2h, 1d) OR an ISO datetime (e.g. 2026-05-16T15:00:00Z)
+    <when>: duration (e.g. 30s, 5m, 2h, 1d) OR an ISO datetime (e.g. 2026-05-16T15:00:00Z),
+            at most 10 years out
 
 Crons (recurring):
   open-claudia cron-add "<5-field cron>" "<prompt>" [--label "<label>"] [--project <name>]
@@ -25,6 +26,8 @@ Watches (silent background monitor — polls a shell check, wakes you only on a
                datetime. Default 2h. A watch that reaches its timeout without
                the check ever passing FIRES anyway on the next poll, with the
                prompt marked "Watch expired" — no watch can end silently.
+    A check that times out (30s) 3 times in a row wakes the agent once, marked
+    "Watch check timing out"; the watch keeps polling.
   open-claudia watch-list                        # watches on this channel + master switch state
   open-claudia watch-remove <id>                 # remove a watch by id
   open-claudia watch-on / watch-off              # global master switch for ALL watches (owner)
@@ -37,6 +40,10 @@ switching providers starts a fresh thread.
 `;
 
 const DUR = /^(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs|d|day|days)$/i;
+// Mirrors core/scheduler MAX_WAKEUP_HORIZON_MS: a wakeup further out than this
+// is a typo or a mis-parsed <when> (one was set 1273 years out).
+const MAX_WAKEUP_YEARS = 10;
+const MAX_WAKEUP_HORIZON_MS = MAX_WAKEUP_YEARS * 365.25 * 24 * 60 * 60 * 1000;
 
 function parseWhen(s) {
   if (!s) return null;
@@ -63,13 +70,41 @@ function takeFlag(args, name) {
   return v;
 }
 
+// Where a job stands once it has fired. A fired job used to stay listed as a
+// future one ("fires 2028-08-01", "EXPIRED (fires on next poll)") while its
+// delivery was queued, running or dead (17 and 21 Sep).
+function jobProgress(j) {
+  const since = j.check && j.watchTriggeredOccurrenceId && j.watchTriggeredOccurrenceId === j.occurrenceId && Number(j.watchTriggeredAt) > 0
+    ? `TRIGGERED ${new Date(Number(j.watchTriggeredAt)).toISOString()}, ` : "";
+  const state = {
+    running: "delivery running",
+    deferred: "delivery waiting for a busy room",
+    failed: `delivery failed (${j.lastError?.code || "error"}), retrying`,
+    "dead-letter": `delivery failed (${j.lastError?.code || "error"}), DEAD: will not fire`,
+  }[j.status];
+  return state ? `${since}${state}` : "";
+}
+
 function fmtJob(j) {
   const when = j.kind === "wakeup"
     ? `fires ${new Date(j.fireAt).toISOString()}`
     : `schedule "${j.schedule}"`;
   const proj = j.project ? ` [${j.project}]` : "";
   const src = j.source ? ` (${j.source})` : "";
-  return `${j.id}  ${j.kind}  ${j.label || "(no label)"}${proj}${src}  ${when}`;
+  const progress = jobProgress(j);
+  return `${j.id}  ${j.kind}  ${j.label || "(no label)"}${proj}${src}  ${when}${progress ? `  [${progress}]` : ""}`;
+}
+
+function fmtWatch(w, now = Date.now()) {
+  const mode = w.repeat ? "repeating" : "one-shot";
+  const progress = jobProgress(w);
+  const expiry = progress ? `  ${progress}`
+    : Number(w.expiresAt) > 0
+      ? (now >= Number(w.expiresAt)
+        ? "  EXPIRED (fires on next poll)"
+        : `  expires ${new Date(Number(w.expiresAt)).toISOString()}`)
+      : "  no expiry (pre-timeout watch)";
+  return `${w.id}  ${mode}  polls "${w.schedule}"${expiry}  check: ${w.check}  → ${w.label || "(no label)"}`;
 }
 
 async function runScheduleWakeup(args) {
@@ -82,6 +117,11 @@ async function runScheduleWakeup(args) {
     console.error(`Could not parse <when>: "${rest[0]}". Use a duration (5m, 2h, 1d) or ISO datetime.`);
     process.exit(2);
   }
+  if (when - Date.now() > MAX_WAKEUP_HORIZON_MS) {
+    const at = new Date(when);
+    console.error(`<when> "${rest[0]}" is ${Number.isNaN(at.getTime()) ? "past any valid date" : at.toISOString()}, more than ${MAX_WAKEUP_YEARS} years out. Check the date; for a far reminder use a yearly cron-add.`);
+    process.exit(2);
+  }
   const prompt = rest.slice(1).join(" ");
   if (!prompt) { console.error("Missing prompt."); process.exit(2); }
   try {
@@ -178,15 +218,7 @@ async function runWatchList() {
     const list = res.watches || [];
     console.log(`Watches: master switch is ${res.enabled ? "ON" : "OFF"}.`);
     if (list.length === 0) { console.log("No watches on this channel."); process.exit(0); }
-    for (const w of list) {
-      const mode = w.repeat ? "repeating" : "one-shot";
-      const expiry = Number(w.expiresAt) > 0
-        ? (Date.now() >= Number(w.expiresAt)
-          ? "  EXPIRED (fires on next poll)"
-          : `  expires ${new Date(Number(w.expiresAt)).toISOString()}`)
-        : "  no expiry (pre-timeout watch)";
-      console.log(`${w.id}  ${mode}  polls "${w.schedule}"${expiry}  check: ${w.check}  → ${w.label || "(no label)"}`);
-    }
+    for (const w of list) console.log(fmtWatch(w));
     process.exit(0);
   } catch (e) { console.error(e.message); process.exit(1); }
 }
@@ -211,6 +243,8 @@ async function runWatchToggle(enabled) {
 
 module.exports = {
   HELP,
+  fmtJob,
+  fmtWatch,
   runScheduleWakeup,
   runCronAdd,
   runCronList,