@fusengine/harness 0.1.90 → 0.1.91

package/src/memory/registry.ts

@@ -0,0 +1,39 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Registry path relative to the home dir. */
+const SUBPATH = ".fuse-harness/cache/lessons/roots.json";
+
+/** Absolute path of the global roots registry, or null when home is unusable. */
+export function registryFile(home: string | undefined = process.env.HOME): string | null {
+  const h = home?.trim();
+  if (!h || !h.startsWith("/")) return null;
+  return `${h}/${SUBPATH}`;
+}
+
+/** Read the registered project roots (deduplicated string entries only). */
+export function readRoots(home?: string): string[] {
+  const file = registryFile(home);
+  if (!file) return [];
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+    return Array.isArray(parsed) ? parsed.filter((e): e is string => typeof e === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Register a project root once (deduplicated, read-modify-write, non-throwing). */
+export function addRoot(root: string, home?: string): void {
+  const file = registryFile(home);
+  if (!file) return;
+  try {
+    const roots = new Set(readRoots(home));
+    if (roots.has(root)) return;
+    roots.add(root);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify([...roots]));
+  } catch {
+    /* non-fatal: a missed root never blocks the session */
+  }
+}

package/src/memory/session-roots.ts

@@ -0,0 +1,99 @@
+/**
+ * Session-scoped lessons roots registry. The flat {@link module:memory/registry}
+ * keeps ONE global list of pending roots — correct mono-session, but wrong with
+ * several concurrent Claude Code sessions: at Stop, one session lists (and, by
+ * bumping the throttle, STEALS) another session's pending lesson on a project it
+ * never touched. This registry keys "which project got code edits, and was its
+ * Stop reminder already fired" by `session_id`, so each Stop sees and consumes
+ * ONLY its own roots. Stored at `$HOME/.fuse-harness/cache/lessons/session-roots.json`;
+ * non-fatal on any I/O failure (a missed reminder never blocks a session).
+ */
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWrite } from "../util/json-io";
+
+/** Per-(session, root) throttle: last code edit vs. last reminder emitted. */
+export interface RootMark {
+  editedAt: number;
+  remindedAt: number;
+}
+/** One session's edited roots plus an `updatedAt` purge cursor. */
+interface SessionEntry {
+  updatedAt: number;
+  roots: Record<string, RootMark>;
+}
+/** Whole registry keyed by sanitized `session_id`. */
+type Registry = Record<string, SessionEntry>;
+
+/** Registry path (rel. home) + stale-bucket purge horizon (bounds growth). */
+const SUBPATH = ".fuse-harness/cache/lessons/session-roots.json";
+const PURGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Absolute registry path, or null when home is unusable. */
+function file(home: string | undefined): string | null {
+  const h = home?.trim();
+  return h && h.startsWith("/") ? `${h}/${SUBPATH}` : null;
+}
+
+/** Read the registry; missing/corrupt/legacy (array) shapes collapse to `{}`. */
+function read(home: string | undefined): Registry {
+  const f = file(home);
+  if (!f) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(f, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Registry) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Purge stale buckets, then atomically persist (unique tmp + rename). Non-throwing. */
+function write(home: string | undefined, reg: Registry, now: number): void {
+  const f = file(home);
+  if (!f) return;
+  for (const [sid, entry] of Object.entries(reg)) {
+    if (!entry || now - (entry.updatedAt ?? 0) > PURGE_MS) delete reg[sid];
+  }
+  try {
+    mkdirSync(dirname(f), { recursive: true });
+    atomicWrite(f, JSON.stringify(reg));
+  } catch {
+    /* non-fatal: a missed root never blocks the session */
+  }
+}
+
+/** Record `field` for `(sid, root)`, refreshing the purge cursor. `home` defaults to `$HOME`. */
+export function markSessionRoot(
+  sid: string, root: string, field: keyof RootMark, value: number, home: string | undefined = process.env.HOME,
+): void {
+  const reg = read(home);
+  const prev = reg[sid];
+  const entry: SessionEntry = prev && typeof prev.roots === "object" && prev.roots !== null ? prev : { updatedAt: value, roots: {} };
+  const mark = entry.roots[root] ?? { editedAt: 0, remindedAt: 0 };
+  entry.roots[root] = { ...mark, [field]: value };
+  entry.updatedAt = value;
+  reg[sid] = entry;
+  write(home, reg, value);
+}
+
+/**
+ * Roots of `sid` with an unsaved code edit past the `window`; each returned
+ * root's `remindedAt` is bumped to `now` so the reminder fires at most once per
+ * window and is consumed ONLY by this session. `home` defaults to `$HOME`.
+ */
+export function collectSessionPending(
+  sid: string, now: number, window: number, home: string | undefined = process.env.HOME,
+): string[] {
+  const reg = read(home);
+  const entry = reg[sid];
+  if (!entry || typeof entry.roots !== "object" || entry.roots === null) return [];
+  const pending: string[] = [];
+  for (const [root, mark] of Object.entries(entry.roots)) {
+    if (mark.editedAt <= mark.remindedAt) continue;
+    if (now - mark.remindedAt < window) continue;
+    pending.push(root);
+    entry.roots[root] = { ...mark, remindedAt: now };
+  }
+  if (pending.length > 0) write(home, reg, now);
+  return pending;
+}

package/src/memory/state.ts

@@ -0,0 +1,58 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { projectLayout } from "../config/layout";
+import { ensureMemoryGitignore } from "./gitignore";
+
+/** Per-project reminder throttle state, stored at `<root>/MEMORY/state.json`. */
+export interface ReminderState {
+  lastRemindedAt: number;
+  lastCodeEditAt: number;
+}
+
+/** Absolute path of the per-project throttle state file. */
+export function stateFileFor(root: string): string {
+  return projectLayout(root).memoryStateFile;
+}
+
+/** Absolute path of the per-project curated lessons file (committable). */
+export function lessonsFileFor(root: string): string {
+  return projectLayout(root).lessonsFile;
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+/** Read both throttle timestamps; missing/corrupt fields default to 0. */
+export function readState(file: string): ReminderState {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial<ReminderState>;
+    return { lastRemindedAt: num(parsed?.lastRemindedAt), lastCodeEditAt: num(parsed?.lastCodeEditAt) };
+  } catch {
+    return { lastRemindedAt: 0, lastCodeEditAt: 0 };
+  }
+}
+
+/** Persist one field without clobbering the other (read-modify-write). */
+export function setStateField(file: string, key: keyof ReminderState, value: number): void {
+  const next: ReminderState = { ...readState(file), [key]: value };
+  const dir = dirname(file);
+  mkdirSync(dir, { recursive: true });
+  ensureMemoryGitignore(dir);
+  atomicWrite(file, JSON.stringify(next));
+}
+
+/** Local wall-clock timestamp for a lesson bullet: `YYYY-MM-DD HH:MM`. */
+export function nowStamp(): string {
+  const d = new Date();
+  const p = (n: number): string => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** Throttle window (ms) from `FUSE_LESSONS_THROTTLE_MIN` (default 5 min). */
+export function throttleMs(env: Record<string, string | undefined> = process.env): number {
+  const raw = env.FUSE_LESSONS_THROTTLE_MIN?.trim();
+  const min = raw ? Number(raw) : 5;
+  return (Number.isFinite(min) ? Math.max(0, min) : 5) * 60_000;
+}

package/src/policy/apex-authorization.ts

@@ -0,0 +1,100 @@
+import { resolveSessions, type AuthEntry } from "../freshness/doc-helpers";
+import { routeReferences } from "../refs/router";
+import { DEFAULT_TTL_SEC, ttlLabel } from "../config/ttl";
+import { CONTEXT7_SOURCE, getSkillSource } from "./skill-source";
+import type { ApexContext, ApexGate } from "./apex";
+
+/** Pending doc-credit target written on a Check-1 deny (parity enforce-apex-phases.ts:80 `state.target`). */
+export interface SessionTarget {
+  project: string;
+  framework: string;
+  set_by: string;
+  set_at: string;
+}
+
+/**
+ * Credit a doc consultation onto one framework's auth entry (parity
+ * track-doc-consultation.py): the once-per-session Check-2 fields
+ * (`doc_sessions` + `sources`) plus the per-framework Check-1 stamp
+ * (`sessions` + `doc_consulted`). Pure.
+ */
+export function creditDocConsultation(prev: AuthEntry | undefined, sessionId: string, source: string, nowIso: string): AuthEntry {
+  const p = prev ?? {};
+  const add = (list: string[], v: string): string[] => (v && !list.includes(v) ? [...list, v] : list);
+  return {
+    ...p,
+    sessions: add(resolveSessions(p), sessionId),
+    doc_sessions: add(p.doc_sessions ?? [], sessionId),
+    sources: add(p.sources ?? (p.source ? [p.source] : []), source),
+    doc_consulted: nowIso,
+  };
+}
+
+/**
+ * Check 1 (parity enforce-apex-phases.ts isAuthorized): the framework's doc or
+ * skill was consulted in THIS session (resolveSessions) AND the stamp is
+ * younger than the TTL (FUSE_ENFORCE_TTL_SEC via src/config/ttl.ts).
+ */
+export function isAuthorized(auth: AuthEntry | undefined, sessionId: string, now: number, ttlMs: number): boolean {
+  if (!auth?.doc_consulted || !resolveSessions(auth).includes(sessionId)) return false;
+  const readEpoch = Date.parse(auth.doc_consulted);
+  return !Number.isNaN(readEpoch) && now - readEpoch < ttlMs;
+}
+
+/**
+ * A fresh same-session `skills/**.md` read whose path names the framework also
+ * satisfies Check 1 (parity track-doc-consultation.py, which stamps
+ * `doc_consulted` on `skills/.*\.md` Reads; the harness records those Reads in
+ * `refsRead`/`refsReadAt` instead, and the track file is per-session).
+ */
+function skillReadAuthorized(ctx: ApexContext, now: number, ttlMs: number): boolean {
+  // Aliases keep every deny-promised path unblockable: laravel skills say "php",
+  // and tailwind's SKILL.md lives under "tailwindcss[-v4]" where \btailwind\b
+  // never matches (the boundary fails before the "c").
+  const alias: Record<string, string> = { laravel: "laravel|php", tailwind: "tailwindcss?" };
+  const nameRe = new RegExp(`\\b(${alias[ctx.framework] ?? ctx.framework})\\b`, "i");
+  return (ctx.refsRead ?? []).some((p) => {
+    if (!/skills\/.*\.md$/i.test(p) || !nameRe.test(p)) return false;
+    const at = ctx.refsReadAt?.[p];
+    return at !== undefined && now - at < ttlMs;
+  });
+}
+
+/**
+ * Gate (Check 1): deny until the framework's doc/skill is freshly consulted.
+ * The deny lists the routed SOLID refs when refs are loaded (parity
+ * formatRoutedDeny), else the framework's skill source (parity getSkillSource:
+ * a real installed SKILL.md path, or the context7 consigne). The RUNTIME
+ * caller persists `state.target` on deny (recordTarget, parity :80-81) so
+ * recordDoc can cross-credit this framework on the next doc consultation.
+ */
+export const apexAuthorizationGate: ApexGate = (ctx) => {
+  const windowMs = ctx.windowMs ?? DEFAULT_TTL_SEC * 1000;
+  const now = ctx.now ?? Date.now();
+  if (isAuthorized(ctx.authorizations?.[ctx.framework], ctx.sessionId, now, windowMs)) return null;
+  if (skillReadAuthorized(ctx, now, windowMs)) return null;
+  const ttl = ttlLabel(Math.round(windowMs / 1000));
+  const title = `APEX: ${ctx.framework} documentation required`;
+  const routed = ctx.refs?.length ? routeReferences(ctx.refs, ctx.filePath, ctx.content) : null;
+  if (!routed) {
+    // Parity enforce-apex-phases.ts:82-87: getSkillSource (skill-source.ts)
+    // resolves the REAL installed SKILL.md, or yields the context7 consigne —
+    // never SOLID_REF's phantom `${PLUGINS_DIR}/generic/SKILL.md`.
+    const src = getSkillSource(ctx.framework);
+    return {
+      kind: "block",
+      title,
+      reason: `APEX: Read doc first (expires every ${ttl}) for ${ctx.framework}! Source: ${src}`,
+      actions: [src === CONTEXT7_SOURCE ? `Query ${CONTEXT7_SOURCE} for ${ctx.framework} docs` : `Read ${src}`],
+    };
+  }
+  const optional = routed.optional.map((r) => r.meta.filePath);
+  const reason = [
+    // H2b: name the full set (required + Optional) and invite the retry.
+    `APEX: Read ALL SOLID references below (including Optional), then retry (expires every ${ttl}) for ${ctx.framework}.`,
+    `Editing: ${ctx.filePath}`,
+    ...(optional.length ? [`Optional: ${optional.join(", ")}`] : []),
+    `Full skill: ${routed.skillPath}`,
+  ].join("\n");
+  return { kind: "block", title, reason, actions: routed.required.map((r) => r.meta.filePath) };
+};

package/src/policy/apex-gates.ts

@@ -0,0 +1,91 @@
+import { routeReferences } from "../refs/router";
+import { skillRefKey } from "../refs/ref-key";
+import type { Prompt } from "../prompt/types";
+import { DEFAULT_TTL_SEC, ttlLabel } from "../config/ttl";
+import { PLUGINS_DIR, SOLID_REF } from "./file-size";
+import type { ApexContext, ApexGate } from "./apex";
+
+/**
+ * True when the SOLID ref read at `path` still counts. Parity require-solid-read.py
+ * `_check_solid_read` (FUSE_ENFORCE_TTL_SEC, default 120s): a SOLID read older than
+ * the window has expired and must be redone. PARITY NOTE: the TTL applies ONLY to
+ * this gate — Python TTL-izes SOLID reads exclusively; the other refsRead consumers
+ * (skillTriggerGate, shadcn/tailwind/design gates) stay session-scoped, so this
+ * predicate must never leak into them. Backward compat: a path with no `refsReadAt`
+ * stamp (tracks recorded before the field existed) or a context without a clock
+ * (`now` absent) counts as read.
+ */
+function refReadFresh(ctx: ApexContext, path: string, windowMs: number): boolean {
+  const at = ctx.refsReadAt?.[path];
+  return at === undefined || ctx.now === undefined || ctx.now - at < windowMs;
+}
+
+/** Gate: the routed SOLID references for this edit must have been read within the TTL. */
+export const solidReadGate: ApexGate = (ctx: ApexContext) => {
+  if (!ctx.refs?.length) return null;
+  const routed = routeReferences(ctx.refs, ctx.filePath, ctx.content);
+  const windowMs = ctx.windowMs ?? DEFAULT_TTL_SEC * 1000;
+  const ttl = ttlLabel(Math.round(windowMs / 1000));
+  if (!routed) {
+    // Parity require-solid-read.py::_build_reason (the `not routed` branch):
+    // refs ARE loaded but none score for this file — Python still denies here,
+    // pointing at the framework's SKILL.md. Note: `!ctx.refs?.length` above
+    // (no refs installed at all) intentionally stays allow — discoverRefs()'s
+    // documented contract ("with no refs the SOLID-read gate stays off").
+    const ref = SOLID_REF[ctx.framework] ?? "generic/";
+    return {
+      kind: "block",
+      title: `APEX: no SOLID reference matched ${ctx.filePath}`,
+      reason: `${ctx.refs.length} SOLID reference(s) are loaded but none scored for this edit (expires every ${ttl}) — read the framework skill directly instead.`,
+      actions: [`Read ${PLUGINS_DIR}/${ref}SKILL.md`],
+    };
+  }
+  // Only reads still inside the TTL window count — a stale read re-blocks
+  // (parity require-solid-read.py, which re-validates the TTL on EVERY edit,
+  // making the "(expires every …)" wording below actually true).
+  const read = new Set((ctx.refsRead ?? []).filter((p) => refReadFresh(ctx, p, windowMs)));
+  // A sub-agent/teammate reads the SAME skill material through a different
+  // root than the marketplace-first path discoverRefs put in ctx.refs (a
+  // version cache, or a standalone .codex/.cursor/.agents dir) — normalize
+  // both sides to the `skills/<skill>/...` suffix so that read still credits.
+  const readKeys = new Set([...read].map(skillRefKey).filter((k): k is string => k !== null));
+  const credited = (path: string): boolean => {
+    if (read.has(path)) return true;
+    const key = skillRefKey(path);
+    return key !== null && readKeys.has(key);
+  };
+  // Parity with the 3 other refsRead-consuming gates (skillTriggerGate's
+  // `skills/${s}/` substring match, shadcnBaseSkillRead, designSkillRead):
+  // reading the ref's PARENT SKILL.md counts as proof of consultation too,
+  // not just the exact ref file path.
+  const skillRead = !!routed.skillPath && credited(routed.skillPath);
+  const missing = skillRead ? [] : routed.required.map((r) => r.meta.filePath).filter((p) => !credited(p));
+  if (missing.length === 0) return null;
+  const optional = routed.optional.map((r) => r.meta.filePath);
+  const reason = [
+    // H2b: the credit needs the routed refs read — say ALL of them (the
+    // Optional line counts too) and that a retry is EXPECTED once read.
+    `Read ALL references below (including Optional), then retry — required before editing ${ctx.filePath} (expires every ${ttl}):`,
+    ...(optional.length ? [`Optional: ${optional.join(", ")}`] : []),
+    `Full skill: ${routed.skillPath}`,
+  ].join("\n");
+  return {
+    kind: "block",
+    title: `APEX: read SOLID references for ${ctx.framework}`,
+    reason,
+    actions: missing,
+  };
+};
+
+/** Gate: the required prior agents (explore + research) must have run within the window. */
+export const freshnessGate: ApexGate = (ctx: ApexContext): Prompt | null => {
+  if (ctx.agentsFresh !== false) return null;
+  const missing = ctx.missingAgents?.length ? ctx.missingAgents : ["explore-codebase", "research-expert"];
+  const ttl = ttlLabel(Math.round((ctx.windowMs ?? DEFAULT_TTL_SEC * 1000) / 1000));
+  return {
+    kind: "block",
+    title: "APEX: explore + research required",
+    reason: `Run ${missing.join(" and ")} within the freshness window (${ttl} TTL) before editing ${ctx.framework}.`,
+    actions: missing.map((name) => `Launch the ${name} agent`),
+  };
+};

package/src/policy/apex-target-steps.ts

@@ -0,0 +1,73 @@
+/**
+ * Per-target phrasing tables for the APEX task-tracking step trio/pair
+ * (view-pending / mark-in-progress / mark-done) — split out of
+ * `apex-target.ts` to keep both files under the SOLID 100-line ceiling.
+ * Kimi Code CLI's native tool is `TodoList` (single tool, full-list re-emit
+ * per call; status enum is `pending | in_progress | done` — never
+ * `completed`, that is Claude's idiom; omitting `todos` queries the current
+ * list without mutating it). Kimi has no documented auto-commit tied to a
+ * status transition, unlike Claude's `TaskUpdate(completed)` — so these
+ * phrasings must NOT promise one. `TaskList` is a distinct Kimi tool for
+ * async background tasks and must never be used here.
+ */
+import type { HarnessId } from "../detect/interfaces/types";
+import type { ApexTaskSteps, ApexAgentSteps } from "./interfaces/types";
+
+/** Codex/Kimi step-trio overrides; any other target falls back to {@link DEFAULT_TASK_STEPS}. */
+const TASK_STEPS: Partial<Record<HarnessId, ApexTaskSteps>> = {
+  codex: {
+    step3: "update_plan → review the current plan",
+    step4: "update_plan → mark the active step in_progress before starting",
+    step7: "update_plan → mark the step completed when done",
+  },
+  kimi: {
+    step3: "TodoList → review the current list (omit todos to query)",
+    step4: "TodoList → mark the active item in_progress before starting",
+    step7: "TodoList → mark the item done when finished",
+  },
+};
+
+/** Default (Claude Code) step trio — zero-regression fallback for any unlisted target. */
+const DEFAULT_TASK_STEPS: ApexTaskSteps = {
+  step3: "TaskList → see pending tasks",
+  step4: "TaskUpdate(in_progress) → before starting",
+  step7: "TaskUpdate(completed) → triggers auto-commit",
+};
+
+/**
+ * Resolve the step3/step4/step7 phrasing for a harness target (APEX
+ * task-context injection). Replaces the former `isCodex` binary ternary.
+ * @param id - Harness id.
+ * @returns The {@link ApexTaskSteps} for that target.
+ */
+export function apexTaskSteps(id: string): ApexTaskSteps {
+  return TASK_STEPS[id as HarnessId] ?? DEFAULT_TASK_STEPS;
+}
+
+/** Codex/Kimi before/done overrides; any other target falls back to {@link DEFAULT_AGENT_STEPS}. */
+const AGENT_STEPS: Partial<Record<HarnessId, ApexAgentSteps>> = {
+  codex: {
+    beforeStart: "Use update_plan → mark the active step in_progress before starting",
+    whenDone: "update_plan → mark the step completed when done",
+  },
+  kimi: {
+    beforeStart: "Use TodoList → mark the active item in_progress before starting",
+    whenDone: "TodoList → mark the item done when finished",
+  },
+};
+
+/** Default (Claude Code) before/done pair — zero-regression fallback for any unlisted target. */
+const DEFAULT_AGENT_STEPS: ApexAgentSteps = {
+  beforeStart: "Use TaskUpdate(taskId, status: in_progress) before starting",
+  whenDone: "TaskUpdate(taskId, status: completed) triggers auto-commit",
+};
+
+/**
+ * Resolve the beforeStart/whenDone phrasing for a harness target (APEX
+ * sub-agent injection). Replaces the former `isCodex` binary ternary.
+ * @param id - Harness id.
+ * @returns The {@link ApexAgentSteps} for that target.
+ */
+export function apexAgentSteps(id: string): ApexAgentSteps {
+  return AGENT_STEPS[id as HarnessId] ?? DEFAULT_AGENT_STEPS;
+}

package/src/policy/apex-target.ts

@@ -0,0 +1,49 @@
+/**
+ * Harness-target helpers for the APEX context builders. Single source of
+ * truth for the home-dir segment / root doc name / plan-tool idiom that
+ * differ between Claude Code and Codex (and beyond), so the builders in
+ * `claude-md-context.ts`, `apex-task-context.ts`, and `inject-apex.ts` never
+ * hardcode `.claude`/`CLAUDE.md`/`TaskCreate` again. Runtime `id` values flow
+ * through the pipeline as plain `string` (see `handleHook(id: string, ...)`),
+ * so these helpers accept `string` and narrow internally — same idiom as the
+ * existing `HOME_DIR[id] ?? ".claude"` precedent in `cartographer/detect.ts`.
+ */
+import { HOME_DIR } from "../config/dotenv";
+import type { HarnessId } from "../detect/interfaces/types";
+
+/**
+ * Home-dir segment for a harness target (".claude", ".codex", ...). Falls
+ * back to ".claude" for any harness without a {@link HOME_DIR} entry.
+ * @param id - Harness id (e.g. "claude-code", "codex").
+ * @returns The home-dir segment, e.g. ".claude".
+ */
+export function harnessHomeSegment(id: string): string {
+  return HOME_DIR[id as HarnessId] ?? ".claude";
+}
+
+/**
+ * Root instructions doc name for a harness target: "AGENTS.md" for Codex and
+ * Kimi Code CLI (both documented conventions), "CLAUDE.md" for every other
+ * target (including the default/unknown fallback).
+ * @param id - Harness id.
+ * @returns The doc file name.
+ */
+export function apexDocName(id: string): string {
+  return id === "codex" || id === "kimi" ? "AGENTS.md" : "CLAUDE.md";
+}
+
+/**
+ * Native plan/track tool name for a harness target: Codex's `update_plan`,
+ * Kimi Code CLI's `TodoList`, or Claude's `TaskCreate` (default). Covers only
+ * the PLAN-step line — other target-specific tool references (`TaskList`,
+ * `TaskUpdate`) are resolved via `apexTaskSteps`/`apexAgentSteps` in
+ * `apex-target-steps.ts` since their surrounding prose differs structurally,
+ * not just by token.
+ * @param id - Harness id.
+ * @returns The plan-tool name.
+ */
+export function apexPlanTool(id: string): string {
+  if (id === "codex") return "update_plan";
+  if (id === "kimi") return "TodoList";
+  return "TaskCreate";
+}

package/src/policy/apex-task-context.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveMaxLines } from "../config/limits";
+import { harnessHomeSegment } from "./apex-target";
+import { apexTaskSteps } from "./apex-target-steps";
+
+/** Parsed task state injected into a Task sub-agent prompt. */
+export interface ApexTaskState {
+  /** Current task id (defaults to "1"). */
+  id: string;
+  /** Task subject (defaults to ""). */
+  subject: string;
+  /** Current phase (defaults to "analyze"). */
+  phase: string;
+  /** Comma-joined consulted doc keys, or "none". */
+  docs: string;
+}
+
+/**
+ * Read the current task state from `task.json`, reproducing the legacy Python
+ * logic. Any read/parse error falls back to `("1", "", "analyze", "none")`.
+ * @param taskFile - Absolute path to `.claude/apex/task.json`.
+ * @returns The parsed {@link ApexTaskState}.
+ */
+export function loadApexTaskState(taskFile: string): ApexTaskState {
+  try {
+    const data = JSON.parse(readFileSync(taskFile, "utf-8")) as Record<string, unknown>;
+    const id = String(data.current_task ?? "1");
+    const tasks = (data.tasks as Record<string, unknown> | undefined) ?? {};
+    const task = (tasks[id] as Record<string, unknown> | undefined) ?? {};
+    const subject = typeof task.subject === "string" ? task.subject : "";
+    const phase = typeof task.phase === "string" ? task.phase : "analyze";
+    const consultedMap = (task.doc_consulted as Record<string, unknown> | undefined) ?? {};
+    const consulted = Object.entries(consultedMap)
+      .filter(([, v]) => typeof v === "object" && v !== null && (v as Record<string, unknown>).consulted === true)
+      .map(([k]) => k);
+    return { id, subject, phase, docs: consulted.join(", ") || "none" };
+  } catch {
+    return { id: "1", subject: "", phase: "analyze", docs: "none" };
+  }
+}
+
+/**
+ * Build the APEX context string injected into a Task sub-agent prompt.
+ * @param state - The parsed task state.
+ * @param maxLines - SOLID per-file line ceiling.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The injection text.
+ */
+export function buildApexTaskContext(state: ApexTaskState, maxLines: number, id: string = "claude-code"): string {
+  const seg = harnessHomeSegment(id);
+  const { step3, step4, step7 } = apexTaskSteps(id);
+  return (
+    `⚠️ APEX MODE - Read ${seg}/apex/AGENTS.md for rules\n\n` +
+    `Current: Task #${state.id} - ${state.subject} (Phase: ${state.phase})\n` +
+    `Docs consulted: ${state.docs}\n\n` +
+    `Agent must:\n` +
+    `1. Read task.json → find last 3 completed tasks\n` +
+    `2. Read their notes in docs/ (task-{ID}-{subject}.md)\n` +
+    `3. ${step3}\n` +
+    `4. ${step4}\n` +
+    `5. Apply SOLID (files < ${maxLines} lines)\n` +
+    `6. Write notes to docs/task-{ID}-{subject}.md\n` +
+    `7. ${step7}`
+  );
+}
+
+/**
+ * Build the PreToolUse Task injection, gated on the existence of the
+ * project's target apex dir (`.claude/apex/`, `.codex/apex/`, ...). Returns
+ * `null` when APEX is not active (no dir).
+ * @param projectRoot - `CLAUDE_PROJECT_DIR` or cwd.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The injection text, or `null` to emit nothing.
+ */
+export function buildApexTaskInjection(projectRoot: string, id: string = "claude-code"): string | null {
+  const apexDir = join(projectRoot, harnessHomeSegment(id), "apex");
+  if (!existsSync(apexDir)) return null;
+  const state = loadApexTaskState(join(apexDir, "task.json"));
+  return buildApexTaskContext(state, resolveMaxLines(), id);
+}