moflo 4.9.22 → 4.9.24

package/.claude/guidance/shipped/moflo-cli-reference.md

@@ -130,22 +130,25 @@ npx flo daemon start
 | `coverage-suggest` | Suggest coverage improvements            | `--path`                                    |
 | `coverage-gaps`    | List coverage gaps with priorities       | `--format`, `--limit`                       |
 
-### 12 Background Workers
-
-| Worker        | Priority | Description                |
-|---------------|----------|----------------------------|
-| `ultralearn`  | normal   | Deep knowledge acquisition |
-| `optimize`    | high     | Performance optimization   |
-| `consolidate` | low      | Memory consolidation       |
-| `predict`     | normal   | Predictive preloading      |
-| `audit`       | critical | Security analysis          |
-| `map`         | normal   | Codebase mapping           |
-| `preload`     | low      | Resource preloading        |
-| `deepdive`    | normal   | Deep code analysis         |
-| `document`    | normal   | Auto-documentation         |
-| `refactor`    | normal   | Refactoring suggestions    |
-| `benchmark`   | normal   | Performance benchmarking   |
-| `testgaps`    | normal   | Test coverage analysis     |
+### Background Workers
+
+The daemon ships nine workers — four scheduled by default plus five
+manual-trigger only. The pre-#970 `audit`, `predict`, and `document`
+workers were removed because they ran without a surfacing layer for
+findings; if AI-driven security scanning returns it should be an opt-in
+`flo doctor` one-shot, not a recurring background task.
+
+| Worker        | Priority | Default       | Description                |
+|---------------|----------|---------------|----------------------------|
+| `map`         | normal   | scheduled 15m | Codebase mapping           |
+| `optimize`    | high     | scheduled 15m | Performance optimization   |
+| `consolidate` | low      | scheduled 30m | Memory consolidation       |
+| `testgaps`    | normal   | scheduled 20m | Test coverage analysis     |
+| `ultralearn`  | normal   | manual        | Deep knowledge acquisition |
+| `refactor`    | normal   | manual        | Refactoring suggestions    |
+| `deepdive`    | normal   | manual        | Deep code analysis         |
+| `benchmark`   | normal   | manual        | Performance benchmarking   |
+| `preload`     | low      | manual        | Resource preloading        |
 
 ### Essential Hook Commands (MCP Preferred)
 

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -126,8 +126,6 @@ For the full `moflo.yaml` schema, gate toggles, model routing, and sandbox confi
 |---------|--------|---------|
 | After major refactor | `optimize` | Performance optimization |
 | After adding features | `testgaps` | Find missing test coverage |
-| After security changes | `audit` | Security analysis |
-| After API changes | `document` | Update documentation |
 | Every 5+ file changes | `map` | Update codebase map |
 | Complex debugging | `deepdive` | Deep code analysis |
 

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

@@ -128,6 +128,7 @@ Credential values listed in `RunnerOptions.credentialValues` are automatically r
 
 - `.claude/guidance/moflo-spell-engine.md` — Definition format, step types, variable interpolation
 - `.claude/guidance/moflo-spell-sandboxing.md` — Capability-based security and permission levels
+- `.claude/guidance/moflo-spell-scheduling.md` — Cron / interval / one-time scheduling, daemon lifecycle, catch-up window, `schedule-executions` audit trail
 - `.claude/guidance/moflo-spell-troubleshooting.md` — Common failure modes when running spells
 - `.claude/guidance/moflo-spell-custom-steps.md` — Pluggable step commands
 - `.claude/guidance/moflo-spell-connectors.md` — Resource connectors and the registry

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 Luminarium, `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/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 Luminarium "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 Luminarium (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 Luminarium** (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).
 

package/bin/index-guidance.mjs

@@ -131,6 +131,18 @@ function loadGuidanceDirs() {
   // 3. CLAUDE.md files are NOT indexed — Claude loads them into context automatically.
   //    Indexing them wastes vectors and creates duplicate keys across subprojects.
 
+  // 4. Project skills — index .claude/skills/<name>/SKILL.md
+  const projectSkillsDir = resolve(projectRoot, '.claude/skills');
+  if (existsSync(projectSkillsDir)) {
+    dirs.push({ path: '.claude/skills', prefix: 'skill', fileFilter: ['SKILL.md'], kind: 'skill' });
+  }
+
+  // 5. Bundled moflo skills — gated by isSelfRef to prevent double-indexing
+  const bundledSkillsDir = resolve(mofloRoot, '.claude/skills');
+  if (!isSelfRef && existsSync(bundledSkillsDir) && resolve(bundledSkillsDir) !== resolve(projectSkillsDir)) {
+    dirs.push({ path: bundledSkillsDir, prefix: 'skill-bundled', fileFilter: ['SKILL.md'], kind: 'skill', absolute: true });
+  }
+
   return dirs;
 }
 
@@ -513,10 +525,12 @@ function buildHierarchy(chunks, chunkPrefix) {
   return hierarchy;
 }
 
-function indexFile(db, filePath, keyPrefix) {
-  const fileName = basename(filePath, extname(filePath));
+function indexFile(db, filePath, keyPrefix, options = {}) {
+  const fileName = options.nameOverride || basename(filePath, extname(filePath));
   const docKey = `doc-${keyPrefix}-${fileName}`;
   const chunkPrefix = `chunk-${keyPrefix}-${fileName}`;
+  const extraMetadata = options.extraMetadata || {};
+  const extraTags = options.extraTags || [];
 
   try {
     const content = readFileSync(filePath, 'utf-8');
@@ -538,6 +552,7 @@ function indexFile(db, filePath, keyPrefix) {
 
     // 1. Store full document
     const docMetadata = {
+      ...extraMetadata,
       type: 'document',
       filePath: relativePath,
       fileSize: stats.size,
@@ -547,7 +562,7 @@ function indexFile(db, filePath, keyPrefix) {
       ragVersion: '2.0',  // Mark as full RAG indexed
     };
 
-    storeEntry(db, docKey, content, docMetadata, [keyPrefix, 'document']);
+    storeEntry(db, docKey, content, docMetadata, [keyPrefix, 'document', ...extraTags]);
     debug(`Stored document: ${docKey}`);
 
     // 2. Chunk and store semantic pieces with full RAG linking
@@ -567,7 +582,7 @@ function indexFile(db, filePath, keyPrefix) {
       children: siblings,
       chunkCount: chunks.length,
     };
-    storeEntry(db, docKey, content, docChildrenMeta, [keyPrefix, 'document']);
+    storeEntry(db, docKey, content, docChildrenMeta, [keyPrefix, 'document', ...extraTags]);
 
     for (let i = 0; i < chunks.length; i++) {
       const chunk = chunks[i];
@@ -589,6 +604,7 @@ function indexFile(db, filePath, keyPrefix) {
       const hierInfo = hierarchy[chunkKey];
 
       const chunkMetadata = {
+        ...extraMetadata,
         type: 'chunk',
         ragVersion: '2.0',
 
@@ -647,7 +663,7 @@ function indexFile(db, filePath, keyPrefix) {
         chunkKey,
         searchableContent,
         chunkMetadata,
-        [keyPrefix, 'chunk', `level-${chunk.level}`, chunk.title.toLowerCase().replace(/[^a-z0-9]+/g, '-')]
+        [keyPrefix, 'chunk', `level-${chunk.level}`, chunk.title.toLowerCase().replace(/[^a-z0-9]+/g, '-'), ...extraTags]
       );
 
       debug(`  Stored chunk ${i}: ${chunk.title} (${chunk.content.length} chars, prev=${!!prevChunk}, next=${!!nextChunk})`);
@@ -699,7 +715,17 @@ function indexDirectory(db, dirConfig) {
     : allMdFiles;
 
   for (const filePath of filtered) {
-    const result = indexFile(db, filePath, dirConfig.prefix);
+    let options = {};
+    if (dirConfig.kind === 'skill') {
+      // kind: 'skill' — key by parent dir name (skill folder), not SKILL.md
+      const skillName = basename(dirname(filePath));
+      options = {
+        nameOverride: skillName,
+        extraMetadata: { kind: 'skill', skill_name: skillName },
+        extraTags: ['skill', `skill-${skillName}`],
+      };
+    }
+    const result = indexFile(db, filePath, dirConfig.prefix, options);
     results.push(result);
   }
 

package/bin/session-start-launcher.mjs

@@ -1435,14 +1435,15 @@ try {
   } catch { /* writing the failure itself must not throw */ }
 }
 
-// ── 3e-729. Purge ephemeral-namespace rows (#729) ───────────────────────────
-// Four namespaces (hive-mind, tasklist, epic-state, test-bridge-fix) store
-// internal moflo run-tracking — never user knowledge — and were polluting the
-// embeddings index. Going forward, writes to those namespaces skip embedding
-// generation (see EPHEMERAL_NAMESPACES in memory/bridge-embedder.ts); existing
-// rows from prior versions get hard-deleted here. Idempotent — returns
-// `purged: 0` once the DB is clean. Runs BEFORE background MCP/daemon spawn
-// so the foreground sql.js write isn't overwritten by a concurrent flush.
+// ── 3e-729. Purge ephemeral-namespace rows + trim tasklist (#729, #968) ─────
+// Three namespaces (hive-mind, epic-state, test-bridge-fix) store internal
+// run-tracking and get hard-deleted on every session start. The fourth
+// embedding-skipped namespace, `tasklist`, backs the dashboard's Flo Runs
+// tab — it's *trimmed* to a retention cap instead of purged so prior runs
+// survive a session restart (#968). Idempotent: returns
+// `{ purged: 0, trimmed: 0 }` when nothing needs cleaning. Runs BEFORE the
+// background MCP/daemon spawn so the foreground sql.js write isn't
+// overwritten by a concurrent flush.
 try {
   const purgePaths = [
     resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/ephemeral-namespace-purge.js'),
@@ -1458,6 +1459,12 @@ try {
         `${plural(result.purged, 'row')} from internal run-tracking`,
       );
     }
+    if (result?.trimmed > 0) {
+      emitMutation(
+        'trimmed flo run history',
+        `${plural(result.trimmed, 'old row')} beyond retention cap`,
+      );
+    }
   }
 } catch (err) {
   // Non-fatal — leftover rows just sit until the next session retries.