@fusengine/harness 0.1.90 → 0.1.91

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

@@ -0,0 +1,38 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { harnessHomeSegment } from "../../policy/apex-target";
+
+/** Two-digit zero-pad. */
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** Compact local timestamp `YYYYMMDD-HHMMSS` (mirrors Python strftime). */
+function stamp(now: number): string {
+  const d = new Date(now);
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+/**
+ * Handle PreCompact: back up the target apex `task.json` (`.claude/apex/`,
+ * `.codex/apex/`, ...) to `backups/`, keep only the 5 newest, and emit a
+ * confirmation. Ports `pre-compact/save-apex-state.py`.
+ * @param cwd - Project root.
+ * @param now - Clock (defaults to `Date.now()`).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty when no task.json).
+ */
+export function saveApexState(cwd: string, now: number = Date.now(), id: string = "claude-code"): string {
+  const seg = harnessHomeSegment(id);
+  const apexDir = join(cwd, seg, "apex");
+  const stateFile = join(apexDir, "task.json");
+  if (!existsSync(stateFile)) return "";
+  const backupDir = join(apexDir, "backups");
+  mkdirSync(backupDir, { recursive: true });
+  copyFileSync(stateFile, join(backupDir, `task-${stamp(now)}.json`));
+  const backups = readdirSync(backupDir).filter((n) => n.startsWith("task-") && n.endsWith(".json")).sort().reverse();
+  for (const old of backups.slice(5)) {
+    try { rmSync(join(backupDir, old), { force: true }); } catch { /* best effort */ }
+  }
+  return JSON.stringify({ additionalContext: `APEX state saved before compaction. Previous task state preserved in ${seg}/apex/backups/` });
+}

package/src/runtime/lifecycle/rules-root.ts

@@ -0,0 +1,83 @@
+/**
+ * Dynamic rules-plugin root resolution. The historical `CLAUDE_PLUGIN_ROOT ??
+ * cwd` chain only worked when the harness exported the plugin root — Kimi
+ * injects `KIMI_PLUGIN_ROOT` instead, and a bare cwd fallback never held a
+ * `rules/` dir. Resolution order (first hit wins):
+ * 1. `CLAUDE_PLUGIN_ROOT` (claude-code/codex plugin-declared hooks);
+ * 2. `KIMI_PLUGIN_ROOT` (kimi plugin-declared hooks);
+ * 3. Per-harness install probe (claude marketplace, codex versioned cache,
+ *    kimi managed plugins) — first `<plugin>/rules` dir whose plugin folder
+ *    name contains "rules";
+ * 4. `cwd` (historical fallback, unchanged behavior).
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { maxSemver } from "../../util/semver";
+
+/** Immediate child dir names of `dir`, or [] when unreadable. */
+function children(dir: string): string[] {
+  try { return readdirSync(dir); } catch { return []; }
+}
+
+/** First existing `<base>/<child>/rules` where `child` names a rules plugin. */
+function probe(base: string, childFilter: (name: string) => boolean): string | null {
+  for (const child of children(base).sort()) {
+    if (!childFilter(child)) continue;
+    const dir = join(base, child, "rules");
+    if (existsSync(dir)) return join(base, child);
+  }
+  return null;
+}
+
+/** Claude: `~/.claude/plugins/marketplaces/<marketplace>/plugins/<rules-plugin>/`. */
+function probeClaude(home: string): string | null {
+  const markets = join(home, ".claude", "plugins", "marketplaces");
+  for (const m of children(markets).sort()) {
+    const hit = probe(join(markets, m, "plugins"), (n) => n.includes("rules"));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Codex: `~/.codex/plugins/cache/<marketplace>/<rules-plugin>/<version>/` (highest semver). */
+function probeCodex(home: string): string | null {
+  const cache = join(home, ".codex", "plugins", "cache");
+  for (const m of children(cache).sort()) {
+    for (const p of children(join(cache, m)).sort()) {
+      if (!p.includes("rules")) continue;
+      const versions = children(join(cache, m, p)).filter((v) => existsSync(join(cache, m, p, v, "rules")));
+      const latest = maxSemver(versions);
+      if (latest) return join(cache, m, p, latest);
+    }
+  }
+  return null;
+}
+
+/** Kimi: `<KIMI_CODE_HOME>/plugins/managed/<rules-plugin>/` (managed install copy). */
+function probeKimi(env: Record<string, string | undefined>, home: string): string | null {
+  const root = env.KIMI_CODE_HOME ?? join(home, ".kimi-code");
+  return probe(join(root, "plugins", "managed"), (n) => n.includes("rules"));
+}
+
+/**
+ * Resolve the directory whose `rules/` subtree holds the `*.md` rule files.
+ * @param id - Harness id (selects the install-layout probe).
+ * @param cwd - Historical fallback root.
+ * @param env - Environment (defaults to `process.env`).
+ * @returns The plugin root to read `rules/` from.
+ */
+export function resolveRulesRoot(
+  id: string,
+  cwd: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  if (env.CLAUDE_PLUGIN_ROOT) return env.CLAUDE_PLUGIN_ROOT;
+  if (env.KIMI_PLUGIN_ROOT) return env.KIMI_PLUGIN_ROOT;
+  const home = env.HOME ?? homedir();
+  const hit = id === "codex" ? probeCodex(home)
+    : id === "kimi" ? probeKimi(env, home)
+    : id === "claude-code" ? probeClaude(home)
+    : null;
+  return hit ?? cwd;
+}

package/src/runtime/lifecycle/security/check-skill.ts

@@ -0,0 +1,63 @@
+/**
+ * Security advisory (PreToolUse Write/Edit on code files) — NON-BLOCKING.
+ * Ports `check-security-skill.py`: nudge the agent to read the security skill,
+ * but always allow the edit.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { securityStatePath } from "./skill-state";
+import { contextResponse } from "../../../adapters/claude";
+import type { NormalizedFile } from "../../normalize";
+
+const CODE_RE = /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java)$/;
+const ADVISORY = "SECURITY: Read security skill references before modifying code. Use: Read skills/security-scan/references/scan-patterns.md";
+
+/** True once today's security skill is marked read. Fail-open: missing/corrupt state reads as unread. */
+function skillAlreadyRead(now: number, home: string): boolean {
+  const path = securityStatePath(now, home);
+  if (!existsSync(path)) return false;
+  try {
+    const state = JSON.parse(readFileSync(path, "utf-8")) as { skill_read?: boolean };
+    return state.skill_read === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a non-blocking PreToolUse advisory when editing a code file before the
+ * security skill has been read, "" otherwise. Renders through the shared
+ * {@link contextResponse} builder (`additionalContext` only) — NEVER a naked
+ * `permissionDecision: "allow"`, which the Codex adapter's own hook shape
+ * (`src/adapters/claude/index.ts`) never emits and which Codex rejects.
+ * @param tool - The tool name (`Write`/`Edit`).
+ * @param filePath - The target file path.
+ * @param now - Clock.
+ * @param home - Home dir.
+ * @returns The advisory response JSON, or "".
+ */
+export function securityAdvisory(tool: string, filePath: string, now: number = Date.now(), home: string = homedir()): string {
+  if (tool !== "Write" && tool !== "Edit") return "";
+  if (!CODE_RE.test(filePath)) return "";
+  if (skillAlreadyRead(now, home)) return "";
+  return contextResponse("PreToolUse", ADVISORY);
+}
+
+/**
+ * Multi-file counterpart for a Codex `apply_patch` envelope: evaluate EACH
+ * add/update file (delete ignored outright; non-code filtered by the same
+ * `CODE_RE` inside {@link securityAdvisory}) and return the advisory
+ * triggered by the FIRST qualifying file, or "" once the skill has been read
+ * or no file qualifies.
+ * @param files - The patch's per-file changes ({@link NormalizedFile}).
+ * @param now - Clock.
+ * @param home - Home dir.
+ */
+export function securityAdvisoryForPatch(files: readonly NormalizedFile[], now: number = Date.now(), home: string = homedir()): string {
+  for (const f of files) {
+    if (f.op === "delete") continue;
+    const advisory = securityAdvisory(f.op === "add" ? "Write" : "Edit", f.filePath, now, home);
+    if (advisory) return advisory;
+  }
+  return "";
+}

package/src/runtime/lifecycle/security/scan-patterns.ts

@@ -0,0 +1,53 @@
+/**
+ * @module security/scan-patterns
+ * OWASP scan pattern table by language. Ports the Python
+ * `security_scan_patterns.py`: each entry is (severity, category, regex, glob).
+ * Go/Rust/unknown intentionally have no patterns (parity: empty result).
+ * @packageDocumentation
+ */
+
+/** Vulnerability severity level (drives the summary counters). */
+export type Severity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+
+/** A single scan rule: a regex applied to files matching `glob`. */
+export interface ScanPattern {
+  severity: Severity;
+  category: string;
+  regex: RegExp;
+  glob: string;
+}
+
+/** OWASP scan patterns keyed by detected language (ported 1:1 from Python). */
+const PATTERNS: Record<string, ScanPattern[]> = {
+  javascript: [
+    { severity: "HIGH", category: "XSS", regex: /innerHTML\s*=/, glob: "*.js" },
+    { severity: "HIGH", category: "XSS", regex: /dangerouslySetInnerHTML/, glob: "*.js" },
+    { severity: "CRITICAL", category: "CODE_EXEC", regex: /eval\(/, glob: "*.js" },
+    { severity: "CRITICAL", category: "CODE_EXEC", regex: /new Function\(/, glob: "*.js" },
+    { severity: "CRITICAL", category: "CMD_INJECTION", regex: /child_process/, glob: "*.js" },
+    { severity: "HIGH", category: "CMD_INJECTION", regex: /shell:\s*true/, glob: "*.js" },
+    { severity: "MEDIUM", category: "WEAK_CRYPTO", regex: /Math\.random\(\)/, glob: "*.js" },
+    { severity: "CRITICAL", category: "SECRETS", regex: /AKIA[0-9A-Z]{16}/, glob: "*.js" },
+  ],
+  php: [
+    { severity: "CRITICAL", category: "RCE", regex: /shell_exec|system\(|passthru\(/, glob: "*.php" },
+    { severity: "CRITICAL", category: "CODE_EXEC", regex: /eval\(|assert\(/, glob: "*.php" },
+    { severity: "HIGH", category: "SQL_INJECTION", regex: /mysql_query\(/, glob: "*.php" },
+  ],
+  python: [
+    { severity: "CRITICAL", category: "CODE_EXEC", regex: /eval\(|exec\(/, glob: "*.py" },
+    { severity: "CRITICAL", category: "CMD_INJECTION", regex: /os\.system\(|subprocess.*shell=True/, glob: "*.py" },
+    { severity: "HIGH", category: "DESERIALIZATION", regex: /pickle\.loads\(/, glob: "*.py" },
+    { severity: "HIGH", category: "TLS", regex: /verify=False|ssl\.CERT_NONE/, glob: "*.py" },
+  ],
+  swift: [
+    { severity: "HIGH", category: "INSECURE_STORAGE", regex: /UserDefaults.*password|token|secret/, glob: "*.swift" },
+    { severity: "MEDIUM", category: "INSECURE_HTTP", regex: /"http:\/\//, glob: "*.swift" },
+    { severity: "HIGH", category: "WEAK_KEYCHAIN", regex: /kSecAttrAccessibleAlways/, glob: "*.swift" },
+  ],
+};
+
+/** Return the scan patterns for a language ("" / go / rust / unknown → none). */
+export function getPatterns(lang: string): ScanPattern[] {
+  return PATTERNS[lang] ?? [];
+}

package/src/runtime/lifecycle/security/scan.ts

@@ -0,0 +1,76 @@
+/**
+ * @module security/scan
+ * OWASP vulnerability scanner. Ports the Python `security-scan.py`: detect the
+ * project language, walk source files (excluding vendored/build dirs), match the
+ * per-language {@link getPatterns} rules, and aggregate a JSON report. Invoked by
+ * the `harness scan` CLI command (skill `/fuse-security:scan`), NOT a hook.
+ * @packageDocumentation
+ */
+import { existsSync, readdirSync, readFileSync, type Dirent } from "node:fs";
+import { join } from "node:path";
+import { getPatterns, type ScanPattern, type Severity } from "./scan-patterns";
+
+const EXCLUDE_RE = /(^|\/)(node_modules|vendor|\.git|dist|build)(\/|$)/;
+const LANG_FILES: readonly (readonly [string, string])[] = [
+  ["package.json", "javascript"], ["composer.json", "php"], ["requirements.txt", "python"],
+  ["pyproject.toml", "python"], ["Package.swift", "swift"], ["go.mod", "go"], ["Cargo.toml", "rust"],
+];
+
+/** A single vulnerability match in the scanned tree. */
+export interface Finding {
+  severity: Severity; category: string; pattern: string; file: string; line: number;
+}
+
+/** The full scan report (mirrors the Python JSON shape). */
+export interface ScanReport {
+  language: string; directory: string;
+  summary: Record<string, number>; findings: Finding[];
+}
+
+/** Detect the project language from its config files (first match wins). */
+export function detectLanguage(dir: string): string {
+  for (const [file, lang] of LANG_FILES) if (existsSync(join(dir, file))) return lang;
+  return "unknown";
+}
+
+/** Recursively collect files whose name ends with `ext`, skipping vendored dirs. */
+function collectFiles(dir: string, ext: string, out: string[] = []): string[] {
+  let entries: Dirent[];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (EXCLUDE_RE.test(full)) continue;
+    if (e.isDirectory()) collectFiles(full, ext, out);
+    else if (e.name.endsWith(ext)) out.push(full);
+  }
+  return out;
+}
+
+/** Apply one pattern to every matching file and collect line-level findings. */
+function scanPattern(dir: string, p: ScanPattern): Finding[] {
+  const ext = p.glob.replace(/^\*/, "");
+  const findings: Finding[] = [];
+  for (const file of collectFiles(dir, ext)) {
+    let text: string;
+    try { text = readFileSync(file, "utf8"); } catch { continue; }
+    text.split("\n").forEach((line, i) => {
+      if (p.regex.test(line)) findings.push({ severity: p.severity, category: p.category, pattern: p.regex.source, file, line: i + 1 });
+    });
+  }
+  return findings;
+}
+
+/** Run the OWASP scan over `dir` and return the aggregated {@link ScanReport}. */
+export function runSecurityScan(dir: string): ScanReport {
+  const language = detectLanguage(dir);
+  const counts: Record<string, number> = { critical: 0, high: 0, medium: 0, low: 0 };
+  const findings: Finding[] = [];
+  for (const p of getPatterns(language)) {
+    const hits = scanPattern(dir, p);
+    findings.push(...hits);
+    const key = p.severity.toLowerCase();
+    counts[key] = (counts[key] ?? 0) + hits.length;
+  }
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+  return { language, directory: dir, summary: { ...counts, total }, findings };
+}

package/src/runtime/lifecycle/security/skill-state.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared security-tracker state: per-UTC-day JSON under
+ * `~/.claude/logs/00-security`. Ports the state helpers of
+ * `check-security-skill.py` / `track-skill-read.py` / `track-mcp-research.py`.
+ */
+import { existsSync, 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-security` state directory. */
+export function securityStateDir(home: string = homedir()): string {
+  return join(claudeHome(home), "logs", "00-security");
+}
+
+/** Current UTC date as `YYYY-MM-DD`. */
+export function todayUtc(now: number = Date.now()): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+/** Current UTC instant as `YYYY-MM-DDTHH:MM:SSZ` (seconds, no millis). */
+export function isoUtc(now: number = Date.now()): string {
+  return new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** Today's security-state file path. */
+export function securityStatePath(now: number = Date.now(), home: string = homedir()): string {
+  return join(securityStateDir(home), `${todayUtc(now)}-state.json`);
+}
+
+/** Load today's security state, or `{}` when missing/corrupt. */
+export function loadSecurityState(now: number = Date.now(), home: string = homedir()): Record<string, unknown> {
+  const path = securityStatePath(now, home);
+  try {
+    if (!existsSync(path)) return {};
+    const data: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return typeof data === "object" && data !== null && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Persist today's security state (indent 2, no trailing newline). */
+export function saveSecurityState(state: Record<string, unknown>, now: number = Date.now(), home: string = homedir()): void {
+  atomicWrite(securityStatePath(now, home), JSON.stringify(state, null, 2));
+}

package/src/runtime/lifecycle/security/track-mcp.ts

@@ -0,0 +1,29 @@
+/**
+ * Security MCP-research tracker (PostToolUse context7/exa). Ports
+ * `track-mcp-research.py`: logs documentation queries to today's state.
+ */
+import { homedir } from "node:os";
+import { isoUtc, loadSecurityState, saveSecurityState } from "./skill-state";
+
+/** A recorded MCP research call. */
+interface ResearchEntry {
+  timestamp: string;
+  tool: string;
+  query: string;
+}
+
+/**
+ * Append a context7/exa research call to today's security state. No-op for other
+ * tools. No stdout.
+ * @param tool - The tool name.
+ * @param input - The tool input (query/libraryId/libraryName).
+ * @param now - Clock.
+ * @param home - Home dir.
+ */
+export function trackMcpResearch(tool: string, input: Record<string, unknown>, now: number = Date.now(), home: string = homedir()): void {
+  if (!tool.includes("context7") && !tool.includes("exa")) return;
+  const query = String(input.query ?? input.libraryId ?? input.libraryName ?? "");
+  const state = loadSecurityState(now, home) as { skill_read?: boolean; reads?: unknown[]; research?: ResearchEntry[] };
+  (state.research ??= []).push({ timestamp: isoUtc(now), tool, query });
+  saveSecurityState(state, now, home);
+}

package/src/runtime/lifecycle/security/track-skill-read.ts

@@ -0,0 +1,31 @@
+/**
+ * Security skill-read tracker (PostToolUse Read). Ports `track-skill-read.py`:
+ * flips `skill_read` once a security skill reference is read.
+ */
+import { homedir } from "node:os";
+import { isoUtc, loadSecurityState, saveSecurityState } from "./skill-state";
+
+const SKILL_RE = /skills\/(security-scan|cve-research|dependency-audit|security-headers|auth-audit)\//;
+
+/** A recorded skill-reference read. */
+interface SkillReadEntry {
+  timestamp: string;
+  file: string;
+}
+
+/**
+ * Mark the security skill as read when a Read hits a security skill reference.
+ * No-op for other tools/paths. No stdout.
+ * @param tool - The tool name.
+ * @param filePath - The read file path.
+ * @param now - Clock.
+ * @param home - Home dir.
+ */
+export function trackSkillRead(tool: string, filePath: string, now: number = Date.now(), home: string = homedir()): void {
+  if (tool !== "Read") return;
+  if (!SKILL_RE.test(filePath)) return;
+  const state = loadSecurityState(now, home) as { skill_read?: boolean; reads?: SkillReadEntry[] };
+  state.skill_read = true;
+  (state.reads ??= []).push({ timestamp: isoUtc(now), file: filePath });
+  saveSecurityState(state, now, home);
+}

package/src/runtime/lifecycle/seo/post-tool-use.ts

@@ -0,0 +1,45 @@
+/**
+ * SEO PostToolUse handler (fs effects). Ports `seo/hooks/validate-seo.ts`: on an
+ * edited HTML-like file under a `.fuse-seo` marker, deny when SEO elements are
+ * missing. Opt-in only — silent when no marker / non-HTML / file unreadable.
+ */
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { isHtmlLike, missingSeoElements } from "../../../policy/seo/validate";
+import { blockResponse } from "../../../adapters/claude";
+import { walkUpFor } from "../../../util/project-root";
+
+/**
+ * Validate the edited file's SEO completeness. Returns a block message (for a
+ * top-level `decision: block` response) when HTML-like, opted-in, and missing
+ * elements; otherwise `null` (allow).
+ * @param payload - The raw PostToolUse payload.
+ * @returns The block reason string, or `null` to allow.
+ */
+export function seoPostToolUse(payload: Record<string, unknown>): string | null {
+  const input = payload.tool_input as { file_path?: string } | undefined;
+  const path = input?.file_path;
+  if (!path || !isHtmlLike(path)) return null;
+  const cwd = typeof payload.cwd === "string" ? payload.cwd : dirname(path);
+  if (!walkUpFor(cwd, ".fuse-seo")) return null;
+  try {
+    const missing = missingSeoElements(readFileSync(path, "utf-8"));
+    if (missing.length === 0) return null;
+    return `fuse-seo: missing SEO elements in ${path}:\n  - ${missing.join("\n  - ")}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * SEO PostToolUse as a ready native response: a top-level `decision: block`
+ * string when the edited file is missing SEO elements, else `null` (allow).
+ * PostToolUse ignores `permissionDecision` (PreToolUse-only), so this must use
+ * the `decision`/`reason` keys to actually feed the failure back to Claude.
+ * @param payload - The raw PostToolUse payload.
+ * @returns The block response string, or `null` to allow.
+ */
+export function seoPostToolUseResponse(payload: Record<string, unknown>): string | null {
+  const block = seoPostToolUse(payload);
+  return block ? blockResponse(block) : null;
+}

package/src/runtime/lifecycle/session-end.ts

@@ -0,0 +1,17 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fusengineCache } from "../home-state";
+import { removeOldFiles } from "../fs-cleanup";
+
+/**
+ * Handle SessionEnd: remove stale `*.tmp` (>1h) under `session-tmp/` and stale
+ * legacy `claude_solid_reads_*` / `claude_session_changes_*` files (>2h) under
+ * `cache`. Ports `session-end/cleanup-session.py`. No stdout.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ */
+export function cleanupSession(home: string = homedir(), now: number = Date.now()): void {
+  const base = fusengineCache(home);
+  removeOldFiles(join(base, "session-tmp"), (n) => n.endsWith(".tmp"), 3600, now);
+  removeOldFiles(base, (n) => n.startsWith("claude_solid_reads_") || n.startsWith("claude_session_changes_"), 7200, now);
+}

package/src/runtime/lifecycle/session-start.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { attachSystemMessage, contextResponse } from "../../adapters/claude";
+import { claudeHome, fusengineCache, sessionsDir } from "../home-state";
+import { devContext } from "../dev-context";
+import { pruneEmptyDirs, purgeTtlTree, removeOldFiles, trimLogFile } from "../fs-cleanup";
+import { apexDocName, harnessHomeSegment } from "../../policy/apex-target";
+
+/** TTLs (seconds) for purgeable cache subtrees (cleanup-old-caches.py). */
+const PURGEABLE: Record<string, number> = { sessions: 48 * 3600, webfetch: 24 * 3600, doc: 48 * 3600, explore: 48 * 3600 };
+
+/**
+ * Read the target's root instructions doc (`~/.claude/CLAUDE.md`,
+ * `~/.codex/AGENTS.md`, `~/.kimi-code/AGENTS.md`, ...), or "" when
+ * missing/unreadable.
+ * @param home - Home dir.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ */
+function claudeMd(home: string, id: string = "claude-code"): string {
+  const path = join(home, harnessHomeSegment(id), apexDocName(id));
+  try {
+    return existsSync(path) ? readFileSync(path, "utf-8") : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Run the legacy SessionStart cleanups (stale states, caches, log trim). */
+export function runSessionStartCleanups(home: string = homedir(), now: number = Date.now()): void {
+  const base = fusengineCache(home);
+  removeOldFiles(sessionsDir(home), (n) => n.startsWith("session-") && n.endsWith(".json"), 86400, now);
+  const user = process.env.USER ?? "unknown";
+  removeOldFiles(base, (n) => n === `changes-${user}.json`, 21600, now);
+  trimLogFile(join(claudeHome(home), "logs", "hooks.log"), 10485760, 5000);
+  removeOldFiles(join(claudeHome(home), "logs", "00-apex"), (n) => n.startsWith("ref-cache-") && n.endsWith(".json"), 86400, now);
+  purgeTtlTree(base, PURGEABLE, now);
+  pruneEmptyDirs(base, Object.keys(PURGEABLE));
+}
+
+/**
+ * Handle core-guards SessionStart: inject CLAUDE.md + dev context as
+ * `additionalContext`, then run the cache/state cleanups. Ports the four
+ * `session-start/*.py` scripts into one harness call.
+ * @param cwd - Project root for dev-context detection.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock for TTL cleanup (defaults to `Date.now()`).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function sessionStartCore(cwd: string, home: string = homedir(), now: number = Date.now(), id: string = "claude-code"): string {
+  const md = claudeMd(home, id);
+  const dev = devContext(cwd);
+  runSessionStartCleanups(home, now);
+  const ctx = [md, dev].filter(Boolean).join("\n");
+  return ctx ? attachSystemMessage(contextResponse("SessionStart", ctx), `${apexDocName(id)} injected`) : "";
+}

package/src/runtime/lifecycle/snapshot/board.ts

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Max board characters injected — a persistent board should stay small; over-long boards are truncated. */
+const MAX_BOARD = 4000;
+
+/**
+ * Collect the persistent task board: the contents of `<root>/.claude/BOARD.md`
+ * (truncated to {@link MAX_BOARD}) plus an instruction to keep it current. The
+ * board lives on disk so it survives context purges — rehydrated every session.
+ * Missing/empty/unreadable board → `""` (section omitted).
+ * @param root - The project root.
+ * @returns The rendered board section body, or `""` when there is no board.
+ */
+export function collectBoard(root: string): string {
+  const path = join(root, ".claude", "BOARD.md");
+  try {
+    if (!existsSync(path)) return "";
+    let body = readFileSync(path, "utf8").trim();
+    if (!body) return "";
+    if (body.length > MAX_BOARD) body = `${body.slice(0, MAX_BOARD)}\n… (truncated)`;
+    const note = "- .claude/BOARD.md (keep current — Write to it as tasks start/finish):";
+    return `${note}\n\n${body}`;
+  } catch {
+    return "";
+  }
+}

package/src/runtime/lifecycle/snapshot/format.ts

@@ -0,0 +1,60 @@
+import { contextResponse } from "../../../adapters/claude";
+import { capFragment, budgetReport } from "../../inject-budget";
+
+/** A titled snapshot section — dropped from the render when its `body` is empty. */
+export interface Section {
+  title: string;
+  body: string;
+}
+
+/**
+ * Render the non-empty `sections` under one reconciliation heading. Empty
+ * sections are dropped; when every section is empty the whole snapshot is `""`.
+ * Each surviving section is passed through {@link capFragment} (harness-produced
+ * content, not owner CLAUDE.md), and a trailing {@link budgetReport} line gives
+ * the owner-requested numeric visibility into what was actually injected.
+ * @param sections - The collected sections in display order.
+ * @returns The assembled markdown block, or `""` when nothing to report.
+ */
+export function renderSections(sections: Section[]): string {
+  const kept = sections
+    .filter((s) => s.body.trim())
+    .map((s) => ({ title: s.title, body: capFragment(s.title, s.body.trim()) }));
+  if (!kept.length) return "";
+  const header =
+    "# Reconciliation snapshot\nReal state of the world at session start — reconcile against this instead of re-discovering it.";
+  const parts = kept.map((s) => `### ${s.title}\n${s.body}`);
+  const report = budgetReport(kept.map((s) => ({ label: s.title, chars: s.body.length })));
+  return `${header}\n\n${parts.join("\n\n")}\n\n_${report}_`;
+}
+
+/**
+ * Concatenate `snapshot` onto an existing SessionStart stdout's
+ * `additionalContext` — it never replaces prior injected context (CLAUDE.md,
+ * dev-context). When `stdout` is empty a fresh {@link contextResponse} is made;
+ * a non-empty but unparseable `stdout` is returned UNCHANGED (the snapshot is
+ * dropped) — fabricating a fresh response there would discard the very CLAUDE.md
+ * injection the invariant protects, so preserving prior context always wins.
+ * @param stdout - The core SessionStart JSON stdout (may be `""`).
+ * @param snapshot - The snapshot markdown to append (no-op when `""`).
+ * @returns The merged hook stdout JSON.
+ */
+export function attachSnapshot(stdout: string, snapshot: string): string {
+  if (!snapshot) return stdout;
+  if (!stdout) return contextResponse("SessionStart", snapshot);
+  try {
+    const parsed = JSON.parse(stdout) as {
+      hookSpecificOutput?: { additionalContext?: string };
+    };
+    const prev = parsed.hookSpecificOutput?.additionalContext ?? "";
+    const merged = prev ? `${prev}\n\n${snapshot}` : snapshot;
+    return JSON.stringify({
+      ...parsed,
+      hookSpecificOutput: { ...parsed.hookSpecificOutput, hookEventName: "SessionStart", additionalContext: merged },
+    });
+  } catch {
+    // Unparseable non-empty stdout: keep it verbatim so prior injected context
+    // (CLAUDE.md) is never discarded — the snapshot is sacrificed, not the invariant.
+    return stdout;
+  }
+}