Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(adr): ADR-466 mission autopilot

ruv1a4eecada97f
diff --git a/v3/docs/adr/ADR-466-mission-autopilot.md b/v3/docs/adr/ADR-466-mission-autopilot.md
new file mode 100644
index 0000000000..07698b2269
--- /dev/null
+++ b/v3/docs/adr/ADR-466-mission-autopilot.md
@@ -0,0 +1,137 @@
+# ADR 466: Mission autopilot
+
+Status: Accepted
+
+Date: 2026-10-06
+
+Builds on: ADR-443 (mission control and its `/loop` manager), ADR-453 (Project Anatole), ADR-464 (the Workflows slot seams)
+
+## 1. Context
+
+A mission can run for days, but today every task hand-over asks. The request is an autopilot option: run, adapt and optimise
+for days or weeks without asking permission for in-scope actions. Three facts shape the design.
+
+**The engine's permission check is not ours to bypass.** The console's per-action confirm is its own; Claude Code's permission
+dialog on a tool call is the engine's. Autopilot removes the first, inside an approved scope. It cannot and must not remove the
+second: a step the person's own settings would block is parked, never performed on their behalf. Unattended running therefore
+also depends on those settings, which the console can only preflight (when the host offers a check) and report.
+
+**A session ends with its turn.** A `claude -p` session ends when its turn completes (spike: 1.9 s). A mod has no scheduler.
+Weeks of liveness come from the session living and the mission's existing `/loop` re-arm (ADR-443 §2.4); autopilot adds the
+per-tick checks and a `host.every` timer, never a scheduler of its own.
+
+**Status fields lie.** Probed on this machine, 2026-10-06:
+
+- `autopilot_status` answered `enabled: true, iterations 0, maxIterations 50, timeoutMinutes 240, tasks 0/0, percent 100,
+ elapsedMs 7377364917` (85 days: a stale session record) and `autopilot_progress` answered `0/0, percent 100`. A progress of
+ 100% with zero tasks, a 50-iteration and 4-hour ceiling, and a clock that never reset make it unusable as the loop's
+ authority. It is not called by the loop; `task_list` returned real tasks and is what the mission store already reads.
+- The ruflo swarm "execution is a no-op" defect means a task marked `completed` is a claim. A step is **done and verified** only
+ when the store says completed AND the envelope's own verify argvs exit 0; with none configured it is **done-unverified**, drawn
+ as such, and teaches the adaptation nothing.
+
+## 2. Decision
+
+### 2.1 The envelope (`data/ap-envelope.ts`)
+
+One scope contract, approved once: tool classes (`read edit test git-local git-branch network spawn mcp`), absolute folders,
+`owner/name` repos, a network host allowlist, named secret env vars (names, never values), spend ceilings per hour, day and
+total, a concurrency cap (1 to 8), a maximum duration (1 hour to 90 days), verify argvs, and a recorded consent to run
+without Anatole. Validation lists every problem and repairs nothing; an unknown field is an error, so nothing can smuggle in a
+grant. **Hard denies are a constant, not a field**: `publish release deploy force-push secret-access
+delete-outside-worktree envelope-edit`. An envelope naming one is rejected, and task text that names one is parked with a
+question that has no approve button (and the loop ignores an approve-once for it anyway).
+
+It is canonicalised, hashed (SHA-256 in plain TypeScript: no console module may assume `node:crypto`), versioned with a
+revision and sealed to `.claude-flow/console/autopilot/envelope.json`. On every tick the sealed hash must equal the hash the
+`start` journal line recorded; a file edited outside the console stops the loop. Any change is a new Start through the confirm
+card, which lists what the change **widens** (`widened(prev, next)`). The band shows `autopilot day 3 · $12/$40 · 2 parked`,
+each part from the journal, the ledger probe and the parked lines; an unread spend is `$n/a`, never `$0`.
+
+### 2.2 The loop (`data/ap-loop.ts`, `data/ap-journal.ts`, `ap-live.ts`)
+
+A pure machine: `foldJournal(events)` is the whole state and `tick(state, facts)` returns events to journal and at most one
+step to start. The order of its checks is the safety property: kill flag, then stopped/idle, then settle what is in flight
+(finished, failed, timed out, or an **orphan** from before a restart with no effect found), then paused, then envelope,
+duration, Anatole, spend, failure ladder, capacity, then the task. A step id is `hash(task, attempt)`; a task with a started or
+done step is never started again; a replayed line changes nothing. The decision is journaled **before** the hand-over: a crash
+between the two leaves a started step the next pass settles by its effect, never a step that ran unrecorded.
+
+The journal is an append-only JSONL file written through a fixed argv (`dd of=<path> oflag=append conv=notrunc`, one element
+for the path, after `checkNoLinks`), every free-text field washed and credential-masked before it is encoded. It is also the
+audit log. Past 80% of its 1.5 MB read cap it is archived beside itself and restarted from `snapshotEvents` (events that fold to
+the same live state). Failure budget 5 in a row pauses and notifies; one failure backs off 1 min, doubling to 1 hour; each step
+has a 30-minute timeout. A beat is journaled every 5 minutes while idle.
+
+Spend: unread waits (never runs on a guess); 80% of the total ceiling pauses (never cutting a step in flight: it is settled
+first); 100% stops; an hour or day ceiling holds the next step back until the window rolls. The reading is the cost ledger's
+list-price estimate for the whole project over the hour, day and run windows, so it over-counts rather than under-counts.
+
+The hand-over is the existing mission `dispatchSpec(...).run()` and `host.submitPrompt`: no executor of our own. To work past a
+parked task, the live module passes it a shadow record with the picked task first (same events, same task objects); the
+mission's own rule of one task at a time and not past a failed one is kept, so autopilot idles with a said reason rather than
+pretend otherwise.
+
+### 2.3 Adapting (`data/ap-adapt.ts`)
+
+It may tune step size, parallelism (never above the envelope's cap), the model tier per step class, the retry count and the
+ordering, each with a hard range, and nothing else (a path allowlist; `__proto__` or `concurrency` reach nothing). A change goes
+propose, then evaluate (a replay over the verified journal steps), then promote: the gate re-checks the result against the
+envelope and ranges and returns an **immutable receipt** whose hash chains to the one before (`verifyReceipts` finds an edited
+link). The current tunables are the fold of the receipts over the defaults, so they survive a restart and each is reversible
+from its own receipt. A **conservative** change (lower parallelism, higher tier, one more retry) needs evidence that the
+setting being left is failing. An **aggressive** one (higher parallelism, lower tier) needs a clean history on the setting being
+left and enters a **trial**: `reviewTrials` reverts it once the new setting does worse over 6 steps. Proposers exist for tier,
+parallelism and retries; step size and ordering are tunable and validated but have no proposer in this release (a said gap).
+Adaptation cannot widen the envelope, spend, tools, network, concurrency or release authority: the envelope is only read.
+
+### 2.4 Parking (`views/ap-parked.ts`)
+
+A task the envelope does not allow, that names a hard deny, that cannot be classified (`cls: null`: the classifier never
+defaults), that touches a path outside the folders, or that the permission preflight says would ask or deny, is **parked** with
+a question and a notice; the loop carries on with other work. The person answers approve once (that task, one step, then the
+envelope applies again) or deny (final). Retries past the policy also park.
+
+### 2.5 Safety
+
+- **Anatole**: the loop pauses when Anatole is off or absent unless the sealed envelope records `acceptWithoutAnatole`, and
+ Start refuses the same way, recording which it was in the `start` line.
+- **Kill**: `Stop` (key `9`), `/ruflo autopilot stop`, or the file `.claude-flow/console/autopilot/KILL`. The file is checked
+ first on every tick (one iteration), journals a stop and is sticky: only a confirmed Start removes it. Stop and Pause need no
+ confirm because they only narrow authority; Resume re-checks every gate on its next tick.
+- **Cost guard**, **digest** (once per UTC day, as a notice and a toast), **masked audit log**: as above.
+- **Permission preflight**: an optional injected `toolCheck` (the engine's `$.tool.check`) maps each class to a representative
+ tool; deny or ask parks the class. Absent, the panel says `preflight not wired` and the engine still decides per call.
+
+### 2.6 UI
+
+Slots only (`views/wf-slots.ts`): a board section "Mission autopilot" (band line, state, gates, sealed envelope, draft editor
+with live validation, Start / Pause / Resume / Stop / Check now, adaptation history with receipts and chain status), a board
+section for the parked queue, a key slot (`9`, stop), an action slot (`8`, start through the confirm card) and a notice slot.
+The editor has buttons for classes, ceilings, concurrency, duration and the Anatole consent; the list fields (folders, repos,
+network, verify) are loaded from `.claude-flow/console/autopilot/envelope.draft.json` and validated before use.
+
+## 3. Consequences
+
+- Inside an approved envelope the console no longer asks, for as long as the session lives. The person's exposure is the
+ envelope, the hard denies, the engine's own permission dialog, and the kill switch.
+- Autopilot is only as unattended as the person's permission settings are permissive, and only as long-lived as the session.
+- Every step that reached `done` without a verify command is flagged unverified; with none configured nothing is learned.
+- Parallelism above 1 is bounded in practice by the mission's own one-task-at-a-time dispatch.
+
+## 4. Test and benchmark plan
+
+`tests/ap-core.spec.ts` (40) and `tests/ap-live.spec.ts` (17), pure and fast: SHA-256 vectors; envelope validation, sealing,
+tamper, widening; journal round trip, washing and the fixed argv; every ordering rule of the machine; **kill-switch property**
+(60 seeded random walks: once the flag is seen no tick ever acts and nothing restarts the loop); **no double start** (60 walks:
+no task has two live steps, no id repeats); **crash-resume** (30 walks, a fresh fold at every third prefix, each orphan
+re-verified and never restarted in the same pass); compaction folds back; the adaptation gate, the chain, the trial revert, and
+a hostile-proposal sweep proving no tunable passes the envelope. Mutation checks run on the kill check, the Anatole gate, the
+hard-deny rule, the 100% stop, the envelope re-check and the hash pin: each turned its test red. Benchmark: `tick` is a pure
+function over at most 400 steps; an 80-tick walk (fold + tick each step) ran in about 1.5 ms here (60 walks in 88 ms).
+
+## 5. Rollback
+
+Remove the import line in `views/wf-register.ts` and the `wireAutopilot` call: the new modules are inert without them. The
+files under `.claude-flow/console/autopilot/` are the loop's own and can be deleted (the journal archive stays beside it).
+`/ruflo autopilot stop` or the KILL file halts a running loop first.