akm-cli 0.9.25-alpha.2 → 0.9.25-alpha.3

package/dist/commands/improve/session-asset.js

@@ -99,6 +99,12 @@ export function buildSessionAccessInstructions(harness, logPath, sessionId) {
             `Parse messages: jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ${logPath}`,
         ].join("\n");
     }
+    if (harness === "codex") {
+        return [
+            `Read with: cat ${logPath}`,
+            `Parse messages: jq -r 'select(.type=="response_item" and .payload.type=="message") | .payload.content[]? | .text // empty' ${logPath}`,
+        ].join("\n");
+    }
     if (harness === "opencode") {
         return [
             `Open the SQLite database at ${JSON.stringify(logPath)} in read-only mode.`,

package/dist/commands/proposal/validators/proposal-quality-validators.js

@@ -333,7 +333,11 @@ const redactedContentValidator = {
         ];
     },
 };
-/** Defense in depth when a reflect proposal bypasses creation-time sanitization (#963). */
+/**
+ * The run-only "Avoid These Patterns" section (#963) in a reflect proposal: one
+ * made before reflect kept the body, or a body that already had it. Reflect
+ * keeps a body as it is, so a person accepting has no way to remove it.
+ */
 const reflectPromptScaffoldingValidator = {
     name: "reflect-prompt-scaffolding",
     appliesTo(proposal) {
@@ -361,15 +365,15 @@ function advisory(validator) {
         validate: (proposal, ctx) => validator.validate(proposal, ctx).map((finding) => ({ ...finding, severity: "warn" })),
     };
 }
-/** The quality validators `validateProposal` runs; the last three protect durable content and block. */
+/** The quality validators `validateProposal` runs; the last two protect durable content and block. */
 export const defaultProposalQualityValidators = [
     ...[
         descriptionQualityValidator,
         lessonContentQualityValidator,
         sourceNotSupersededValidator,
         reflectSizeGuardValidator,
+        reflectPromptScaffoldingValidator,
     ].map(advisory),
     reflectTruncationMarkerValidator,
     redactedContentValidator,
-    reflectPromptScaffoldingValidator,
 ];

package/dist/commands/proposal/validators/proposal-validators.js

@@ -131,14 +131,13 @@ export const defaultProposalValidators = [
  * and was previously safe to run in full there because every quality
  * validator was advisory (`advisory()` downgrades findings to `severity:
  * "warn"`, which {@link runProposalValidators}'s `ok` never treats as
- * failing). Blocking durable-content validators (the #952 truncation marker,
- * #962 redaction marker, and #963 reflected prompt scaffolding) deliberately
+ * failing). Blocking durable-content validators (the #952 truncation marker
+ * and #962 redaction marker) deliberately
  * remain outside this subset, so running the full
  * {@link defaultProposalValidators} list at mint time could throw
  * `invalid_canonical_structure` for any lesson/task/workflow reflect
- * proposal whose body leaks the truncation marker — instead of letting
- * `sanitizeReflectPayload` mint the proposal and defer it with
- * `reflect-truncation-leak`, per the #952 design. Quality validators (prose
+ * proposal whose body carries the truncation marker — instead of minting it
+ * for a person to review. Quality validators (prose
  * shape, reflect size ratio, and durable-content guards) belong at
  * `proposal accept` / drain-promotion time, which already calls
  * {@link validateProposal} (the full list) via `preflightProposalPromotion`

package/dist/core/asset/asset-serialize.js

@@ -95,7 +95,7 @@ export function assembleAsset(frontmatter, body) {
  *   - exactly one `\n` terminates the file
  *
  * This helper is the single point of truth for the fence-and-body template.
- * Three command surfaces (`reflect`, `distill`, `consolidate`) call it
+ * Two command surfaces (`distill`, `consolidate`) call it
  * directly because their inputs are pre-validated LLM payloads where the
  * full `yamlStringify` may emit shapes (`|`-block scalars, anchors) that
  * the project's hand-rolled `parseFrontmatter` subset parser cannot read.

package/dist/core/content-safety.js

@@ -6,36 +6,12 @@ export const REDACTED_CONTENT_MARKER = "[REDACTED]";
 /** Reflect prompt section that contains run diagnostics, not proposed asset content. */
 export const REFLECT_AVOID_PATTERNS_HEADING = "Avoid These Patterns";
 const REFLECT_AVOID_PATTERNS_RE = /^##[ \t]+Avoid These Patterns[ \t]*$/i;
-const SECTION_BOUNDARY_RE = /^#{1,2}(?:[ \t]+|$)/;
 export function containsRedactedContent(content) {
     return content.includes(REDACTED_CONTENT_MARKER);
 }
 export function containsReflectPromptScaffolding(content) {
     return content.split(/\r?\n/).some((line) => REFLECT_AVOID_PATTERNS_RE.test(line));
 }
-/**
- * Remove every echoed run-only "Avoid These Patterns" section while preserving
- * the next peer/top-level section. Reflect alone calls this sanitizer; authored
- * source assets are never rewritten by this helper.
- */
-export function stripReflectPromptScaffolding(content) {
-    const newline = content.includes("\r\n") ? "\r\n" : "\n";
-    const lines = content.split(/\r?\n/);
-    const kept = [];
-    let stripped = false;
-    for (let index = 0; index < lines.length;) {
-        if (!REFLECT_AVOID_PATTERNS_RE.test(lines[index] ?? "")) {
-            kept.push(lines[index] ?? "");
-            index += 1;
-            continue;
-        }
-        stripped = true;
-        index += 1;
-        while (index < lines.length && !SECTION_BOUNDARY_RE.test(lines[index] ?? ""))
-            index += 1;
-    }
-    return { content: kept.join(newline).replace(/(?:\r?\n){3,}/g, `${newline}${newline}`), stripped };
-}
 /**
  * Return a secret-free rejection reason when generated content is unsafe to
  * persist. `redactedContent` is the same body after applying the dispatch

package/dist/integrations/agent/prompts.js

@@ -70,10 +70,8 @@ function knownTypeList() {
 export const REFLECT_CONTENT_CAP = 12_000;
 /**
  * Marker appended to truncated asset content when it exceeds the active
- * content budget (#952). Exported so `sanitizeReflectPayload` can detect a
- * model that echoed this notice back into its rewrite instead of proposing
- * real content, and so the output contracts can reference the exact string
- * to forbid.
+ * content budget (#952). Exported so the proposal validators can refuse a body
+ * that still carries it.
  */
 export const REFLECT_TRUNCATION_MARKER = "... [truncated — focus on the visible portion]";
 /**
@@ -119,16 +117,12 @@ export function reflectResponseContract(mode, targetScoped) {
     if (mode === "json_schema") {
         return reflectLlmSchemaContract
             .replace("{{FIELD_RULE}}", targetScoped
-            ? "The response has exactly the required fields `content`, `confidence`, and `frontmatterPatch`; do not echo `ref` or arbitrary `frontmatter`."
-            : "The response has exactly the required fields `ref`, `content`, `confidence`, and `frontmatterPatch`; `ref` must identify the selected asset.")
-            .replaceAll("{{TRUNCATION_MARKER}}", REFLECT_TRUNCATION_MARKER)
+            ? "The response has exactly the required fields `confidence` and `frontmatterPatch`; do not echo `ref` or arbitrary `frontmatter`."
+            : "The response has exactly the required fields `ref`, `confidence`, and `frontmatterPatch`; `ref` must identify the selected asset.")
             .trim();
     }
     const refLine = targetScoped ? "" : "AKM_REFLECT_REF: <selected asset ref>\n";
-    return reflectLlmFramedContract
-        .replace("{{REF_LINE}}", refLine)
-        .replaceAll("{{TRUNCATION_MARKER}}", REFLECT_TRUNCATION_MARKER)
-        .trim();
+    return reflectLlmFramedContract.replace("{{REF_LINE}}", refLine).trim();
 }
 export function buildReflectOutputRepairPrompt(mode, targetScoped) {
     return reflectOutputRepair.replace("{{OUTPUT_CONTRACT}}", reflectResponseContract(mode, targetScoped)).trim();
@@ -158,23 +152,47 @@ function sourceHasNonEmptyDescription(assetContent) {
     return value.length > 0;
 }
 /**
- * Build the prompt for `akm reflect [ref]`. Asks the agent to review an
- * existing asset (plus any negative feedback / lint findings) and propose
- * an improved version. Returns a {@link ReflectPromptResult} containing the
- * prompt string and an optional character ceiling for max-tokens enforcement.
+ * The frontmatter problems akm can see for itself, named in the prompt so the
+ * model fixes them instead of having to spot them: a description split by a
+ * stray period or carrying an escaped quote, no `when_to_use`, no title. A
+ * missing description has its own instruction (#636).
+ */
+function frontmatterProblems(assetContent) {
+    const fm = assetContent?.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!assetContent || !fm)
+        return [];
+    const block = fm[1] ?? "";
+    const problems = [];
+    const raw = block
+        .match(/^description\s*:(.*(?:\r?\n[ \t]+.*)*)/m)?.[1]
+        ?.replace(/\s+/g, " ")
+        .trim() ?? "";
+    const split = [...raw.matchAll(/[\w`)\]]\. [a-z]/g)].find((m) => !/\b(?:e\.g|i\.e|vs|etc|cf)$/i.test(raw.slice(0, (m.index ?? 0) + 1)));
+    if (split) {
+        problems.push(`the \`description\` is broken: a stray period splits a sentence ("${raw}"); repair only the break, keeping its wording and every name, number, path and status word in it`);
+    }
+    else if (raw.includes('\\"')) {
+        problems.push("the `description` is broken by an escaped quote; repair only the quoting, keeping the rest of its wording");
+    }
+    if (!/^when_to_use\s*:\s*(?:\S|\r?\n[ \t]+\S)/m.test(block)) {
+        problems.push("there is no `when_to_use`: write one, a single sentence the body supports, saying when to reach for this asset");
+    }
+    if (!/^title\s*:\s*\S/m.test(block) && !/^#[ \t]+\S/m.test(assetContent.slice(fm[0].length))) {
+        problems.push("the body has no level-1 title: give one in `title`");
+    }
+    return problems;
+}
+/**
+ * Build the prompt for `akm reflect [ref]`. Asks the agent to check an
+ * existing asset's `description`, `when_to_use` and title against its body
+ * (plus any negative feedback / lint findings) and return the fields that
+ * need a fix. Returns a {@link ReflectPromptResult} containing the prompt
+ * string.
  */
 export function buildReflectPrompt(input) {
     const sections = [];
     if (input.ref && input.type && input.name) {
-        // Change 2 — type-conditioned goal framing
-        const isLesson = input.type === "lesson";
-        const isSkill = input.type === "skill";
-        const goalSentence = isLesson
-            ? `Your task is to distill what usage signals reveal about this ${input.type} asset — when to reach for it, what goes wrong without it, and what real use has revealed that the asset itself does not say. Do not reproduce the source content; your proposal must add information the source does not contain.`
-            : isSkill
-                ? "Your task is to review this skill asset, identify what the feedback and related distilled lessons show is broken, missing, unclear, or durable enough to promote into long-term documentation, and produce a single improved proposal. If the strongest evidence points to companion reference material rather than the main SKILL.md, you may instead propose a skill-adjacent knowledge doc such as `knowledge/skills/<skill>/references/<topic>`."
-                : `Your task is to review this ${input.type} asset, identify what the feedback signals as broken, missing, or unclear, and produce an improved version. Do not reproduce the source content unchanged; your proposal must correct or add something the source lacks.`;
-        sections.push(goalSentence);
+        sections.push(`Your task is to check this ${input.type} asset's \`description\`, \`when_to_use\` and title against its body and the feedback below, and fix any that is missing, broken, or claims something the body does not cover. AKM keeps the body exactly as it is: you change only these fields, and when none needs a change you return null for each.`);
         sections.push(`Target ref: ${input.ref}`);
         sections.push(`Asset-type guidance: ${hintForType(input.type)}`);
     }
@@ -200,12 +218,9 @@ export function buildReflectPrompt(input) {
         sections.push("Recent feedback / signals:");
         sections.push("- (no feedback events recorded)");
     }
-    else if (input.type === "skill" && input.relatedLessons && input.relatedLessons.length > 0) {
-        sections.push("No direct feedback events were recorded. Limit substantive changes to what is justified by the related distilled lessons below; do not speculate beyond that evidence.");
-    }
     else {
-        // ref is set but no feedback — explicitly constrain scope to schema compliance
-        sections.push("No usage feedback recorded. Limit your proposal to schema and structural improvements only: missing required frontmatter fields, unclear `when_to_use`, ambiguous description, or broken formatting. Do not speculate about runtime weaknesses you have not observed.");
+        // ref is set but no feedback — explicitly constrain scope to broken or missing fields
+        sections.push("No usage feedback recorded. Fix only a missing or broken `description`, `when_to_use` or title; otherwise return null for each.");
     }
     if (input.standardsContext?.trim()) {
         sections.push("Standards to follow (the rulebook for this target):");
@@ -253,7 +268,7 @@ export function buildReflectPrompt(input) {
         sections.push("```");
     }
     else if (input.ref) {
-        sections.push("(No existing content — propose a fresh asset that fits the ref.)");
+        sections.push("(No existing content.)");
     }
     else {
         sections.push("(No existing asset content was supplied.)");
@@ -263,23 +278,10 @@ export function buildReflectPrompt(input) {
         for (const line of input.schemaHints)
             sections.push(`- ${line}`);
     }
-    if (input.relatedLessons && input.relatedLessons.length > 0) {
-        sections.push("Related distilled lessons to evaluate for consolidation:");
-        for (const lesson of input.relatedLessons) {
-            sections.push(`Lesson ref: ${lesson.ref}`);
-            sections.push("```");
-            sections.push(lesson.content.trimEnd());
-            sections.push("```");
-        }
-        sections.push("Evaluate whether these lessons contain strong evidence of factual, repeatable guidance that should be promoted into long-term skill documentation.");
-        sections.push("Promote only guidance that is durable, generally applicable, and supported by repeated evidence. Do not copy anecdotal details, one-off incidents, or duplicate wording verbatim.");
-        sections.push("If the guidance belongs in the main skill instructions, update the skill proposal. If it belongs in a companion reference document, return a `knowledge/skills/<skill>/references/<topic>` proposal instead.");
-    }
     if (input.rejectedProposals && input.rejectedProposals.length > 0) {
         const lines = ["## Previously Rejected Proposals"];
         lines.push("The following proposals for this ref were already reviewed and rejected. " +
-            "Do NOT reproduce the same content or the same structural shape. " +
-            "Your new proposal must meaningfully differ from each of these in its approach, framing, or evidence used.");
+            "Do not propose the same change again; if no other change is justified, return null for each field.");
         for (const rp of input.rejectedProposals) {
             lines.push(`\nRef: ${rp.ref}`);
             lines.push(`Rejection reason: ${rp.reason}`);
@@ -303,58 +305,16 @@ export function buildReflectPrompt(input) {
             "The following is your previous draft proposal. " +
             "Identify specific weaknesses: missing evidence, vague wording, incomplete frontmatter, " +
             "or claims that duplicate existing content without adding new signal. " +
-            "Then produce an improved version that addresses those weaknesses. " +
-            "The revised proposal must be meaningfully better than the draft below — " +
-            "do not return the same content unchanged.\n\n" +
+            "Then produce an improved version that addresses those weaknesses.\n\n" +
             "Previous draft:\n```\n" +
             input.priorDraft.trimEnd() +
             "\n```");
     }
-    sections.push("Produce a single proposal that addresses the feedback and respects the asset-type contract. If the proposal's frontmatter is missing `when_to_use`, you MUST generate one — a one-line trigger sentence describing exactly when a user should reach for this asset.");
-    // Content-preservation safety rails (#reflect-pipeline-fixes).
-    // These rules counter the observed failure modes where reflect rewrites
-    // asset content into shorter prose, drops concrete structure, or strips
-    // load-bearing frontmatter. Loud and explicit so small models follow.
-    //
-    // Guard-audit finding 15: this used to also hand back a maxOutputChars
-    // value so an LLM-path caller could convert it into a hard `max_tokens`
-    // cap on the API request. llm/client.ts's own doc comment (and
-    // commands/improve/reflect.ts's recorded history of responses actually
-    // getting cut off) is explicit that a character-derived max_tokens causes
-    // silent truncation — a real model's output is measured in tokens, not
-    // characters, and the ratio between the two varies enough that any fixed
-    // conversion either truncates legitimate output or provides no real cap at
-    // all. The size policy below is already enforced twice more (the prompt
-    // rules the model reads, and the post-processor's own size check), so nothing
-    // is lost by not adding a THIRD, byte-derived enforcement point that can
-    // only ever cut a response off early, never usefully re-check it.
     if (input.ref && input.assetContent?.trim()) {
-        // Strip frontmatter to get source body length — mirrors checkReflectSize which
-        // compares body-only lengths. Inline regex avoids importing parseFrontmatter.
-        const rawContent = input.assetContent.trimEnd();
-        const fmBodyMatch = rawContent.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
-        const sourceBodyLen = (fmBodyMatch ? fmBodyMatch[1] : rawContent).trim().length;
-        // Compute concrete char bounds matching checkReflectSize constants:
-        //   REFLECT_SIZE_GUARD_MIN_BYTES=200, REFLECT_SHRINK_RATIO_MIN=0.5,
-        //   REFLECT_ABSOLUTE_FLOOR_BYTES=150, REFLECT_EXPAND_RATIO_MAX=2.5,
-        //   REFLECT_ABSOLUTE_CEILING_BYTES=2500, REFLECT_ABSOLUTE_MAX_BYTES=25000.
-        // Embed concrete counts only when the gate will actually fire (source >= 200 chars).
-        const showCharBounds = sourceBodyLen >= 200;
-        const minChars = Math.max(Math.round(0.5 * sourceBodyLen), 150);
-        // A source already past the 25000 cap may not grow, and need not shrink to the cap.
-        const maxChars = Math.max(Math.min(Math.max(Math.round(2.5 * sourceBodyLen), 2500), 25000), sourceBodyLen);
-        sections.push([
-            "## Content preservation rules (MUST follow)",
-            "1. PRESERVE ALL concrete content: code blocks, fenced snippets, CLI commands, numbered/bulleted checklists, tables, YAML/JSON examples, file paths, configuration keys, environment variable names, and CSS/HTML selectors. These are load-bearing — do NOT replace them with prose summaries.",
-            "2. PRESERVE the source asset's frontmatter. The post-processor reassembles the final asset from the original frontmatter plus your body. Do NOT emit `---` frontmatter delimiters at the top of `content` — start `content` with the markdown body (e.g. `# Heading` or the first paragraph). If you include frontmatter anyway, identity fields (`name`, `ref`, `id`, `slug`, `type`) will be reset to the original values.",
-            showCharBounds
-                ? `3. DO NOT shrink the asset. Your body must be at least ${minChars} characters (source body is ${sourceBodyLen} chars; floor is 50%). If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. \`<!-- removed obsolete section X because ... -->\`).`
-                : "3. DO NOT shrink the asset dramatically. The improved body must be at least 50% of the source body length. If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. `<!-- removed obsolete section X because ... -->`).",
-            showCharBounds
-                ? `4. DO NOT pad the asset with speculative material. Your body must be at most ${maxChars} characters (source body is ${sourceBodyLen} chars; ceiling is ${maxChars === sourceBodyLen ? "100%" : "250%"}). Do not add invented sections, hypothetical examples, or padding prose.`
-                : "4. DO NOT pad the asset with speculative material. The improved body must be at most 250% of the source body length unless the feedback explicitly requests added sections.",
-            "5. Improve clarity of surrounding prose, fix structural issues, add missing required frontmatter fields. Do NOT rewrite a runbook into an essay.",
-        ].join("\n"));
+        const problems = frontmatterProblems(input.assetContent);
+        sections.push(problems.length > 0
+            ? `akm found these problems in the asset; fix each one:\n${problems.map((p) => `- ${p}`).join("\n")}`
+            : "akm found no missing or broken field.");
     }
     sections.push(reflectResponseContract(input.outputMode ?? "json_schema", input.ref !== undefined));
     return { prompt: sections.join("\n\n") };

package/dist/integrations/harnesses/codex/index.js

@@ -1,23 +1,14 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * OpenAI Codex CLI harness (P2 integration, plan §"The adapter contract").
- *
- * Per-harness barrel gathering the Codex integration surfaces:
- *   - agent command builder → ./agent-builder.ts    (codexBuilder)
- *   - result extractor      → ./result-extractor.ts (codexResultExtractor)
- *
- * It also defines {@link CodexHarness}, the {@link AkmHarness} descriptor that
- * `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log reader or
- * config importer yet.
- */
 import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
 import { codexBuilder } from "./agent-builder.js";
 import { codexResultExtractor } from "./result-extractor.js";
+import { CodexProvider } from "./session-log.js";
 export { codexBuilder, codexResumeArgs, writeCodexOutputSchemaFile } from "./agent-builder.js";
 export { codexResultExtractor } from "./result-extractor.js";
+export { CodexProvider } from "./session-log.js";
 /**
  * OpenAI Codex CLI.
  *
@@ -26,6 +17,8 @@ export { codexResultExtractor } from "./result-extractor.js";
 export class CodexHarness extends BaseHarness {
     id = "codex";
     displayName = "OpenAI Codex CLI";
+    // No `setupDetectionDir`: `~/.codex` holds credentials and session rollouts,
+    // not assets, so `akm setup` must not offer it as a stash source.
     agentBuilder = codexBuilder;
     resultExtractor = codexResultExtractor;
     // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
@@ -40,7 +33,9 @@ export class CodexHarness extends BaseHarness {
     // user config-dir var commonly exported in shell profiles, so it would stamp
     // identity onto manual runs (see `AkmHarness.presenceEnv`).
     presenceEnv = ["CODEX_SANDBOX"];
+    sessionLogProvider = () => new CodexProvider();
     capabilities = caps({
+        sessionLogs: true,
         agentDispatch: true,
         detection: true,
     });

package/dist/integrations/harnesses/codex/session-log.js

@@ -0,0 +1,211 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
+import { AbstractSessionLogProvider } from "../../session-logs/provider-base.js";
+/**
+ * Root directory holding Codex's rollout files, one per session, as
+ * `YYYY/MM/DD/rollout-<timestamp>-<thread-id>.jsonl`.
+ *
+ * Resolved per call (not memoized at module load) so `CODEX_HOME` — Codex's own
+ * override of `~/.codex` — can be set after import; tests point it at a fixture
+ * directory instead of the real history.
+ */
+function codexSessionsDir() {
+    return path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "sessions");
+}
+/** Bytes read to get a rollout's first record, `session_meta`: its embedded base instructions make it 20-50 KB. */
+const META_PEEK_BYTES = 128 * 1024;
+/**
+ * User-role blocks Codex injects itself, which are not the person's words: the
+ * AGENTS.md instructions and the context tags it is known to wrap (environment,
+ * plugin recommendations, an invoked skill's text, ...). Any other block is kept:
+ * a stray bit of context costs less than a dropped reply.
+ */
+const INJECTED_CONTEXT_RE = /^\s*(?:# AGENTS\.md instructions[\s\S]*<\/INSTRUCTIONS>|<(environment_context|user_instructions|recommended_plugins|skill|turn_aborted)>[\s\S]*<\/\1>)\s*$/i;
+/** The `session_meta` record, always a rollout's first; `undefined` for any other record. */
+function parseSessionMeta(entry) {
+    const e = entry;
+    if (e?.type !== "session_meta" || !e.payload)
+        return undefined;
+    const { timestamp, cwd, source } = e.payload;
+    const startedAt = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+    return {
+        ...(Number.isNaN(startedAt) ? {} : { startedAt }),
+        ...(typeof cwd === "string" ? { cwd } : {}),
+        isAgent: typeof source === "object" && source !== null && ("subagent" in source || "internal" in source),
+    };
+}
+/** The text of a message's or tool output's content: a plain string, or blocks whose images and audio carry none. */
+function blockText(blocks, keep = () => true) {
+    if (typeof blocks === "string")
+        return blocks;
+    if (!Array.isArray(blocks))
+        return "";
+    const parts = [];
+    for (const block of blocks) {
+        const text = block?.text;
+        if (typeof text === "string" && keep(text))
+            parts.push(text);
+    }
+    return parts.join("\n");
+}
+/**
+ * A tool call's input as text. A shell call surfaces its command line (`cmd`, or
+ * `command` as a string or an argv array) so the inline-ref scanner can match
+ * `akm remember "..."` without JSON-quote escaping mangling the regex; any
+ * other input stays as it was written.
+ */
+function toolInputText(input) {
+    let args = input;
+    if (typeof input === "string") {
+        try {
+            args = JSON.parse(input);
+        }
+        catch {
+            return input;
+        }
+    }
+    const fields = args && typeof args === "object" ? args : {};
+    const cmd = fields.cmd ?? fields.command;
+    if (typeof cmd === "string")
+        return cmd;
+    if (Array.isArray(cmd))
+        return cmd.join(" ");
+    return typeof input === "string" ? input : (JSON.stringify(input) ?? "");
+}
+/**
+ * Parse one rollout record into a normalized {@link SessionEvent}. The
+ * conversation lives in `response_item` records; the rest (`event_msg` UI events
+ * that repeat it, `turn_context`, `world_state`, token counts, compaction
+ * markers) and items with nothing to read (`reasoning` is encrypted) give
+ * `undefined`. Codex's `developer` messages are its own instructions, so they
+ * are skipped too.
+ *
+ * Tool calls become `[tool:<name>] <input>` and their results `[tool_result]
+ * <output>`, the shapes the Claude reader writes. A result is a `tool` event:
+ * Codex has no enclosing user message to give it.
+ */
+function parseCodexRecord(entry, sessionId, filePath, fallbackTsMs) {
+    const e = entry;
+    const item = e?.type === "response_item" ? e.payload : undefined;
+    if (!item)
+        return undefined;
+    const toolName = typeof item.name === "string" ? item.name : "tool";
+    let role = "assistant";
+    let text;
+    switch (item.type) {
+        case "message":
+            if (item.role !== "user" && item.role !== "assistant")
+                return undefined;
+            role = item.role;
+            text = blockText(item.content, item.role === "user" ? (t) => !INJECTED_CONTEXT_RE.test(t) : undefined);
+            break;
+        case "function_call":
+            text = `[tool:${toolName}] ${toolInputText(item.arguments)}`;
+            break;
+        case "custom_tool_call":
+            text = `[tool:${toolName}] ${typeof item.input === "string" ? item.input : ""}`;
+            break;
+        case "local_shell_call":
+            text = `[tool:shell] ${toolInputText(item.action)}`;
+            break;
+        case "function_call_output":
+        case "custom_tool_call_output": {
+            role = "tool";
+            const output = blockText(item.output);
+            text = output ? `[tool_result] ${output}` : "";
+            break;
+        }
+        default:
+            return undefined;
+    }
+    if (!text.trim())
+        return undefined;
+    const ts = typeof e?.timestamp === "string" ? Date.parse(e.timestamp) || fallbackTsMs : fallbackTsMs;
+    return { harness: "codex", text, ts, sessionId, role, filePath };
+}
+/**
+ * Codex native session-log reader.
+ *
+ * Events, refs, extraction keys, and the harness registry all use `codex`. The
+ * session id is the thread id in the rollout's file name (the id `codex resume`
+ * takes) and `projectHint` is the session's working directory.
+ */
+export class CodexProvider extends AbstractSessionLogProvider {
+    name = "codex";
+    availabilityRoot() {
+        return codexSessionsDir();
+    }
+    listSessions(input = {}) {
+        return this.listSessionsFromFiles({
+            sinceMs: input.sinceMs ?? 0,
+            enumerate: () => this.walkFiles(input.location ?? codexSessionsDir(), (name) => /^rollout-.+\.jsonl$/.test(name)),
+            summarize: (rolloutPath, stat) => {
+                const meta = this.#peekMeta(rolloutPath);
+                if (meta?.isAgent)
+                    return undefined;
+                return this.sessionRef({
+                    // The thread id is the 36-character UUID that ends the file name.
+                    sessionId: path.basename(rolloutPath, ".jsonl").slice(-36),
+                    filePath: rolloutPath,
+                    startedAt: meta?.startedAt ?? stat.ctimeMs,
+                    endedAt: stat.mtimeMs,
+                    projectHint: meta?.cwd,
+                });
+            },
+        });
+    }
+    readSession(ref) {
+        const stat = fs.statSync(ref.filePath);
+        const events = [];
+        const inlineRefs = [];
+        let meta;
+        for (const line of fs.readFileSync(ref.filePath, "utf8").split("\n").filter(Boolean)) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue; // a partial line (the session is still being written) or garbage
+            }
+            meta ??= parseSessionMeta(entry);
+            const parsed = parseCodexRecord(entry, ref.sessionId, ref.filePath, stat.mtimeMs);
+            if (!parsed)
+                continue;
+            events.push(parsed);
+            inlineRefs.push(...extractInlineRefMentions(parsed.text, parsed.ts));
+        }
+        return {
+            ref: this.sessionRef({
+                sessionId: ref.sessionId,
+                filePath: ref.filePath,
+                startedAt: meta?.startedAt ?? events[0]?.ts ?? stat.ctimeMs,
+                endedAt: events[events.length - 1]?.ts ?? stat.mtimeMs,
+                projectHint: meta?.cwd,
+            }),
+            events,
+            inlineRefs,
+        };
+    }
+    /** The `session_meta` record on a rollout's first line, read without loading the file. */
+    #peekMeta(filePath) {
+        try {
+            const fd = fs.openSync(filePath, "r");
+            try {
+                const head = Buffer.alloc(META_PEEK_BYTES);
+                const firstLine = head.toString("utf8", 0, fs.readSync(fd, head, 0, head.length, 0)).split("\n", 1)[0] ?? "";
+                return parseSessionMeta(JSON.parse(firstLine));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            return undefined; // unreadable / vanished file, or a first line that is not one whole record
+        }
+    }
+}

package/dist/integrations/harnesses/types.js

@@ -34,14 +34,14 @@ export function isSessionLogHarness(h) {
  * `HarnessCapabilities` union type here, and each subclass narrows it to a
  * literal `sessionLogs: true`/`false` variant via `caps({...})`.
  * `sessionLogProvider` is intentionally NOT declared here at all (not even
- * optional): the 8 non-session-log subclasses simply never declare it, which
+ * optional): the 7 non-session-log subclasses simply never declare it, which
  * satisfies `NonSessionLogHarness`'s `sessionLogProvider?: undefined` (an
  * absent optional property satisfies an `undefined`-typed optional); had this
  * class declared it as `sessionLogProvider?: () => SessionLogHarness`
  * instead, every non-session-log subclass would inherit that (function |
  * undefined) type and fail to satisfy `NonSessionLogHarness` at the
- * `HARNESS_REGISTRY` `satisfies` check. The two session-log subclasses
- * (Claude, OpenCode) declare their own required `sessionLogProvider`.
+ * `HARNESS_REGISTRY` `satisfies` check. The three session-log subclasses
+ * (Claude, Codex, OpenCode) declare their own required `sessionLogProvider`.
  */
 export class BaseHarness {
     setupDetectionDir;