@luckydraw/cumulus 1.0.3 → 1.0.5

package/dist/lib/tool-inventory.js

@@ -0,0 +1,317 @@
+/**
+ * Tool inventory + allowlist compilation (task 137).
+ *
+ * WHY THIS EXISTS
+ * A thread that should only be able to do a few things (a public web-app visitor
+ * panel) previously had to be configured with a DENYLIST — @cdda hand-enumerated 47
+ * tool names to get a safe surface. That inverts maintenance onto every app author:
+ * any tool cumulus or the Claude CLI adds in a future release is silently granted to
+ * every visitor on every deployed app until each author notices and edits their list.
+ *
+ * The fix is an allowlist. But `--allowedTools` on the Claude CLI is an AUTO-APPROVE
+ * list, not a restriction — measured under three permission modes, `--allowedTools Glob`
+ * failed to block Bash every time, and cumulus spawns with `--permission-mode
+ * bypassPermissions` where an auto-approve list is a guaranteed no-op. `--disallowedTools`
+ * DOES restrict there (also measured). So an allowlist has to be COMPILED into a denylist:
+ *
+ *     denylist = (everything that exists) − (what this thread may use)
+ *
+ * which is why this module has to know the full inventory.
+ *
+ * WHERE THE INVENTORY COMES FROM (three sources, because no single one is complete)
+ *  1. Built-in CLI tools — read from the `system:init` stream event, which carries the
+ *     CLI's own `tools[]`. Probed once per process (see probeBuiltinTools).
+ *  2. cumulus's own MCP tools — derived from the definitions cumulus itself ships.
+ *  3. Namespace `extraMcpServers` — NOT knowable here, and deliberately not closed over.
+ *     Those are the app author's own shim tools, granted to that namespace on purpose.
+ *
+ * The seed list is a FLOOR, not merely a fallback: the inventory is always the union of
+ * the probe and the seed, so a probe that returns a short list (different cwd, different
+ * plugin set, a future CLI that changes the event shape) can never quietly widen what a
+ * constrained thread is allowed to reach.
+ */
+import { spawn } from 'child_process';
+import * as os from 'os';
+import { getToolDefinitions } from '../mcp/tool-handler.js';
+/**
+ * Built-in Claude CLI tools, as reported by `system:init` on CLI 2.1.217.
+ *
+ * This is a FLOOR for the inventory, not a fallback — see the module comment. Adding a
+ * name here can only ever deny more on an allowlisted thread; it has no effect on a
+ * thread without `allowedTools`. Safe to update from a probe of a newer CLI.
+ */
+export const SEED_BUILTIN_TOOLS = [
+    'Bash',
+    'CronCreate',
+    'CronDelete',
+    'CronList',
+    'DesignSync',
+    'Edit',
+    'EnterWorktree',
+    'ExitWorktree',
+    'Monitor',
+    'NotebookEdit',
+    'PushNotification',
+    'Read',
+    'RemoteTrigger',
+    'ReportFindings',
+    'ScheduleWakeup',
+    'SendMessage',
+    'Skill',
+    'Task',
+    'TaskCreate',
+    'TaskGet',
+    'TaskList',
+    'TaskOutput',
+    'TaskStop',
+    'TaskUpdate',
+    'ToolSearch',
+    'WebFetch',
+    'WebSearch',
+    'Workflow',
+    'Write',
+];
+/**
+ * Tools served by the `gateway-agents` MCP server.
+ *
+ * Duplicated here rather than imported because `gateway-agents-mcp.ts` calls `main()`
+ * at top level — it is a stdio binary, and importing it would start a server. A source
+ * tripwire test asserts this list matches the tool definitions in that file, so the two
+ * cannot drift (same shape as task 132's artifact tripwire).
+ *
+ * `broadcast` is absent on purpose: it is deliberately not served (task 135).
+ */
+export const GATEWAY_AGENTS_TOOL_NAMES = [
+    'cancel_job',
+    'cancel_schedule',
+    'create_plastic_app',
+    'job_log',
+    'list_agents',
+    'list_emails',
+    'list_jobs',
+    'list_schedules',
+    'notify_user',
+    'run_job',
+    'schedule_trigger',
+    'send_email',
+    'send_to_agent',
+    'update_pipeline',
+    'upload_media',
+];
+/** MCP server keys cumulus attaches itself (see generateMcpConfig). */
+const CUMULUS_HISTORY_SERVER = 'cumulus-history';
+const GATEWAY_AGENTS_SERVER = 'gateway-agents';
+/** How long to wait for the CLI to emit its init event before giving up on the probe. */
+const PROBE_TIMEOUT_MS = 15_000;
+/** Fully-qualified names of the MCP tools cumulus ships itself. */
+export function cumulusMcpToolNames() {
+    const history = getToolDefinitions().map(t => `mcp__${CUMULUS_HISTORY_SERVER}__${t.name}`);
+    const agents = GATEWAY_AGENTS_TOOL_NAMES.map(n => `mcp__${GATEWAY_AGENTS_SERVER}__${n}`);
+    return [...history, ...agents];
+}
+/**
+ * Ask the Claude CLI what built-in tools it has, by reading the `tools[]` array off its
+ * `system:init` stream event and killing the subprocess immediately.
+ *
+ * Measured cost: init arrives ~871ms in and is the ONLY event before the kill — no
+ * assistant output, no result event, so nothing comes back from the model. A prompt is
+ * required: with stdin closed the CLI exits before emitting init (0 lines), and merely
+ * holding stdin open emits nothing at all (20s). Hence the one-character `x`.
+ *
+ * Runs in a neutral cwd so a project's own settings cannot shape the answer, and the
+ * result is unioned with the seed floor by the caller either way.
+ *
+ * Rejects on timeout, spawn failure, or a missing/empty `tools[]`. Never throws
+ * synchronously; the caller treats any rejection as "use the floor".
+ *
+ * `claudePath` is supplied by the caller, which already has it resolved. Taking it as a
+ * parameter rather than importing `resolveClaudeCli` avoids a module cycle: that function
+ * lives in gateway.ts, which imports this module.
+ */
+export function probeBuiltinTools(claudePath) {
+    return new Promise((resolve, reject) => {
+        const bin = claudePath || 'claude';
+        // Same env hygiene as the real spawn: CLAUDE* vars would leak the parent session.
+        const cleanEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('CLAUDE') && key !== 'CLAUDECODE'));
+        let child;
+        try {
+            child = spawn(bin, [
+                '--print',
+                '--output-format',
+                'stream-json',
+                '--verbose',
+                '--permission-mode',
+                'bypassPermissions',
+                'x',
+            ], { stdio: ['ignore', 'pipe', 'ignore'], cwd: os.tmpdir(), env: cleanEnv });
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        let settled = false;
+        let buf = '';
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+            fn();
+        };
+        const timer = setTimeout(() => finish(() => reject(new Error('tool inventory probe timed out'))), PROBE_TIMEOUT_MS);
+        // Don't hold the event loop open on a probe nobody is waiting for.
+        timer.unref?.();
+        child.stdout?.on('data', (chunk) => {
+            buf += chunk.toString();
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.type !== 'system' || parsed.subtype !== 'init')
+                    continue;
+                const tools = Array.isArray(parsed.tools)
+                    ? parsed.tools.filter((t) => typeof t === 'string')
+                    : [];
+                if (tools.length === 0) {
+                    finish(() => reject(new Error('init event carried no tools')));
+                    return;
+                }
+                finish(() => resolve(tools));
+                return;
+            }
+        });
+        child.on('error', err => finish(() => reject(err)));
+        // 'close', not 'exit': close fires after stdio has drained, so a CLI that prints init
+        // and exits immediately still resolves. On 'exit' the reject could win the race.
+        child.on('close', () => finish(() => reject(new Error('CLI exited before emitting init'))));
+    });
+}
+/** Memoized so the probe runs at most once per gateway process. */
+let inventoryPromise = null;
+/**
+ * The full set of tool names a spawned turn could otherwise reach.
+ *
+ * Deliberately NOT threaded through `MessagePipelineOptions`: task 113 is the recorded
+ * case of a field added to one of four spawn paths and silently doing nothing in the
+ * other three, and here a miss would fail OPEN. Module-scope memoization means the single
+ * args-assembly site is the only consumer and it cannot be half-wired.
+ */
+export function getToolInventory(claudePath) {
+    if (!inventoryPromise) {
+        inventoryPromise = probeBuiltinTools(claudePath)
+            .catch(err => {
+            console.warn(`[Gateway] Tool inventory probe failed (${err instanceof Error ? err.message : err}); ` +
+                'using the seed floor. Allowlisted threads stay closed.');
+            return [];
+        })
+            .then(probed => {
+            const all = new Set([...SEED_BUILTIN_TOOLS, ...probed, ...cumulusMcpToolNames()]);
+            return [...all].sort();
+        });
+    }
+    return inventoryPromise;
+}
+/** Test seam: drop the memo so a suite can probe with a stub. */
+export function resetToolInventoryCache() {
+    inventoryPromise = null;
+}
+/** The bare tool name of an `mcp__server__tool` entry, or the name itself. */
+export function bareToolName(name) {
+    if (!name.startsWith('mcp__'))
+        return name;
+    const parts = name.split('__');
+    return parts.length > 2 ? parts.slice(2).join('__') : name;
+}
+/**
+ * Compile an allowlist into the denylist the CLI actually honours.
+ *
+ * Returns `existingDisallowed` UNCHANGED when no allowlist is configured — additive, so
+ * every thread that does not opt in behaves exactly as before.
+ *
+ * An allowlist entry matches an inventory entry exactly, or as its bare name, so
+ * `read_file` allows `mcp__cumulus-history__read_file` (the system prompt calls it
+ * `read_file`; a user should not have to know the prefix). An entry that matches nothing
+ * is inert — and inertness DENIES, so a typo fails closed.
+ *
+ * `disallowedTools` still applies on top: it can subtract from an allowlist but never add.
+ */
+export function compileDisallowedTools(allowedTools, inventory, existingDisallowed) {
+    if (!allowedTools)
+        return existingDisallowed;
+    const allowed = new Set(allowedTools);
+    const denied = new Set(existingDisallowed ?? []);
+    for (const name of inventory) {
+        if (allowed.has(name) || allowed.has(bareToolName(name)))
+            continue;
+        denied.add(name);
+    }
+    return denied.size ? [...denied].sort() : undefined;
+}
+/**
+ * Is `name` (a bare tool name) reachable on this thread?
+ *
+ * Deliberately inventory-INDEPENDENT: it reads the thread's stated intent, so it gives the
+ * same answer on the Claude CLI path and the direct-provider path, whose real inventories
+ * differ. Available iff the allowlist admits it (or there is no allowlist) and the denylist
+ * does not name it.
+ */
+export function toolAvailable(name, policy) {
+    const denied = (policy.disallowedTools ?? []).some(d => d === name || bareToolName(d) === name);
+    if (denied)
+        return false;
+    if (!policy.allowedTools)
+        return true;
+    return policy.allowedTools.some(a => a === name || bareToolName(a) === name);
+}
+export function promptCapabilities(policy) {
+    return {
+        // Both halves are load-bearing since task 139: the section describes
+        // `run_job`, and run_job itself is refused server-side for a thread that
+        // cannot run shell. Keeping it for a thread with only one of the two would
+        // describe something unreachable.
+        backgroundWork: toolAvailable('Bash', policy) && toolAvailable('run_job', policy),
+        scheduling: toolAvailable('schedule_trigger', policy),
+        interAgent: toolAvailable('send_to_agent', policy),
+    };
+}
+/** Section header prefixes, keyed by the capability that keeps them. */
+const GATED_SECTIONS = [
+    ['backgroundWork', 'BACKGROUND WORK:'],
+    ['scheduling', 'SCHEDULING'],
+    ['interAgent', 'INTER-AGENT MESSAGING:'],
+];
+/**
+ * Remove prompt sections whose tools this thread cannot reach.
+ *
+ * Sections in SYSTEM_PROMPT_TEMPLATE are blank-line-delimited blocks whose first line is a
+ * header, so this is a split/filter/join — lossless when nothing is gated (regression-locked),
+ * and a no-op on a custom template that has no such headers.
+ *
+ * Only ever REMOVES text, so an unconstrained thread's prompt is byte-identical and the task
+ * 117 static-prompt budget cannot be breached by this function.
+ */
+export function applyCapabilityGates(template, caps) {
+    const dropPrefixes = GATED_SECTIONS.filter(([cap]) => !caps[cap]).map(([, prefix]) => prefix);
+    if (dropPrefixes.length === 0)
+        return template;
+    return template
+        .split('\n\n')
+        .filter(block => !dropPrefixes.some(prefix => block.startsWith(prefix)))
+        .join('\n\n');
+}
+//# sourceMappingURL=tool-inventory.js.map

package/dist/lib/tool-inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-inventory.js","sourceRoot":"","sources":["../../src/lib/tool-inventory.ts"],"names":[],"mappings":"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"}

package/docs/conditional-continuation.md

@@ -1,167 +1,122 @@
-# Conditional Thread Continuation — the Watcher-with-Deadline Pattern
+# Conditional Thread Continuation — `run_job`
 
-**Status:** Adopted convention (Karl, 2026-07-26). No gateway code — this pattern composes
-two primitives that already exist. A more robust gateway-native mechanism is sketched at
-the end for when this outgrows convention.
+**Status:** Gateway-native since task 139 (2026-08-15). Supersedes the
+watcher-with-deadline convention adopted 2026-07-26, which is described at the
+end for anyone reading old threads.
 
 ## The problem
 
-A thread kicks off something long-running with an uncertain finish time — a compile, a
-test suite, a deploy, a download. The thread should continue **the moment the outcome is
-known** (success _or_ failure), not after an arbitrary sleep, and not by burning a
-scheduled AI turn every N minutes to poll ("did it finish yet?" cron turns dilute thread
-history — the exact failure class tasks 088–092 fixed).
+A thread kicks off something long-running with an uncertain finish time — a
+compile, a test suite, a deploy, a download. The thread should continue **the
+moment the outcome is known** (success _or_ failure), not after an arbitrary
+sleep, and not by burning a scheduled AI turn every N minutes to poll ("did it
+finish yet?" cron turns dilute thread history — the exact failure class tasks
+088–092 fixed).
 
-## The two primitives
+## The answer
 
-### 1. `POST /api/agents/inject` — immediate continuation
+```
+run_job("npm run build", label: "build")
+  → { started: true, id: "job_a7f3c2d1", logPath: "..." }
+```
 
-Any process with a valid gateway API key can inject a message into a thread. The thread
-starts a new turn immediately; if it's mid-stream, the message queues and delivers at
-busy→idle (the task 100 unified queue). Exact shape (verified against
-`server.ts handleAgentInject`):
+Then **end the turn**. When the job exits, the gateway starts a new turn on the
+thread carrying the exit code, the working directory, the log path and the tail
+of the output.
 
-```bash
-curl -s -X POST http://localhost:8090/api/agents/inject \
-  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-  -d '{"targets": "THREAD_NAME", "sender": "build-watcher", "message": "..."}'
-```
+Companions: `list_jobs()`, `job_log(id, tail?)` (works while it is still
+running, so progress can be checked without waiting), `cancel_job(id)`.
 
-- `targets` (string or array) and `sender` and `message` are required. There is no
-  `target`/`from` — those names will 400.
-- Auth: `X-API-Key: <key>` or `Authorization: Bearer <key>`.
-- On thundercat, a key is readable from the gateway config:
-  `KEY=$(jq -r '.apiKeys[0]' "${CUMULUS_DIR:-$HOME/.cumulus}/gateway.config.json")`
-  Read it through `$CUMULUS_DIR`, never as a literal `~/.cumulus` — a hard-coded path
-  points a sandboxed run (tests, a second gateway) straight at the production gateway
-  with the production admin key (task 111).
-
-### 2. `schedule_trigger` MCP tool — the time-based floor
-
-Available in every thread (gateway-agents MCP). `{id, trigger: "once", at: "<ISO datetime>",
-message}` fires one injection at a fixed time then auto-removes; `trigger: "cron"` +
-`cron` recurs (1-minute resolution). Persisted in thread config — **survives gateway
-restarts**, which the watcher does not. Companions: `list_schedules`, `cancel_schedule`.
-
-## The pattern
-
-**Watcher for immediacy, one-shot schedule for the guarantee.** The condition-watcher
-doesn't need to live in the gateway: the thread's Claude subprocess runs on the same
-machine and can leave a detached process behind.
-
-### Step 1 — detach the job with a watcher wrapper
-
-For a _process-exit_ condition (the common case — build/test/deploy), the wrapper simply
-runs the job and fires when it exits, success or error:
-
-```bash
-KEY=$(jq -r '.apiKeys[0]' "${CUMULUS_DIR:-$HOME/.cumulus}/gateway.config.json")
-nohup sh -c '
-  npm run build > /tmp/build.log 2>&1
-  rc=$?
-  curl -s -X POST http://localhost:8090/api/agents/inject \
-    -H "X-API-Key: '"$KEY"'" -H "Content-Type: application/json" \
-    -d "{\"targets\":\"cumulus\",\"sender\":\"build-watcher\",
-         \"message\":\"[watcher] Build finished, exit $rc. Log: /tmp/build.log. First: cancel_schedule(\\\"build-deadline\\\").\"}"
-' >/dev/null 2>&1 &
-```
+### Write the command plainly
 
-For a condition that isn't a process exit (file appears, port answers, log line shows up),
-put an `until` loop before the curl:
+No `&`, no `> log 2>&1`, no `nohup`, no `setsid`. The gateway supplies all of
+that, and adding your own breaks the log capture that the completion report
+reads from. A command ending in `exit N` is fine — the status is captured by an
+`EXIT` trap, not by trailing statements.
 
-```bash
-until <check-command>; do sleep 5; done   # e.g. curl -sf http://localhost:3000/health
-```
+### For a condition that is not a process exit
 
-Guidelines:
-
-- **`>/dev/null 2>&1 &`** — redirecting _both_ streams is what makes the watcher survive
-  the Claude turn ending, and it is the only part that does. The turn's subprocess exits
-  at turn end; anything still holding its inherited stdout/stderr pipes is killed by
-  SIGPIPE (exit 141) on the next write. `nohup` alone does not save it (it ignores SIGHUP,
-  the wrong signal, and only auto-redirects when stdout is a terminal — here it is a pipe),
-  and neither does `setsid` (nothing is signalling the process group). Prefer a real log
-  file over `/dev/null` when the woken turn will need to diagnose. Surviving the turn is
-  all this buys — the watcher is still unsupervised and does NOT survive a machine reboot;
-  that's what step 2 is for.
-- **Always report failure too.** The wrapper fires on _outcome_, not on _success_ —
-  include the exit code and a log path so the woken turn can diagnose without re-running.
-- **Tell the woken turn to cancel the deadline** (put it in the message, as above) so the
-  fallback never double-fires.
-- Name the `sender` after the condition (`build-watcher`, `deploy-watcher`) — it prefixes
-  the injected message and reads clearly in history.
-- **Do not reply to the watcher.** Injected messages carry a "Reply using
-  `send_to_agent(...)`" footer intended for agent-to-agent traffic. A watcher is a script,
-  not an agent, so replying to it mints an empty thread named after the sender and burns a
-  turn in it. Measured while verifying task 109: a woken turn replied to `job-watcher` and
-  a `job-watcher` thread appeared on disk. Act on the report instead.
-
-### Step 2 — set the deadline fallback
-
-In the same turn that spawns the watcher, set a one-shot schedule as the floor:
+Put the wait inside the job. A job _is_ a shell, so the same loop that used to
+go in a watcher goes here, and it inherits supervision and reporting for free:
 
 ```
-schedule_trigger({
-  id: "build-deadline",
-  trigger: "once",
-  at: "<now + generous timeout, ISO 8601>",
-  message: "[deadline] The build watcher never reported back. Check /tmp/build.log and whether the process is still running."
-})
+run_job("until curl -sf http://localhost:3000/health; do sleep 5; done", label: "wait for health")
 ```
 
-Why this matters: the watcher is an unsupervised background process. If the machine
-reboots, the gateway is restarted mid-job, or the script dies, the thread would otherwise
-wait forever. The schedule persists in thread config, so the thread is _guaranteed_ to
-wake — worst case at the deadline, best case the instant the condition fires.
+### When NOT to use it
+
+A command that finishes within a couple of minutes should just run in the
+foreground. If it runs past the Bash tool's limit the harness backgrounds it and
+notifies the thread, which keeps waiting in-turn — correct for twenty minutes,
+wrong for six hours. `run_job` is for the second case, and for when the thread
+should be free meanwhile.
+
+## Why this is a tool and not a documented recipe
+
+Cumulus tried the documented-recipe route three times — task 108 (redirect both
+streams), 109 (watcher + deadline), 116 (the worked one-liner in the content
+store) — and it kept failing in the world, at a standing cost of ~290 prompt
+tokens on every turn of every thread. Three measured reasons:
+
+1. **The cure had to be applied at every layer.** A driver script that redirects
+   its own output does not save the children it spawns. @ordimor got two of
+   three layers right and lost the job anyway.
+2. **The watcher could die independently of the job.** It was itself background
+   work with its own redirect requirement. Task 109's postmortem found exactly
+   that: the watcher never fired.
+3. **One killer was not curable from the thread side at all.** systemd's default
+   `KillMode=control-group` reaps every process in the unit's cgroup when the
+   main process exits, and `systemctl reload` makes the gateway exit (Rule #9).
+   Neither `setsid`, `nohup`, nor redirecting escapes a cgroup — a cgroup is not
+   a session. Every reload killed every background job on the box.
+
+`run_job` removes 1 and 2 by construction: the daemon spawns the job with a file
+descriptor rather than a pipe (so SIGPIPE is unreachable, not cured) and outside
+the turn's process tree (so interjecting cannot reach it), and the registry that
+reports completion cannot die independently of the daemon that owns the job.
+
+Killer 3 needs `KillMode=process` on the service unit — shipped in the unit
+template generated by `cumulus-gateway setup`. **Without it, jobs still work but
+do not survive a gateway restart.** They are not lost silently either way: on
+startup the registry checks every recorded job, re-adopts the ones still
+running, and reports the rest — with their real exit code if the job got far
+enough to record one, otherwise honestly as `interrupted`, which explicitly says
+the work may or may not have completed.
+
+## `schedule_trigger` is still here, for a different job
+
+`schedule_trigger({id, trigger: "once"|"cron", at|cron, message})` injects a
+message into the thread at a **time**. That is deferred reminders, drip
+sequences and genuinely periodic work — not condition-waiting.
+
+It is no longer needed as a deadline backstop for background work: that leg
+existed because an unsupervised watcher could vanish, and the registry cannot.
 
-### Step 3 — on wake, cancel the other leg
+### Anti-pattern: cron polling turns
 
-- Watcher fired → first action: `cancel_schedule("build-deadline")`.
-- Deadline fired → check the log/process manually; kill any orphaned watcher
-  (`pkill -f build-watcher-marker` if you tagged the command line).
+Do **not** use `trigger: "cron"` to poll a condition every N minutes. Each poll
+burns a full AI turn and appends "checked, nothing yet" noise to thread history,
+degrading retrieval for every future turn.
 
-### Anti-pattern: cron polling turns
+## Superseded: the watcher-with-deadline convention (2026-07-26 → 2026-08-15)
+
+Threads used to compose two primitives by hand: a detached `curl` to
+`POST /api/agents/inject` wrapped around the job, plus a one-shot
+`schedule_trigger` as the floor in case the watcher died. Recorded here only so
+older thread history reads coherently — do not write new ones.
+
+Its four known limitations are what `run_job` was built to remove:
+
+| Limitation of the convention                                              | Status                                                        |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| No supervision — a bare background process, nothing restarts or tracks it | Fixed: the registry owns the job                              |
+| No visibility — no way to enumerate or cancel a pending watcher           | Fixed: `list_jobs` / `job_log` / `cancel_job`                 |
+| Needed a gateway API key in the script's command line                     | Fixed: no key involved at all                                 |
+| Reboot amnesia — schedules survived restarts, watchers did not            | Fixed: adoption on startup, or an honest `interrupted` report |
 
-Do **not** use `schedule_trigger` with `trigger: "cron"` to poll a condition every N
-minutes. Each poll burns a full AI turn and appends "checked, nothing yet" noise to
-thread history, degrading retrieval quality for every future turn. Cron is for genuinely
-periodic work (weekly reports, drip follow-ups), not condition-waiting.
-
-## Known limitations of this pattern
-
-These are accepted trade-offs of the convention, and the reason a robust version may be
-worth building later:
-
-1. **No supervision** — the watcher is a bare background process; nothing restarts it.
-   The deadline fallback bounds the damage but adds latency in the failure case.
-2. **No visibility** — there is no `list_watches`; a pending watcher is invisible to the
-   thread, the user, and the dashboard. You can't enumerate or cancel what you can't see.
-3. **Key in the script** — the watcher needs a gateway API key in its environment/command
-   line. On thundercat (single-user box) this is acceptable; it would not be under
-   namespace-scoped multi-tenant use (task 097 P7).
-4. **Reboot amnesia** — schedules survive restarts, watchers don't. After a reboot only
-   the deadline leg remains.
-
-## Later: the robust version (`await_condition`, gateway-native)
-
-If condition-waiting becomes a recurring pattern, the honest fix is a first-class
-gateway watcher living beside `scheduler.ts` (per Rule #2 it needs a task doc before any
-implementation). Sketch:
-
-- **Tool:** `await_condition({id, check, interval, timeout, message})` — the gateway
-  polls `check` (a shell predicate) every `interval` seconds and injects `message` the
-  moment it exits 0. `timeout` fires a "condition never came true" injection instead of
-  waiting forever.
-- **Persistence:** watches stored in thread config like schedules → survive gateway
-  restarts and machine reboots (poll loop resumes on startup). This alone removes
-  limitations 1, 2, and 4.
-- **Visibility:** `list_watches` / `cancel_watch` companions, same shape as
-  `list_schedules` / `cancel_schedule`; dashboard can surface pending watches.
-- **Reuse:** fires through the same `sendMessage` path as the scheduler, so queueing,
-  busy→idle drain, and history semantics are identical to today's injections.
-- **Design question to settle in the task doc:** the predicate is the gateway executing a
-  configured shell command. Fine for admin threads on a single-user box; under P7
-  namespace scoping it needs an allowlist or per-namespace opt-in before scoped keys can
-  create watches.
-
-Until then: watcher + deadline, as above.
+The key point was also a real hazard rather than a theoretical one: the recipe
+read `apiKeys[0]` — the gateway's **admin** key — and because it was seeded into
+every thread's content store as topic-free boilerplate, it surfaced on
+unrelated queries and taught an app's visitor-facing model to invent HTTP calls
+against the gateway (task 134). `run_job` needs no credential, and the seeded
+recipe has been deleted.