@luckydraw/cumulus 1.0.4 → 1.0.5

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",