moflo 4.9.21 → 4.9.23

package/.claude/guidance/shipped/moflo-spell-scheduling.md

@@ -0,0 +1,225 @@
+# Spell Scheduling — Cron, Daemon, Catch-Up, and Failure Modes
+
+**Purpose:** Reference for spell scheduling — definition syntax, CLI subcommands, daemon lifecycle, catch-up window semantics, and the failure modes you will hit. For the user-driven `/spell-schedule` walkthrough, see `.claude/skills/spell-schedule/SKILL.md`. For the engine itself (steps, args, runner), see `.claude/guidance/moflo-spell-engine.md`.
+
+---
+
+## When to Schedule a Spell
+
+**Use scheduling when the spell must fire on a clock without a human present.** Don't reach for it for one-shot runs you can `flo spell cast` yourself.
+
+| Trigger | Use |
+|---------|-----|
+| "Run X every weekday at 9am" | Schedule with `--cron` |
+| "Run X every 6 hours" | Schedule with `--interval` |
+| "Run X once at <future time>" | Schedule with `--at` |
+| "Run X right now" | `flo spell cast -n X` — not a schedule |
+| "Run X when file Y changes" | Hook or worker — not a schedule |
+
+The scheduler is poll-based (1-minute floor). It is not a real-time trigger system.
+
+---
+
+## CLI Subcommands
+
+**All scheduling lives under `flo spell schedule`.** No external cron, no second runtime.
+
+| Subcommand | Purpose |
+|------------|---------|
+| `create -n <spell> --cron|--interval|--at <value>` | Create an ad-hoc schedule |
+| `list` (alias `ls`) | List all schedules (definitions only — does NOT prove they fired) |
+| `executions [--schedule <id>] [--limit N]` (alias `exec`, `history`) | Read the `schedule-executions` audit trail — the only way to confirm a schedule actually ran |
+| `cancel <schedule-id>` | Disable a schedule (soft delete — record stays, `enabled: false`) |
+
+**`list` shows what should fire. `executions` shows what did fire.** When verifying a new schedule, read `executions` — `list` only proves the record was written.
+
+---
+
+## Definition-Embedded Schedules
+
+**A spell can declare its schedule inline in YAML.** The daemon registers it on every start.
+
+```yaml
+name: nightly-audit
+schedule:
+  cron: "0 2 * * *"        # UTC, 5-field cron (minute hour day-of-month month day-of-week)
+  enabled: true            # default true; set false to keep the def without scheduling
+  mofloLevel: hooks        # optional cap (narrows scheduler-level cap, never widens)
+steps:
+  - id: audit
+    type: bash
+    config:
+      command: ./scripts/audit.sh
+```
+
+**Exactly one of `cron`, `interval`, or `at` must be set.** Validation rejects `cron: "invalid"`, `interval: "10w"` (only `s/m/h/d` units), or non-ISO datetimes — the spell fails to load before the scheduler ever sees it.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `cron` | string | 5-field, UTC, no seconds field |
+| `interval` | string | `<n>(s|m|h|d)` — `s` is allowed but ignored below 60s (poll floor) |
+| `at` | string | ISO 8601 datetime, must be in the future at load time |
+| `enabled` | bool | Defaults `true`; gate without deleting the record |
+| `mofloLevel` | enum | `read` < `hooks` < `swarm`; per-schedule cap — narrows only |
+
+Definition-embedded schedules get IDs of the form `sched-def-<spell-name>` (one per spell). Ad-hoc schedules get `sched-adhoc-<timestamp>-<rand>` (one per `flo spell schedule create`).
+
+---
+
+## Configuration in `moflo.yaml`
+
+**The scheduler is on by default.** Disable it without affecting other daemon workers via `scheduler.enabled: false`.
+
+```yaml
+scheduler:
+  enabled: true             # set false to disable scheduled spells
+  pollIntervalMs: 60000     # how often the scheduler checks for due spells
+  maxConcurrent: 2          # max concurrent scheduled spell executions
+  catchUpWindowMs: 3600000  # max age (ms) of a missed run that should still fire
+```
+
+All four fields are optional. **Non-positive values are rejected at load and replaced with the defaults** — `pollIntervalMs: 0` won't silently break the poll loop.
+
+Practical floors:
+- `pollIntervalMs` is the granularity floor. Sub-minute schedules don't fire faster.
+- `maxConcurrent: 1` serializes everything — useful when scheduled spells share a write lock.
+- `catchUpWindowMs: 0` disables catch-up entirely; missed runs are skipped on restart.
+
+---
+
+## Storage Namespaces
+
+**Two memory namespaces back the scheduler.** Both are project-scoped — schedules and history don't leak across projects.
+
+| Namespace | Contents | Written by | Read by |
+|-----------|----------|------------|---------|
+| `scheduled-spells` | `SpellSchedule` records (id, spellName, timing, nextRunAt, enabled, args) | `flo spell schedule create`, definition load | Scheduler poll loop, `flo spell schedule list` |
+| `schedule-executions` | `ScheduleExecution` audit records (startedAt, completedAt, success, error, duration, manualRun) | Scheduler at execute-start and execute-end | The Arcane Console, `flo spell schedule executions` |
+
+When debugging "did my schedule fire?", read `schedule-executions` directly via `mcp__moflo__memory_list namespace=schedule-executions` if the CLI is unavailable.
+
+---
+
+## Catch-Up Window Semantics
+
+**On daemon startup, schedules whose `nextRunAt` is in the past are evaluated against `catchUpWindowMs`.** This is the single most common source of "why didn't my run fire?" confusion.
+
+| Lag (now − nextRunAt) | Behavior | Event emitted |
+|-----------------------|----------|---------------|
+| ≤ `pollIntervalMs` | Treated as routine cron drift; fires on next poll | `schedule:due` only |
+| > `pollIntervalMs` and ≤ `catchUpWindowMs` | Fires on next poll as a caught-up run | `schedule:catchup` then `schedule:due` |
+| > `catchUpWindowMs` | Skipped; `nextRunAt` advances past the missed slot | `schedule:skipped` |
+
+This prevents a daemon that was offline for days from firing dozens of stale schedules at once.
+
+**One-time `at:` schedules past their trigger get auto-disabled rather than rescheduled.** Re-enabling returns `null` because there's no future run to compute.
+
+---
+
+## Concurrency and Overlap Rules
+
+**`maxConcurrent` (default 2) caps total in-flight scheduled spells.** Same-schedule overlap is never allowed regardless of `maxConcurrent`.
+
+| Situation | Outcome |
+|-----------|---------|
+| Same schedule's prior run still in flight when next fire is due | New fire skipped (`schedule:skipped`); regular cadence continues |
+| `maxConcurrent` saturated by other schedules | Due fire waits until next poll — nothing is queued |
+| Manual run via `runScheduleNow` (dashboard "Run now") | Runs outside the poll loop; respects per-schedule overlap; does NOT advance `nextRunAt` |
+
+There is no internal queue. A fire that didn't get a slot just shows up again on the next tick if it's still due.
+
+---
+
+## `mofloLevel` Composition for Scheduled Runs
+
+**Three caps compose for every scheduled cast; the most restrictive wins.** Per-schedule caps can never widen the scheduler-level cap.
+
+```
+effectiveLevel = min(
+  daemon.defaultMofloLevel,    // moflo.yaml scheduler-level cap
+  spell.mofloLevel,            // spell definition cap
+  schedule.mofloLevel          // per-schedule cap
+)
+```
+
+Where `min` follows the level lattice `read < hooks < swarm`. A spell that needs `swarm` cannot run if any cap above it is `hooks` or `read` — it fails the capability gate at execute time, not at schedule create time.
+
+---
+
+## Daemon Prerequisite and Cross-Platform Autostart
+
+**Schedules only fire while the daemon is running.** The scheduler is just code inside the daemon worker pool — no daemon, no schedules.
+
+For survival across reboot, register the OS-native autostart service:
+
+```bash
+flo daemon install     # one-time setup; idempotent
+flo daemon status      # shows registration AND running-process state
+flo daemon uninstall   # remove the autostart hook
+```
+
+| Platform | Mechanism | Path |
+|----------|-----------|------|
+| macOS | launchd `LaunchAgent` | `~/Library/LaunchAgents/com.moflo.daemon.plist` |
+| Linux | systemd `--user` unit | `~/.config/systemd/user/moflo-daemon.service` |
+| Windows | Task Scheduler `ONLOGON` | Task name `MoFloDaemon` (via `schtasks`) |
+
+`flo spell schedule create` prompts to install the autostart service when none is registered, so a freshly-scheduled spell survives the next reboot without an extra step. Cancel the last enabled schedule and the service is auto-removed (so an idle daemon doesn't autostart forever).
+
+---
+
+## Scheduler Event Types
+
+**The scheduler emits typed events the daemon forwards to the dashboard event stream.** Subscribe via `scheduler.on(listener)`; the returned function unsubscribes. Listener exceptions are caught so a misbehaving subscriber can't break the poll loop.
+
+| Event | When |
+|-------|------|
+| `schedule:catchup` | A missed run (lag > one poll interval, within catch-up window) is about to fire |
+| `schedule:due` | A schedule is due (always emitted, with or without catch-up) |
+| `schedule:started` | Execution started; an execution record exists in `schedule-executions` |
+| `schedule:completed` | Execution finished with `success: true` |
+| `schedule:failed` | Execution finished with `success: false` or threw |
+| `schedule:skipped` | Execution skipped (overlap, expired catch-up, missing spell, sandbox-required mismatch) |
+| `schedule:disabled` | Schedule disabled (manual cancel or auto-disable because the spell vanished) |
+
+---
+
+## Common Failure Modes
+
+**Most "schedule isn't firing" reports trace to one of these.** Walk the list before reading scheduler source.
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `executions` is empty after the schedule's `nextRunAt` passed | Daemon not running | `flo daemon status` → `flo daemon start`; install autostart |
+| `executions` shows `schedule:skipped` repeatedly | Same-schedule overlap (prior run never finished) | Check the spell — likely hung; cancel, fix, recreate |
+| `executions` shows `schedule:skipped` once at startup | `nextRunAt` outside `catchUpWindowMs` | Expected after a long outage; next normal fire will land |
+| Run fires but spell errors `SANDBOX_REQUIRED` | Spell needs `sandbox: required` and host doesn't supply one | Install sandbox runtime (Docker/bwrap) or remove `sandbox.required` from the spell |
+| Schedule auto-disabled with `schedule:disabled` event | The spell name no longer resolves in the grimoire | Restore the spell file, then re-enable the schedule |
+| Cron fires an hour off | Cron is UTC; user-typed time was local | Convert to UTC before `--cron`; see `/spell-schedule` skill |
+| `executions` shows `success: true` but no side-effect | Spell ran but interpolation/credentials failed silently inside a step | Run the spell manually (`flo spell cast -n <name>`) and inspect step output |
+
+---
+
+## Verification Recipe (Schedule Round-Trip)
+
+**To confirm a fresh schedule works end-to-end without waiting for the cron tick:**
+
+1. Create the schedule with `--interval 1m` (or `--at` near the current time).
+2. `flo spell schedule list` → verify `nextRunAt` is in the next minute.
+3. `flo daemon status` → confirm running.
+4. Wait one poll cycle (~60s).
+5. `flo spell schedule executions --schedule <id>` → expect one row with `success: true`.
+6. Cancel and recreate with the real cadence.
+
+If step 5 is empty, jump straight to the failure-modes table above — don't loop in step 4.
+
+---
+
+## See Also
+
+- `.claude/skills/spell-schedule/SKILL.md` — User-facing walkthrough for creating a schedule (procedural counterpart to this reference)
+- `.claude/guidance/moflo-spell-engine.md` — Definition format, step types, variable interpolation
+- `.claude/guidance/moflo-spell-runner.md` — Execution lifecycle, dry-run, layering, errors
+- `.claude/guidance/moflo-spell-sandboxing.md` — Capability levels (`read`/`hooks`/`swarm`) referenced by the `mofloLevel` cap
+- `.claude/guidance/moflo-spell-troubleshooting.md` — Broader spell failure-mode catalog beyond scheduling
+- `.claude/guidance/moflo-core-guidance.md` — CLI, hooks, daemon, MCP reference hub

package/.claude/guidance/shipped/moflo-spell-troubleshooting.md

@@ -144,6 +144,7 @@ A step appears to run (`exitCode: 0`), produces no output, and downstream steps
 - `.claude/guidance/moflo-spell-sandboxing.md` — Capability types, enforcement layers, permission levels (the model these failures exercise)
 - `.claude/guidance/moflo-spell-engine.md` — Step definition format and types
 - `.claude/guidance/moflo-spell-runner.md` — Dry-run validation, error codes, pause/resume
+- `.claude/guidance/moflo-spell-scheduling.md` — Scheduled-spell-specific failure modes (catch-up window, overlap, missing spell auto-disable, daemon-down)
 - `.claude/guidance/moflo-yaml-reference.md` — `sandbox:` block in `moflo.yaml` (master toggle, tier selection)
 - `src/cli/spells/core/bwrap-sandbox.ts` — Source for `--unshare-net` and namespace setup
 - `src/cli/spells/core/permission-resolver.ts` — Capability → permission level derivation

package/.claude/helpers/gate.cjs

@@ -7,7 +7,7 @@ var cp = require('child_process');
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {}, flMode: null, swarmInitialized: false, hiveInitialized: false };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -60,7 +60,7 @@ function writeState(s) {
 
 // Load moflo.yaml gate config (defaults: all enabled)
 function loadGateConfig() {
-  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true };
+  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true, swarm_invocation_gate: true };
   try {
     var yamlPath = path.join(PROJECT_DIR, 'moflo.yaml');
     if (fs.existsSync(yamlPath)) {
@@ -71,6 +71,7 @@ function loadGateConfig() {
       if (/testing_gate:\s*false/i.test(content)) defaults.testing_gate = false;
       if (/simplify_gate:\s*false/i.test(content)) defaults.simplify_gate = false;
       if (/learnings_gate:\s*false/i.test(content)) defaults.learnings_gate = false;
+      if (/swarm_invocation_gate:\s*false/i.test(content)) defaults.swarm_invocation_gate = false;
     }
   } catch (e) { /* use defaults */ }
   return defaults;
@@ -111,6 +112,21 @@ var NS_NAV_RES = [
   /\b(class|function|method|component|service|entity|module)\b/,
 ];
 
+// Detect whether the current prompt invoked /fl or /flo with a swarm/hive flag (#952).
+// When set, check-before-agent BLOCKS the Agent spawn until the matching MCP init
+// (mcp__moflo__swarm_init or mcp__moflo__hive-mind_init) has been recorded — the user
+// explicitly opted in to the protected coordination surface, so falling back to
+// raw Agent dispatch silently regresses headline moflo product capability.
+//
+// SYNC: duplicated verbatim in src/cli/init/helpers-generator.ts.
+function detectFlMode(promptText) {
+  var p = promptText || '';
+  if (!/^\s*\/(?:fl|flo)\b/i.test(p)) return null;
+  if (/(?:^|\s)(?:-s|--swarm)\b/.test(p)) return 'swarm';
+  if (/(?:^|\s)(?:-h|--hive)\b/.test(p)) return 'hive';
+  return null;
+}
+
 function classifyNamespaceHint(promptText) {
   var lower = (promptText || '').toLowerCase();
   if (NS_TEST_RE.test(lower)) return 'Memory namespace hint: use "tests" for test inventory and coverage lookups.';
@@ -154,6 +170,12 @@ function applyPromptStateReset(state, promptText) {
   // subsequent agents (parent + subagents that spawn their own agents) all
   // see the new classification on their first check-before-agent.
   state.lastNamespaceHintEmittedBy = {};
+  // #952 — derive flMode from the user prompt, and reset the matching init
+  // flag. Each /fl invocation must call its protected MCP init; the previous
+  // prompt's swarm/hive registration does not satisfy this prompt's gate.
+  state.flMode = detectFlMode(promptText);
+  state.swarmInitialized = false;
+  state.hiveInitialized = false;
 }
 // Match npm/yarn/pnpm/bun test, npx vitest|jest|..., bare runners at command-start only,
 // and language-native test commands. The bare-runner arm is anchored so that
@@ -305,6 +327,47 @@ switch (command) {
         writeState(s);
       }
     }
+    // #952 — when /fl was invoked with -s/-h, the protected MCP init must run
+    // BEFORE any Agent spawn. Hard block: the user explicitly opted in to
+    // moflo's coordination surface, so silently dispatching `Agent` calls
+    // without `mcp__moflo__swarm_init` / `mcp__moflo__hive-mind_init` is the
+    // failure mode this gate exists to prevent (CLAUDE.md "⛔ Protected
+    // functionality — swarm + hive-mind"). Other Agent uses remain advisory.
+    if (config.swarm_invocation_gate) {
+      if (s.flMode === 'swarm' && !s.swarmInitialized) {
+        process.stderr.write('BLOCKED: /fl was invoked with -s/--swarm but mcp__moflo__swarm_init has not been called.\n');
+        process.stderr.write('Run mcp__moflo__swarm_init first, then mcp__moflo__agent_spawn for each role, then dispatch Agent.\n');
+        process.stderr.write('See .claude/skills/fl/execution-modes.md "SWARM mode" and CLAUDE.md "⛔ Protected functionality".\n');
+        process.stderr.write('Disable via moflo.yaml: gates: swarm_invocation_gate: false\n');
+        process.exit(2);
+      }
+      if (s.flMode === 'hive' && !s.hiveInitialized) {
+        process.stderr.write('BLOCKED: /fl was invoked with -h/--hive but mcp__moflo__hive-mind_init has not been called.\n');
+        process.stderr.write('Run mcp__moflo__hive-mind_init first, then dispatch Agent or hive-mind workers.\n');
+        process.stderr.write('See .claude/skills/fl/execution-modes.md "HIVE-MIND mode" and CLAUDE.md "⛔ Protected functionality".\n');
+        process.stderr.write('Disable via moflo.yaml: gates: swarm_invocation_gate: false\n');
+        process.exit(2);
+      }
+    }
+    break;
+  }
+  case 'record-swarm-init': {
+    // #952 — wired to mcp__moflo__swarm_init PostToolUse. Marks the gate
+    // satisfied so subsequent Agent spawns under /fl -s pass.
+    var s = readState();
+    if (!s.swarmInitialized) {
+      s.swarmInitialized = true;
+      writeState(s);
+    }
+    break;
+  }
+  case 'record-hive-init': {
+    // #952 — wired to mcp__moflo__hive-mind_init PostToolUse.
+    var s = readState();
+    if (!s.hiveInitialized) {
+      s.hiveInitialized = true;
+      writeState(s);
+    }
     break;
   }
   case 'check-before-scan': {
@@ -508,7 +571,11 @@ switch (command) {
     break;
   }
   case 'session-reset': {
-    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} });
+    // Derive from STATE_DEFAULTS so adding a new state field requires only one
+    // edit (the defaults object) — the literal that used to live here drifted
+    // every time a field was added and is what motivated #952's audit of state
+    // shape consistency.
+    writeState(Object.assign({}, STATE_DEFAULTS, { sessionStart: new Date().toISOString() }));
     break;
   }
   default:

package/.claude/skills/fl/execution-modes.md

@@ -4,7 +4,9 @@ The execution mode chooses how work is carried out across the phases. Pass `-s/-
 
 ## SWARM mode (`-s`, `--swarm`)
 
-Swarm mode spawns agents via the Task tool.
+> **MANDATORY when `-s` is passed.** Your first Execute-phase action MUST be `mcp__moflo__swarm_init`, followed by `mcp__moflo__agent_spawn` for each role. Spawning subagents via `Agent` (or `Task`) without first registering the swarm is a violation of issue #952. The `Agent` PreToolUse gate will BLOCK the call until `swarm_init` runs. Even when you also use `Agent` for parallelism, the moflo swarm IS the registration surface — call it first. See CLAUDE.md "⛔ Protected functionality — swarm + hive-mind".
+
+Swarm mode coordinates agents through the moflo swarm coordinator, then spawns workers via the `Agent` tool.
 
 Roles:
 - `researcher` — analyzes the issue, searches memory, finds patterns
@@ -13,36 +15,57 @@ Roles:
 - `/flo-simplify` — moflo's adaptive code review skill (sized to diff, parallel agents on big changes)
 - `reviewer` — reviews code before PR
 
-Pattern:
+Required pattern:
 ```javascript
 // 1. Create the task list first
-TaskCreate({ subject: "Research issue", ... })
-TaskCreate({ subject: "Implement changes", ... })
-TaskCreate({ subject: "Test implementation", ... })
-TaskCreate({ subject: "Run /flo-simplify on changed files", ... })
-TaskCreate({ subject: "Review and PR", ... })
+TaskCreate({ subject: "📋 [Researcher] Research issue", ... })
+TaskCreate({ subject: "💻 [Coder] Implement changes", ... })
+TaskCreate({ subject: "🧪 [Tester] Test implementation", ... })
+TaskCreate({ subject: "🔍 [Reviewer] Run /flo-simplify on changed files", ... })
+
+// 2. Init the swarm — MANDATORY, gate-enforced
+mcp__moflo__swarm_init({ topology: "hierarchical", maxAgents: 8, strategy: "specialized" })
 
-// 2. Init the swarm
-Bash("flo swarm init --topology hierarchical --max-agents 8 --strategy specialized")
+// 3. Register each agent with the coordinator — MANDATORY
+mcp__moflo__agent_spawn({ type: "researcher", ... })
+mcp__moflo__agent_spawn({ type: "coder", ... })
+mcp__moflo__agent_spawn({ type: "tester", ... })
+mcp__moflo__agent_spawn({ type: "reviewer", ... })
 
-// 3. Spawn agents (run_in_background: true)
-Task({ prompt: "...", subagent_type: "researcher", run_in_background: true })
-Task({ prompt: "...", subagent_type: "coder", run_in_background: true })
+// 4. Now safe to dispatch via Agent tool for parallel execution
+Agent({ prompt: "...", subagent_type: "researcher", run_in_background: true })
+Agent({ prompt: "...", subagent_type: "coder", run_in_background: true })
 
-// 4. Wait for results, synthesize, continue
+// 5. Wait for results, synthesize, continue
 ```
 
 ## HIVE-MIND mode (`-h`, `--hive`)
 
+> **MANDATORY when `-h` is passed.** Your first Execute-phase action MUST be `mcp__moflo__hive-mind_init`. The `Agent` PreToolUse gate will BLOCK any subagent spawn until hive-mind init has run. See CLAUDE.md "⛔ Protected functionality — swarm + hive-mind".
+
 Use for consensus-based decisions:
 - Architecture choices
 - Approach tradeoffs
 - Design decisions with multiple valid options
 
+Required pattern:
+```javascript
+// 1. Init the hive — MANDATORY, gate-enforced
+mcp__moflo__hive-mind_init({ ... })
+
+// 2. Spawn workers + reach consensus via mcp__moflo__hive-mind_consensus
+mcp__moflo__hive-mind_spawn({ ... })
+mcp__moflo__hive-mind_consensus({ ... })
+```
+
 ## NORMAL mode (default)
 
 Single Claude execution without spawning sub-agents.
-- Still uses the Task tool for tracking
+- Still uses TaskCreate for tracking
 - Still creates tasks for visibility
 - Post-task neural learning hooks still fire
-- No agent spawning
+- No agent spawning, no swarm/hive init required
+
+## Why these are MANDATORY
+
+Swarm and hive-mind are headline moflo product surface (CLAUDE.md "⛔ Protected functionality"). When the user explicitly opts in via `-s`/`-h`, the protected MCP surface MUST be exercised — falling back to "Claude-native parallelism" via `Agent` tool calls without coordinator registration is the failure mode that prompted issue #952. The PreToolUse gate enforces this; opt-out is `gates.swarm_invocation_gate: false` in `moflo.yaml`.

package/.claude/skills/fl/phases.md

@@ -2,6 +2,47 @@
 
 Phase-by-phase notes for the full `/flo <issue>` run. Phase 2 (Ticket) lives in `./ticket.md`.
 
+## Phase 0: Record run start (Flo Runs dashboard)
+
+Before research, write a row to the `tasklist` namespace so the Arcane Console "Flo Runs" tab shows this run live and after the next session restart (#968). Skip this phase ONLY when `--epic-branch` is set — the epic orchestrator owns the parent record and the per-story spell engine writes its own row.
+
+Compute and **remember** for Phase 5:
+- `runId` — `flo-<issue-number-or-"new">-<startedAt-ms>` (sortable, unique).
+- `startedAt` — `Date.now()` snapshot (ms since epoch).
+
+Pick the matching `context.type`:
+| Mode | type | label format |
+|------|------|--------------|
+| Full / ticket on existing issue | `ticket` | `#<n> — <title>` |
+| `-r` research | `research` | `#<n> — Research` |
+| `-t` with title (no issue # yet) | `new-ticket` | `New: <title>` |
+| Epic detected | `epic` | `Epic #<n> — <title> (0/<total> stories)` |
+| `-wf <spell>` | `spell` | `<spell-name> → <args>` |
+
+Then call once:
+
+```
+mcp__moflo__memory_store
+  namespace: "tasklist"
+  key: "<runId>"
+  upsert: true
+  value: {
+    "status": "running",
+    "context": {
+      "type": "<ticket|research|new-ticket|epic|spell>",
+      "label": "<computed label>",
+      "issueNumber": <n | omit>,
+      "issueTitle": "<title | omit>",
+      "execMode": "<normal|swarm|hive>"
+    },
+    "spellName": "<same as label>",
+    "startedAt": <startedAt>,
+    "updatedAt": "<new Date().toISOString()>"
+  }
+```
+
+The schema mirrors `storeFloRunRecord` in `src/cli/services/daemon-dashboard.ts` — keep it in sync if you ever change one. The session-start launcher retains the most recent ~200 tasklist rows so this record outlives the session and renders in the Flo Runs tab on subsequent restarts.
+
 ## Phase 1: Research (also `-r`)
 
 ### 1.1 Fetch the issue + history (cheap, before any file exploration)
@@ -150,3 +191,29 @@ Closes #<issue-number>"
 gh issue edit <issue-number> --remove-label "in-progress" --add-label "ready-for-review"
 gh issue comment <issue-number> --body "PR created: <pr-url>"
 ```
+
+### 5.5 Finalize run record (Flo Runs dashboard)
+
+Update the tasklist row written in Phase 0 with the terminal status. Same `runId`, `upsert: true`. On success:
+
+```
+mcp__moflo__memory_store
+  namespace: "tasklist"
+  key: "<runId>"          # same key from Phase 0
+  upsert: true
+  value: {
+    "status": "completed",
+    "success": true,
+    "context": <same context object as Phase 0>,
+    "spellName": "<same label as Phase 0>",
+    "startedAt": <startedAt from Phase 0>,
+    "duration": <Date.now() - startedAt>,
+    "updatedAt": "<new Date().toISOString()>"
+  }
+```
+
+On failure (tests still red after retries, or any aborting error): same shape with `"status": "failed"`, `"success": false`, and an `"error": "<short summary>"` field.
+
+This finalize call MUST also fire if the run aborts *before* reaching Phase 5 (early failure during research, ticket, or implement) — otherwise the dashboard shows a permanently "running" row for a dead run.
+
+Skip this when `--epic-branch` is set — the epic orchestrator records its own outcome.

package/.claude/skills/spell-schedule/SKILL.md

@@ -39,9 +39,19 @@ npx flo doctor 2>&1 | grep -i daemon
 
 If the daemon is not running, prompt the user:
 - "The moflo daemon isn't running. Schedules only fire while the daemon is up. Start it now?"
-- If yes: `npx flo daemon start` (or instruct them to enable OS autostart for survival across reboots).
+- If yes: `npx flo daemon start`.
 - If they decline, warn the user that the schedule will be created but won't fire until the daemon is started.
 
+OS-native autostart (launchd / systemd / Task Scheduler) is **automatic**: the
+first `flo spell schedule create` registers the daemon as a login service so
+schedules survive reboot, and the cancel that takes the enabled-schedule count
+to 0 unregisters it. Users only need to think about it in two cases:
+
+- `--no-autostart` on `create` — skip registration (use in containers/CI where
+  the daemon is already managed externally).
+- `--keep-autostart` on `cancel` — keep the login service registered through a
+  cancel-then-recreate dance.
+
 ### Step 2 — Identify the target spell
 
 If `$ARGUMENTS` was provided, use it as the spell name/alias. Otherwise, list spells and let the user pick:
@@ -107,17 +117,20 @@ Capture the schedule ID from output and surface it to the user along with the ne
 
 ### Step 5 — Verify the wiring
 
-Tail the schedule executions for the first fire so the user can confirm the daemon actually picks it up:
+Tail the actual execution history for this schedule so the user can confirm the daemon picked it up:
 
 ```bash
-npx flo spell schedule list 2>&1
+npx flo spell schedule executions --schedule <schedule-id> 2>&1
 ```
 
-If the user wants to wait for the first fire (interval ≤ 5m), poll `flo spell schedule list` or the daemon dashboard. Otherwise, summarize and exit:
+`executions` reads from the daemon-written `schedule-executions` namespace and shows started time, status (success/failed/running), duration, and whether the run was manual. This is the only command that proves a schedule actually fired — `flo spell schedule list` only shows the schedule definition.
+
+If the user wants to wait for the first fire (interval ≤ 5m), poll `flo spell schedule executions --schedule <id>` or watch The Arcane Console (the daemon's localhost UI). Otherwise, summarize and exit:
 
 ```
 Scheduled: <schedule-id>
 Next run:  <ISO datetime UTC> (<local-equivalent>)
+Verify:    npx flo spell schedule executions --schedule <schedule-id>
 Cancel:    npx flo spell schedule cancel <schedule-id>
 ```
 
@@ -139,7 +152,7 @@ If the user asks to **run now** without altering the cadence:
 
 ## Important — gotchas
 
-- **Daemon prerequisite**: schedules only fire while the daemon is running. Tell the user this explicitly. For survival across reboots, `flo daemon install` registers the OS-level autostart service.
+- **Daemon prerequisite**: schedules only fire while the daemon is running. Tell the user this explicitly. OS autostart for reboot survival is now wired automatically — see Step 1.
 - **Catch-up window** (default 1h, `scheduler.catchUpWindowMs` in `moflo.yaml`): if the daemon was offline when a run was due, runs within the window still fire on the next poll. Older missed runs are skipped with a `schedule:skipped` event.
 - **maxConcurrent** (default 2): caps the number of scheduled spells running concurrently. Same-schedule overlap is never allowed.
 - **No update CLI yet**: `flo spell schedule` exposes create/list/cancel only. To change a cadence, cancel + recreate.

package/README.md

@@ -419,7 +419,7 @@ flo daemon status    # shows whether the service is registered AND running
 
 `flo spell schedule create` warns when the daemon isn't installed so you don't quietly miss runs.
 
-**Monitoring.** The daemon dashboard surfaces live schedules, recent executions, and per-schedule controls (disable / re-enable / run now). It starts alongside the daemon at `http://localhost:3117` (override with `--dashboard-port` or disable with `--no-dashboard`).
+**Monitoring.** **The Arcane Console** (the moflo daemon's localhost UI) surfaces live schedules, recent executions, and per-schedule controls (disable / re-enable / run now). It starts alongside the daemon at `http://localhost:3117` (override with `--dashboard-port` or disable with `--no-dashboard`).
 
 For full configuration (`scheduler:` block in `moflo.yaml`), event types, and the catch-up window after restarts, see [docs/SPELLS.md#scheduling](docs/SPELLS.md#scheduling).