@tpsdev-ai/flair-mcp 0.45.0 → 0.47.0

package/dist/continuity-capture-hook.d.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Flair continuity-capture hook for Claude Code (flair#1257 slice 2) — the
+ * PostToolUse/Stop hook target that auto-journals the agent's working state
+ * into the ephemeral Memory tier, so an unseen kill/crash/OOM never loses the
+ * cadence. Registered (opt-in) via `flair doctor --fix` / `flair hook install
+ * --continuity`; the resume side lives in ./session-start-hook.ts.
+ *
+ * WHAT IT WRITES — see ./continuity.ts's module doc for the full, binding
+ * capture discipline. In one breath: at most ONE ephemeral+private row per
+ * fire; mutating tools only; Bash description-only (NEVER the command);
+ * Write/Edit/NotebookEdit path-only; Stop = a hard-bounded excerpt of
+ * assistant-chosen prose; never the raw hook JSON, never tool results, never
+ * an attempt at secret-scrubbing (the bound is the control).
+ *
+ * NO-OP-ON-ANY-FAILURE GUARANTEE (same posture as session-start-hook.ts):
+ * this binary can never block or break the agent's turn. Malformed stdin,
+ * missing identity, missing state file, Flair unreachable, a #1261 guard 400,
+ * a timeout, an unexpected throw — every one degrades to "journal nothing",
+ * at most one debug-level stderr line (the installed command discards
+ * stderr), and exit 0. Malformed hook JSON in particular journals NOTHING —
+ * no partial extraction that might pull raw tool results into the journal
+ * (Sherlock's input-validation tightening).
+ *
+ * A hard timeout (FLAIR_CONTINUITY_TIMEOUT_MS, default 2s) bounds the journal
+ * write so a slow Flair can't make the agent wait on its own diary.
+ *
+ * CONFIG (env, read identically to the other hook binaries):
+ *   FLAIR_AGENT_ID   (required — absent → no-op)
+ *   FLAIR_URL        (default http://localhost:19926 via flair-client)
+ *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
+ *   FLAIR_CONTINUITY_TIMEOUT_MS (default 2000; clamped 250..10000)
+ *   FLAIR_SESSION_DIR (default ~/.flair/session — test override)
+ *   FLAIR_HOOK_PROBE (probe mode: exit immediately, no stdin read, no writes)
+ */
+import { type ContinuityClient } from "./continuity.js";
+/** Injectable dependencies so the whole flow is unit-testable without a live
+ *  Flair daemon or a real ~/.flair (homeOverride discipline). */
+export interface CaptureDeps {
+    makeClient?: (agentId: string) => ContinuityClient | Promise<ContinuityClient>;
+    sessionDir?: string;
+    env?: Record<string, string | undefined>;
+    now?: () => Date;
+    /** Debug-level warn sink (default: one stderr line). Never stdout. */
+    warn?: (message: string) => void;
+}
+export interface CaptureOutcome {
+    /** True only when a journal row was accepted by Flair. */
+    wrote: boolean;
+    /** Why nothing was written (or "written"). Diagnostic only — the process
+     *  exit code is 0 regardless (fail-open). */
+    reason: "written" | "probe" | "malformed-input" | "not-capturable" | "no-agent-id" | "bad-session-id" | "no-state" | "write-failed";
+}
+/**
+ * Core capture flow. NEVER throws; never writes to stdout. Returns a
+ * diagnostic outcome for tests — the binary ignores it and exits 0.
+ */
+export declare function runCapture(rawInput: string, deps?: CaptureDeps): Promise<CaptureOutcome>;

package/dist/continuity-capture-hook.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Flair continuity-capture hook for Claude Code (flair#1257 slice 2) — the
+ * PostToolUse/Stop hook target that auto-journals the agent's working state
+ * into the ephemeral Memory tier, so an unseen kill/crash/OOM never loses the
+ * cadence. Registered (opt-in) via `flair doctor --fix` / `flair hook install
+ * --continuity`; the resume side lives in ./session-start-hook.ts.
+ *
+ * WHAT IT WRITES — see ./continuity.ts's module doc for the full, binding
+ * capture discipline. In one breath: at most ONE ephemeral+private row per
+ * fire; mutating tools only; Bash description-only (NEVER the command);
+ * Write/Edit/NotebookEdit path-only; Stop = a hard-bounded excerpt of
+ * assistant-chosen prose; never the raw hook JSON, never tool results, never
+ * an attempt at secret-scrubbing (the bound is the control).
+ *
+ * NO-OP-ON-ANY-FAILURE GUARANTEE (same posture as session-start-hook.ts):
+ * this binary can never block or break the agent's turn. Malformed stdin,
+ * missing identity, missing state file, Flair unreachable, a #1261 guard 400,
+ * a timeout, an unexpected throw — every one degrades to "journal nothing",
+ * at most one debug-level stderr line (the installed command discards
+ * stderr), and exit 0. Malformed hook JSON in particular journals NOTHING —
+ * no partial extraction that might pull raw tool results into the journal
+ * (Sherlock's input-validation tightening).
+ *
+ * A hard timeout (FLAIR_CONTINUITY_TIMEOUT_MS, default 2s) bounds the journal
+ * write so a slow Flair can't make the agent wait on its own diary.
+ *
+ * CONFIG (env, read identically to the other hook binaries):
+ *   FLAIR_AGENT_ID   (required — absent → no-op)
+ *   FLAIR_URL        (default http://localhost:19926 via flair-client)
+ *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
+ *   FLAIR_CONTINUITY_TIMEOUT_MS (default 2000; clamped 250..10000)
+ *   FLAIR_SESSION_DIR (default ~/.flair/session — test override)
+ *   FLAIR_HOOK_PROBE (probe mode: exit immediately, no stdin read, no writes)
+ */
+import { isProbeMode, readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
+import { buildJournalRow, bumpSeq, isSafeFileId, planCapture, resolveContinuityTimeoutMs, resolveSessionDir, } from "./continuity.js";
+/** Read all of stdin. Resolves on EOF, with a short fallback for manual runs
+ *  where nothing is piped (so it never hangs). */
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+        setTimeout(() => resolve(data), 200).unref?.();
+    });
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("continuity_write_timeout")), ms);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/** LAZY on purpose: @tpsdev-ai/flair-client resolves via its BUILT dist/, and
+ *  this module must both LOAD and TYPECHECK without that dist present — the
+ *  root `bun test test/unit/` lane AND the strict test-suite typecheck lane
+ *  each run before the client is built (see the ordering note in
+ *  test/unit/hook-install.test.ts). Tests always inject makeClient, so only
+ *  the real binary ever takes this path; the real module boundary is
+ *  exercised by the package-lane tests, which build the client first.
+ *
+ *  `@ts-ignore`, deliberately NOT `@ts-expect-error`: with the dist built the
+ *  import DOES resolve, and an expect-error directive would then itself be
+ *  the error. ts-ignore is inert in that state — verified locally in BOTH
+ *  states (dist present and dist deleted). */
+async function defaultClientFactory(agentId) {
+    // @ts-ignore -- resolvable only once flair-client's dist is built; see doc above
+    const mod = await import("@tpsdev-ai/flair-client");
+    const FlairClient = mod.FlairClient;
+    return new FlairClient({
+        agentId,
+        url: readEnvOrUnset("FLAIR_URL"),
+        keyPath: readEnvOrUnset("FLAIR_KEY_PATH"),
+    });
+}
+/**
+ * Core capture flow. NEVER throws; never writes to stdout. Returns a
+ * diagnostic outcome for tests — the binary ignores it and exits 0.
+ */
+export async function runCapture(rawInput, deps = {}) {
+    const env = deps.env ?? process.env;
+    const warn = deps.warn ?? ((message) => console.error(`flair-continuity-capture: ${message}`));
+    const now = deps.now ?? (() => new Date());
+    // Malformed / non-object hook JSON ⇒ journal NOTHING (Sherlock: no partial
+    // extraction — a half-parsed payload must never leak fields into a row).
+    let input;
+    try {
+        const parsed = JSON.parse(rawInput);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { wrote: false, reason: "malformed-input" };
+        }
+        input = parsed;
+    }
+    catch {
+        return { wrote: false, reason: "malformed-input" };
+    }
+    // Pure capture decision first — a read-only tool or an empty Stop exits
+    // before touching the filesystem or minting a seq.
+    const plan = planCapture(input);
+    if (!plan)
+        return { wrote: false, reason: "not-capturable" };
+    const agentId = env.FLAIR_AGENT_ID;
+    if (typeof agentId !== "string" || agentId === "" || !isSafeFileId(agentId)) {
+        return { wrote: false, reason: "no-agent-id" };
+    }
+    const harnessSessionId = input.session_id;
+    if (!isSafeFileId(harnessSessionId))
+        return { wrote: false, reason: "bad-session-id" };
+    // Per-process state, seeded by the SessionStart hook. Missing/unreadable ⇒
+    // continuity was never seeded for this harness session ⇒ journal nothing.
+    const sessionDir = deps.sessionDir ?? resolveSessionDir(env);
+    const state = bumpSeq(sessionDir, agentId, harnessSessionId, now());
+    if (!state)
+        return { wrote: false, reason: "no-state" };
+    const row = buildJournalRow(agentId, state, plan, now());
+    const makeClient = deps.makeClient ?? defaultClientFactory;
+    try {
+        const client = await makeClient(agentId);
+        await withTimeout(Promise.resolve(client.request("PUT", `/Memory/${row.id}`, row)), resolveContinuityTimeoutMs(env));
+        return { wrote: true, reason: "written" };
+    }
+    catch (err) {
+        // Fail-open: Flair unreachable, timeout, or the #1261 guard's 400 — one
+        // debug-level line, no retry, never a non-zero exit. The agent's turn is
+        // never blocked by its own journal.
+        const detail = err instanceof Error ? err.message : String(err);
+        warn(`journal write skipped (${detail.slice(0, 200)})`);
+        return { wrote: false, reason: "write-failed" };
+    }
+}
+/** Entry point. Reads stdin, captures, exits 0. Prints NOTHING to stdout —
+ *  a PostToolUse/Stop hook's stdout is harness-interpreted surface, and this
+ *  hook has nothing to say to it. */
+async function main() {
+    // Probe mode (flair#1007 pattern): being reached is the whole answer.
+    // Exits BEFORE reading stdin and before any filesystem or network touch —
+    // a probe must cost nothing and change nothing (especially no seq burn).
+    if (isProbeMode())
+        return;
+    try {
+        stripInterpolationLiteralsFromEnv();
+        await runCapture(await readStdin());
+    }
+    catch {
+        // Swallow everything — fail-open is the contract.
+    }
+}
+const importMeta = import.meta;
+const isMain = importMeta.main === true ||
+    (typeof process !== "undefined" &&
+        process.argv[1] != null &&
+        import.meta.url === `file://${process.argv[1]}`);
+if (isMain) {
+    void main().catch(() => { });
+}

package/dist/continuity.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Continuity core (flair#1257 slice 2) — the shared logic behind the Claude
+ * Code continuity hook adapter: the ephemeral session journal (write side,
+ * `flair-continuity-capture`) and the agent-pull resume path grown into
+ * `flair-session-start`.
+ *
+ * Design record: flair#1257 ("FINAL design (K&S ruled)" + the merged slice-2
+ * acceptance scenarios + Sherlock's capture-content rulings). The shape in one
+ * paragraph: continuity is the EXISTING `ephemeral` Memory tier (24h TTL,
+ * private-only — the #1261 server guard refuses ephemeral+shared), auto-written
+ * by harness hooks (PostToolUse/Stop), and resumed by agent-pull: SessionStart
+ * emits at most ONE hint line ("N entries from your previous session…"), never
+ * journal content. Promotion to durable memory is REM distillation's job
+ * (#1205, slice 3) — nothing here summarizes or promotes.
+ *
+ * CAPTURE DISCIPLINE (Sherlock-ruled, binding — do not drift)
+ * -----------------------------------------------------------
+ * - PostToolUse journals ONLY the mutating-tool allowlist (MUTATING_TOOLS
+ *   below). Read-only tools journal nothing — their results are
+ *   world-recoverable, and journaling them would copy tool payloads into a
+ *   store with cross-session readback.
+ * - Bash: journal the `description` field ONLY — NEVER the command string.
+ *   Argv is exactly where secrets ride; a journal that copies command lines
+ *   re-creates the transcript-leak class. No description ⇒ the literal
+ *   "bash: (no description)", never a fallback to the command.
+ * - Write/Edit/NotebookEdit: file path only — never content, never diffs.
+ * - Stop: a dedicated summary/intent field from the hook payload when present,
+ *   else the final assistant text — either way HARD-bounded (see
+ *   CAPTURE_BOUND_CHARS). Empty text ⇒ no journal (never a placeholder, never
+ *   a synthesis from tool results).
+ * - One row max per hook fire. Never the raw hook JSON. Never tool_response.
+ *   No secret-scrubbing attempts — the bound plus the already-user-visible
+ *   property of assistant prose IS the control; pattern-matching secrets is a
+ *   losing game and would only add false confidence.
+ *
+ * ROW SHAPE (per the merged acceptance set)
+ * -----------------------------------------
+ *   durability: "ephemeral", visibility: "private" (EXPLICIT — defense in
+ *   depth above the #1261 guard, never the durability-keyed default),
+ *   tags: ["adk:continuity:<sessionId>"], sessionId, and
+ *   meta: { seq, processUUID, sessionId, hook, tool? } — seq is a monotonic
+ *   per-process counter (ordering insurance over createdAt alone), processUUID
+ *   disambiguates concurrent processes sharing one agent identity.
+ *
+ * LOCAL FILES (never journal content — IDs and counters only)
+ * -----------------------------------------------------------
+ * - Pointer file  <dir>/<agentId>.current            (0600, dir 0700)
+ *     { sessionId, processUUID, updatedAt } — the last-known session for this
+ *     agent identity; the resume fast path. Rotated by SessionStart.
+ * - State file    <dir>/<agentId>.<harnessSessionId>.state.json (0600)
+ *     { sessionId, processUUID, seq, … } — seeded by SessionStart, read and
+ *     seq-incremented (atomically, tmp+rename) by every capture fire. Keyed by
+ *     the HARNESS session id so concurrent processes never share a state file
+ *     (scenario S8) and compaction — same harness session id — finds the same
+ *     file untouched (scenario S7: compaction ≠ restart; no rotation, no new
+ *     sessionId).
+ *
+ * FAIL-OPEN THROUGHOUT: continuity is a recovery aid, not a correctness gate.
+ * Flair unreachable, a #1261 guard 400, a malformed payload, a missing state
+ * file — every failure degrades to "journal nothing / hint nothing" and never
+ * blocks the agent's turn or boot.
+ */
+/** Tag prefix for journal rows — `adk:continuity:<sessionId>`. One tag, which
+ *  is exactly the shape #1205's REM `scope:"tagged"` distillation consumes. */
+export declare const CONTINUITY_TAG_PREFIX = "adk:continuity:";
+/**
+ * THE capture bound, in characters — applied as a HARD truncate (with a
+ * visible ellipsis) to EVERY journal content line, not just the Stop excerpt.
+ * Sherlock ruled a single uniform bound ("a bound that varies by content type
+ * is hard to audit — 400 chars, hard truncate, every time").
+ *
+ * This bound is LOAD-BEARING, not cosmetic: it is what keeps a Stop excerpt a
+ * summary instead of a dump, and it is the control that makes the capture
+ * class acceptable at all. Raising it — or "capturing the full final text" —
+ * is a security REGRESSION, not an enhancement.
+ */
+export declare const CAPTURE_BOUND_CHARS = 400;
+/**
+ * The mutating-tool allowlist — a CLOSED set; anything not listed journals
+ * nothing (fail-closed). Why each member is here and the notable exclusions:
+ * Write/Edit/NotebookEdit mutate file/cell state (NotebookEdit is included
+ * precisely because a cell edit is a state mutation, not a read); Bash can
+ * mutate anything. Read/Grep/Glob/WebFetch/WebSearch and every other
+ * read-only tool are EXCLUDED because their results are world-recoverable —
+ * the agent can simply re-observe them, and journaling them would copy tool
+ * payloads into the journal.
+ */
+export declare const MUTATING_TOOLS: readonly ["Write", "Edit", "NotebookEdit", "Bash"];
+export type MutatingTool = (typeof MUTATING_TOOLS)[number];
+/** Default resume-search page — older context is distillation's job (#1205). */
+export declare const RESUME_SEARCH_LIMIT = 50;
+/** Fallback (agentId-wide) search page — bounded superset of one session. */
+export declare const FALLBACK_SEARCH_LIMIT = 200;
+/** Journal-write timeout (ms): the hook must never make the agent wait on a
+ *  slow Flair. Overridable via FLAIR_CONTINUITY_TIMEOUT_MS, clamped below. */
+export declare const DEFAULT_CONTINUITY_TIMEOUT_MS = 2000;
+export declare function isSafeFileId(value: unknown): value is string;
+export declare function resolveContinuityTimeoutMs(env?: Record<string, string | undefined>): number;
+/** Where pointer + state files live. FLAIR_SESSION_DIR overrides for tests
+ *  (homeOverride discipline — no test ever touches the real ~/.flair). */
+export declare function resolveSessionDir(env?: Record<string, string | undefined>): string;
+export declare function pointerPath(sessionDir: string, agentId: string): string;
+export declare function statePath(sessionDir: string, agentId: string, harnessSessionId: string): string;
+export interface SessionPointer {
+    sessionId: string;
+    processUUID: string;
+    updatedAt: string;
+}
+export interface SessionState {
+    sessionId: string;
+    processUUID: string;
+    seq: number;
+    agentId: string;
+    harnessSessionId: string;
+    updatedAt: string;
+}
+/** Read + parse the pointer file. null on ANY problem (missing, unreadable,
+ *  malformed, wrong shape) — a bad pointer degrades to the fallback search,
+ *  never to an error. */
+export declare function readPointer(sessionDir: string, agentId: string): SessionPointer | null;
+/** Read + parse a state file. null on ANY problem — capture then journals
+ *  nothing (continuity wasn't seeded for this harness session). */
+export declare function readState(sessionDir: string, agentId: string, harnessSessionId: string): SessionState | null;
+/**
+ * Mint a fresh sessionId + processUUID, seed the per-harness-session state
+ * file (seq 0) and rotate the pointer file to the new session. Called by the
+ * SessionStart hook on startup/resume/clear — NEVER on compaction (the caller
+ * gates on `source`; compaction keeps the same harness session id, so the same
+ * state file — and therefore the same sessionId — stays in place untouched,
+ * which is what makes scenario S7 hold by construction).
+ *
+ * Throws on fs failure — the caller treats that as "continuity unavailable"
+ * and proceeds (fail-open), it never propagates out of the hook.
+ */
+export declare function seedSession(sessionDir: string, agentId: string, harnessSessionId: string, now?: Date): SessionState;
+/**
+ * Atomically increment the state file's seq and return the NEW state (the one
+ * whose seq this capture fire owns). Write-to-temp + rename so a concurrent
+ * reader never sees a torn file. Returns null on any failure — the caller
+ * journals nothing rather than journaling with a wrong/duplicate seq.
+ *
+ * The seq is consumed BEFORE the network write, so even a failed write burns
+ * its seq — gaps are fine, non-monotonicity is not.
+ */
+export declare function bumpSeq(sessionDir: string, agentId: string, harnessSessionId: string, now?: Date): SessionState | null;
+/** Subset of the Claude Code hook payload the capture bin reads. It extracts
+ *  ONLY these fields — the raw hook JSON (tool_input.command, tool_response,
+ *  transcript_path, …) is NEVER stored or forwarded. */
+export interface CaptureHookInput {
+    hook_event_name?: unknown;
+    session_id?: unknown;
+    tool_name?: unknown;
+    tool_input?: unknown;
+    /** Stop payloads: the final assistant message text, when the harness
+     *  provides it. Assistant-chosen prose — already user-visible. */
+    last_assistant_message?: unknown;
+    /** A dedicated summary/intent field, when the harness provides one —
+     *  preferred over raw final text (intent-class by construction). */
+    summary?: unknown;
+    [key: string]: unknown;
+}
+export interface CapturePlan {
+    hook: "PostToolUse" | "Stop";
+    tool?: MutatingTool;
+    /** The full journal content line — already hard-bounded. */
+    content: string;
+}
+/** HARD truncate at CAPTURE_BOUND_CHARS with a visible ellipsis, so a reader
+ *  knows the excerpt is incomplete and never acts on a cut sentence as if it
+ *  were whole. See CAPTURE_BOUND_CHARS — the bound is load-bearing. */
+export declare function hardBound(text: string): string;
+/**
+ * Pure capture decision: hook payload → at most one journal line, or null for
+ * "journal nothing" (read-only tool, empty Stop text, unknown/missing fields).
+ * This function IS the capture discipline — see the module doc; every branch
+ * below maps to a Sherlock-ruled rule.
+ */
+export declare function planCapture(input: CaptureHookInput): CapturePlan | null;
+export declare function continuityTag(sessionId: string): string;
+export interface JournalRow {
+    id: string;
+    agentId: string;
+    content: string;
+    type: "session";
+    durability: "ephemeral";
+    /** EXPLICIT on every write — never the durability-keyed default. Hook-side
+     *  half of the #1261 defense-in-depth pair (server guard is the other). */
+    visibility: "private";
+    tags: string[];
+    sessionId: string;
+    meta: {
+        seq: number;
+        processUUID: string;
+        sessionId: string;
+        hook: string;
+        tool?: string;
+    };
+    createdAt: string;
+}
+export declare function buildJournalRow(agentId: string, state: SessionState, plan: CapturePlan, now?: Date): JournalRow;
+/** Minimal client surface both hook binaries depend on (eases testing —
+ *  structurally satisfied by the real FlairClient). */
+export interface ContinuityClient {
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+}
+export interface ResumeEntry {
+    id: string;
+    seq: number | null;
+    processUUID: string | null;
+    sessionId: string | null;
+    createdAt: string;
+}
+export interface ResumeResult {
+    /** The prior session's journal entries, seq-ordered — ONE process's entries
+     *  only, never an interleave of two processUUIDs. */
+    entries: ResumeEntry[];
+    /** The session those entries belong to (for the hint's search tag). */
+    sessionId: string | null;
+}
+/**
+ * Resume discovery, both layers as ruled on the issue:
+ *
+ *   FAST PATH — the pointer file named a prior session: search exactly that
+ *   session's tag. A session's rows are all one process's by construction
+ *   (sessionId is minted per process), so the tag IS the process filter.
+ *
+ *   FALLBACK — no (readable) pointer: agentId-wide ephemeral search,
+ *   disambiguated by the processUUID carried in row meta. Entries are grouped
+ *   by processUUID and ONLY the most recent group is returned — a resume
+ *   reconstruction MUST NEVER interleave entries from two distinct
+ *   processUUIDs (scenario S8; two live processes sharing an identity).
+ *   Rows without a processUUID cannot be attributed and are skipped.
+ *
+ * Every failure (Flair down, auth error, malformed response) resolves to zero
+ * entries — the caller then emits no hint. Never throws.
+ */
+export declare function discoverResume(client: ContinuityClient, agentId: string, pointer: SessionPointer | null, now?: Date): Promise<ResumeResult>;
+/**
+ * The resume hint — at most ONE line, informational, agent-pull (scenario
+ * S10): it names the count and the search tag, and NEVER carries journal
+ * content (not even summarized). Zero entries ⇒ null ⇒ the hook emits no hint
+ * at all — an empty journal is normal operation, not a warning.
+ */
+export declare function buildResumeHint(result: ResumeResult): string | null;
+/** The SessionStart payload fields the boot path reads. The "how did this
+ *  session start" discriminator has appeared as both `source` and
+ *  `how_started` across harness doc generations — read either. */
+export interface ContinuityBootInput {
+    source?: unknown;
+    how_started?: unknown;
+    session_id?: unknown;
+    [key: string]: unknown;
+}
+export interface ContinuityBoot {
+    active: boolean;
+    priorPointer: SessionPointer | null;
+}
+/**
+ * Filesystem half of the resume path (pointer read → mint → rotate → seed the
+ * capture state file), called by the SessionStart hook. Pure local work —
+ * runs regardless of Flair reachability so capture always has its state file.
+ * Never throws; any fs failure degrades to "resume hint may still fire,
+ * capture won't" — fail-open in both directions.
+ *
+ * COMPACTION IS NOT A RESTART (scenario S7): when the harness reports the
+ * session start came from compaction, NOTHING runs — no pointer read, no
+ * rotation, no state-file touch. The harness session id is unchanged across
+ * compaction, so the capture hook keeps finding the same state file and the
+ * same sessionId; the journal never fragments.
+ */
+export declare function prepareContinuityBoot(input: ContinuityBootInput, agentId: string, env?: Record<string, string | undefined>): ContinuityBoot;

package/dist/continuity.js

@@ -0,0 +1,494 @@
+/**
+ * Continuity core (flair#1257 slice 2) — the shared logic behind the Claude
+ * Code continuity hook adapter: the ephemeral session journal (write side,
+ * `flair-continuity-capture`) and the agent-pull resume path grown into
+ * `flair-session-start`.
+ *
+ * Design record: flair#1257 ("FINAL design (K&S ruled)" + the merged slice-2
+ * acceptance scenarios + Sherlock's capture-content rulings). The shape in one
+ * paragraph: continuity is the EXISTING `ephemeral` Memory tier (24h TTL,
+ * private-only — the #1261 server guard refuses ephemeral+shared), auto-written
+ * by harness hooks (PostToolUse/Stop), and resumed by agent-pull: SessionStart
+ * emits at most ONE hint line ("N entries from your previous session…"), never
+ * journal content. Promotion to durable memory is REM distillation's job
+ * (#1205, slice 3) — nothing here summarizes or promotes.
+ *
+ * CAPTURE DISCIPLINE (Sherlock-ruled, binding — do not drift)
+ * -----------------------------------------------------------
+ * - PostToolUse journals ONLY the mutating-tool allowlist (MUTATING_TOOLS
+ *   below). Read-only tools journal nothing — their results are
+ *   world-recoverable, and journaling them would copy tool payloads into a
+ *   store with cross-session readback.
+ * - Bash: journal the `description` field ONLY — NEVER the command string.
+ *   Argv is exactly where secrets ride; a journal that copies command lines
+ *   re-creates the transcript-leak class. No description ⇒ the literal
+ *   "bash: (no description)", never a fallback to the command.
+ * - Write/Edit/NotebookEdit: file path only — never content, never diffs.
+ * - Stop: a dedicated summary/intent field from the hook payload when present,
+ *   else the final assistant text — either way HARD-bounded (see
+ *   CAPTURE_BOUND_CHARS). Empty text ⇒ no journal (never a placeholder, never
+ *   a synthesis from tool results).
+ * - One row max per hook fire. Never the raw hook JSON. Never tool_response.
+ *   No secret-scrubbing attempts — the bound plus the already-user-visible
+ *   property of assistant prose IS the control; pattern-matching secrets is a
+ *   losing game and would only add false confidence.
+ *
+ * ROW SHAPE (per the merged acceptance set)
+ * -----------------------------------------
+ *   durability: "ephemeral", visibility: "private" (EXPLICIT — defense in
+ *   depth above the #1261 guard, never the durability-keyed default),
+ *   tags: ["adk:continuity:<sessionId>"], sessionId, and
+ *   meta: { seq, processUUID, sessionId, hook, tool? } — seq is a monotonic
+ *   per-process counter (ordering insurance over createdAt alone), processUUID
+ *   disambiguates concurrent processes sharing one agent identity.
+ *
+ * LOCAL FILES (never journal content — IDs and counters only)
+ * -----------------------------------------------------------
+ * - Pointer file  <dir>/<agentId>.current            (0600, dir 0700)
+ *     { sessionId, processUUID, updatedAt } — the last-known session for this
+ *     agent identity; the resume fast path. Rotated by SessionStart.
+ * - State file    <dir>/<agentId>.<harnessSessionId>.state.json (0600)
+ *     { sessionId, processUUID, seq, … } — seeded by SessionStart, read and
+ *     seq-incremented (atomically, tmp+rename) by every capture fire. Keyed by
+ *     the HARNESS session id so concurrent processes never share a state file
+ *     (scenario S8) and compaction — same harness session id — finds the same
+ *     file untouched (scenario S7: compaction ≠ restart; no rotation, no new
+ *     sessionId).
+ *
+ * FAIL-OPEN THROUGHOUT: continuity is a recovery aid, not a correctness gate.
+ * Flair unreachable, a #1261 guard 400, a malformed payload, a missing state
+ * file — every failure degrades to "journal nothing / hint nothing" and never
+ * blocks the agent's turn or boot.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+// ── constants ───────────────────────────────────────────────────────────────
+/** Tag prefix for journal rows — `adk:continuity:<sessionId>`. One tag, which
+ *  is exactly the shape #1205's REM `scope:"tagged"` distillation consumes. */
+export const CONTINUITY_TAG_PREFIX = "adk:continuity:";
+/**
+ * THE capture bound, in characters — applied as a HARD truncate (with a
+ * visible ellipsis) to EVERY journal content line, not just the Stop excerpt.
+ * Sherlock ruled a single uniform bound ("a bound that varies by content type
+ * is hard to audit — 400 chars, hard truncate, every time").
+ *
+ * This bound is LOAD-BEARING, not cosmetic: it is what keeps a Stop excerpt a
+ * summary instead of a dump, and it is the control that makes the capture
+ * class acceptable at all. Raising it — or "capturing the full final text" —
+ * is a security REGRESSION, not an enhancement.
+ */
+export const CAPTURE_BOUND_CHARS = 400;
+/**
+ * The mutating-tool allowlist — a CLOSED set; anything not listed journals
+ * nothing (fail-closed). Why each member is here and the notable exclusions:
+ * Write/Edit/NotebookEdit mutate file/cell state (NotebookEdit is included
+ * precisely because a cell edit is a state mutation, not a read); Bash can
+ * mutate anything. Read/Grep/Glob/WebFetch/WebSearch and every other
+ * read-only tool are EXCLUDED because their results are world-recoverable —
+ * the agent can simply re-observe them, and journaling them would copy tool
+ * payloads into the journal.
+ */
+export const MUTATING_TOOLS = ["Write", "Edit", "NotebookEdit", "Bash"];
+/** Default resume-search page — older context is distillation's job (#1205). */
+export const RESUME_SEARCH_LIMIT = 50;
+/** Fallback (agentId-wide) search page — bounded superset of one session. */
+export const FALLBACK_SEARCH_LIMIT = 200;
+/** Journal-write timeout (ms): the hook must never make the agent wait on a
+ *  slow Flair. Overridable via FLAIR_CONTINUITY_TIMEOUT_MS, clamped below. */
+export const DEFAULT_CONTINUITY_TIMEOUT_MS = 2000;
+const CONTINUITY_TIMEOUT_FLOOR_MS = 250;
+const CONTINUITY_TIMEOUT_CEILING_MS = 10_000;
+/** Identifier shape for everything interpolated into a session-dir FILENAME
+ *  (agentId, harness session id). No `/`, no `\`, no whitespace — traversal
+ *  is impossible by shape; length-capped so a hostile hook payload can't
+ *  manufacture pathological filenames. */
+const SAFE_FILE_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+export function isSafeFileId(value) {
+    return typeof value === "string" && SAFE_FILE_ID_RE.test(value);
+}
+export function resolveContinuityTimeoutMs(env = process.env) {
+    const raw = env.FLAIR_CONTINUITY_TIMEOUT_MS;
+    const parsed = raw != null ? Number(raw) : NaN;
+    return Number.isFinite(parsed) && parsed >= CONTINUITY_TIMEOUT_FLOOR_MS && parsed <= CONTINUITY_TIMEOUT_CEILING_MS
+        ? parsed
+        : DEFAULT_CONTINUITY_TIMEOUT_MS;
+}
+// ── session dir / pointer / state files ─────────────────────────────────────
+/** Where pointer + state files live. FLAIR_SESSION_DIR overrides for tests
+ *  (homeOverride discipline — no test ever touches the real ~/.flair). */
+export function resolveSessionDir(env = process.env) {
+    const override = env.FLAIR_SESSION_DIR;
+    if (typeof override === "string" && override.trim() !== "")
+        return override;
+    return join(homedir(), ".flair", "session");
+}
+export function pointerPath(sessionDir, agentId) {
+    return join(sessionDir, `${agentId}.current`);
+}
+export function statePath(sessionDir, agentId, harnessSessionId) {
+    return join(sessionDir, `${agentId}.${harnessSessionId}.state.json`);
+}
+/** 0600/0700 — the files carry session identifiers (never journal content),
+ *  but they are still per-agent working state; keep them owner-only. */
+function writeFilePrivate(path, data) {
+    writeFileSync(path, data, { mode: 0o600 });
+    // writeFileSync's mode only applies on CREATE — an existing file keeps its
+    // old bits, so re-assert.
+    chmodSync(path, 0o600);
+}
+function ensureSessionDir(sessionDir) {
+    mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+}
+/** Read + parse the pointer file. null on ANY problem (missing, unreadable,
+ *  malformed, wrong shape) — a bad pointer degrades to the fallback search,
+ *  never to an error. */
+export function readPointer(sessionDir, agentId) {
+    try {
+        const raw = readFileSync(pointerPath(sessionDir, agentId), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.sessionId === "string" && parsed.sessionId !== "") {
+            return {
+                sessionId: parsed.sessionId,
+                processUUID: typeof parsed.processUUID === "string" ? parsed.processUUID : "",
+                updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read + parse a state file. null on ANY problem — capture then journals
+ *  nothing (continuity wasn't seeded for this harness session). */
+export function readState(sessionDir, agentId, harnessSessionId) {
+    try {
+        const raw = readFileSync(statePath(sessionDir, agentId, harnessSessionId), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed.sessionId === "string" && parsed.sessionId !== "" &&
+            typeof parsed.processUUID === "string" && parsed.processUUID !== "" &&
+            typeof parsed.seq === "number" && Number.isFinite(parsed.seq)) {
+            return {
+                sessionId: parsed.sessionId,
+                processUUID: parsed.processUUID,
+                seq: parsed.seq,
+                agentId: typeof parsed.agentId === "string" ? parsed.agentId : agentId,
+                harnessSessionId: typeof parsed.harnessSessionId === "string" ? parsed.harnessSessionId : harnessSessionId,
+                updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Mint a fresh sessionId + processUUID, seed the per-harness-session state
+ * file (seq 0) and rotate the pointer file to the new session. Called by the
+ * SessionStart hook on startup/resume/clear — NEVER on compaction (the caller
+ * gates on `source`; compaction keeps the same harness session id, so the same
+ * state file — and therefore the same sessionId — stays in place untouched,
+ * which is what makes scenario S7 hold by construction).
+ *
+ * Throws on fs failure — the caller treats that as "continuity unavailable"
+ * and proceeds (fail-open), it never propagates out of the hook.
+ */
+export function seedSession(sessionDir, agentId, harnessSessionId, now = new Date()) {
+    ensureSessionDir(sessionDir);
+    const state = {
+        sessionId: `cs-${randomUUID()}`,
+        processUUID: randomUUID(),
+        seq: 0,
+        agentId,
+        harnessSessionId,
+        updatedAt: now.toISOString(),
+    };
+    writeFilePrivate(statePath(sessionDir, agentId, harnessSessionId), JSON.stringify(state, null, 2) + "\n");
+    const pointer = { sessionId: state.sessionId, processUUID: state.processUUID, updatedAt: state.updatedAt };
+    writeFilePrivate(pointerPath(sessionDir, agentId), JSON.stringify(pointer, null, 2) + "\n");
+    return state;
+}
+/**
+ * Atomically increment the state file's seq and return the NEW state (the one
+ * whose seq this capture fire owns). Write-to-temp + rename so a concurrent
+ * reader never sees a torn file. Returns null on any failure — the caller
+ * journals nothing rather than journaling with a wrong/duplicate seq.
+ *
+ * The seq is consumed BEFORE the network write, so even a failed write burns
+ * its seq — gaps are fine, non-monotonicity is not.
+ */
+export function bumpSeq(sessionDir, agentId, harnessSessionId, now = new Date()) {
+    const current = readState(sessionDir, agentId, harnessSessionId);
+    if (!current)
+        return null;
+    const next = { ...current, seq: current.seq + 1, updatedAt: now.toISOString() };
+    const finalPath = statePath(sessionDir, agentId, harnessSessionId);
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        writeFilePrivate(tmpPath, JSON.stringify(next, null, 2) + "\n");
+        renameSync(tmpPath, finalPath);
+        return next;
+    }
+    catch {
+        return null;
+    }
+}
+/** HARD truncate at CAPTURE_BOUND_CHARS with a visible ellipsis, so a reader
+ *  knows the excerpt is incomplete and never acts on a cut sentence as if it
+ *  were whole. See CAPTURE_BOUND_CHARS — the bound is load-bearing. */
+export function hardBound(text) {
+    if (text.length <= CAPTURE_BOUND_CHARS)
+        return text;
+    return `${text.slice(0, CAPTURE_BOUND_CHARS)}…`;
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+/**
+ * Pure capture decision: hook payload → at most one journal line, or null for
+ * "journal nothing" (read-only tool, empty Stop text, unknown/missing fields).
+ * This function IS the capture discipline — see the module doc; every branch
+ * below maps to a Sherlock-ruled rule.
+ */
+export function planCapture(input) {
+    const hook = input.hook_event_name;
+    if (hook === "PostToolUse") {
+        const tool = input.tool_name;
+        // Closed allowlist, fail-closed: an unknown or absent tool name journals
+        // nothing. Read-only tools land here by design (world-recoverable).
+        if (typeof tool !== "string" || !MUTATING_TOOLS.includes(tool))
+            return null;
+        const toolInput = (input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {});
+        if (tool === "Bash") {
+            // description ONLY — NEVER the command string, and never a fallback to
+            // it. The command is argv: exactly where our leak history lives.
+            const description = asNonEmptyString(toolInput.description);
+            return { hook, tool, content: hardBound(description ? `bash: ${description}` : "bash: (no description)") };
+        }
+        // Write / Edit / NotebookEdit: file path only — never content, never
+        // diffs. NotebookEdit's path key has appeared as both `notebook_path` and
+        // `file_path` across harness doc generations — accept either; both are
+        // paths, neither is content.
+        const pathField = tool === "NotebookEdit" ? (toolInput.notebook_path ?? toolInput.file_path) : toolInput.file_path;
+        const path = asNonEmptyString(pathField);
+        const label = tool === "Write" ? "write" : tool === "Edit" ? "edit" : "notebook-edit";
+        return { hook, tool: tool, content: hardBound(path ? `${label}: ${path}` : `${label}: (no file path)`) };
+    }
+    if (hook === "Stop") {
+        // Prefer a dedicated summary/intent field when the payload carries one
+        // (intent-class by construction beats prose the agent happened to emit);
+        // else the final assistant text. Both are assistant-chosen, user-visible
+        // prose — never tool payloads — and both get the same hard bound.
+        const source = asNonEmptyString(input.summary) ?? asNonEmptyString(input.last_assistant_message);
+        if (!source)
+            return null; // tool-only turn ⇒ no journal, no placeholder
+        return { hook, content: hardBound(`stop: ${source.trim()}`) };
+    }
+    return null;
+}
+// ── journal row construction ────────────────────────────────────────────────
+export function continuityTag(sessionId) {
+    return `${CONTINUITY_TAG_PREFIX}${sessionId}`;
+}
+export function buildJournalRow(agentId, state, plan, now = new Date()) {
+    const meta = {
+        seq: state.seq,
+        processUUID: state.processUUID,
+        sessionId: state.sessionId,
+        hook: plan.hook,
+    };
+    if (plan.tool)
+        meta.tool = plan.tool;
+    return {
+        id: `${agentId}-${randomUUID()}`,
+        agentId,
+        content: plan.content,
+        type: "session",
+        durability: "ephemeral",
+        visibility: "private",
+        tags: [continuityTag(state.sessionId)],
+        sessionId: state.sessionId,
+        meta,
+        createdAt: now.toISOString(),
+    };
+}
+/**
+ * Fetch this agent's own ephemeral rows through the SUPPORTED read surface —
+ * `GET /Memory?agentId=<id>` (the same verb the REM nightly runner's snapshot
+ * step uses) — then filter client-side.
+ *
+ * This replaces the original `POST /Memory/search_by_conditions` read
+ * (flair#1257 slice 3 fix): search_by_conditions is an ops-API operation, and
+ * the Memory resource exposes no REST handler for that path — the POST 405s
+ * ("does not have a post method... /Memory/search_by_conditions"), verified
+ * against a real Harper in test/integration/continuity-rem-promotion-1257.
+ * Because discoverResume fails open by design, that 405 didn't error — it
+ * silently made EVERY resume come back empty (no hint, ever): the fail-open
+ * masked a dead read path, exactly the "unrun check looks like a pass" shape.
+ *
+ * The client-side filters mirror what the old conditions asked the server
+ * for: own agentId (the GET's query param is NOT an owner filter — the read
+ * scope returns other agents' non-private rows too; journal rows are private
+ * so only our own arrive, but the filter must not lean on that) and
+ * durability "ephemeral".
+ */
+async function fetchOwnEphemeralRows(client, agentId) {
+    const raw = await client.request("GET", `/Memory?agentId=${encodeURIComponent(agentId)}`);
+    return rowsFrom(raw).filter((r) => r.agentId === agentId && r.durability === "ephemeral");
+}
+function rowsFrom(result) {
+    if (Array.isArray(result))
+        return result;
+    const wrapped = result?.results;
+    return Array.isArray(wrapped) ? wrapped : [];
+}
+/** Expired rows are excluded HERE, not just by MemoryMaintenance — the reap is
+ *  asynchronous, so a row whose expiresAt is past may still be in storage
+ *  (scenario S4: it must never reach the agent regardless). */
+function isLive(row, now) {
+    if (typeof row.expiresAt !== "string" || row.expiresAt === "")
+        return true;
+    const expiry = Date.parse(row.expiresAt);
+    return !Number.isFinite(expiry) || expiry > now.getTime();
+}
+function continuitySessionOf(row) {
+    const meta = row.meta;
+    if (meta && typeof meta.sessionId === "string" && meta.sessionId !== "")
+        return meta.sessionId;
+    if (Array.isArray(row.tags)) {
+        for (const tag of row.tags) {
+            if (typeof tag === "string" && tag.startsWith(CONTINUITY_TAG_PREFIX)) {
+                const sid = tag.slice(CONTINUITY_TAG_PREFIX.length);
+                if (sid !== "")
+                    return sid;
+            }
+        }
+    }
+    return null;
+}
+function toEntry(row) {
+    const meta = row.meta;
+    return {
+        id: typeof row.id === "string" ? row.id : "",
+        seq: meta && typeof meta.seq === "number" && Number.isFinite(meta.seq) ? meta.seq : null,
+        processUUID: meta && typeof meta.processUUID === "string" && meta.processUUID !== "" ? meta.processUUID : null,
+        sessionId: continuitySessionOf(row),
+        createdAt: typeof row.createdAt === "string" ? row.createdAt : "",
+    };
+}
+/** seq ascending (monotonic per process — the primary order), createdAt as
+ *  tiebreak ONLY (and as the order for legacy rows lacking a seq). */
+function seqOrder(a, b) {
+    if (a.seq != null && b.seq != null && a.seq !== b.seq)
+        return a.seq - b.seq;
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt < b.createdAt ? -1 : 1;
+    return 0;
+}
+/**
+ * Resume discovery, both layers as ruled on the issue:
+ *
+ *   FAST PATH — the pointer file named a prior session: search exactly that
+ *   session's tag. A session's rows are all one process's by construction
+ *   (sessionId is minted per process), so the tag IS the process filter.
+ *
+ *   FALLBACK — no (readable) pointer: agentId-wide ephemeral search,
+ *   disambiguated by the processUUID carried in row meta. Entries are grouped
+ *   by processUUID and ONLY the most recent group is returned — a resume
+ *   reconstruction MUST NEVER interleave entries from two distinct
+ *   processUUIDs (scenario S8; two live processes sharing an identity).
+ *   Rows without a processUUID cannot be attributed and are skipped.
+ *
+ * Every failure (Flair down, auth error, malformed response) resolves to zero
+ * entries — the caller then emits no hint. Never throws.
+ */
+export async function discoverResume(client, agentId, pointer, now = new Date()) {
+    try {
+        if (pointer) {
+            const priorTag = continuityTag(pointer.sessionId);
+            const rows = (await fetchOwnEphemeralRows(client, agentId))
+                .filter((r) => Array.isArray(r.tags) && r.tags.includes(priorTag))
+                .filter((r) => isLive(r, now));
+            const entries = rows.map(toEntry).sort(seqOrder).slice(0, RESUME_SEARCH_LIMIT);
+            return { entries, sessionId: entries.length > 0 ? pointer.sessionId : null };
+        }
+        const rows = (await fetchOwnEphemeralRows(client, agentId))
+            .filter((r) => isLive(r, now))
+            .filter((r) => continuitySessionOf(r) !== null)
+            .slice(0, FALLBACK_SEARCH_LIMIT);
+        const groups = new Map();
+        for (const row of rows) {
+            const entry = toEntry(row);
+            if (!entry.processUUID)
+                continue; // unattributable — never guess
+            const list = groups.get(entry.processUUID) ?? [];
+            list.push(entry);
+            groups.set(entry.processUUID, list);
+        }
+        let best = null;
+        let bestLatest = "";
+        for (const list of groups.values()) {
+            const latest = list.reduce((max, e) => (e.createdAt > max ? e.createdAt : max), "");
+            if (best === null || latest > bestLatest) {
+                best = list;
+                bestLatest = latest;
+            }
+        }
+        if (!best || best.length === 0)
+            return { entries: [], sessionId: null };
+        const entries = [...best].sort(seqOrder).slice(0, RESUME_SEARCH_LIMIT);
+        return { entries, sessionId: entries[0]?.sessionId ?? null };
+    }
+    catch {
+        return { entries: [], sessionId: null };
+    }
+}
+/**
+ * The resume hint — at most ONE line, informational, agent-pull (scenario
+ * S10): it names the count and the search tag, and NEVER carries journal
+ * content (not even summarized). Zero entries ⇒ null ⇒ the hook emits no hint
+ * at all — an empty journal is normal operation, not a warning.
+ */
+export function buildResumeHint(result) {
+    const n = result.entries.length;
+    if (n === 0 || !result.sessionId)
+        return null;
+    const noun = n === 1 ? "entry" : "entries";
+    return `Continuity: ${n} short-term journal ${noun} from your previous session survived — search memory tag "${continuityTag(result.sessionId)}" if you need to recall what dropped from context.`;
+}
+/**
+ * Filesystem half of the resume path (pointer read → mint → rotate → seed the
+ * capture state file), called by the SessionStart hook. Pure local work —
+ * runs regardless of Flair reachability so capture always has its state file.
+ * Never throws; any fs failure degrades to "resume hint may still fire,
+ * capture won't" — fail-open in both directions.
+ *
+ * COMPACTION IS NOT A RESTART (scenario S7): when the harness reports the
+ * session start came from compaction, NOTHING runs — no pointer read, no
+ * rotation, no state-file touch. The harness session id is unchanged across
+ * compaction, so the capture hook keeps finding the same state file and the
+ * same sessionId; the journal never fragments.
+ */
+export function prepareContinuityBoot(input, agentId, env = process.env) {
+    const startedFrom = typeof input.source === "string" ? input.source : typeof input.how_started === "string" ? input.how_started : "";
+    if (startedFrom === "compact")
+        return { active: false, priorPointer: null };
+    // Without a harness session id there is nothing to key the capture state
+    // file by (manual runs, older harnesses) — stay fully inert.
+    if (!isSafeFileId(agentId) || !isSafeFileId(input.session_id))
+        return { active: false, priorPointer: null };
+    const sessionDir = resolveSessionDir(env);
+    const priorPointer = readPointer(sessionDir, agentId);
+    try {
+        seedSession(sessionDir, agentId, input.session_id);
+    }
+    catch {
+        // Session dir unwritable — capture can't run this session, but a resume
+        // hint from the prior pointer is still valid and still cheap.
+    }
+    return { active: true, priorPointer };
+}

package/dist/env-guard.d.ts

@@ -54,3 +54,21 @@ export declare const ENV_RESURRECTED_BY_FLAIR_CLIENT: readonly ["FLAIR_URL"];
  * accepts an injectable env for tests. Real (substituted) values are untouched.
  */
 export declare function stripInterpolationLiteralsFromEnv(env?: NodeJS.ProcessEnv, names?: readonly string[]): void;
+/**
+ * Hook probe mode (flair#1007) — shared by every hook binary this package
+ * ships (session-start-hook.ts, continuity-capture-hook.ts). `flair doctor`
+ * sets FLAIR_HOOK_PROBE to ask "does this command still resolve and execute?"
+ * and a probed binary answers by exiting immediately, before stdin, clients,
+ * network or any side effect — being reached at all IS the answer.
+ *
+ * Lives here (this module has no @tpsdev-ai/flair-client import) so the
+ * capture binary can share the ONE definition without pulling the client's
+ * built dist into module graphs that must load before it is built (see
+ * test/unit's CI-ordering note in test/unit/hook-install.test.ts).
+ * session-start-hook.ts re-exports it unchanged.
+ *
+ * Any non-empty value other than "0" enables it, so `FLAIR_HOOK_PROBE=1` and
+ * `FLAIR_HOOK_PROBE=true` both work and an accidentally-empty variable does
+ * not.
+ */
+export declare function isProbeMode(env?: Record<string, string | undefined>): boolean;

package/dist/env-guard.js

@@ -68,3 +68,24 @@ export function stripInterpolationLiteralsFromEnv(env = process.env, names = ENV
         }
     }
 }
+/**
+ * Hook probe mode (flair#1007) — shared by every hook binary this package
+ * ships (session-start-hook.ts, continuity-capture-hook.ts). `flair doctor`
+ * sets FLAIR_HOOK_PROBE to ask "does this command still resolve and execute?"
+ * and a probed binary answers by exiting immediately, before stdin, clients,
+ * network or any side effect — being reached at all IS the answer.
+ *
+ * Lives here (this module has no @tpsdev-ai/flair-client import) so the
+ * capture binary can share the ONE definition without pulling the client's
+ * built dist into module graphs that must load before it is built (see
+ * test/unit's CI-ordering note in test/unit/hook-install.test.ts).
+ * session-start-hook.ts re-exports it unchanged.
+ *
+ * Any non-empty value other than "0" enables it, so `FLAIR_HOOK_PROBE=1` and
+ * `FLAIR_HOOK_PROBE=true` both work and an accidentally-empty variable does
+ * not.
+ */
+export function isProbeMode(env = process.env) {
+    const raw = env.FLAIR_HOOK_PROBE;
+    return typeof raw === "string" && raw !== "" && raw !== "0";
+}

package/dist/session-start-hook.d.ts

@@ -74,6 +74,7 @@
  *   }
  */
 import { type PresencePoster } from "./presence.js";
+import { isProbeMode } from "./env-guard.js";
 /** Minimal surface of FlairClient this hook depends on (eases testing).
  *  `request` is optional and structurally matches PresencePoster (presence.ts)
  *  — the real FlairClient always has it. When present, this hook also fires a
@@ -90,11 +91,11 @@ interface BootstrapClient extends Partial<PresencePoster> {
     } | undefined>;
 }
 /**
- * Probe mode (flair#1007) — see the module doc. Any non-empty value other
- * than "0" enables it, so `FLAIR_HOOK_PROBE=1` and `FLAIR_HOOK_PROBE=true`
- * both work and an accidentally-empty variable does not.
+ * Probe mode (flair#1007) — see the module doc. The predicate itself moved to
+ * ./env-guard.ts when the continuity capture binary (flair#1257) started
+ * sharing it; re-exported here unchanged so existing importers keep working.
  */
-export declare function isProbeMode(env?: Record<string, string | undefined>): boolean;
+export { isProbeMode };
 /**
  * Core hook logic, with injectable dependencies so it can be unit-tested
  * without a live Flair daemon. Returns the exact string to print to stdout.
@@ -104,4 +105,3 @@ export declare function isProbeMode(env?: Record<string, string | undefined>): b
  * @param makeClient factory for the bootstrap client (defaults to FlairClient)
  */
 export declare function runHook(rawInput: string, makeClient?: (agentId: string) => BootstrapClient): Promise<string>;
-export {};

package/dist/session-start-hook.js

@@ -76,7 +76,8 @@
 import { FlairClient } from "@tpsdev-ai/flair-client";
 import { basename } from "node:path";
 import { deriveActivity, postPresenceSafe, resolvePresenceTimeoutMs } from "./presence.js";
-import { readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
+import { isProbeMode, readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
+import { buildResumeHint, discoverResume, prepareContinuityBoot, resolveContinuityTimeoutMs, } from "./continuity.js";
 /** Claude Code SessionStart additionalContext hard limit (chars). */
 const MAX_CHARS = 10_000;
 /** Token budget for the bootstrap call — matches the proven prototype. */
@@ -88,14 +89,11 @@ const TIMEOUT_CEILING_MS = 30_000;
 /** Empty, inert hook output. Printing this is always a safe no-op. */
 const NOOP_OUTPUT = "{}";
 /**
- * Probe mode (flair#1007) — see the module doc. Any non-empty value other
- * than "0" enables it, so `FLAIR_HOOK_PROBE=1` and `FLAIR_HOOK_PROBE=true`
- * both work and an accidentally-empty variable does not.
+ * Probe mode (flair#1007) — see the module doc. The predicate itself moved to
+ * ./env-guard.ts when the continuity capture binary (flair#1257) started
+ * sharing it; re-exported here unchanged so existing importers keep working.
  */
-export function isProbeMode(env = process.env) {
-    const raw = env.FLAIR_HOOK_PROBE;
-    return typeof raw === "string" && raw !== "" && raw !== "0";
-}
+export { isProbeMode };
 /** Resolve the bootstrap timeout from env, clamped to a sane range. */
 function resolveTimeoutMs() {
     const raw = process.env.FLAIR_HOOK_TIMEOUT_MS;
@@ -182,6 +180,16 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
     const presenceDone = typeof client.request === "function"
         ? postPresenceSafe(client, deriveActivity({ channel: "claude-code" }), undefined, resolvePresenceTimeoutMs())
         : Promise.resolve();
+    // Continuity resume (flair#1257 slice 2) — the local half (pointer read →
+    // mint → rotate → seed capture state) runs unconditionally when applicable;
+    // the search half runs CONCURRENTLY with bootstrap below, bounded by its own
+    // short timeout, and resolves to null (no hint) on any failure. It needs the
+    // signed request() surface; a lightweight bootstrap-only client (tests)
+    // skips it entirely.
+    const continuity = prepareContinuityBoot(input, agentId);
+    const resumeHintDone = continuity.active && typeof client.request === "function"
+        ? withTimeout(discoverResume(client, agentId, continuity.priorPointer).then((result) => buildResumeHint(result)), resolveContinuityTimeoutMs()).catch(() => null)
+        : Promise.resolve(null);
     let context = "";
     try {
         const res = await withTimeout(Promise.resolve(client.bootstrap({
@@ -192,15 +200,23 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
         context = res && res.context ? String(res.context) : "";
     }
     catch {
-        await presenceDone;
-        return NOOP_OUTPUT; // flair unreachable / auth error / timeout → no-op
+        context = ""; // flair unreachable / auth error / timeout → no bootstrap context
     }
+    const resumeHint = await resumeHintDone;
     await presenceDone;
-    if (!context.trim())
+    // Combine: bootstrap context first, then AT MOST one continuity hint line.
+    // Either piece may be absent; both absent ⇒ the inert no-op output.
+    const pieces = [];
+    if (context.trim())
+        pieces.push(context);
+    if (resumeHint)
+        pieces.push(resumeHint);
+    if (pieces.length === 0)
         return NOOP_OUTPUT;
-    if (context.length > MAX_CHARS)
-        context = context.slice(0, MAX_CHARS);
-    return hookOutput(context);
+    let combined = pieces.join("\n\n");
+    if (combined.length > MAX_CHARS)
+        combined = combined.slice(0, MAX_CHARS);
+    return hookOutput(combined);
 }
 /** Default client factory — constructs a real FlairClient from FLAIR_* env,
  *  identical to how src/index.ts builds it. */

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "flair-mcp": "dist/mcp-shim.cjs",
-    "flair-session-start": "dist/session-start-hook.js"
+    "flair-session-start": "dist/session-start-hook.js",
+    "flair-continuity-capture": "dist/continuity-capture-hook.js"
   },
   "files": [
     "dist/",
@@ -17,7 +18,7 @@
     "build": "tsc --noCheck",
     "test": "bun test",
     "prepublishOnly": "npm run build",
-    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/mcp-shim.cjs','dist/index.js','dist/session-start-hook.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair-mcp: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
+    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/mcp-shim.cjs','dist/index.js','dist/session-start-hook.js','dist/continuity-capture-hook.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair-mcp: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
   },
   "publishConfig": {
     "access": "public"
@@ -27,7 +28,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.45.0",
+    "@tpsdev-ai/flair-client": "0.47.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",