moflo 4.12.1 → 4.12.3-rc.1

package/.claude/agents/base-template-generator.md

@@ -1,6 +1,6 @@
 ---
 name: base-template-generator
-description: Use this agent when you need to create foundational templates, boilerplate code, or starter configurations for new projects, components, or features. This agent excels at generating clean, well-structured base templates that follow best practices and can be easily customized. Examples: <example>Context: User needs to start a new React component and wants a solid foundation. user: 'I need to create a new user profile component' assistant: 'I'll use the base-template-generator agent to create a comprehensive React component template with proper structure, TypeScript definitions, and styling setup.' <commentary>Since the user needs a foundational template for a new component, use the base-template-generator agent to create a well-structured starting point.</commentary></example> <example>Context: User is setting up a new API endpoint and needs a template. user: 'Can you help me set up a new REST API endpoint for user management?' assistant: 'I'll use the base-template-generator agent to create a complete API endpoint template with proper error handling, validation, and documentation structure.' <commentary>The user needs a foundational template for an API endpoint, so use the base-template-generator agent to provide a comprehensive starting point.</commentary></example>
+description: Create foundational templates, boilerplate code, and starter configurations for new projects, components, or features. Use for scaffolding a new component, API endpoint, model, config, or test suite from scratch.
 color: orange
 ---
 
@@ -19,6 +19,26 @@ On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_g
 
 You are a Base Template Generator, an expert architect specializing in creating clean, well-structured foundational templates and boilerplate code. Your expertise lies in establishing solid starting points that follow industry best practices, maintain consistency, and provide clear extension paths.
 
+## When you get dispatched
+
+Worked examples of the requests that route here — these live in the body, not the
+frontmatter `description`, because the description is always-resident routing
+context while this body only loads on dispatch.
+
+<example>
+Context: User needs to start a new React component and wants a solid foundation.
+user: 'I need to create a new user profile component'
+assistant: 'I'll use the base-template-generator agent to create a comprehensive React component template with proper structure, TypeScript definitions, and styling setup.'
+<commentary>Since the user needs a foundational template for a new component, use the base-template-generator agent to create a well-structured starting point.</commentary>
+</example>
+
+<example>
+Context: User is setting up a new API endpoint and needs a template.
+user: 'Can you help me set up a new REST API endpoint for user management?'
+assistant: 'I'll use the base-template-generator agent to create a complete API endpoint template with proper error handling, validation, and documentation structure.'
+<commentary>The user needs a foundational template for an API endpoint, so use the base-template-generator agent to provide a comprehensive starting point.</commentary>
+</example>
+
 Your core responsibilities:
 - Generate comprehensive base templates for components, modules, APIs, configurations, and project structures
 - Ensure all templates follow established coding standards and best practices from the project's CLAUDE.md guidelines

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

@@ -123,14 +123,54 @@ auto_update:
   helpers: true                          # Sync .claude/helpers/ from moflo source
   hook_block_drift: regenerate           # warn | regenerate | off (default: regenerate since #1227)
   claudemd_injection_drift: regenerate   # warn | regenerate | off
+
+# Which skill categories to install (OPTIONAL — omit to get every skill)
+skills:
+  categories: [core, memory, spells]     # core | memory | spells
 ```
 
 If your `moflo.yaml` predates the `sandbox:` or `auto_update:` blocks, they are auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
 
+### Narrowing Installed Skills with `skills.categories`
+
+**Omit the `skills:` block entirely to receive every moflo skill — that is the default and the recommended setting.** Add `skills.categories` only when you want a smaller always-resident skill listing, and expect to lose the commands in the categories you drop.
+
+Every installed skill's name and description sit in Claude's context in every session, so a project that will never author a spell can reclaim that space. The cost is real but small — the full set is roughly 2,000 tokens.
+
+| Category | Skills | Drop it when |
+|----------|--------|--------------|
+| `core` | `/fl`, `/healer`, `/verify`, `/flo-simplify`, `/eldar`, `/quicken`, `/ward`, `/divine`, `/meditate`, `/guidance`, `/commune`, `/luminarium` | Never — these are the everyday commands |
+| `memory` | `/memory-patterns`, `/vector-search`, `/memory-optimization`, `/memory-team`, `/memory-worktree` | You are not building on moflo's memory stack and have finished any team/worktree sharing setup |
+| `spells` | `/spell-builder`, `/spell-schedule`, `/connector-builder` | You do not author or schedule spells in this project |
+
+Both YAML list styles work:
+
+```yaml
+skills:
+  categories: [core, memory]
+```
+
+```yaml
+skills:
+  categories:
+    - core
+    - memory
+```
+
+**Key behaviors:**
+
+- **Omitting `skills:` means no restriction.** Every shipped skill syncs on every session start, exactly as before this option existed.
+- **`/flo` and `/fl` are never gated.** The ticket spell is the primary entry point and installs regardless of selection.
+- **An unknown category name is ignored, not fatal.** A typo narrows nothing rather than silently stripping your skills.
+- **Narrowing stops future syncing; it does not delete.** Skills already on disk stay until you remove them — moflo will not re-add them once excluded, so delete the directories under `.claude/skills/` to reclaim the context.
+- **Re-widening is instant.** Add the category back and the next session start restores its skills.
+
 ### Key Behaviors
 
 | Config | Effect |
 |--------|--------|
+| `skills.categories` omitted | Install every skill (default) |
+| `skills.categories: [core]` | Install only core skills; `memory` + `spells` stop syncing |
 | `auto_index.guidance: false` | Skip guidance indexing on session start |
 | `auto_index.code_map: false` | Skip code map generation on session start |
 | `auto_meditate.enabled: false` | Opt out of automatic session-lesson distillation (`/meditate` still works manually) |

package/.claude/helpers/gate.cjs

@@ -134,6 +134,13 @@ var command = process.argv[2];
 
 var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
 
+// Appended to every memory-first denial. Without it, a context audit of Claude
+// Code's denial telemetry reads moflo's gate enforcements as permission-setup
+// failures and "fixes" them with allow rules — which cannot override a hook
+// block at all (#1307 finding 5). Naming the gate makes the cause self-evident.
+var GATE_ORIGIN_NOTE = 'This is a moflo hook, not a Claude Code permission rule — allow-rules cannot override it.';
+var GATE_DISABLE_NOTE = 'Disable per-gate via moflo.yaml: gates: memory_first: false';
+
 // #1294 Finding 3 — reads/scans of EPHEMERAL files under the OS temp dir
 // (background-task output/transcripts, agent scratchpads) are transient tool
 // I/O and never carry indexable project knowledge, so they must not trip the
@@ -713,7 +720,7 @@ switch (command) {
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (isEphemeralPath(process.env.TOOL_INPUT_path)) break;
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -726,7 +733,7 @@ switch (command) {
     if (isEphemeralPath(fp)) break;
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'record-task-created': {
@@ -775,11 +782,12 @@ switch (command) {
     // "Memory namespace hint: ..." sentence so the BLOCK message stays uniform.
     var hint = s2.lastNamespaceHint || classifyBashNamespaceHint(cmd) || '';
     process.stderr.write(
-      'BLOCKED: Search memory before reading files via Bash.\n' +
+      'BLOCKED [moflo memory_first gate]: Search memory before reading files via Bash.\n' +
       'Example: mcp__moflo__memory_search { query: "<topic>", namespace: "<one of: guidance | code-map | patterns | learnings | tests>" }\n' +
       (hint ? hint + '\n' : '') +
       'On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' +
-      'Disable per-gate via moflo.yaml: gates: memory_first: false\n'
+      GATE_ORIGIN_NOTE + '\n' +
+      GATE_DISABLE_NOTE + '\n'
     );
     process.exit(2);
     break;

package/.claude/skills/distill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: distill
-description: Alias for /flo-simplify. Review changed code for reuse, quality, and efficiency, then fix any issues found — effort scales to the diff size.
+description: Alias for /flo-simplify — see that skill's description.
 ---
 
 # /distill is an alias for /flo-simplify

package/.claude/skills/perf-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: perf-audit
-description: Alias for /quicken. Ad-hoc performance audit — reveals N+1 queries, needless re-renders, missing caching, memory leaks, and redundant computation in your diff (or a named path), and prescribes the fix inline.
+description: Alias for /quicken — see that skill's description.
 arguments: "[path or area | --all]"
 ---
 

package/.claude/skills/test-gaps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-gaps
-description: Alias for /ward. Ad-hoc test-gap audit — reveals untested functions, uncovered edge cases, and missing error-handling/integration tests in your diff (or a named path), and conjures ready-to-paste test skeletons inline.
+description: Alias for /ward — see that skill's description.
 arguments: "[path or area | --all]"
 ---
 

package/bin/gate.cjs

@@ -134,6 +134,13 @@ var command = process.argv[2];
 
 var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
 
+// Appended to every memory-first denial. Without it, a context audit of Claude
+// Code's denial telemetry reads moflo's gate enforcements as permission-setup
+// failures and "fixes" them with allow rules — which cannot override a hook
+// block at all (#1307 finding 5). Naming the gate makes the cause self-evident.
+var GATE_ORIGIN_NOTE = 'This is a moflo hook, not a Claude Code permission rule — allow-rules cannot override it.';
+var GATE_DISABLE_NOTE = 'Disable per-gate via moflo.yaml: gates: memory_first: false';
+
 // #1294 Finding 3 — reads/scans of EPHEMERAL files under the OS temp dir
 // (background-task output/transcripts, agent scratchpads) are transient tool
 // I/O and never carry indexable project knowledge, so they must not trip the
@@ -713,7 +720,7 @@ switch (command) {
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (isEphemeralPath(process.env.TOOL_INPUT_path)) break;
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -726,7 +733,7 @@ switch (command) {
     if (isEphemeralPath(fp)) break;
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'record-task-created': {
@@ -775,11 +782,12 @@ switch (command) {
     // "Memory namespace hint: ..." sentence so the BLOCK message stays uniform.
     var hint = s2.lastNamespaceHint || classifyBashNamespaceHint(cmd) || '';
     process.stderr.write(
-      'BLOCKED: Search memory before reading files via Bash.\n' +
+      'BLOCKED [moflo memory_first gate]: Search memory before reading files via Bash.\n' +
       'Example: mcp__moflo__memory_search { query: "<topic>", namespace: "<one of: guidance | code-map | patterns | learnings | tests>" }\n' +
       (hint ? hint + '\n' : '') +
       'On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' +
-      'Disable per-gate via moflo.yaml: gates: memory_first: false\n'
+      GATE_ORIGIN_NOTE + '\n' +
+      GATE_DISABLE_NOTE + '\n'
     );
     process.exit(2);
     break;

package/bin/hooks.mjs

@@ -26,7 +26,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { createProcessManager } from './lib/process-manager.mjs';
 import { shouldDaemonAutoStart } from './lib/daemon-config.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
-import { findProjectRoot } from './lib/moflo-paths.mjs';
+import { resolveStateRoot } from './lib/moflo-paths.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -35,7 +35,10 @@ const __dirname = dirname(__filename);
 // in bin/ during development but gets synced to .claude/scripts/ in consumer
 // projects, so __dirname-relative paths break. findProjectRoot() works
 // everywhere and resolves identically to the TS bridge (see lib/moflo-paths.mjs).
-const projectRoot = findProjectRoot();
+// #1315 — resolveStateRoot, NOT findProjectRoot: this layer mkdirs
+// `.moflo/` state, and findProjectRoot honors CLAUDE_PROJECT_DIR verbatim,
+// so a sub-workspace-rooted session minted an island here every start.
+const projectRoot = resolveStateRoot();
 const logFile = resolve(projectRoot, '.moflo', 'logs', 'hooks.log');
 try { mkdirSync(dirname(logFile), { recursive: true }); } catch { /* best effort */ }
 const pm = createProcessManager(projectRoot);

package/bin/index-all.mjs

@@ -111,6 +111,41 @@ function killProcessTree(child) {
   }
 }
 
+// The step currently in flight, so a termination signal can reap it (#1317).
+let currentChild = null;
+let shuttingDown = false;
+
+// Reap on SIGTERM/SIGINT (#1317). hooks.mjs session-end calls pm.killAll(),
+// which SIGTERMs THIS process. Without a handler Node's default action kills us
+// instantly and the in-flight step is orphaned: it lives in its OWN process
+// group (detached:true in runStep, below), so the signal aimed at us never
+// reaches it, and no group-kill of our group can either. It reparents to init
+// and keeps burning CPU and writing .moflo/moflo.db after the session is gone —
+// build-embeddings most often, the same ~2 GB fastembed process as #744.
+// killProcessTree is the teardown primitive #744 already built; it was simply
+// never wired to the signal path.
+function handleTerminationSignal(signal) {
+  if (shuttingDown) return; // second signal while tearing down — ignore
+  shuttingDown = true;
+  log(`SIGNAL ${signal} — reaping in-flight step before exit`);
+  // Synchronous on both platforms: process.kill delivers before returning,
+  // spawnSync('taskkill') blocks. Safe to process.exit() immediately after.
+  killProcessTree(currentChild);
+  currentChild = null;
+  process.exit(signal === 'SIGINT' ? 130 : 143);
+}
+
+// 'SIGTERM' is never delivered on Windows — Node permits the listener but it
+// cannot fire, and Windows is already correct via taskkill /T. Registering it
+// unconditionally is therefore harmless, not a portability assumption.
+// 'SIGBREAK' is the Windows-only console-termination signal.
+for (const sig of ['SIGTERM', 'SIGINT']) {
+  try { process.on(sig, () => handleTerminationSignal(sig)); } catch { /* signal unsupported here */ }
+}
+if (platform() === 'win32') {
+  try { process.on('SIGBREAK', () => handleTerminationSignal('SIGBREAK')); } catch { /* ignore */ }
+}
+
 function runStep(label, cmd, args, timeoutMs = 120_000, extraEnv = null) {
   return new Promise((resolveStep) => {
     const start = Date.now();
@@ -122,6 +157,7 @@ function runStep(label, cmd, args, timeoutMs = 120_000, extraEnv = null) {
       detached: platform() !== 'win32', // POSIX: own process group for tree-kill
       env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
     });
+    currentChild = child;
     let timedOut = false;
     const timer = setTimeout(() => {
       timedOut = true;
@@ -129,6 +165,7 @@ function runStep(label, cmd, args, timeoutMs = 120_000, extraEnv = null) {
     }, timeoutMs);
     child.once('exit', (code, signal) => {
       clearTimeout(timer);
+      if (currentChild === child) currentChild = null;
       const elapsed = ((Date.now() - start) / 1000).toFixed(1);
       if (timedOut) {
         log(`FAIL  ${label} (${elapsed}s): timed out after ${timeoutMs}ms, child killed`);
@@ -143,6 +180,7 @@ function runStep(label, cmd, args, timeoutMs = 120_000, extraEnv = null) {
     });
     child.once('error', (err) => {
       clearTimeout(timer);
+      if (currentChild === child) currentChild = null;
       const elapsed = ((Date.now() - start) / 1000).toFixed(1);
       log(`FAIL  ${label} (${elapsed}s): ${err.message?.split('\n')[0] || 'unknown'}`);
       resolveStep(false);

package/bin/lib/moflo-paths.mjs

@@ -12,7 +12,7 @@
  * helpers no longer ship: the version-bump-gated cherry-pick lives entirely
  * in the launcher and the TS service `cli/services/cherry-pick-learnings.ts`.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { basename, dirname, join, parse, resolve } from 'node:path';
 
 export const MOFLO_DIR = '.moflo';
@@ -127,6 +127,42 @@ export function findAncestorMofloRoot(dir) {
  * @param {{ cwd?: string; honorEnv?: boolean }} [opts]
  * @returns {string} absolute project root
  */
+/**
+ * Pure-JS twin of `src/cli/services/project-root.ts:resolveStateRoot()` (#1315).
+ *
+ * Use this — never `findProjectRoot()` — anywhere the bin/hook layer is about
+ * to CREATE `.moflo/` state. `findProjectRoot` returns `CLAUDE_PROJECT_DIR`
+ * verbatim, and Claude Code sets that to the SESSION directory; in a monorepo
+ * session rooted at a sub-workspace the launcher therefore mkdir'd a `.moflo/`
+ * island there every session. That made the healer's nested-island fix a
+ * perpetual loop: archive it, next session re-mints it.
+ *
+ * Semantics (kept in lockstep with the TS side): an EXISTING
+ * `CLAUDE_PROJECT_DIR` wins outright and is never climbed above — the marker
+ * walk has no upper bound, so climbing past an explicit anchor would let a
+ * stray ancestor `.moflo/moflo.db` capture every project beneath it. Otherwise
+ * walk up from cwd and take the topmost marker, which is what stops a
+ * sub-directory invocation from minting an island where it stands. A value
+ * naming a directory that does not exist is ignored rather than materialized.
+ *
+ * @param {{ cwd?: string }} [opts]
+ * @returns {string} absolute project root
+ */
+export function resolveStateRoot(opts) {
+  const envDir = process.env.CLAUDE_PROJECT_DIR;
+  const envAbs = envDir ? resolve(envDir) : undefined;
+  const resolved = envAbs && existsSync(envAbs)
+    ? envAbs
+    : findProjectRoot({ honorEnv: false, cwd: opts?.cwd });
+  // Canonicalize so this compares equal to the realpath'd root the TS side
+  // derives (macOS /var → /private/var). Falls back when the path is absent.
+  try {
+    return realpathSync(resolve(resolved));
+  } catch {
+    return resolve(resolved);
+  }
+}
+
 export function findProjectRoot(opts) {
   const honorEnv = opts?.honorEnv !== false;
   if (honorEnv && process.env.CLAUDE_PROJECT_DIR) {

package/bin/lib/process-manager.mjs

@@ -219,7 +219,22 @@ export function createProcessManager(root) {
           if (process.platform === 'win32') {
             execFileSync('taskkill', ['/T', '/F', '/PID', String(entry.pid)], { windowsHide: true, timeout: 10000 });
           } else {
-            process.kill(entry.pid, 'SIGTERM');
+            // POSIX tree-kill (#1317). Windows walks the tree via taskkill /T;
+            // a bare SIGTERM here only hit the one PID, so anything the tracked
+            // process left in its group survived session-end. Everything spawn()
+            // launches is detached (setsid), so the tracked PID leads its own
+            // group and the negative PID reaches those children.
+            //
+            // NOTE this does NOT reach grandchildren that called setsid again —
+            // index-all's steps do exactly that, which is why index-all reaps
+            // them itself on SIGTERM. This is defence in depth, not the whole fix.
+            try {
+              process.kill(-entry.pid, 'SIGTERM');
+            } catch {
+              // No such process group — e.g. an entry registered by
+              // registerBackgroundPid() whose process doesn't lead one.
+              process.kill(entry.pid, 'SIGTERM');
+            }
           }
           killed++;
         } catch {

package/bin/lib/registry-cleanup.cjs

@@ -32,7 +32,15 @@ function killTrackedSync(projectDir) {
           if (process.platform === 'win32') {
             childProcess.execFileSync('taskkill', ['/T', '/F', '/PID', String(entries[i].pid)], { windowsHide: true, timeout: 5000 });
           } else {
-            process.kill(entries[i].pid, 'SIGTERM');
+            // POSIX tree-kill — mirrors process-manager.mjs killAll (#1317).
+            // This is the second reaper over the same registry (session-end via
+            // hook-handler.cjs), so it must not be left behind on the bare-PID
+            // kill or session-end orphans depend on which path ran.
+            try {
+              process.kill(-entries[i].pid, 'SIGTERM');
+            } catch (groupErr) {
+              process.kill(entries[i].pid, 'SIGTERM');
+            }
           }
           killed++;
         } catch (e) { /* ok */ }

package/bin/lib/retired-files.mjs

@@ -33,10 +33,17 @@
  * @module bin/lib/retired-files
  */
 
-import { existsSync, readFileSync, unlinkSync } from 'fs';
-import { resolve } from 'path';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
 import { createHash } from 'crypto';
 
+/**
+ * Consumer-relative path of the retained-files record written by
+ * `writeRetainedRecord`. Exported so tests and `flo healer` resolve the same
+ * location instead of re-deriving the string.
+ */
+export const RETAINED_RECORD_REL = join('.moflo', 'retired-retained.json');
+
 /**
  * Compute sha256 of file content. Returns null on read errors so the caller
  * can decide what to do — we never want a transient stat/read failure to
@@ -156,17 +163,29 @@ export function classifyRetiredFile(projectRoot, entry) {
  * Failures are non-fatal — a single un-deletable file (Windows AV hold,
  * EBUSY) must not stop pruning the rest. The caller surfaces the report.
  *
+ * `preserved` is the flat path list the launcher banner samples from;
+ * `preservedDetails` carries the same set with the manifest's retirement
+ * provenance attached, for the machine-readable record (#1307 finding 3).
+ *
  * @param {string} projectRoot
  * @param {string} manifestPath
- * @returns {{ pruned: string[], preserved: string[], unknown: string[], failed: Array<{path:string, message:string}> }}
+ * @returns {{ pruned: string[], preserved: string[], preservedDetails: Array<{path:string, retiredIn?:string, retiredBy?:string}>, unknown: string[], failed: Array<{path:string, message:string}> }}
  */
 export function applyRetiredPrune(projectRoot, manifestPath) {
   const { entries } = loadRetiredManifest(manifestPath);
-  const report = { pruned: [], preserved: [], unknown: [], failed: [] };
+  const report = { pruned: [], preserved: [], preservedDetails: [], unknown: [], failed: [] };
   for (const entry of entries) {
     const { action } = classifyRetiredFile(projectRoot, entry);
     if (action === 'absent') continue;
-    if (action === 'preserve') { report.preserved.push(entry.path); continue; }
+    if (action === 'preserve') {
+      report.preserved.push(entry.path);
+      report.preservedDetails.push({
+        path: entry.path,
+        ...(entry.retiredIn ? { retiredIn: entry.retiredIn } : {}),
+        ...(entry.retiredBy ? { retiredBy: entry.retiredBy } : {}),
+      });
+      continue;
+    }
     if (action === 'unknown') { report.unknown.push(entry.path); continue; }
     // action === 'prune'
     try {
@@ -181,3 +200,104 @@ export function applyRetiredPrune(projectRoot, manifestPath) {
   }
   return report;
 }
+
+/**
+ * Reconcile an existing retained record against what is actually on disk.
+ *
+ * `writeRetainedRecord` only runs inside the launcher's UPGRADE branch (that
+ * is where `applyRetiredPrune` lives), so on its own it cannot keep the record
+ * honest: a user who reads the record and deletes the files would keep a
+ * record naming those files until their next moflo upgrade — the record would
+ * outlive what it describes, which is the same "not actionable" complaint
+ * #1307 raised about the truncated banner.
+ *
+ * This runs on EVERY session start instead, and is written to cost nothing in
+ * the common case: one `existsSync` when no record is present (overwhelmingly
+ * the norm), and only then a stat per retained entry.
+ *
+ * Never throws — advisory bookkeeping must not break session start.
+ *
+ * @param {string} projectRoot
+ * @returns {{ changed: boolean, removed: string[], remaining: number }}
+ */
+export function reconcileRetainedRecord(projectRoot) {
+  const result = { changed: false, removed: [], remaining: 0 };
+  const abs = resolve(projectRoot, RETAINED_RECORD_REL);
+  try {
+    if (!existsSync(abs)) return result;               // fast path — no record
+    // Corrupt/hand-edited record: drop it rather than reason about it. Parsed
+    // in its own try so a JSON error lands here and the bad file is actually
+    // removed, instead of falling to the outer catch and lingering forever.
+    let parsed = null;
+    try {
+      parsed = JSON.parse(readFileSync(abs, 'utf-8'));
+    } catch { /* handled below */ }
+    if (!parsed || !Array.isArray(parsed.retained)) {
+      unlinkSync(abs);
+      result.changed = true;
+      return result;
+    }
+    const stillPresent = [];
+    for (const entry of parsed.retained) {
+      if (entry && typeof entry.path === 'string' && existsSync(resolve(projectRoot, entry.path))) {
+        stillPresent.push(entry);
+      } else if (entry && typeof entry.path === 'string') {
+        result.removed.push(entry.path);
+      }
+    }
+    result.remaining = stillPresent.length;
+    if (result.removed.length === 0) return result;    // nothing to do
+    result.changed = true;
+    if (stillPresent.length === 0) {
+      unlinkSync(abs);
+      return result;
+    }
+    writeFileSync(abs, JSON.stringify({ ...parsed, retained: stillPresent }, null, 2) + '\n', 'utf-8');
+    return result;
+  } catch {
+    return result;
+  }
+}
+
+/**
+ * Persist the retained (customized-and-therefore-preserved) retired files to
+ * `.moflo/retired-retained.json` (#1307 finding 3).
+ *
+ * Before this, the only place the retained set appeared was a launcher stdout
+ * banner truncated to 5 entries — so "delete manually if unwanted" was not
+ * actionable for the remainder, and nothing on disk let you reconstruct the
+ * set (`installed-files.json` doesn't track pre-#948 agents/skills).
+ *
+ * The record is advisory state, not a manifest: it is rewritten from scratch
+ * on every launcher run, and deleted when nothing is retained so a stale file
+ * never claims paths the consumer has since removed.
+ *
+ * Never throws — a failure to write an advisory record must not break session
+ * start on any consumer. Returns the absolute path written, or null.
+ *
+ * @param {string} projectRoot
+ * @param {Array<{path:string, retiredIn?:string, retiredBy?:string}>} preservedDetails
+ * @param {string} [mofloVersion] - version that produced this record, if known
+ * @returns {string|null} absolute path written, or null if nothing was written
+ */
+export function writeRetainedRecord(projectRoot, preservedDetails, mofloVersion) {
+  const abs = resolve(projectRoot, RETAINED_RECORD_REL);
+  try {
+    if (!Array.isArray(preservedDetails) || preservedDetails.length === 0) {
+      // Nothing retained — drop any record from a previous run.
+      if (existsSync(abs)) unlinkSync(abs);
+      return null;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    const payload = {
+      version: 1,
+      note: 'Retired moflo files preserved because they were customized locally. Safe to delete manually if unwanted; moflo will not remove them.',
+      ...(mofloVersion ? { mofloVersion } : {}),
+      retained: preservedDetails,
+    };
+    writeFileSync(abs, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+    return abs;
+  } catch {
+    return null;
+  }
+}