@fusengine/harness 0.1.89 → 0.1.91

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);
+}

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);
+}