@tpsdev-ai/flair 0.45.0 → 0.46.0

package/dist/doctor-client.js

@@ -154,6 +154,272 @@ export function parseLegacySessionStartHookCommand(command) {
 export function isFlairHookCommand(command) {
     return typeof command === "string" && command.includes("@tpsdev-ai/flair-mcp") && command.includes(SESSION_START_HOOK_MARKER);
 }
+// ── the continuity capture hooks (flair#1257 slice 2) ──────────────────────
+//
+// Continuity's write side is a pair of Claude Code hook entries — PostToolUse
+// (mutating tools only, via the matcher below) and Stop — both running the
+// SAME `flair-continuity-capture` binary shipped by @tpsdev-ai/flair-mcp.
+// Same ONE-builder discipline as the SessionStart command above (#1007):
+// every path that writes these entries (`flair doctor --fix`, `flair hook
+// install --continuity` in src/hook-install.ts) goes through
+// buildContinuityCaptureHookCommand, so the invocation's failure behaviour is
+// defined and tested in one place.
+//
+// Unlike the SessionStart command, this one captures NOTHING to re-emit: a
+// PostToolUse/Stop hook's stdout is harness-interpreted surface and the
+// capture binary never has anything to say to it, so the wrapper discards
+// BOTH streams and absorbs failure (`>/dev/null 2>/dev/null || true`). The
+// same #1007 reasoning applies: if the npx resolution breaks, the silence has
+// to be a property of the command string, because the binary's own fail-open
+// guarantee is behind the door that stopped opening. hookCommandIsSilenced()
+// recognizes this shape unchanged.
+//
+// INSTALLING THESE HOOKS IS THE OPT-IN. There is no env flag: an agent whose
+// settings.json carries the pair journals; one that doesn't, doesn't. Doctor
+// therefore reports "absent" as "not enabled" — informational, never a pass,
+// never a failure (see checkContinuityCaptureHooks / cli.ts's rendering).
+/** The exact substring identifying a Flair continuity-capture hook command. */
+export const CONTINUITY_CAPTURE_HOOK_MARKER = "flair-continuity-capture";
+/**
+ * The PostToolUse matcher written alongside our hook entry — the EXACT
+ * mutating-tool allowlist the capture binary enforces internally
+ * (packages/flair-mcp/src/continuity.ts's MUTATING_TOOLS: Write/Edit/
+ * NotebookEdit mutate file/cell state, Bash can mutate anything; read-only
+ * tools are world-recoverable and journal nothing). The matcher is an
+ * EFFICIENCY (no process spawn for a Read), not the control — the binary's
+ * own allowlist is the control and fires regardless of who spawns it.
+ */
+export const CONTINUITY_POST_TOOL_USE_MATCHER = "Write|Edit|NotebookEdit|Bash";
+/**
+ * Build the exact `command` string registered for BOTH continuity hook events
+ * (PostToolUse and Stop run the same binary; the payload's hook_event_name
+ * tells it which fired). Same strict value allow-list as the SessionStart
+ * builder — throws rather than emitting a quoted approximation.
+ */
+export function buildContinuityCaptureHookCommand(agentId, flairUrl) {
+    if (!isHookCommandValueSafe(agentId)) {
+        throw new Error(`agent id '${agentId}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
+    }
+    if (flairUrl != null && flairUrl !== "" && !isHookCommandValueSafe(flairUrl)) {
+        throw new Error(`Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
+    }
+    const env = flairUrl ? `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl}` : `FLAIR_AGENT_ID=${agentId}`;
+    const invocation = `${env} npx -y -p @tpsdev-ai/flair-mcp ${CONTINUITY_CAPTURE_HOOK_MARKER}`;
+    return `sh -c '${invocation} >/dev/null 2>/dev/null || true'`;
+}
+/** Does this command invoke the Flair continuity-capture binary at all? */
+export function isFlairContinuityCommand(command) {
+    return (typeof command === "string" &&
+        command.includes("@tpsdev-ai/flair-mcp") &&
+        command.includes(CONTINUITY_CAPTURE_HOOK_MARKER));
+}
+/** The two hook events continuity registers under. */
+export const CONTINUITY_HOOK_EVENTS = ["PostToolUse", "Stop"];
+function findContinuityEntry(config, event) {
+    const groups = config?.hooks?.[event];
+    if (!Array.isArray(groups))
+        return null;
+    for (let gi = 0; gi < groups.length; gi++) {
+        const hooks = groups[gi]?.hooks;
+        if (!Array.isArray(hooks))
+            continue;
+        for (let hi = 0; hi < hooks.length; hi++) {
+            if (typeof hooks[hi]?.command === "string" && hooks[hi].command.includes(CONTINUITY_CAPTURE_HOOK_MARKER)) {
+                return { group: groups[gi], hookIndex: hi, groupIndex: gi };
+            }
+        }
+    }
+    return null;
+}
+function continuityEventReport(config, event) {
+    const found = findContinuityEntry(config, event);
+    if (!found)
+        return { present: false, currentForm: false };
+    const hook = found.group.hooks[found.hookIndex];
+    const command = typeof hook?.command === "string" ? hook.command : "";
+    const matcher = typeof found.group?.matcher === "string" ? found.group.matcher : undefined;
+    const shapeOk = hook?.type === "command" &&
+        command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${CONTINUITY_CAPTURE_HOOK_MARKER}`) &&
+        hookCommandIsSilenced(command);
+    const matcherOk = event !== "PostToolUse" || matcher === CONTINUITY_POST_TOOL_USE_MATCHER;
+    return { present: true, command, matcher, currentForm: shapeOk && matcherOk };
+}
+/**
+ * Doctor's check-5 twin of checkSessionStartHook for the continuity pair —
+ * pure fs read, no probe. A missing or unparseable settings.json reads as
+ * "absent" (not enabled), matching checkSessionStartHook's tolerance.
+ */
+export function checkContinuityCaptureHooks(homeDir) {
+    const path = join(homeDir, ".claude", "settings.json");
+    let config = {};
+    const raw = readTextFile(path);
+    if (raw && raw.trim()) {
+        try {
+            config = JSON.parse(raw);
+        }
+        catch {
+            config = {};
+        }
+    }
+    const postToolUse = continuityEventReport(config, "PostToolUse");
+    const stop = continuityEventReport(config, "Stop");
+    let state;
+    if (!postToolUse.present && !stop.present)
+        state = "absent";
+    else if (!postToolUse.present || !stop.present)
+        state = "partial";
+    else if (postToolUse.currentForm && stop.currentForm)
+        state = "installed";
+    else
+        state = "stale";
+    return { path, postToolUse, stop, state };
+}
+/**
+ * Pure merge of the continuity pair into a parsed settings object — the ONE
+ * mutation core both write paths (`flair doctor --fix` via
+ * fixContinuityCaptureHooks below, `flair hook install --continuity` via
+ * src/hook-install.ts) share. Idempotent: re-running with unchanged inputs is
+ * a structural no-op. Only OUR entries are ever touched — sibling hooks,
+ * groups and keys are preserved byte-identical; a group we don't own keeps
+ * its matcher (our binary's internal allowlist still filters — the matcher is
+ * an efficiency, not the control).
+ */
+export function computeContinuityHookInstall(config, agentId, flairUrl) {
+    const command = buildContinuityCaptureHookCommand(agentId, flairUrl);
+    const newConfig = JSON.parse(JSON.stringify(config ?? {}));
+    const actions = { PostToolUse: "noop", Stop: "noop" };
+    let changed = false;
+    newConfig.hooks = newConfig.hooks && typeof newConfig.hooks === "object" && !Array.isArray(newConfig.hooks) ? newConfig.hooks : {};
+    for (const event of CONTINUITY_HOOK_EVENTS) {
+        const existing = findContinuityEntry(newConfig, event);
+        if (existing) {
+            const hook = existing.group.hooks[existing.hookIndex];
+            const soleOwner = existing.group.hooks.length === 1;
+            const wantMatcher = event === "PostToolUse" && soleOwner;
+            const matcherCurrent = !wantMatcher || existing.group.matcher === CONTINUITY_POST_TOOL_USE_MATCHER;
+            if (hook.command === command && hook.type === "command" && matcherCurrent)
+                continue;
+            existing.group.hooks[existing.hookIndex] = { type: "command", command };
+            if (wantMatcher)
+                existing.group.matcher = CONTINUITY_POST_TOOL_USE_MATCHER;
+            actions[event] = "update";
+            changed = true;
+            continue;
+        }
+        newConfig.hooks[event] = Array.isArray(newConfig.hooks[event]) ? newConfig.hooks[event] : [];
+        const group = { hooks: [{ type: "command", command }] };
+        if (event === "PostToolUse")
+            group.matcher = CONTINUITY_POST_TOOL_USE_MATCHER;
+        newConfig.hooks[event].push(group);
+        actions[event] = "add";
+        changed = true;
+    }
+    return { changed, actions, newConfig };
+}
+/**
+ * Pure removal of the continuity pair — deletes ONLY our entries (marker
+ * substring match, exactly how install finds them), then prunes any group /
+ * event array / `hooks` key left empty by that removal. Never touches
+ * anything else.
+ */
+export function computeContinuityHookRemoval(config) {
+    const newConfig = JSON.parse(JSON.stringify(config ?? {}));
+    const actions = { PostToolUse: "noop", Stop: "noop" };
+    let changed = false;
+    for (const event of CONTINUITY_HOOK_EVENTS) {
+        const existing = findContinuityEntry(newConfig, event);
+        if (!existing)
+            continue;
+        existing.group.hooks.splice(existing.hookIndex, 1);
+        if (existing.group.hooks.length === 0) {
+            newConfig.hooks[event].splice(existing.groupIndex, 1);
+        }
+        if (newConfig.hooks[event].length === 0) {
+            delete newConfig.hooks[event];
+        }
+        actions[event] = "remove";
+        changed = true;
+    }
+    if (changed && newConfig.hooks && typeof newConfig.hooks === "object" && Object.keys(newConfig.hooks).length === 0) {
+        delete newConfig.hooks;
+    }
+    return { changed, actions, newConfig };
+}
+/**
+ * `flair doctor --fix` write path: register (or repair to current form) the
+ * continuity pair in ~/.claude/settings.json. Merge-safe read-parse-write,
+ * mirroring fixSessionStartHook — creates the file if absent, refuses on a
+ * file it cannot parse.
+ */
+export function fixContinuityCaptureHooks(homeDir, agentId, flairUrl) {
+    const path = join(homeDir, ".claude", "settings.json");
+    if (!agentId) {
+        return {
+            ok: false,
+            path,
+            changed: false,
+            message: "no agent id known — pass --agent <id> (or set FLAIR_AGENT_ID) so doctor knows which agent to wire the continuity hooks to",
+        };
+    }
+    if (!isHookCommandValueSafe(agentId)) {
+        return {
+            ok: false,
+            path,
+            changed: false,
+            message: `agent id '${agentId}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`,
+        };
+    }
+    if (flairUrl != null && flairUrl !== "" && !isHookCommandValueSafe(flairUrl)) {
+        return {
+            ok: false,
+            path,
+            changed: false,
+            message: `Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`,
+        };
+    }
+    try {
+        let config = {};
+        const raw = readTextFile(path);
+        if (raw && raw.trim())
+            config = JSON.parse(raw);
+        const { changed, newConfig } = computeContinuityHookInstall(config, agentId, flairUrl);
+        if (!changed) {
+            return { ok: true, path, changed: false, message: `continuity capture hooks already current in ${path}` };
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+        return { ok: true, path, changed: true, message: `wired the continuity capture hooks (PostToolUse + Stop) in ${path} (agent '${agentId}')` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, changed: false, message: `could not write ${path}: ${reason}` };
+    }
+}
+/**
+ * Symmetric removal path (`flair doctor --fix` when disabling / `flair hook
+ * uninstall --continuity`). A no-op when nothing is wired — never creates a
+ * file that didn't exist, refuses on a file it cannot parse.
+ */
+export function removeContinuityCaptureHooks(homeDir) {
+    const path = join(homeDir, ".claude", "settings.json");
+    const raw = readTextFile(path);
+    if (!raw || !raw.trim()) {
+        return { ok: true, path, changed: false, message: `no ${path} — continuity capture hooks are not enabled` };
+    }
+    try {
+        const config = JSON.parse(raw);
+        const { changed, newConfig } = computeContinuityHookRemoval(config);
+        if (!changed) {
+            return { ok: true, path, changed: false, message: `no continuity capture hooks found in ${path} — nothing to remove` };
+        }
+        writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+        return { ok: true, path, changed: true, message: `removed the continuity capture hooks (PostToolUse + Stop) from ${path}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, changed: false, message: `could not update ${path}: ${reason}` };
+    }
+}
 // ── shared helpers ──────────────────────────────────────────────────────────
 /**
  * Run `fn` with process.env.HOME temporarily pointed at `homeDir`, then

package/dist/federation/scheduler.js

@@ -57,12 +57,12 @@
  * `flair federation sync --admin-pass-file`, which reads it through
  * readAdminPassFileSecure() and refuses a file that is not owner-only.
  */
-import { existsSync, chmodSync, rmSync, readFileSync } from "node:fs";
+import { existsSync, chmodSync, rmSync, readFileSync, mkdirSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 export const LAUNCHD_LABEL = "dev.flair.federation.sync";
 export const SYSTEMD_TIMER_UNIT = "flair-federation-sync.timer";
 export const SYSTEMD_SERVICE_UNIT = "flair-federation-sync.service";
@@ -132,7 +132,7 @@ export function validateInterval(intervalSeconds) {
             `For sub-minute latency use \`flair federation watch --interval <s>\` in a foreground session instead.`);
     }
 }
-function buildSubstitutions(opts, shimPath, flairBin) {
+function buildSubstitutions(opts, shimPath, flairBin, nodeBin) {
     validateInterval(opts.intervalSeconds);
     const adminPassFile = opts.adminPassFile ?? "";
     if (adminPassFile && !existsSync(adminPassFile)) {
@@ -141,6 +141,7 @@ function buildSubstitutions(opts, shimPath, flairBin) {
     }
     return {
         FLAIR_BIN: flairBin,
+        NODE_BIN: nodeBin,
         SHIM_PATH: shimPath,
         HOME: opts.homeOverride ?? homedir(),
         INTERVAL_SECONDS: String(opts.intervalSeconds),
@@ -165,9 +166,29 @@ function launchdDomain() {
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
     const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
-    const subs = buildSubstitutions(opts, shimPath, flairBin);
+    const subs = buildSubstitutions(opts, shimPath, flairBin, nodeBin);
+    // 0. Create the log directory the unit files point stdout/stderr at.
+    // Nothing else ever creates it — launchd kills a job whose StandardOutPath
+    // directory is missing (spawn error 209) and systemd fails the unit (#1231).
+    //
+    // Mode 0700 is load-bearing, NOT cosmetic: this directory also receives
+    // REM's nightly log, which carries distillation CANDIDATE CONTENT — actual
+    // memory text, not just sync counts and errors. Relaxing it to 0755 (e.g.
+    // "for shared debugging") would expose memory content to every local user.
+    const logsDir = resolve(subs.HOME, ".flair", "logs");
+    try {
+        mkdirSync(logsDir, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        throw new Error(`could not create the scheduler log directory ${logsDir}: ${err?.message ?? err}. ` +
+            `The service manager writes the job's stdout/stderr there; without it the first run dies ` +
+            `before producing any output. Fix whatever blocks creating that directory, then re-run ` +
+            `\`flair federation sync enable\`.`);
+    }
+    const stderrLogPath = resolve(logsDir, "federation-sync.stderr.log");
     // 1. Deploy the shim (always — both platforms invoke it).
     const shimContents = renderTemplate(readTemplate(templateRoot, "bin/flair-federation-sync.sh.tmpl"), subs);
     writeFileWithDir(shimPath, shimContents, 0o700);
@@ -179,14 +200,28 @@ export function enableScheduler(opts) {
         writeFileWithDir(plistPath, plistContents, 0o600);
         const loadCommand = ["launchctl", "bootstrap", launchdDomain(), plistPath];
         let loadResult;
+        let firstRun;
         if (!opts.skipLoad) {
             // Bootout first in case a prior install left the job loaded — this is
             // what makes re-running enable (e.g. to change --interval) idempotent
             // rather than a "service already loaded" failure.
             spawnReport(["launchctl", "bootout", launchdDomain(), plistPath]);
             loadResult = spawnReport(loadCommand);
+            if (loadResult.code === 0) {
+                // Ordering gate (#1231): verify the first run ONLY after the load
+                // exited 0. A load failure is its own failure mode with its own
+                // remedy — kickstarting on top of it would blur which actor failed.
+                firstRun = verifyFirstRun({
+                    plat,
+                    darwinTarget: `${launchdDomain()}/${LAUNCHD_LABEL}`,
+                    stderrLogPath,
+                });
+            }
         }
-        return { platform: plat, shimPath, schedulerPath: plistPath, intervalSeconds: opts.intervalSeconds, loadCommand, loadResult };
+        return {
+            platform: plat, shimPath, schedulerPath: plistPath, intervalSeconds: opts.intervalSeconds,
+            loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+        };
     }
     // Linux: systemd user units.
     const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
@@ -197,15 +232,24 @@ export function enableScheduler(opts) {
     writeFileWithDir(timerPath, timerContents, 0o600);
     const loadCommand = ["systemctl", "--user", "enable", "--now", SYSTEMD_TIMER_UNIT];
     let loadResult;
+    let firstRun;
     if (!opts.skipLoad) {
         spawnReport(["systemctl", "--user", "daemon-reload"]);
         // Restart so a changed --interval takes effect on re-enable; `enable
         // --now` alone leaves an already-running timer on its old schedule.
         loadResult = spawnReport(loadCommand);
-        if (loadResult.code === 0)
+        if (loadResult.code === 0) {
             spawnReport(["systemctl", "--user", "restart", SYSTEMD_TIMER_UNIT]);
+            // Ordering gate (#1231): only after the load exited 0. Starts the
+            // SERVICE unit directly (oneshot ⇒ blocks until the run exits) rather
+            // than waiting out the timer.
+            firstRun = verifyFirstRun({ plat, linuxServiceUnit: SYSTEMD_SERVICE_UNIT, stderrLogPath });
+        }
     }
-    return { platform: plat, shimPath, schedulerPath: timerPath, intervalSeconds: opts.intervalSeconds, loadCommand, loadResult };
+    return {
+        platform: plat, shimPath, schedulerPath: timerPath, intervalSeconds: opts.intervalSeconds,
+        loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+    };
 }
 /** Removes the scheduler entry. Peer records and sync history are untouched. */
 export function disableScheduler(opts = {}) {
@@ -432,6 +476,14 @@ export function assessDriver(input) {
  * success-vs-failure decision (flair#850: never print a success headline
  * before activation is known to have succeeded), extracted from the CLI
  * action so it is unit-testable without spawning launchctl/systemctl.
+ *
+ * flair#1231 deepened the #850 rule by one layer: activation exiting 0 proves
+ * the service manager ACCEPTED the job, not that the job can run — a stripped
+ * exec bit and a missing log directory both passed activation and killed the
+ * first real run invisibly. So the ✅ headline is now additionally gated on
+ * `firstRunVerified`: success may not be claimed until the thing the operator
+ * asked for — a sync run through the service manager — has been observed to
+ * happen once.
  */
 export function formatEnableReport(r, input) {
     const activationFailed = !!r.loadResult && r.loadResult.code !== 0;
@@ -459,6 +511,58 @@ export function formatEnableReport(r, input) {
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair federation sync status`);
         return { lines, ok: false };
     }
+    if (!r.firstRunVerified) {
+        const fr = r.firstRun;
+        const headline = fr?.outcome === "run-failed"
+            ? `⚠️  Federation sync driver installed but the first run FAILED (${describeExitCode(fr.exitCode)})`
+            : fr?.outcome === "timeout"
+                ? `⚠️  Federation sync driver installed but the first run did not complete within ${Math.round(fr.budgetMs / 1000)}s — cannot confirm it works`
+                : fr?.outcome === "manager-unavailable"
+                    ? `⚠️  Federation sync driver installed but the service manager is unreachable — cannot verify the first run`
+                    : fr?.outcome === "start-failed"
+                        ? `⚠️  Federation sync driver installed but the first run could not be started`
+                        : `⚠️  Federation sync driver installed but the first run was never verified`;
+        const lines = [
+            headline,
+            `   Interval:    every ${r.intervalSeconds}s`,
+            `   Scheduler:   ${r.schedulerPath}`,
+            `   Shim:        ${r.shimPath}`,
+            credLine,
+        ];
+        if (input.target)
+            lines.push(`   Target:      ${input.target}`);
+        if (r.loadResult)
+            lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
+        if (fr) {
+            lines.push(`   First run:   ${fr.detail}`);
+            if (fr.stderrTail) {
+                lines.push(`   Log tail (${fr.logPath}):`);
+                for (const l of fr.stderrTail.split("\n"))
+                    lines.push(`     ${l}`);
+            }
+            else if (fr.logEmpty) {
+                lines.push(`   Log file ${fr.logPath} exists but is EMPTY — the run died before writing anything.`);
+            }
+            else {
+                lines.push(`   No log file at ${fr.logPath}.`);
+            }
+        }
+        lines.push("");
+        if (fr?.outcome === "timeout") {
+            lines.push(`   The run may legitimately still be going. Check the log above and \`flair federation status\`;`);
+            lines.push(`   nothing has been CONFIRMED to sync yet.`);
+        }
+        else if (fr?.outcome === "manager-unavailable") {
+            lines.push(`   The driver files are installed, but launchctl/systemctl could not be consulted, so whether`);
+            lines.push(`   sync runs is UNKNOWN. Fix the service manager for this session, then re-run \`flair federation sync enable\`.`);
+        }
+        else {
+            lines.push(`   Nothing has synced. Fix the cause above, then re-run \`flair federation sync enable\`.`);
+        }
+        lines.push("");
+        lines.push(`   Check anytime with: flair federation sync status`);
+        return { lines, ok: false };
+    }
     const lines = [
         `✅ Federation sync driver enabled (${r.platform})`,
         `   Interval:    every ${r.intervalSeconds}s`,
@@ -470,9 +574,10 @@ export function formatEnableReport(r, input) {
         lines.push(`   Target:      ${input.target}`);
     if (r.loadResult)
         lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
+    lines.push(`   First run:   completed through the service manager, exit 0`);
     lines.push("");
-    lines.push(`The first sync runs immediately. Confirm with \`flair federation status\`,`);
-    lines.push(`which now reports whether anything is actually driving sync.`);
+    lines.push(`Confirm anytime with \`flair federation status\`,`);
+    lines.push(`which reports whether anything is actually driving sync.`);
     lines.push(`Disable with \`flair federation sync disable\`.`);
     return { lines, ok: true };
 }

package/dist/hook-install.js

@@ -54,7 +54,7 @@
 //      reuses bootstrap's own maxTokens machinery.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, hookCommandIsSilenced, isHookCommandValueSafe, } from "./doctor-client.js";
+import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, } from "./doctor-client.js";
 // ── harness registry ────────────────────────────────────────────────────────
 /** v1 supports exactly one harness. The flag/type exist so a second harness
  *  is an additive registry entry, not a rewrite (Kern's #719 verdict: "a
@@ -352,3 +352,152 @@ export function hookStatus(homeDir, harness) {
         agentId: env.agentId, flairUrl: env.flairUrl, command, parseError: null,
     };
 }
+// ── continuity capture hooks (flair#1257 slice 2) ──────────────────────────
+//
+// The PostToolUse + Stop pair that auto-journals working state into the
+// ephemeral Memory tier (see packages/flair-mcp/src/continuity.ts for the
+// capture discipline). INSTALLING THIS PAIR IS THE OPT-IN — there is no env
+// flag — so it gets the same standalone, symmetric, dry-run-able command
+// surface as the SessionStart hook (`flair hook install|uninstall
+// --continuity`, wired in src/cli.ts), sharing this module's Sherlock
+// conditions: fail-closed on malformed settings.json, backup before any real
+// mutation, idempotent merge that never touches unrelated hooks/keys,
+// --dry-run computes the delta without writing (no backup either). The pure
+// mutation cores (computeContinuityHookInstall / computeContinuityHookRemoval)
+// live in src/doctor-client.ts next to the ONE command builder so `flair
+// doctor --fix` and this family cannot drift apart.
+/** Mirror of buildHookCommand for the continuity pair — delegates to the ONE
+ *  builder in doctor-client.ts. Throws on unrepresentable values;
+ *  installContinuityHooks() checks first and reports instead. */
+export function buildContinuityHookCommand(agentId, flairUrl) {
+    return buildContinuityCaptureHookCommand(agentId, flairUrl);
+}
+/** Install (or repair to current form) the continuity capture pair. */
+export function installContinuityHooks(opts) {
+    const { homeDir, harness, agentId, flairUrl } = opts;
+    const dryRun = !!opts.dryRun;
+    const path = hookSettingsPath(homeDir, harness);
+    for (const [label, value] of [["agent id", agentId], ["Flair URL", flairUrl]]) {
+        if (!isHookCommandValueSafe(value)) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${label} '${value}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -) — refusing to write it`,
+                backupPath: null, actions: null,
+            };
+        }
+    }
+    if (dryRun) {
+        const read = readSettingsFile(path);
+        if (read.parseError) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${read.parseError} — dry run: nothing would be written until this is fixed`,
+                backupPath: null, actions: null,
+            };
+        }
+        const { changed, actions } = computeContinuityHookInstall(read.parsed ?? {}, agentId, flairUrl);
+        const message = changed
+            ? `would wire the continuity capture hooks (PostToolUse: ${actions.PostToolUse}, Stop: ${actions.Stop}) in ${path} (dry run — nothing written)`
+            : `continuity capture hooks already current in ${path} — no changes`;
+        return { ok: true, path, harness, dryRun, message, backupPath: null, actions };
+    }
+    let backupPath = null;
+    if (existsSync(path)) {
+        try {
+            backupPath = takeBackup(path);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false, path, harness, dryRun,
+                message: `could not back up ${path} before mutating it: ${reason} — refusing to touch it`,
+                backupPath: null, actions: null,
+            };
+        }
+    }
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `${read.parseError} — refusing to modify a file we can't safely parse. Original left untouched at ${path}` +
+                (backupPath ? `; backup copy at ${backupPath}.` : "."),
+            backupPath, actions: null,
+        };
+    }
+    const { changed, actions, newConfig } = computeContinuityHookInstall(read.parsed ?? {}, agentId, flairUrl);
+    if (!changed) {
+        return { ok: true, path, harness, dryRun, message: `continuity capture hooks already current in ${path}`, backupPath, actions };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return {
+        ok: true, path, harness, dryRun,
+        message: `wired the continuity capture hooks (PostToolUse: ${actions.PostToolUse}, Stop: ${actions.Stop}) in ${path}`,
+        backupPath, actions,
+    };
+}
+/** Symmetric removal of the continuity pair — only ours, everything else in
+ *  the file left untouched. A no-op when nothing is installed. */
+export function uninstallContinuityHooks(opts) {
+    const { homeDir, harness } = opts;
+    const dryRun = !!opts.dryRun;
+    const path = hookSettingsPath(homeDir, harness);
+    if (dryRun) {
+        const read = readSettingsFile(path);
+        if (read.parseError) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${read.parseError} — dry run: nothing would be removed until this is fixed`,
+                backupPath: null, actions: null,
+            };
+        }
+        const { changed, actions } = computeContinuityHookRemoval(read.parsed ?? {});
+        const message = changed
+            ? `would remove the continuity capture hooks (PostToolUse: ${actions.PostToolUse}, Stop: ${actions.Stop}) from ${path} (dry run — nothing written)`
+            : `no continuity capture hooks found in ${path} — nothing to remove`;
+        return { ok: true, path, harness, dryRun, message, backupPath: null, actions };
+    }
+    let backupPath = null;
+    if (existsSync(path)) {
+        try {
+            backupPath = takeBackup(path);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false, path, harness, dryRun,
+                message: `could not back up ${path} before mutating it: ${reason} — refusing to touch it`,
+                backupPath: null, actions: null,
+            };
+        }
+    }
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `${read.parseError} — refusing to modify a file we can't safely parse. Original left untouched at ${path}` +
+                (backupPath ? `; backup copy at ${backupPath}.` : "."),
+            backupPath, actions: null,
+        };
+    }
+    const { changed, actions, newConfig } = computeContinuityHookRemoval(read.parsed ?? {});
+    if (!changed) {
+        return { ok: true, path, harness, dryRun, message: `no continuity capture hooks found in ${path} — nothing to remove`, backupPath, actions };
+    }
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return {
+        ok: true, path, harness, dryRun,
+        message: `removed the continuity capture hooks (PostToolUse + Stop) from ${path}`,
+        backupPath, actions,
+    };
+}
+/** Read-only continuity status for `flair hook status` — the same report
+ *  doctor's check consumes, resolved through the harness's settings path. */
+export function continuityHookStatus(homeDir, harness) {
+    // hookSettingsPath and checkContinuityCaptureHooks both resolve
+    // ~/.claude/settings.json from homeDir; asserting through the harness
+    // registry keeps a future second harness from silently reading the wrong
+    // file.
+    void hookSettingsPath(homeDir, harness);
+    return checkContinuityCaptureHooks(homeDir);
+}