@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/lifecycle/lessons/dispatch.ts

@@ -0,0 +1,88 @@
+/**
+ * fuse-lessons scope dispatch (TS port of the 4 handler scripts). Routes by
+ * event: SessionStart/SubagentStart inject `MEMORY/LESSON.md`; Stop reminds the
+ * stopping session about ITS OWN projects with unsaved code edits; PostToolUse
+ * marks the write to arm/silence the throttle. The reminder + mark logic (incl.
+ * the per-`session_id` scoping that fixes the multi-session misdirection) lives
+ * in {@link module:runtime/lifecycle/lessons/reminder}; this module keeps the
+ * event router + lesson-file injection. Non-fatal by design.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { renderInform } from "../../inform";
+import { projectRoot } from "../../../util/project-root";
+import { atomicWrite } from "../../../util/json-io";
+import { curateLessons } from "../aipilot/curate-lessons";
+import { compressInjection } from "../aipilot/lesson-inject";
+import { capFragment } from "../../inject-budget";
+import { lessonsArchiveFileFor, lessonsFileFor } from "./state";
+import { markWrite, remindWrite } from "./reminder";
+
+/**
+ * Persist a curation ATOMICALLY and ARCHIVE-FIRST for zero-loss: prepend the
+ * moved bullets to LESSON-archive.md, THEN rewrite LESSON.md. On ANY write error
+ * the original file is left untouched (returns `original`) so a bullet is never
+ * lost — a rare archive-then-trim-fail leaves a duplicate (never a loss), which
+ * the next dedup pass reconciles.
+ */
+function persistCuration(file: string, root: string, curated: string, archive: string, original: string): string {
+  try {
+    if (archive) {
+      const af = lessonsArchiveFileFor(root);
+      const prev = existsSync(af) ? readFileSync(af, "utf-8") : "";
+      atomicWrite(af, prev ? `${archive}\n${prev}` : archive);
+    }
+    atomicWrite(file, curated);
+    return curated;
+  } catch { return original; }
+}
+
+/**
+ * Inject `MEMORY/LESSON.md` for `event`. Mechanical curation (dedup + cap→archive)
+ * rewrites the FILE; the injected BLOCK is then COMPRESSED (newest bullets whole,
+ * older ones distilled to their rule) so a growing file never inflates the
+ * SessionStart/SubagentStart context. A hard {@link capFragment} budget is the
+ * last-resort backstop on top of compression — the regression that motivated it
+ * was this exact block silently reaching ~44k tokens. Any curation report
+ * surfaces via systemMessage.
+ */
+function injectMemory(cwd: string, event: string, now: number, id: string): string {
+  const root = projectRoot(cwd);
+  const file = lessonsFileFor(root);
+  if (!existsSync(file)) return "";
+  let content = "";
+  try { content = readFileSync(file, "utf-8").trim(); } catch { return ""; }
+  if (!content) return "";
+  const { content: curated, archive, report } = curateLessons(content, now, root);
+  if (curated !== content) content = persistCuration(file, root, curated, archive, content);
+  const body = capFragment("lessons", compressInjection(content));
+  const ctx = `Project lessons — never reproduce these:\n${body}\nYou may append OR refine/merge/dedupe bullets in MEMORY/LESSON.md — keep it terse.`;
+  const notice = report ? `lessons injected\nLESSON.md curation:\n${report}` : "lessons injected";
+  return renderInform(id, event, ctx, notice);
+}
+
+/**
+ * Route a fuse-lessons event to its handler. Returns the native stdout for
+ * context-injecting events (SessionStart/SubagentStart/UserPromptSubmit inject
+ * MEMORY/LESSON.md, Stop reminds) or "" for the side-effect-only PostToolUse mark.
+ * @param event - The raw hook event name.
+ * @param payload - The raw hook payload.
+ * @param cwd - Project root for memory injection.
+ * @param now - Clock.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native stdout (possibly empty).
+ */
+export function dispatchLessons(event: string, payload: Record<string, unknown>, cwd: string, now: number, id: string = "claude-code"): string {
+  switch (event) {
+    case "SessionStart":
+    case "SubagentStart":
+    case "UserPromptSubmit":
+      return injectMemory(cwd, event, now, id);
+    case "Stop":
+      return remindWrite(payload, now);
+    case "PostToolUse":
+      markWrite(payload, now);
+      return "";
+    default:
+      return "";
+  }
+}

package/src/runtime/lifecycle/lessons/reminder.ts

@@ -0,0 +1,89 @@
+/**
+ * fuse-lessons write-mark + Stop-reminder, scoped by `session_id` when present.
+ *
+ * WITH a session id (normal Claude Code): each `(session, root)` pair carries
+ * its own edit/reminder throttle in {@link module:memory/session-roots}, so a
+ * Stop lists and silences ONLY the roots THAT session edited — concurrent
+ * sessions on different projects never cross-remind nor steal each other's
+ * throttle. WITHOUT a usable session id (a harness that omits it, or the legacy
+ * on-disk state) it falls back to the original mono-session behavior: the global
+ * flat root registry + the per-project `MEMORY/state.json` throttle.
+ */
+import { dirname, resolve } from "node:path";
+import { contextResponse } from "../../../adapters/claude";
+import { sanitizeSessionId } from "../../home-state";
+import { addRoot, readRoots } from "../../../memory/registry";
+import { collectSessionPending, markSessionRoot } from "../../../memory/session-roots";
+import { nowStamp, readState, setStateField, throttleMs } from "../../../memory/state";
+import { isCodeFile, projectRootOrNull } from "../../../util/project-root";
+import { lessonsStateFileFor } from "./state";
+
+/** Sanitized session id from a raw hook payload, or null (→ legacy fallback). */
+function sessionOf(payload: Record<string, unknown>): string | null {
+  return sanitizeSessionId(payload.session_id);
+}
+
+/** Legacy (no session id): pending roots across the global flat registry. */
+function collectLegacyPending(now: number, window: number): string[] {
+  const pending: string[] = [];
+  for (const root of readRoots()) {
+    const stateFile = lessonsStateFileFor(root);
+    const { lastRemindedAt, lastCodeEditAt } = readState(stateFile);
+    if (lastCodeEditAt <= lastRemindedAt) continue;
+    if (now - lastRemindedAt < window) continue;
+    pending.push(root);
+    setStateField(stateFile, "lastRemindedAt", now);
+  }
+  return pending;
+}
+
+/** Stop reminder body listing each pending project's lessons file. */
+function reminderText(pending: string[]): string {
+  const stamp = nowStamp();
+  const targets = pending.map((r) => `- ${r}/MEMORY/LESSON.md`).join("\n");
+  return `Before ending: if this session hit a mistake/blocker worth never ` +
+    `reproducing, append 1-3 COMPACT bullets OR sharpen/merge existing ones ` +
+    `(format \`- [${stamp}] what went wrong → do instead\`, use exactly this ` +
+    `timestamp) in each project's lessons file below. Skip if nothing ` +
+    `notable.\n${targets}`;
+}
+
+/**
+ * Stop: emit one reminder covering the stopping session's pending projects.
+ * @param payload - Raw hook payload (`session_id` selects the scoped path).
+ * @param now - Clock.
+ * @returns Native Stop stdout, or "" when nothing is pending.
+ */
+export function remindWrite(payload: Record<string, unknown>, now: number): string {
+  const window = throttleMs();
+  const sid = sessionOf(payload);
+  const pending = sid ? collectSessionPending(sid, now, window) : collectLegacyPending(now, window);
+  if (pending.length === 0) return "";
+  return contextResponse("Stop", reminderText(pending));
+}
+
+/**
+ * PostToolUse: record the edit against the throttle. A code file arms the
+ * reminder; writing `MEMORY/LESSON.md` silences it (the lesson was just saved).
+ * Session-scoped when `session_id` is present, else the legacy global path.
+ * @param payload - Raw hook payload (`tool_input.file_path`, `session_id`).
+ * @param now - Clock.
+ */
+export function markWrite(payload: Record<string, unknown>, now: number): void {
+  const input = payload.tool_input as { file_path?: string } | undefined;
+  if (!input?.file_path) return;
+  const abs = resolve(input.file_path);
+  const root = projectRootOrNull(dirname(abs));
+  if (!root) return;
+  const isLesson = abs === resolve(root, "MEMORY", "LESSON.md");
+  if (!isLesson && !isCodeFile(abs)) return;
+  const sid = sessionOf(payload);
+  if (sid) {
+    markSessionRoot(sid, root, isLesson ? "remindedAt" : "editedAt", now);
+  } else if (isLesson) {
+    setStateField(lessonsStateFileFor(root), "lastRemindedAt", now);
+  } else {
+    setStateField(lessonsStateFileFor(root), "lastCodeEditAt", now);
+    addRoot(root);
+  }
+}

package/src/runtime/lifecycle/lessons/state.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-project lessons paths. The `fuse-lessons` plugin stores its lessons under
+ * `<root>/MEMORY/` (NOT the harness `.harness/memory/`), so these two path
+ * helpers override the layout while ALL state/gitignore/throttle logic is
+ * reused from `src/memory` (`setStateField`, `ensureMemoryGitignore`,
+ * `readState`, `nowStamp`, `throttleMs`).
+ */
+import { join } from "node:path";
+
+/** Absolute `<root>/MEMORY/LESSON.md` — the curated, committable lessons file. */
+export function lessonsFileFor(root: string): string {
+  return join(root, "MEMORY", "LESSON.md");
+}
+
+/** Absolute `<root>/MEMORY/LESSON-archive.md` — cold storage for capped-out bullets. */
+export function lessonsArchiveFileFor(root: string): string {
+  return join(root, "MEMORY", "LESSON-archive.md");
+}
+
+/** Absolute `<root>/MEMORY/state.json` — machine-local throttle counter. */
+export function lessonsStateFileFor(root: string): string {
+  return join(root, "MEMORY", "state.json");
+}

package/src/runtime/lifecycle/memory/agent-lesson.ts

@@ -0,0 +1,35 @@
+/**
+ * SubagentStop memory handler. Ports `capture-agent-lesson.py`: log a finished
+ * agent's conclusion and, when salient enough, store it as a Graphiti episode.
+ * Skips explore-codebase/websearch agents and errored exits.
+ */
+import { isoUtc } from "../security/skill-state";
+import { postEpisode } from "./client";
+import { SALIENCE_THRESHOLD, agentSeverity, salience } from "./salience";
+import { appendMemoryLog } from "./state";
+
+/** Agents whose conclusions are never captured. */
+const SKIP = new Set(["explore-codebase", "websearch"]);
+
+/**
+ * Handle SubagentStop: log + maybe store the agent's conclusion. Side-effect
+ * only (no stdout).
+ * @param payload - The raw hook payload.
+ * @param now - Clock.
+ */
+export async function captureAgentLesson(payload: Record<string, unknown>, now: number): Promise<void> {
+  const name = typeof payload.agent_name === "string" ? payload.agent_name : "unknown";
+  const lastMsg = typeof payload.last_assistant_message === "string" ? payload.last_assistant_message : "";
+  const exitReason = typeof payload.exit_reason === "string" ? payload.exit_reason : "unknown";
+  if (!lastMsg || exitReason === "error" || SKIP.has(name)) return;
+  const lesson = lastMsg.slice(0, 1000);
+  const ts = isoUtc(now);
+  appendMemoryLog("agent-lessons.log", `[${ts}] ${name} | ${exitReason} | ${lesson.slice(0, 80)}...`);
+  if (salience(agentSeverity(name)) <= SALIENCE_THRESHOLD) return;
+  await postEpisode({
+    name: "agent_lesson",
+    episode_body: `Agent ${name} conclusion: ${lesson}`,
+    source_description: `agent-stop-${name}`,
+    reference_time: ts,
+  });
+}

package/src/runtime/lifecycle/memory/capture-error.ts

@@ -0,0 +1,41 @@
+/**
+ * PostToolUse (Bash) memory handler. Ports `auto-capture-error.py`: on a
+ * non-zero Bash exit with stderr, store an episode in Graphiti and surface a
+ * `<memory-capture>` hint to search past errors / store the eventual solution.
+ */
+import { contextResponse } from "../../../adapters/claude";
+import { isoUtc } from "../security/skill-state";
+import { postEpisode } from "./client";
+import { SALIENCE_THRESHOLD, bashSeverity, salience } from "./salience";
+
+/** Extract exit code + stderr from a PostToolUse Bash payload (either field). */
+function bashResult(payload: Record<string, unknown>): { exit: string; stderr: string } {
+  const r = (payload.tool_result ?? payload.tool_response) as { exit_code?: unknown; stderr?: unknown } | undefined;
+  return { exit: String(r?.exit_code ?? "0"), stderr: typeof r?.stderr === "string" ? r.stderr : "" };
+}
+
+/**
+ * Handle a Bash PostToolUse: capture a failed command's error in neural memory
+ * and return the native additionalContext stdout (or "" when nothing to emit).
+ * @param payload - The raw hook payload.
+ * @param now - Clock.
+ * @returns The native stdout (possibly empty).
+ */
+export async function captureBashError(payload: Record<string, unknown>, now: number): Promise<string> {
+  const { exit, stderr } = bashResult(payload);
+  if (exit === "0" || !stderr) return "";
+  const sev = bashSeverity(stderr);
+  if (salience(sev) <= SALIENCE_THRESHOLD) return "";
+  const errorMsg = stderr.slice(0, 500);
+  await postEpisode({
+    name: "bash_error",
+    episode_body: `Bash error (exit ${exit}): ${errorMsg}`,
+    source_description: "auto-capture",
+    reference_time: isoUtc(now),
+  });
+  const ctx =
+    `Error captured in neural memory (Graphiti).\n` +
+    `Search for similar past errors: use mcp__qdrant__qdrant-find with query "${errorMsg}"\n` +
+    `If you solve this, store the solution: use mcp__qdrant__qdrant-store`;
+  return contextResponse("PostToolUse", ctx);
+}

package/src/runtime/lifecycle/memory/client.ts

@@ -0,0 +1,65 @@
+/**
+ * Graphiti neural-memory HTTP client (best-effort). Ports the urllib calls in
+ * the memory-neural scripts: POST /episodes (store) + POST /search (recall).
+ * Every call swallows network errors and honors a 5s timeout, so a hook never
+ * fails or hangs when the Graphiti server is absent.
+ */
+
+const TIMEOUT_MS = 5000;
+
+/** Base URL `http://<NEURAL_MEMORY_HOST>:<GRAPHITI_PORT>` (env-overridable). */
+export function neuralBase(env: NodeJS.ProcessEnv = process.env): string {
+  const host = env.NEURAL_MEMORY_HOST ?? "localhost";
+  const port = env.GRAPHITI_PORT ?? "8000";
+  return `http://${host}:${port}`;
+}
+
+/** A Graphiti episode payload. */
+export interface Episode {
+  name: string;
+  episode_body: string;
+  source_description: string;
+  reference_time: string;
+}
+
+/** POST an episode to Graphiti `/episodes`. Resolves silently on any failure. */
+export async function postEpisode(ep: Episode, env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  try {
+    await fetch(`${neuralBase(env)}/episodes`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(ep),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch { /* best effort */ }
+}
+
+/** A single recall hit (content or name). */
+export interface RecallHit {
+  content?: string;
+  name?: string;
+}
+
+/**
+ * POST a query to Graphiti `/search`; returns hits or `[]` on any failure
+ * (network error, timeout, non-2xx, malformed JSON).
+ * @param query - The search query.
+ * @param numResults - Max results requested.
+ * @param env - Env (for host/port overrides).
+ * @returns The recall hits, possibly empty.
+ */
+export async function searchMemory(query: string, numResults: number, env: NodeJS.ProcessEnv = process.env): Promise<RecallHit[]> {
+  try {
+    const resp = await fetch(`${neuralBase(env)}/search`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query, num_results: numResults }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!resp.ok) return [];
+    const data = (await resp.json()) as { results?: RecallHit[] };
+    return Array.isArray(data.results) ? data.results : [];
+  } catch {
+    return [];
+  }
+}

package/src/runtime/lifecycle/memory/dispatch.ts

@@ -0,0 +1,42 @@
+/**
+ * fuse-memory-neural scope dispatcher (async; the handlers hit Graphiti over
+ * HTTP, best-effort). Routes by event: SessionStart recalls past lessons,
+ * PostToolUse captures Bash errors / tracks graphiti+qdrant ops, SubagentStop
+ * captures agent conclusions. Returns the native stdout when handled, or `null`
+ * to fall through to the generic pipeline.
+ */
+import { captureAgentLesson } from "./agent-lesson";
+import { captureBashError } from "./capture-error";
+import { trackMemoryOp } from "./track-ops";
+import { recallOnSession } from "./recall";
+
+/** Is this a graphiti/qdrant MCP tool call? */
+function isMemoryTool(tool: string): boolean {
+  return tool.startsWith("mcp__graphiti") || tool.startsWith("mcp__qdrant");
+}
+
+/**
+ * Dispatch a memory-scope lifecycle event to its ported handler.
+ * @param event - Raw hook event name.
+ * @param payload - Raw hook payload.
+ * @param cwd - Project root.
+ * @param now - Clock.
+ * @returns The native stdout, or `null` when unhandled.
+ */
+export async function dispatchMemory(event: string, payload: Record<string, unknown>, cwd: string, now: number): Promise<string | null> {
+  if (event === "SessionStart") return recallOnSession(cwd, now);
+  if (event === "SubagentStop" || event === "Stop") {
+    await captureAgentLesson(payload, now);
+    return "";
+  }
+  if (event === "PostToolUse") {
+    const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
+    if (tool === "Bash") return captureBashError(payload, now);
+    if (isMemoryTool(tool)) {
+      trackMemoryOp(payload, now);
+      return "";
+    }
+    return null;
+  }
+  return null;
+}

package/src/runtime/lifecycle/memory/recall.ts

@@ -0,0 +1,30 @@
+/**
+ * SessionStart memory handler. Ports `recall-on-session.py`: detect the project
+ * type, recall relevant lessons from Graphiti, log the recall, and inject a
+ * neural-memory-recall additionalContext block.
+ */
+import { basename } from "node:path";
+import { contextResponse } from "../../../adapters/claude";
+import { isoUtc } from "../security/skill-state";
+import { searchMemory } from "./client";
+import { appendMemoryLog, detectProjectType } from "./state";
+
+/**
+ * Handle SessionStart: recall past lessons for this project and return the
+ * native additionalContext stdout (or "" when there is nothing to recall).
+ * @param cwd - Project root.
+ * @param now - Clock.
+ * @returns The native stdout (possibly empty).
+ */
+export async function recallOnSession(cwd: string, now: number): Promise<string> {
+  const projectType = detectProjectType(cwd);
+  const projectName = basename(cwd);
+  const hits = await searchMemory(`${projectType} ${projectName} common errors`, 5);
+  appendMemoryLog("recalls.log", `[${isoUtc(now)}] session_recall | ${projectType} | ${projectName}`);
+  if (hits.length === 0) return "";
+  const lessons = hits.slice(0, 5).map((r) => `- ${r.content || r.name || "unknown"}`).join("\n");
+  const ctx =
+    `Relevant lessons from past sessions:\n${lessons}\n` +
+    `For deeper search: use mcp__qdrant__qdrant-find with project-specific queries.`;
+  return contextResponse("SessionStart", ctx);
+}

package/src/runtime/lifecycle/memory/salience.ts

@@ -0,0 +1,31 @@
+/**
+ * Salience + severity scoring for the memory-neural scope. Ports the
+ * `_severity` / `_agent_severity` helpers and the shared salience formula from
+ * `auto-capture-error.py` and `capture-agent-lesson.py`.
+ */
+
+/** Episodes at or below this salience are not stored. */
+export const SALIENCE_THRESHOLD = 0.3;
+
+/** Severity (1-10) of a Bash stderr by keyword (mirrors auto-capture-error). */
+export function bashSeverity(stderr: string): number {
+  const s = stderr.toLowerCase();
+  if (s.includes("fatal") || s.includes("panic")) return 10;
+  if (s.includes("error") || s.includes("failed")) return 8;
+  if (s.includes("warning")) return 4;
+  if (s.includes("deprecated")) return 2;
+  return 5;
+}
+
+/** Severity (1-10) of a finished agent by name (mirrors capture-agent-lesson). */
+export function agentSeverity(name: string): number {
+  if (name === "sniper" || name === "sniper-faster") return 8;
+  if (name === "research-expert") return 6;
+  if (name.endsWith("-expert")) return 7;
+  return 5;
+}
+
+/** Salience from severity: 0.40·sev/10 + 0.30 + 0.20·0.5 + 0.10·0.5. */
+export function salience(severity: number): number {
+  return (0.4 * severity) / 10 + 0.3 + 0.2 * 0.5 + 0.1 * 0.5;
+}

package/src/runtime/lifecycle/memory/state.ts

@@ -0,0 +1,49 @@
+/**
+ * fuse-memory-neural scope state: per-line logs under
+ * `~/.claude/logs/00-memory` + project-type detection. Ports the shared
+ * filesystem helpers of the four memory-neural scripts.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { claudeHome } from "../../home-state";
+import { atomicWrite } from "../../../util/json-io";
+
+/** `~/.claude/logs/00-memory` log directory. */
+export function memoryLogDir(home: string = homedir()): string {
+  return join(claudeHome(home), "logs", "00-memory");
+}
+
+/**
+ * Append a line to a memory log file, creating the dir. When `rotateAt > 0` and
+ * the file exceeds it, keep only the newest `keep` lines. Best-effort (errors
+ * swallowed), so a hook never fails on a logging issue.
+ * @param name - Log file name (e.g. `operations.log`).
+ * @param line - Line to append (newline added).
+ * @param rotateAt - Rotate when line count exceeds this (0 disables).
+ * @param keep - Lines to keep on rotation.
+ * @param home - Home dir.
+ */
+export function appendMemoryLog(name: string, line: string, rotateAt = 0, keep = 0, home: string = homedir()): void {
+  const dir = memoryLogDir(home);
+  try {
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, name);
+    appendFileSync(file, `${line}\n`, "utf-8");
+    if (rotateAt > 0) {
+      const lines = readFileSync(file, "utf-8").split("\n").filter((l) => l.length > 0);
+      if (lines.length > rotateAt) atomicWrite(file, `${lines.slice(-keep).join("\n")}\n`);
+    }
+  } catch { /* best effort */ }
+}
+
+/** Detect the project type from cwd markers (mirrors recall-on-session.py). */
+export function detectProjectType(cwd: string): string {
+  const markers: Array<[string, string]> = [
+    ["package.json", "node"], ["composer.json", "php"],
+    ["Package.swift", "swift"], ["Cargo.toml", "rust"], ["go.mod", "go"],
+  ];
+  for (const [f, t] of markers) if (existsSync(join(cwd, f))) return t;
+  if (existsSync(join(cwd, "requirements.txt")) || existsSync(join(cwd, "pyproject.toml"))) return "python";
+  return "unknown";
+}

package/src/runtime/lifecycle/memory/track-ops.ts

@@ -0,0 +1,15 @@
+/**
+ * PostToolUse (mcp__graphiti|mcp__qdrant) memory handler. Ports
+ * `track-memory-ops.py`: append `[ts] <tool> | ok|error` to
+ * `operations.log`, rotating at 1000 lines (keeping the newest 500).
+ */
+import { isoUtc } from "../security/skill-state";
+import { appendMemoryLog } from "./state";
+
+/** Append a memory-operation log line for a graphiti/qdrant tool call. */
+export function trackMemoryOp(payload: Record<string, unknown>, now: number): void {
+  const tool = typeof payload.tool_name === "string" ? payload.tool_name : "unknown";
+  const result = (payload.tool_result ?? payload.tool_response) as { error?: unknown } | undefined;
+  const status = result?.error ? "error" : "ok";
+  appendMemoryLog("operations.log", `[${isoUtc(now)}] ${tool} | ${status}`, 1000, 500);
+}

package/src/runtime/lifecycle/post-compact.ts

@@ -0,0 +1,38 @@
+/**
+ * @module post-compact
+ * PostCompact handler (core scope): re-inject the reconciliation snapshot plus a
+ * one-line reminder that read-state may have been reset by compaction, so the
+ * agent re-reads files before editing. Deduped per session/window (compaction can
+ * fan out too). Fully fail-open — any error yields "".
+ * @packageDocumentation
+ */
+import { contextResponse } from "../../adapters/claude";
+import { oncePerWindow } from "../inject-dedup";
+import { defaultStateDir } from "../paths";
+import { renderSnapshot } from "./snapshot";
+
+/** Re-inject at most once per 30s per session (compaction fan-out + retries). */
+const COMPACT_DEDUP_MS = 30_000;
+
+/** One-line reminder prepended to the re-injected snapshot. */
+const REMINDER = "Context was compacted — reread files before editing (read-state may be reset).";
+
+/**
+ * Handle PostCompact: emit the reminder + reconciliation snapshot as
+ * `additionalContext`, deduped per session. "" on dedup-suppress or any error.
+ * @param data - The raw PostCompact payload (`session_id`, `trigger`).
+ * @param cwd - Project root.
+ * @param moduleUrl - `import.meta.url` of the caller (locates the running package for the version line).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout, or "".
+ */
+export function postCompactContext(data: Record<string, unknown>, cwd: string, moduleUrl: string, now: number = Date.now()): string {
+  try {
+    const sessionId = typeof data.session_id === "string" ? data.session_id : "unknown";
+    if (!oncePerWindow(`postcompact:${sessionId}`, COMPACT_DEDUP_MS, { now, dir: defaultStateDir(cwd) })) return "";
+    const snapshot = renderSnapshot(cwd, moduleUrl);
+    return contextResponse("PostCompact", snapshot ? `${REMINDER}\n\n${snapshot}` : REMINDER);
+  } catch {
+    return "";
+  }
+}

package/src/runtime/lifecycle/post-edit-ts.ts

@@ -0,0 +1,49 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import { contextResponse } from "../../adapters/claude";
+
+const TS_EXT = /\.(ts|tsx)$/;
+const TIMEOUT_MS = 10000;
+
+/** True when `bin` is resolvable on PATH (mirrors shutil.which). */
+function hasBin(bin: string): boolean {
+  try {
+    execFileSync(process.platform === "win32" ? "where" : "which", [bin], { stdio: "pipe", timeout: 2000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run `bin args`, returning `{ code, out }` (code 1 on spawn error). */
+function run(bin: string, args: string[]): { code: number; out: string } {
+  try {
+    const out = execFileSync(bin, args, { encoding: "utf-8", stdio: "pipe", timeout: TIMEOUT_MS });
+    return { code: 0, out };
+  } catch (err) {
+    const e = err as { status?: number; stdout?: string | Buffer };
+    return { code: e.status ?? 1, out: typeof e.stdout === "string" ? e.stdout : e.stdout?.toString() ?? "" };
+  }
+}
+
+/**
+ * Handle PostToolUse for TS/TSX: report eslint/prettier issues (never fixes) as
+ * additionalContext. Ports `post-tool-use/post-edit-typescript.py`.
+ * @param filePath - The edited file path.
+ * @returns The native hook stdout (possibly empty).
+ */
+export function postEditTypescript(filePath: string): string {
+  if (!filePath || !TS_EXT.test(filePath) || !existsSync(filePath)) return "";
+  const issues: string[] = [];
+  if (hasBin("eslint")) {
+    const r = run("eslint", ["--no-fix", "--format", "compact", filePath]);
+    if (r.code !== 0 && r.out.trim()) issues.push(`ESLint:\n${r.out.trim()}`);
+  }
+  if (hasBin("prettier")) {
+    const r = run("prettier", ["--check", filePath]);
+    if (r.code !== 0) issues.push(`Prettier: ${basename(filePath)} needs formatting`);
+  }
+  if (issues.length === 0) return "";
+  return contextResponse("PostToolUse", `Lint issues in ${basename(filePath)}: ${issues.join(" | ")}`);
+}

package/src/runtime/lifecycle/post-tracking.ts

@@ -0,0 +1,40 @@
+/**
+ * PostToolUse side-effect trackers for non-core scopes (carto/security/
+ * changelog). Pure side-effects — never produces stdout.
+ */
+import type { NormalizedEvent } from "../normalize";
+import type { PluginScope } from "./dispatch";
+import { trackEnrichment } from "./cartographer/track-enrichment";
+import { trackSkillRead } from "./security/track-skill-read";
+import { trackMcpResearch } from "./security/track-mcp";
+import { trackWatchResearch } from "./changelog-research";
+import { dispatchLessons } from "./lessons/dispatch";
+
+/**
+ * Dispatch the appropriate PostToolUse tracker for the invoking scope. Carto
+ * persists manual enrichments; security records skill reads + MCP research;
+ * changelog records watch research; lessons arms the per-project throttle.
+ * Side-effect only.
+ * @param scope - The invoking plugin scope.
+ * @param event - The normalized event.
+ * @param input - The raw tool input.
+ * @param now - Clock.
+ * @param payload - The raw hook payload (for the lessons mark).
+ * @param cwd - The project root (for the lessons mark).
+ */
+export function postTrackingSideEffects(scope: PluginScope, event: NormalizedEvent, input: Record<string, unknown>, now: number, payload: Record<string, unknown> = {}, cwd: string = process.cwd()): void {
+  if (scope === "carto" && (event.tool === "Edit" || event.tool === "Write") && event.filePath) {
+    trackEnrichment(event.filePath);
+    return;
+  }
+  if (scope === "security") {
+    trackSkillRead(event.tool, event.filePath ?? "", now);
+    trackMcpResearch(event.tool, input, now);
+    return;
+  }
+  if (scope === "changelog") {
+    trackWatchResearch(event.tool, input, now);
+    return;
+  }
+  if (scope === "lessons") dispatchLessons("PostToolUse", payload, cwd, now);
+}