claudelink 1.4.3 → 1.5.0

package/dist/compact-analyzer.js

@@ -0,0 +1,309 @@
+"use strict";
+// Compact-loss analyzer (read-only) — the calibration engine for intelligent
+// auto-compact. Scans the fleet's existing transcripts for compact events and,
+// for each, records the ground-truth effect + four intelligence-LOSS signals
+// in the surrounding turns. Run on NATURALLY-OCCURRING compacts (the founder's
+// manual /compact discipline + Claude Code's built-in auto-compact), so we
+// build a labeled loss dataset and validate the heuristics BEFORE the watcher
+// ever auto-triggers one. No injection, no terminal contact.
+//
+// Ground truth is exact: Claude Code records each compact as a transcript line
+//   { type:"system", subtype:"compact_boundary",
+//     compactMetadata:{ trigger:"auto"|"manual", preTokens, postTokens, durationMs } }
+// so we know the real context size before/after — no estimation.
+//
+// CAVEAT (carried into the case study): manual compacts fire at task
+// boundaries; the auto-trigger fires at an economic threshold (mid-task). These
+// are different populations. This analyzer validates the loss-signal DETECTION
+// MECHANICS on real events; the loss RATES it reports for manual compacts are
+// NOT extrapolatable to auto-trigger rates — the armed soak measures those.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathALossBaseline = pathALossBaseline;
+exports.analyzeCompactEvents = analyzeCompactEvents;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const readline_1 = __importDefault(require("readline"));
+const usage_reader_js_1 = require("./usage-reader.js");
+// Window sizes (in real user/assistant turns) for signal computation, kept
+// tight so legitimate repeats far from a compact don't register as loss.
+const PRE_WINDOW = 12;
+const POST_WINDOW = 12;
+const REEXPLAIN_CHARS = 1500; // a human user message longer than this = re-explain
+// Primary distinguishing argument per tool, so a signature captures "same
+// action" without being so loose it matches everything.
+function toolSignature(name, input) {
+    const i = input || {};
+    if (name === "Bash")
+        return "Bash:" + String(i.command || "").slice(0, 80);
+    if (["Read", "Edit", "Write", "NotebookEdit"].includes(name))
+        return name + ":" + (i.file_path || "");
+    if (["Grep", "Glob"].includes(name))
+        return name + ":" + (i.pattern || i.glob || "");
+    // generic: name + a short stable slice of the args
+    try {
+        return name + ":" + JSON.stringify(i).slice(0, 80);
+    }
+    catch {
+        return name;
+    }
+}
+const READ_TOOLS = new Set(["Read", "Grep", "Glob"]);
+function parseTurn(o, prevWasBoundary) {
+    const t = o?.type;
+    if (t !== "user" && t !== "assistant")
+        return null;
+    const m = o?.message;
+    if (!m)
+        return null;
+    const toolSigs = [];
+    const readSigs = [];
+    let text = "";
+    let isToolResult = false;
+    if (Array.isArray(m.content)) {
+        for (const b of m.content) {
+            if (!b || typeof b !== "object")
+                continue;
+            if (b.type === "tool_use") {
+                const sig = toolSignature(b.name, b.input);
+                toolSigs.push(sig);
+                if (READ_TOOLS.has(b.name))
+                    readSigs.push(sig);
+            }
+            else if (b.type === "text") {
+                text += b.text || "";
+            }
+            else if (b.type === "tool_result") {
+                isToolResult = true;
+            }
+        }
+    }
+    else if (typeof m.content === "string") {
+        text = m.content;
+    }
+    // A user line that is purely a tool_result is not a human turn; skip for
+    // re-explain purposes but it's still a turn for recovery counting.
+    return {
+        role: t,
+        text,
+        textLen: text.length,
+        toolSigs,
+        readSigs,
+        // The compact summary is the large user message immediately after the
+        // boundary (and is flagged by the harness as a compact summary in content).
+        isCompactSummary: t === "user" && prevWasBoundary && !isToolResult && text.length > 0,
+    };
+}
+async function analyzeFile(file, seenBoundaries, out, projectLabel, roles) {
+    const seq = [];
+    let prevWasBoundary = false;
+    const rl = readline_1.default.createInterface({ input: fs_1.default.createReadStream(file, { encoding: "utf-8" }), crlfDelay: Infinity });
+    for await (const line of rl) {
+        let o;
+        try {
+            o = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (o?.type === "system" && o?.subtype === "compact_boundary") {
+            seq.push({ kind: "boundary", meta: o.compactMetadata || {}, uuid: o.uuid || `${file}:${seq.length}` });
+            prevWasBoundary = true;
+            continue;
+        }
+        const turn = parseTurn(o, prevWasBoundary);
+        if (turn) {
+            seq.push({ kind: "turn", turn });
+            prevWasBoundary = false;
+        }
+    }
+    // Index the turn positions for windowing.
+    for (let i = 0; i < seq.length; i++) {
+        const it = seq[i];
+        if (it.kind !== "boundary")
+            continue;
+        if (seenBoundaries.has(it.uuid))
+            continue; // dedupe forked re-emits
+        seenBoundaries.add(it.uuid);
+        const meta = it.meta;
+        const pre = meta.preTokens ?? null;
+        const post = meta.postTokens ?? null;
+        // Gather pre/post turns (real turns only) within the windows.
+        const preTurns = [];
+        for (let j = i - 1; j >= 0 && preTurns.length < PRE_WINDOW; j--) {
+            if (seq[j].kind === "turn")
+                preTurns.push(seq[j].turn);
+        }
+        const postTurns = [];
+        for (let j = i + 1; j < seq.length && postTurns.length < POST_WINDOW; j++) {
+            if (seq[j].kind === "turn")
+                postTurns.push(seq[j].turn);
+            if (seq[j].kind === "boundary")
+                break; // stop at the next compact
+        }
+        const preToolSigs = new Set();
+        const preReadSigs = new Set();
+        for (const t of preTurns) {
+            t.toolSigs.forEach((s) => preToolSigs.add(s));
+            t.readSigs.forEach((s) => preReadSigs.add(s));
+        }
+        let reworkHits = 0;
+        let refetchHits = 0;
+        let turnsToRecover = null;
+        let userReexplain = false;
+        let recoverCount = 0;
+        for (const t of postTurns) {
+            recoverCount++;
+            // rework: a post-compact tool action whose signature appeared pre-compact
+            for (const s of t.toolSigs)
+                if (preToolSigs.has(s))
+                    reworkHits++;
+            // refetch (re-ask proxy): a post-compact read of something read pre-compact
+            for (const s of t.readSigs)
+                if (preReadSigs.has(s))
+                    refetchHits++;
+            // recovery: first post-compact assistant turn issuing a NEW tool action
+            if (turnsToRecover === null && t.role === "assistant") {
+                const hasNew = t.toolSigs.some((s) => !preToolSigs.has(s));
+                if (hasNew)
+                    turnsToRecover = recoverCount;
+            }
+            // re-explain: a human user message (not the summary, not a tool_result)
+            // longer than the threshold
+            if (!t.isCompactSummary && t.role === "user" && t.toolSigs.length === 0 && t.textLen > REEXPLAIN_CHARS) {
+                userReexplain = true;
+            }
+        }
+        out.push({
+            project: projectLabel,
+            roles,
+            trigger: meta.trigger ?? null,
+            preTokens: pre,
+            postTokens: post,
+            reductionPct: pre && post && pre > 0 ? Math.round((100 * (pre - post)) / pre) : null,
+            durationMs: meta.durationMs ?? null,
+            reworkHits,
+            refetchHits,
+            turnsToRecover,
+            userReexplain,
+        });
+    }
+}
+function median(nums) {
+    if (nums.length === 0)
+        return 0;
+    const s = [...nums].sort((a, b) => a - b);
+    return s[Math.floor(s.length / 2)];
+}
+const BUCKETS = [
+    ["<100K", 0, 100000],
+    ["100-250K", 100000, 250000],
+    ["250-500K", 250000, 500000],
+    ["500K-1M", 500000, 1000000],
+    [">=1M", 1000000, Infinity],
+];
+function pathALossBaseline(events) {
+    const rate = (es, pred) => es.length ? es.filter(pred).length / es.length : 0;
+    const byPreTokenBucket = BUCKETS.map(([label, lo, hi]) => {
+        const es = events.filter((e) => (e.preTokens ?? 0) >= lo && (e.preTokens ?? 0) < hi);
+        const recov = es.map((e) => e.turnsToRecover).filter((n) => n !== null);
+        return {
+            bucket: label,
+            count: es.length,
+            reworkRate: rate(es, (e) => e.reworkHits > 0),
+            reexplainRate: rate(es, (e) => e.userReexplain),
+            medianTurnsToRecover: recov.length ? median(recov) : null,
+        };
+    }).filter((b) => b.count > 0);
+    const worstCases = [...events]
+        .sort((a, b) => b.reworkHits - a.reworkHits || (b.turnsToRecover ?? 0) - (a.turnsToRecover ?? 0))
+        .slice(0, 5)
+        .map((e) => ({
+        project: e.project,
+        preTokens: e.preTokens,
+        reworkHits: e.reworkHits,
+        turnsToRecover: e.turnsToRecover,
+        userReexplain: e.userReexplain,
+    }));
+    const recovAll = events.map((e) => e.turnsToRecover).filter((n) => n !== null);
+    return {
+        source: "historical Path-A (Claude Code /compact); HEURISTIC signals; NON-representative of auto-trigger rates (manual = task-boundary timing). Validates detection mechanics, not arming-phase loss rates.",
+        totalEvents: events.length,
+        byPreTokenBucket,
+        worstCases,
+        comparison: {
+            pathA: {
+                source: "historical /compact (this dataset)",
+                events: events.length,
+                reworkRate: rate(events, (e) => e.reworkHits > 0),
+                reexplainRate: rate(events, (e) => e.userReexplain),
+                medianTurnsToRecover: recovAll.length ? median(recovAll) : null,
+            },
+            pathB: null,
+            defaultSoakPath: "A",
+            note: "Path B (CLEAR+reinject) has no historical data and cannot be measured read-only — its loss signals only exist if the path is executed in the founder-gated soak. A is the conservative-soak default; B is tested against A's measured baseline.",
+        },
+    };
+}
+async function analyzeCompactEvents(agents, windowDays = 30) {
+    const windowStartMs = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+    const byProject = new Map();
+    for (const a of agents) {
+        const cwd = (0, usage_reader_js_1.cwdForPid)(a.pid);
+        if (!cwd)
+            continue;
+        const id = (0, usage_reader_js_1.projectIdFromCwd)(cwd);
+        const e = byProject.get(id) || { roles: [], cwd };
+        e.roles.push(a.role);
+        byProject.set(id, e);
+    }
+    const events = [];
+    const seen = new Set();
+    for (const [id, { roles, cwd }] of byProject) {
+        const dir = path_1.default.join(usage_reader_js_1.PROJECTS_DIR, id);
+        const label = roles.length === 1 ? roles[0] : `${path_1.default.basename(cwd)} (${roles.length} agents)`;
+        let files = [];
+        try {
+            files = fs_1.default.readdirSync(dir).filter((f) => f.endsWith(".jsonl")).map((f) => path_1.default.join(dir, f));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            try {
+                if (fs_1.default.statSync(file).mtimeMs < windowStartMs)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            await analyzeFile(file, seen, events, label, roles);
+        }
+    }
+    // Roll up by trigger type.
+    const byTrigger = {};
+    for (const trig of new Set(events.map((e) => e.trigger || "unknown"))) {
+        const es = events.filter((e) => (e.trigger || "unknown") === trig);
+        const recov = es.map((e) => e.turnsToRecover).filter((n) => n !== null);
+        byTrigger[trig] = {
+            count: es.length,
+            medianPreTokens: median(es.map((e) => e.preTokens || 0)),
+            medianPostTokens: median(es.map((e) => e.postTokens || 0)),
+            medianReductionPct: median(es.map((e) => e.reductionPct || 0)),
+            reworkRate: es.length ? es.filter((e) => e.reworkHits > 0).length / es.length : 0,
+            refetchRate: es.length ? es.filter((e) => e.refetchHits > 0).length / es.length : 0,
+            userReexplainRate: es.length ? es.filter((e) => e.userReexplain).length / es.length : 0,
+            medianTurnsToRecover: recov.length ? median(recov) : null,
+        };
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        windowDays,
+        totalEvents: events.length,
+        byTrigger,
+        events,
+    };
+}
+//# sourceMappingURL=compact-analyzer.js.map

package/dist/compact-analyzer.js.map

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

package/dist/compact-decision.d.ts

@@ -0,0 +1,19 @@
+export type CompactAction = {
+    kind: "fire";
+} | {
+    kind: "ask";
+} | {
+    kind: "skip";
+    reason: string;
+};
+export interface CompactDecisionInput {
+    idle: boolean;
+    ambiguous: boolean;
+    safeToClear: boolean;
+    consentAgeMs: number | null;
+    consentFreshMs: number;
+    economicGreen: boolean;
+    msSinceLastAsk: number | null;
+    askCooldownMs: number;
+}
+export declare function decideCompactAction(i: CompactDecisionInput): CompactAction;

package/dist/compact-decision.js

@@ -0,0 +1,47 @@
+"use strict";
+// T1 consent handshake — pure decision core for the armed /compact path.
+//
+// Background: before this, the watcher auto-fired /compact the moment an
+// allowlisted agent was idle at a turn boundary (the Stop hook touches
+// checkpoint_ts every turn, so the old "fresh_consent" gate was satisfied
+// automatically — the agent never actually said yes). This module replaces
+// that silent fire with a two-phase handshake:
+//
+//   ASK  — when occupancy is high + the agent is idle + compacting is
+//          economically worth a turn, type a prompt asking the agent to flush
+//          its handoff and CONSENT via signal_checkpoint(safe_to_clear=true).
+//   FIRE — only once a GENUINE consent is on record (checkpoint_safe_to_clear
+//          === 1, set solely by the explicit signal_checkpoint MCP call and
+//          unforgeable by the per-turn hook touch) AND that consent is fresh
+//          AND the agent is idle right now, type /compact.
+//
+// The function is pure so the gate ordering + freshness + cooldown logic can be
+// pinned by tests independently of the watcher's transcript/DB plumbing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideCompactAction = decideCompactAction;
+// Precedence: ambiguous → FIRE (durable consent) → ASK (throttled) → skip.
+// FIRE is evaluated BEFORE the ask-cooldown so a yes is never starved by the
+// throttle that exists only to stop us re-asking every tick. A fresh consent
+// with no prior ask still fires — an agent that volunteered safe_to_clear=true
+// on its own is just as valid as one answering our prompt.
+function decideCompactAction(i) {
+    if (i.ambiguous)
+        return { kind: "skip", reason: "ambiguous-session" };
+    const consentFresh = i.safeToClear && i.consentAgeMs !== null && i.consentAgeMs < i.consentFreshMs;
+    if (consentFresh) {
+        // Consent is necessary, not sufficient — re-check idle at FIRE time.
+        if (!i.idle)
+            return { kind: "skip", reason: "consented-but-not-idle" };
+        return { kind: "fire" };
+    }
+    // No fire-eligible consent → consider asking. Asking costs the agent a turn,
+    // so only when idle (won't interrupt) and economically worth it.
+    if (!i.idle)
+        return { kind: "skip", reason: "not-idle" };
+    if (!i.economicGreen)
+        return { kind: "skip", reason: "economics-below-overhead" };
+    if (i.msSinceLastAsk !== null && i.msSinceLastAsk < i.askCooldownMs)
+        return { kind: "skip", reason: "ask-cooldown" };
+    return { kind: "ask" };
+}
+//# sourceMappingURL=compact-decision.js.map

package/dist/compact-decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-decision.js","sourceRoot":"","sources":["../src/compact-decision.ts"],"names":[],"mappings":";AAAA,yEAAyE;AACzE,EAAE;AACF,yEAAyE;AACzE,uEAAuE;AACvE,0EAA0E;AAC1E,2EAA2E;AAC3E,+CAA+C;AAC/C,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,2DAA2D;AAC3D,EAAE;AACF,gFAAgF;AAChF,yEAAyE;;AAuCzE,kDAkBC;AAvBD,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,2DAA2D;AAC3D,SAAgB,mBAAmB,CAAC,CAAuB;IACzD,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAEtE,MAAM,YAAY,GAChB,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,YAAY,KAAK,IAAI,IAAI,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,cAAc,CAAC;IAChF,IAAI,YAAY,EAAE,CAAC;QACjB,qEAAqE;QACrE,IAAI,CAAC,CAAC,CAAC,IAAI;YAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;QACvE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IAED,6EAA6E;IAC7E,iEAAiE;IACjE,IAAI,CAAC,CAAC,CAAC,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACzD,IAAI,CAAC,CAAC,CAAC,aAAa;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;IAClF,IAAI,CAAC,CAAC,cAAc,KAAK,IAAI,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,aAAa;QACjE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAClD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/compact-executor.d.ts

@@ -0,0 +1,27 @@
+export type CompactPath = "A" | "B";
+export declare const DEFAULT_PATH: CompactPath;
+export declare const HANDOFF_DIR: string;
+export declare function isHandoffPathSafe(p: string): boolean;
+export declare const HANDOFF_TEMPLATE = "# ClaudeLink handoff \u2014 <role>\n\n## Current task & progress\n<what you are doing right now and how far along>\n\n## Key decisions / context you must NOT lose\n<constraints, choices already made, facts that won't be re-derivable>\n\n## Exact next step\n<the very next action to take on resume>\n\n## Open threads\n<anything in flight, awaited, or deferred>\n";
+export declare function handoffPathFor(agentId: string): string;
+export declare function preparePrompt(perTurnCostUsd: number, handoffFile: string): string;
+export declare function postCompactPrompt(p: CompactPath, handoffFile: string): string;
+export declare function verifyHandoff(file: string): {
+    ok: boolean;
+    bytes: number;
+};
+export interface CompactStep {
+    action: "send-prepare-prompt" | "await-ready" | "verify-handoff" | "inject-compact" | "inject-clear" | "reinject-handoff" | "send-postcompact-prompt";
+    detail: string;
+    injects: boolean;
+}
+export declare function planCompact(p: CompactPath, perTurnCostUsd: number, handoffFile: string): CompactStep[];
+export type ExecMode = "dry" | "armed";
+export interface ExecResult {
+    path: CompactPath;
+    mode: ExecMode;
+    steps: CompactStep[];
+    executed: boolean;
+    note: string;
+}
+export declare function executeCompact(agentId: string, p: CompactPath, perTurnCostUsd: number, mode?: ExecMode): ExecResult;

package/dist/compact-executor.js

@@ -0,0 +1,160 @@
+"use strict";
+// Compact executor — the prepare-then-compact handshake and the two
+// state-preservation paths (§C of the auto-compact design), built in DRY mode:
+// every flow is a PLANNER that logs the ordered steps it WOULD take. The actual
+// terminal-injection points are guarded stubs — nothing types into a terminal
+// here. Arming (real injection) is founder-gated and happens in the supervised
+// soak, where the A-vs-B winner is MEASURED (it cannot be measured read-only:
+// a path's loss-signals only exist if that path is executed).
+//
+// HYPOTHESIS (explicitly a hypothesis, not a measurement) — informs the soak's
+// starting posture, does NOT decide it:
+//   Path A (/compact + handoff-file) = belt-and-suspenders. Claude Code's own
+//     summary PLUS the agent's structured handoff. If the handoff misses
+//     something, the model summary is a safety net. Lower risk FLOOR.
+//   Path B (CLEAR + handoff-reinject) = total control. Skip /compact entirely;
+//     the handoff IS the new context. No dependency on /compact's opaque
+//     summarization — potentially a higher ceiling — but if the handoff misses
+//     something it is GONE, no safety net. Higher risk floor.
+//   => Start the soak with A as the CONSERVATIVE DEFAULT; test B as the
+//      optimization against A's measured baseline. (Per senior review + pushback #4.)
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HANDOFF_TEMPLATE = exports.HANDOFF_DIR = exports.DEFAULT_PATH = void 0;
+exports.isHandoffPathSafe = isHandoffPathSafe;
+exports.handoffPathFor = handoffPathFor;
+exports.preparePrompt = preparePrompt;
+exports.postCompactPrompt = postCompactPrompt;
+exports.verifyHandoff = verifyHandoff;
+exports.planCompact = planCompact;
+exports.executeCompact = executeCompact;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+exports.DEFAULT_PATH = "A"; // conservative-soak default
+exports.HANDOFF_DIR = path_1.default.join(os_1.default.homedir(), ".claudelink", "handoffs");
+// Marker substrings from HANDOFF_TEMPLATE — used by verifyHandoff to detect a
+// "filled in nothing, just kept the stub" handoff. The template itself is
+// ~270 bytes which sails over the >200-byte size gate, so a byte-count check
+// alone is bypassable. Updated together with HANDOFF_TEMPLATE.
+const HANDOFF_PLACEHOLDERS = [
+    "<role>",
+    "<what you are doing right now",
+    "<constraints, choices already made",
+    "<the very next action to take on resume>",
+    "<anything in flight, awaited, or deferred>",
+];
+// True iff `p` resolves under ~/.claudelink/handoffs/. Used at the
+// signal_checkpoint ingress to reject agent-supplied paths that would let a
+// confused agent satisfy the handoff gate with any large file on disk
+// (e.g. /etc/passwd, a node_modules tarball). Returns false for any path that
+// can't be resolved.
+function isHandoffPathSafe(p) {
+    try {
+        const resolved = path_1.default.resolve(p);
+        const root = path_1.default.resolve(exports.HANDOFF_DIR);
+        return resolved === root || resolved.startsWith(root + path_1.default.sep);
+    }
+    catch {
+        return false;
+    }
+}
+// The structured essence the agent preserves across a compact. The 780K it
+// re-reads every turn is mostly dead weight; this is the few-KB that matters.
+exports.HANDOFF_TEMPLATE = `# ClaudeLink handoff — <role>
+
+## Current task & progress
+<what you are doing right now and how far along>
+
+## Key decisions / context you must NOT lose
+<constraints, choices already made, facts that won't be re-derivable>
+
+## Exact next step
+<the very next action to take on resume>
+
+## Open threads
+<anything in flight, awaited, or deferred>
+`;
+function handoffPathFor(agentId) {
+    return path_1.default.join(exports.HANDOFF_DIR, `${agentId}.md`);
+}
+// Step 2 of the handshake: the prepare-for-compact prompt (NOT a blind /compact).
+function preparePrompt(perTurnCostUsd, handoffFile) {
+    return (`Your context is now costing ~$${perTurnCostUsd.toFixed(2)}/turn to re-read. ` +
+        `Before I compact it, write a handoff to ${handoffFile} capturing: current task + progress; ` +
+        `key decisions/context you must not lose; the exact next step; open threads. ` +
+        `Reply READY when the file is written.`);
+}
+// Step 6: the post-compact re-orient prompt, points the agent at its essence.
+function postCompactPrompt(p, handoffFile) {
+    if (p === "A") {
+        return `Context compacted. Resume from your handoff at ${handoffFile} (plus the compact summary above).`;
+    }
+    return `Fresh context. Your handoff is at ${handoffFile} — resume from it; that is your full working state.`;
+}
+// Verify the agent actually wrote a non-trivial handoff before compacting.
+// Two checks, both required: file must be >200 bytes AND must NOT contain any
+// of the HANDOFF_TEMPLATE placeholders unfilled. A byte-count alone is
+// bypassable because the template itself is ~270 bytes — an agent that wrote
+// the template verbatim with nothing else would satisfy size but have zero
+// real content. The placeholder scan catches that.
+function verifyHandoff(file) {
+    try {
+        const st = fs_1.default.statSync(file);
+        if (st.size <= 200)
+            return { ok: false, bytes: st.size };
+        const body = fs_1.default.readFileSync(file, "utf-8");
+        for (const ph of HANDOFF_PLACEHOLDERS) {
+            if (body.includes(ph))
+                return { ok: false, bytes: st.size };
+        }
+        return { ok: true, bytes: st.size };
+    }
+    catch {
+        return { ok: false, bytes: 0 };
+    }
+}
+// The ordered plan for a given path. This is what the soak would execute; in dry
+// mode we only LOG it. The `injects` flags mark exactly which steps touch the
+// terminal — all of them stay stubbed until founder-armed.
+function planCompact(p, perTurnCostUsd, handoffFile) {
+    const common = [
+        { action: "send-prepare-prompt", detail: preparePrompt(perTurnCostUsd, handoffFile), injects: true },
+        { action: "await-ready", detail: "wait for the agent to reply READY (bounded timeout)", injects: false },
+        { action: "verify-handoff", detail: `verify ${handoffFile} exists and is non-trivial`, injects: false },
+    ];
+    if (p === "A") {
+        return [
+            ...common,
+            { action: "inject-compact", detail: "type /compact (Claude Code summarizes)", injects: true },
+            { action: "send-postcompact-prompt", detail: postCompactPrompt("A", handoffFile), injects: true },
+        ];
+    }
+    return [
+        ...common,
+        { action: "inject-clear", detail: "type /clear (fresh context, no model summary)", injects: true },
+        { action: "reinject-handoff", detail: "inject the handoff file contents as the new starting message", injects: true },
+        { action: "send-postcompact-prompt", detail: postCompactPrompt("B", handoffFile), injects: true },
+    ];
+}
+// Execute (or, in dry mode, PLAN) a compact via the chosen path. In dry mode it
+// returns the plan without touching anything. "armed" mode is NOT reachable yet:
+// it throws, because real injection is founder-gated and must be wired with the
+// idle-prompt safety detector under supervision — not enabled from here.
+function executeCompact(agentId, p, perTurnCostUsd, mode = "dry") {
+    const handoffFile = handoffPathFor(agentId);
+    const steps = planCompact(p, perTurnCostUsd, handoffFile);
+    if (mode === "armed") {
+        throw new Error("compact-executor: armed injection is not enabled — founder-gated, requires the idle-prompt safety detector and a supervised soak.");
+    }
+    return {
+        path: p,
+        mode: "dry",
+        steps,
+        executed: false,
+        note: "dry plan only — no terminal contact; injection steps marked injects:true are stubbed pending founder-armed soak",
+    };
+}
+//# sourceMappingURL=compact-executor.js.map

package/dist/compact-executor.js.map

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

package/dist/context-watcher-settings.d.ts

@@ -0,0 +1,21 @@
+export type WatcherMode = "observe" | "inject";
+export interface ContextWatcherSettings {
+    enabled: boolean;
+    mode: WatcherMode;
+    intervalSec: number;
+    contextOccupancyThreshold: number;
+    dollarPerTurnThreshold: number;
+    handshakeOverheadTokens: number;
+    activeWindowMin: number;
+    thresholdTokens: number;
+    compactBaselineTokens: number;
+    cooldownMin: number;
+    message: string;
+    askMessage: string;
+    consentFreshMin: number;
+    injectAllowlist: string[];
+    oneShot: boolean;
+    activeSince: string | null;
+}
+export declare function readContextWatcherSettings(): ContextWatcherSettings;
+export declare function writeContextWatcherSettings(partial: Partial<ContextWatcherSettings>): ContextWatcherSettings;