opensquid 0.5.395

package/dist/hooks/engine-vocab-gate.test.js

@@ -0,0 +1,170 @@
+/**
+ * Tests for engine-vocab-gate (0.7.21 / drift D6).
+ *
+ * Covers the pure-function decomposition (isEngineRepoCwd,
+ * scanCommitMessage, parseDiffForConsumerNames) so we don't need to
+ * set up a git fixture for every assertion. End-to-end coverage via
+ * the existing pre-tool-use integration tests is left as a follow-up.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { checkOverrideEnv, isEngineRepoCwd, parseDiffForConsumerNames, scanCommitMessage, } from "./engine-vocab-gate.js";
+describe("isEngineRepoCwd", () => {
+    it("matches monorepo engine subdir", () => {
+        expect(isEngineRepoCwd("/Users/slee/projects/loop/engine")).toBe(true);
+    });
+    it("matches monorepo engine subdir with trailing slash", () => {
+        expect(isEngineRepoCwd("/Users/slee/projects/loop/engine/")).toBe(true);
+    });
+    it("matches standalone loop-engine repo", () => {
+        expect(isEngineRepoCwd("/Users/slee/projects/loop-engine")).toBe(true);
+    });
+    it("matches any other -engine repo", () => {
+        expect(isEngineRepoCwd("/home/alice/work/search-engine")).toBe(true);
+    });
+    it("does NOT match an unrelated subdir", () => {
+        expect(isEngineRepoCwd("/Users/slee/projects/loop/opensquid")).toBe(false);
+    });
+    it("does NOT match a path that just contains 'engine' in the middle", () => {
+        expect(isEngineRepoCwd("/Users/slee/engine-tutorials/lesson1")).toBe(false);
+    });
+    it("does NOT match the repo parent (loop monorepo root)", () => {
+        expect(isEngineRepoCwd("/Users/slee/projects/loop")).toBe(false);
+    });
+});
+describe("scanCommitMessage", () => {
+    it("flags 'opensquid' in a -m message", () => {
+        expect(scanCommitMessage('git commit -m "ships in lockstep with opensquid 0.7.11"')).toBe("opensquid");
+    });
+    it("flags 'opensquid' in a HEREDOC -m body", () => {
+        const cmd = `git commit -m "$(cat <<'EOF'
+fix something
+ships alongside opensquid 0.7.x
+EOF
+)"`;
+        expect(scanCommitMessage(cmd)).toBe("opensquid");
+    });
+    it("flags 'claude code' with various separators", () => {
+        expect(scanCommitMessage('git commit -m "tested against Claude Code session UUID"')).toBe("Claude Code");
+        expect(scanCommitMessage('git commit -m "claude_code adapter update"')).toBe("claude_code");
+        expect(scanCommitMessage('git commit -m "claude-code session"')).toBe("claude-code");
+    });
+    it("returns null on a clean engine commit message", () => {
+        expect(scanCommitMessage('git commit -m "fix(phase_ledger): drop session_id from storage scheme"')).toBeNull();
+    });
+    it("returns null when there is no -m flag at all", () => {
+        expect(scanCommitMessage("git status")).toBeNull();
+        expect(scanCommitMessage("git commit")).toBeNull();
+    });
+    it("does NOT false-fire on substrings like 'openssquidly'", () => {
+        // CONSUMER_NAME_REGEX uses \b word boundaries so partial matches don't trip.
+        expect(scanCommitMessage('git commit -m "openssquidly is not a real word"')).toBeNull();
+    });
+});
+describe("parseDiffForConsumerNames", () => {
+    it("flags an added line in CHANGELOG.md that mentions opensquid", () => {
+        const diff = `diff --git a/CHANGELOG.md b/CHANGELOG.md
+index abc..def 100644
+--- a/CHANGELOG.md
++++ b/CHANGELOG.md
+@@ -1,3 +1,4 @@
++ships in lockstep with opensquid 0.7.11
+ existing line
+`;
+        const hits = parseDiffForConsumerNames(diff);
+        expect(hits).toHaveLength(1);
+        expect(hits[0].file).toBe("CHANGELOG.md");
+        expect(hits[0].match).toBe("opensquid");
+    });
+    it("flags an added comment in src/lib.rs that mentions 'Claude Code'", () => {
+        const diff = `diff --git a/src/lib.rs b/src/lib.rs
+--- a/src/lib.rs
++++ b/src/lib.rs
+@@ -10,0 +11 @@
++    // Tested against Claude Code session UUID format.
+`;
+        const hits = parseDiffForConsumerNames(diff);
+        expect(hits).toHaveLength(1);
+        expect(hits[0].file).toBe("src/lib.rs");
+    });
+    it("does NOT flag added lines under src/host/claude_code/", () => {
+        const diff = `diff --git a/src/host/claude_code/adapter.rs b/src/host/claude_code/adapter.rs
+--- a/src/host/claude_code/adapter.rs
++++ b/src/host/claude_code/adapter.rs
+@@ -0,0 +1 @@
++// Claude Code-specific adapter logic — opensquid is the consumer.
+`;
+        const hits = parseDiffForConsumerNames(diff);
+        expect(hits).toHaveLength(0);
+    });
+    it("does NOT flag MIT attribution comment lines", () => {
+        const diff = `diff --git a/src/engine/buffer.rs b/src/engine/buffer.rs
+--- a/src/engine/buffer.rs
++++ b/src/engine/buffer.rs
+@@ -0,0 +1 @@
++// MIT-licensed code cherry-picked from claude_code's transcript reader.
+`;
+        const hits = parseDiffForConsumerNames(diff);
+        expect(hits).toHaveLength(0);
+    });
+    it("does NOT flag removed lines (we only care about additions)", () => {
+        const diff = `diff --git a/CHANGELOG.md b/CHANGELOG.md
+--- a/CHANGELOG.md
++++ b/CHANGELOG.md
+@@ -1,2 +1,1 @@
+-old line that mentioned opensquid
+ kept line
+`;
+        const hits = parseDiffForConsumerNames(diff);
+        expect(hits).toHaveLength(0);
+    });
+    it("returns empty array on a fully clean engine diff", () => {
+        const diff = `diff --git a/src/engine/mod.rs b/src/engine/mod.rs
+--- a/src/engine/mod.rs
++++ b/src/engine/mod.rs
+@@ -10,0 +11 @@
++    let task_id = ctx.task_id();
+`;
+        expect(parseDiffForConsumerNames(diff)).toEqual([]);
+    });
+    it("collects multiple hits across multiple files", () => {
+        const diff = `diff --git a/CHANGELOG.md b/CHANGELOG.md
+--- a/CHANGELOG.md
++++ b/CHANGELOG.md
+@@ -1,0 +1 @@
++now compatible with opensquid 0.7.x
+diff --git a/src/serve.rs b/src/serve.rs
+--- a/src/serve.rs
++++ b/src/serve.rs
+@@ -10,0 +11 @@
++    // The opensquid MCP server expects this format.
+`;
+        const hits = parseDiffForConsumerNames(diff);
+        expect(hits).toHaveLength(2);
+        expect(hits.map((h) => h.file)).toEqual(["CHANGELOG.md", "src/serve.rs"]);
+    });
+});
+describe("checkOverrideEnv", () => {
+    const previousValue = process.env.OPENSQUID_SKIP_ENGINE_VOCAB_GATE;
+    beforeEach(() => {
+        delete process.env.OPENSQUID_SKIP_ENGINE_VOCAB_GATE;
+    });
+    afterEach(() => {
+        if (previousValue === undefined) {
+            delete process.env.OPENSQUID_SKIP_ENGINE_VOCAB_GATE;
+        }
+        else {
+            process.env.OPENSQUID_SKIP_ENGINE_VOCAB_GATE = previousValue;
+        }
+    });
+    it("returns true when the env var is exactly '1'", () => {
+        process.env.OPENSQUID_SKIP_ENGINE_VOCAB_GATE = "1";
+        expect(checkOverrideEnv()).toBe(true);
+    });
+    it("returns false when the env var is unset", () => {
+        expect(checkOverrideEnv()).toBe(false);
+    });
+    it("returns false when the env var is some other value", () => {
+        process.env.OPENSQUID_SKIP_ENGINE_VOCAB_GATE = "true";
+        expect(checkOverrideEnv()).toBe(false);
+    });
+});

package/dist/hooks/heartbeat.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Token-threshold heartbeat — opensquid's in-ecosystem replacement for
+ * the auto-classifier subprocess.
+ *
+ * The agent (Claude Code itself) is the LLM in the loop and is already
+ * authenticated. There is no reason to spawn a second LLM subprocess
+ * to classify what the user said — the agent can do that work inline
+ * per the CLAUDE.md classify-and-act block.
+ *
+ * What the agent IS bad at: noticing when its in-context understanding
+ * has drifted enough that it should re-anchor via `recall`. That's a
+ * timing problem opensquid can solve cleanly: count tokens in the
+ * transcript, compare to a checkpoint, and if the delta crosses a
+ * threshold, drop a one-line nudge into the next turn's UserPromptSubmit
+ * stdout so the agent sees it at the top of its system context.
+ *
+ * Flow:
+ *   Stop hook (every turn) → `checkAndMaybeArm(sessionId, transcriptPath)`
+ *     - Estimates total transcript tokens (char count / 4)
+ *     - Loads last checkpoint from `<data-root>/sessions/<sid>/heartbeat-checkpoint.json`
+ *     - If (current - last) >= threshold, writes a marker at
+ *       `<data-root>/sessions/<sid>/heartbeat-pending.txt` AND updates
+ *       the checkpoint to the current count
+ *   UserPromptSubmit hook (next turn) → `consumePendingHeartbeat(sessionId)`
+ *     - Reads marker if present, returns its contents (for stdout injection)
+ *     - Deletes the marker so the nudge fires exactly once per crossing
+ *
+ * Threshold: `OPENSQUID_HEARTBEAT_TOKENS` env, default 20000.
+ *   Calibrated against the existing CLAUDE.md "drifts after ~10 unrelated
+ *   turns" observation (~2000 tokens per turn typical).
+ *
+ * Zero subprocess. Zero external LLM. Zero new dependency. The agent
+ * (which already exists in the loop) does the actual recall + classify
+ * work inline after seeing the nudge.
+ */
+/** Default threshold — see file docstring for rationale. */
+export declare const DEFAULT_HEARTBEAT_TOKENS = 20000;
+/**
+ * Resolve the configured heartbeat threshold. Env var `OPENSQUID_HEARTBEAT_TOKENS`
+ * overrides; values <= 0 or non-numeric fall back to the default. Returning a
+ * sentinel `Infinity` would let callers disable cheaply, but we keep the
+ * contract simple: any positive integer is honored.
+ */
+export declare function heartbeatThresholdTokens(): number;
+/**
+ * Rough token estimate from raw text — char-count / 4. Cheap, dependency-
+ * free, and accurate enough for "did the conversation grow by 20K tokens
+ * since last checkpoint" decisions. Real tokenizers (tiktoken,
+ * @anthropic-ai/tokenizer) would be more accurate but add a runtime dep
+ * for marginal gain on a threshold comparison.
+ */
+export declare function estimateTokens(text: string): number;
+export declare function estimateTranscriptTokens(transcriptPath: string): Promise<number>;
+interface Checkpoint {
+    last_token_count: number;
+    last_checkpoint_at: string;
+}
+export declare function readCheckpoint(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<Checkpoint | null>;
+export declare function writeCheckpoint(sessionId: string, checkpoint: Checkpoint, options?: {
+    dataRoot?: string;
+}): Promise<void>;
+/**
+ * Build the one-line nudge that gets injected into the agent's next-
+ * turn system context. Kept short — the agent's existing system prompt
+ * (CLAUDE.md classify-and-act + the user-is-god promoted lesson)
+ * already tells it what to do with classification work.
+ */
+export declare function formatHeartbeatNudge(delta: number, threshold: number): string;
+/**
+ * Stop-hook entrypoint: check whether the transcript has grown past
+ * the threshold since the last checkpoint. If so, arm a pending
+ * heartbeat marker for UserPromptSubmit to surface on the next turn,
+ * and bump the checkpoint to the current count.
+ *
+ * Returns the nudge text written (or null if no arming happened) for
+ * test introspection and Stop-hook stderr surfacing.
+ */
+export declare function checkAndMaybeArm(sessionId: string, transcriptPath: string, options?: {
+    dataRoot?: string;
+    thresholdTokens?: number;
+}): Promise<string | null>;
+/**
+ * UserPromptSubmit-hook entrypoint: consume any armed heartbeat marker
+ * and return its text. Caller injects via stdout. Marker is removed so
+ * the nudge fires exactly once per threshold crossing.
+ */
+export declare function consumePendingHeartbeat(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<string | null>;
+/** Test/SessionEnd helper — paths the cleanup phase removes. */
+export declare function heartbeatSessionFiles(sessionId: string, dataRoot?: string): string[];
+/** Set the flag — called after the heartbeat nudge is surfaced. */
+export declare function markRecallRequired(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<void>;
+/** Check whether the flag is set for this session. */
+export declare function isRecallRequired(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<boolean>;
+/** Clear the flag — called after the agent calls recall. */
+export declare function clearRecallRequired(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/hooks/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src.legacy/hooks/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAMjD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAyCD,wBAAsB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBtF;AAwCD,UAAU,UAAU;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAUD,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAe5B;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAO7E;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BxB;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAcxB;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAMpF;AA2BD,mEAAmE;AACnE,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,sDAAsD;AACtD,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED,4DAA4D;AAC5D,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/hooks/heartbeat.js

@@ -0,0 +1,316 @@
+/**
+ * Token-threshold heartbeat — opensquid's in-ecosystem replacement for
+ * the auto-classifier subprocess.
+ *
+ * The agent (Claude Code itself) is the LLM in the loop and is already
+ * authenticated. There is no reason to spawn a second LLM subprocess
+ * to classify what the user said — the agent can do that work inline
+ * per the CLAUDE.md classify-and-act block.
+ *
+ * What the agent IS bad at: noticing when its in-context understanding
+ * has drifted enough that it should re-anchor via `recall`. That's a
+ * timing problem opensquid can solve cleanly: count tokens in the
+ * transcript, compare to a checkpoint, and if the delta crosses a
+ * threshold, drop a one-line nudge into the next turn's UserPromptSubmit
+ * stdout so the agent sees it at the top of its system context.
+ *
+ * Flow:
+ *   Stop hook (every turn) → `checkAndMaybeArm(sessionId, transcriptPath)`
+ *     - Estimates total transcript tokens (char count / 4)
+ *     - Loads last checkpoint from `<data-root>/sessions/<sid>/heartbeat-checkpoint.json`
+ *     - If (current - last) >= threshold, writes a marker at
+ *       `<data-root>/sessions/<sid>/heartbeat-pending.txt` AND updates
+ *       the checkpoint to the current count
+ *   UserPromptSubmit hook (next turn) → `consumePendingHeartbeat(sessionId)`
+ *     - Reads marker if present, returns its contents (for stdout injection)
+ *     - Deletes the marker so the nudge fires exactly once per crossing
+ *
+ * Threshold: `OPENSQUID_HEARTBEAT_TOKENS` env, default 20000.
+ *   Calibrated against the existing CLAUDE.md "drifts after ~10 unrelated
+ *   turns" observation (~2000 tokens per turn typical).
+ *
+ * Zero subprocess. Zero external LLM. Zero new dependency. The agent
+ * (which already exists in the loop) does the actual recall + classify
+ * work inline after seeing the nudge.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { resolveDataRoot } from "../codex/store.js";
+/** Default threshold — see file docstring for rationale. */
+export const DEFAULT_HEARTBEAT_TOKENS = 20_000;
+/**
+ * Resolve the configured heartbeat threshold. Env var `OPENSQUID_HEARTBEAT_TOKENS`
+ * overrides; values <= 0 or non-numeric fall back to the default. Returning a
+ * sentinel `Infinity` would let callers disable cheaply, but we keep the
+ * contract simple: any positive integer is honored.
+ */
+export function heartbeatThresholdTokens() {
+    const raw = process.env.OPENSQUID_HEARTBEAT_TOKENS;
+    if (!raw)
+        return DEFAULT_HEARTBEAT_TOKENS;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_HEARTBEAT_TOKENS;
+    return n;
+}
+/**
+ * Rough token estimate from raw text — char-count / 4. Cheap, dependency-
+ * free, and accurate enough for "did the conversation grow by 20K tokens
+ * since last checkpoint" decisions. Real tokenizers (tiktoken,
+ * @anthropic-ai/tokenizer) would be more accurate but add a runtime dep
+ * for marginal gain on a threshold comparison.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Read the Claude Code transcript file and estimate the agent-facing
+ * token count for "did the conversation drift since last checkpoint."
+ *
+ * 0.7.7 (#161) — replaces the previous whole-file char/4 estimate
+ * which inflated massively on long sessions because the transcript
+ * JSONL contains tool_result bodies (file reads, base64 images, git
+ * logs), thinking blocks, attachments, system frames, and
+ * permission-mode entries that don't represent conversation pressure.
+ *
+ * On a real session today this dropped a 125 MB transcript from
+ * reporting "31 million tokens" to a number that actually reflects
+ * the user+assistant exchange, so heartbeat fires when it should
+ * instead of constantly off inflated numbers.
+ *
+ * Counts:
+ *   - user message text/string content
+ *   - assistant text content
+ *   - tool_result content — capped at 2000 chars per result, since
+ *     the agent does read these but they shouldn't dominate
+ *
+ * Skips:
+ *   - thinking blocks (agent internal CoT)
+ *   - tool_use args (compact, plus they're outbound work not context)
+ *   - system / file-history-snapshot / permission-mode / ai-title /
+ *     last-prompt / attachment frames
+ *
+ * Returns 0 on any read failure (graceful, gate stays open).
+ */
+const TOOL_RESULT_CAP_CHARS = 2000;
+export async function estimateTranscriptTokens(transcriptPath) {
+    try {
+        const raw = await fs.readFile(transcriptPath, "utf8");
+        let total = 0;
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.type !== "user" && parsed.type !== "assistant")
+                continue;
+            total += countContentChars(parsed.message?.content);
+        }
+        return Math.ceil(total / 4);
+    }
+    catch {
+        return 0;
+    }
+}
+function countContentChars(content) {
+    if (typeof content === "string")
+        return content.length;
+    if (!Array.isArray(content))
+        return 0;
+    let chars = 0;
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        switch (b.type) {
+            case "text":
+                if (typeof b.text === "string")
+                    chars += b.text.length;
+                break;
+            case "tool_result": {
+                // tool_result content can be a string OR an array of blocks
+                const c = b.content;
+                if (typeof c === "string") {
+                    chars += Math.min(c.length, TOOL_RESULT_CAP_CHARS);
+                }
+                else if (Array.isArray(c)) {
+                    let inner = 0;
+                    for (const part of c) {
+                        if (part && typeof part === "object") {
+                            const p = part;
+                            if (typeof p.text === "string")
+                                inner += p.text.length;
+                        }
+                    }
+                    chars += Math.min(inner, TOOL_RESULT_CAP_CHARS);
+                }
+                break;
+            }
+            // thinking / tool_use / image / etc. — intentionally not counted
+        }
+    }
+    return chars;
+}
+function checkpointPath(sessionId, dataRoot) {
+    return path.join(resolveDataRoot(dataRoot), "sessions", sessionId, "heartbeat-checkpoint.json");
+}
+function pendingPath(sessionId, dataRoot) {
+    return path.join(resolveDataRoot(dataRoot), "sessions", sessionId, "heartbeat-pending.txt");
+}
+export async function readCheckpoint(sessionId, options = {}) {
+    try {
+        const raw = await fs.readFile(checkpointPath(sessionId, options.dataRoot), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed.last_token_count === "number" &&
+            typeof parsed.last_checkpoint_at === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCheckpoint(sessionId, checkpoint, options = {}) {
+    const p = checkpointPath(sessionId, options.dataRoot);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, JSON.stringify(checkpoint, null, 2) + "\n", "utf8");
+}
+/**
+ * Build the one-line nudge that gets injected into the agent's next-
+ * turn system context. Kept short — the agent's existing system prompt
+ * (CLAUDE.md classify-and-act + the user-is-god promoted lesson)
+ * already tells it what to do with classification work.
+ */
+export function formatHeartbeatNudge(delta, threshold) {
+    return (`🦑 [opensquid heartbeat] ${delta.toLocaleString()} tokens since last re-anchor ` +
+        `(threshold: ${threshold.toLocaleString()}). Before answering: ` +
+        `(1) call \`recall\` with your current task to refresh context; ` +
+        `(2) scan recent user turns for substantive items needing memorize / remember / promote.`);
+}
+/**
+ * Stop-hook entrypoint: check whether the transcript has grown past
+ * the threshold since the last checkpoint. If so, arm a pending
+ * heartbeat marker for UserPromptSubmit to surface on the next turn,
+ * and bump the checkpoint to the current count.
+ *
+ * Returns the nudge text written (or null if no arming happened) for
+ * test introspection and Stop-hook stderr surfacing.
+ */
+export async function checkAndMaybeArm(sessionId, transcriptPath, options = {}) {
+    const threshold = options.thresholdTokens ?? heartbeatThresholdTokens();
+    const currentTokens = await estimateTranscriptTokens(transcriptPath);
+    if (currentTokens === 0)
+        return null;
+    const previous = await readCheckpoint(sessionId, { dataRoot: options.dataRoot });
+    let baseline = previous?.last_token_count ?? 0;
+    // 0.7.7 (#161, audit MED #3): the estimator was rewritten in 0.7.7
+    // to count only conversation bodies (not whole-file char/4) — typical
+    // 20x deflation vs the old value. Existing checkpoints written by
+    // the old estimator now show wildly higher numbers than the new
+    // estimator returns, which would make `delta = current - baseline`
+    // permanently negative → heartbeat never fires. Detect that case
+    // (baseline > 10x current) and reset the baseline to 0 so the next
+    // crossing is the first under the new regime.
+    if (baseline > currentTokens * 10) {
+        baseline = 0;
+    }
+    const delta = currentTokens - baseline;
+    if (delta < threshold)
+        return null;
+    const nudge = formatHeartbeatNudge(delta, threshold);
+    const p = pendingPath(sessionId, options.dataRoot);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, nudge + "\n", "utf8");
+    await writeCheckpoint(sessionId, { last_token_count: currentTokens, last_checkpoint_at: new Date().toISOString() }, { dataRoot: options.dataRoot });
+    return nudge;
+}
+/**
+ * UserPromptSubmit-hook entrypoint: consume any armed heartbeat marker
+ * and return its text. Caller injects via stdout. Marker is removed so
+ * the nudge fires exactly once per threshold crossing.
+ */
+export async function consumePendingHeartbeat(sessionId, options = {}) {
+    const p = pendingPath(sessionId, options.dataRoot);
+    let nudge;
+    try {
+        nudge = (await fs.readFile(p, "utf8")).trim();
+    }
+    catch {
+        return null;
+    }
+    try {
+        await fs.rm(p);
+    }
+    catch {
+        // already gone — concurrent UserPromptSubmit or test cleanup
+    }
+    return nudge.length === 0 ? null : nudge;
+}
+/** Test/SessionEnd helper — paths the cleanup phase removes. */
+export function heartbeatSessionFiles(sessionId, dataRoot) {
+    return [
+        checkpointPath(sessionId, dataRoot),
+        pendingPath(sessionId, dataRoot),
+        recallRequiredFlagPath(sessionId, dataRoot),
+    ];
+}
+// =====================================================================
+// 0.7.26 / D7 — recall-required flag
+//
+// After the heartbeat nudge is consumed (surfaced to the agent via
+// UserPromptSubmit), set a per-session flag that BLOCKS any
+// mcp__opensquid__* tool call other than `recall` until the agent
+// actually calls recall.
+//
+// Catches D7: heartbeat fires, agent acknowledges, agent continues
+// without calling recall. The mechanism exists, the agent's compliance
+// was the failure point. Make it teeth.
+//
+// Lifecycle:
+//   - markRecallRequired: called from UPS after consumePendingHeartbeat
+//     returns a nudge
+//   - isRecallRequired: checked from pre-tool-use before any
+//     mcp__opensquid__* tool call
+//   - clearRecallRequired: called from pre-tool-use when the agent
+//     calls mcp__opensquid__recall
+// =====================================================================
+function recallRequiredFlagPath(sessionId, dataRoot) {
+    return path.join(resolveDataRoot(dataRoot), "sessions", sessionId, "recall-required.flag");
+}
+/** Set the flag — called after the heartbeat nudge is surfaced. */
+export async function markRecallRequired(sessionId, options = {}) {
+    const p = recallRequiredFlagPath(sessionId, options.dataRoot);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, new Date().toISOString() + "\n", "utf8");
+}
+/** Check whether the flag is set for this session. */
+export async function isRecallRequired(sessionId, options = {}) {
+    const p = recallRequiredFlagPath(sessionId, options.dataRoot);
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Clear the flag — called after the agent calls recall. */
+export async function clearRecallRequired(sessionId, options = {}) {
+    const p = recallRequiredFlagPath(sessionId, options.dataRoot);
+    try {
+        await fs.rm(p);
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/hooks/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../src.legacy/hooks/heartbeat.ts"],"names":[],"mappings":"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"}