fix(codex): handle large sessions and correct skill invocation

README.md

@@ -146,8 +146,8 @@ Pick your coding agent — you can be looking at your first report in minutes:
 | Coding agent | Setup |
 | --- | --- |
 | **Claude Code** | Add the repository marketplace, install `better-harness@better-harness`, start a new session, then use the report prompt below. |
-| **Codex Desktop** | Add the repository under **Settings > Plugins > + Add > From Marketplace**, install Better Harness, start a new task, then use the report prompt below. |
-| **Codex CLI** | Add the Git marketplace, then run `codex plugin add better-harness@better-harness`. |
+| **Codex Desktop** | Add the repository under **Settings > Plugins > + Add > From Marketplace**, install Better Harness, start a new task, then invoke `@better-harness`. |
+| **Codex CLI** | Add the Git marketplace, run `codex plugin add better-harness@better-harness`, then invoke `$better-harness:better-harness`. |
 | **Qoder Desktop / CLI** | Nothing to install when Qoder Desktop is installed — Better Harness is built in and available to both. Open your repository and use the report prompt below. |
 | **Cursor** | Load the plugin from source — see [Installation](#installation). |
 
@@ -214,8 +214,12 @@ stays explicit rather than being inferred.
    empty for this single-plugin repository.
 4. Select **Add marketplace**, then install **Better Harness** from the new
    marketplace.
-5. Start a new task in the repository you want to review and use the report
-   prompt from [Quick start](#quick-start).
+5. Start a new task in the repository you want to review and run the report
+   prompt:
+
+```text
+@better-harness review this project's AI coding workflow and generate a report
+```
 
 Use `https://github.com/QoderAI/better-harness.git` with Git ref `main`.
 
@@ -242,7 +246,7 @@ Start a new Codex task in the repository you want to review and run the report
 prompt:
 
 ```text
-/better-harness review this project's AI coding workflow and generate a report
+$better-harness:better-harness review this project's AI coding workflow and generate a report
 ```
 
 Use the repository URL with `marketplace add`, not a raw `marketplace.json`

README.zh-CN.md

@@ -142,8 +142,8 @@ Better Harness 开放了三个相互关联的层次，而不只是一个斜杠
 | 编码智能体 | 设置方式 |
 | --- | --- |
 | **Claude Code** | 添加本仓库 Marketplace，安装 `better-harness@better-harness`，启动新会话，然后使用下方的报告提示词。 |
-| **Codex Desktop** | 在 **Settings > Plugins > + Add > From Marketplace** 中添加本仓库，安装 Better Harness，启动新任务，然后使用下方的报告提示词。 |
-| **Codex CLI** | 添加 Git Marketplace，然后运行 `codex plugin add better-harness@better-harness`。 |
+| **Codex Desktop** | 在 **Settings > Plugins > + Add > From Marketplace** 中添加本仓库，安装 Better Harness，启动新任务，然后调用 `@better-harness`。 |
+| **Codex CLI** | 添加 Git Marketplace，运行 `codex plugin add better-harness@better-harness`，然后调用 `$better-harness:better-harness`。 |
 | **Qoder Desktop / CLI** | 安装 Qoder Desktop 后无需额外安装——Better Harness 已内置，并可在桌面端和 CLI 中使用。打开仓库并使用下方的报告提示词。 |
 | **Cursor** | 从源码加载插件——参见[安装](#installation)。 |
 
@@ -207,7 +207,11 @@ Claude Code 默认会在仓库的 `.claude/better-harness` 报告根目录下生
 2. 选择 **+ Add > From Marketplace**。
 3. 输入 Git 仓库 URL，设置 Git ref；对于这个单插件仓库，**Sparse paths** 留空。
 4. 选择 **Add marketplace**，然后从新 Marketplace 中安装 **Better Harness**。
-5. 在需要审查的仓库中启动新任务，并使用[快速开始](#quick-start)中的报告提示词。
+5. 在需要审查的仓库中启动新任务，并运行报告提示词：
+
+```text
+@better-harness 审查此项目的 AI 编码工作流并生成报告
+```
 
 仓库 URL 使用 `https://github.com/QoderAI/better-harness.git`，Git ref 使用 `main`。
 
@@ -233,7 +237,7 @@ codex plugin add better-harness@better-harness
 在需要审查的仓库中启动新的 Codex 任务，并运行报告提示词：
 
 ```text
-/better-harness 审查此项目的 AI 编码工作流并生成报告
+$better-harness:better-harness 审查此项目的 AI 编码工作流并生成报告
 ```
 
 使用 `marketplace add` 时应传入仓库 URL，而不是原始 `marketplace.json` URL。

scripts/session-analysis/platforms/codex.mjs

@@ -1010,7 +1010,9 @@ export class CodexSessionAnalyzer extends SessionAnalyzer {
         });
     for (const session of selection.sessions) {
       const sessionEvents = await this.readSession(session, scope, eventOptions);
-      events.push(...sessionEvents);
+      for (const event of sessionEvents) {
+        events.push(event);
+      }
       detailedSessions.push(this.mergeSession(sessionEvents, session));
     }
 

test/better-harness-skill.test.mjs

@@ -86,6 +86,23 @@ test("non-Qoder providers default to validated durable HTML with an explicit inl
   assert.match(readme, /\.claude\/better-harness/);
 });
 
+test("Codex README examples use host-specific skill invocation syntax", () => {
+  for (const readmePath of ["README.md", "README.zh-CN.md"]) {
+    const readme = read(readmePath);
+    const desktopQuickStart = readme.match(/^\| \*\*Codex Desktop\*\* \|.*$/mu)?.[0] ?? "";
+    const cliQuickStart = readme.match(/^\| \*\*Codex CLI\*\* \|.*$/mu)?.[0] ?? "";
+    const desktop = readme.match(/#### Codex Desktop\n([\s\S]*?)\n#### Codex CLI/u)?.[1] ?? "";
+    const cli = readme.match(/#### Codex CLI\n([\s\S]*?)\n### Qoder/u)?.[1] ?? "";
+
+    assert.match(desktopQuickStart, /`@better-harness`/u);
+    assert.match(cliQuickStart, /`\$better-harness:better-harness`/u);
+    assert.match(desktop, /^@better-harness(?:[ \t]|$)/mu);
+    assert.match(cli, /^\$better-harness:better-harness(?:[ \t]|$)/mu);
+    assert.doesNotMatch(desktop, /^[ \t]*\/better-harness(?:[ \t]|$)/mu);
+    assert.doesNotMatch(cli, /^[ \t]*\/better-harness(?:[ \t]|$)/mu);
+  }
+});
+
 test("Step 1 establishes one provider-labelled evidence bundle", () => {
   const skill = read("skills/better-harness/SKILL.md");
 

test/session-analysis.test.mjs

@@ -1710,6 +1710,41 @@ test("Qoder file-reads rank suspected wrong-file reads without raw commands", as
   }
 });
 
+test("Codex analyzer preserves large session event counts without overflowing the stack", async () => {
+  const { CodexSessionAnalyzer } = await import("../scripts/session-analysis/platforms/codex.mjs");
+  const analyzer = new CodexSessionAnalyzer();
+  const eventCount = 150_000;
+  const sessionId = "codex-large-session";
+  const workspace = path.join(os.tmpdir(), "better-harness-codex-large-workspace");
+  const session = {
+    sessionId,
+    workspace,
+    sourceKinds: ["codex-session-jsonl"],
+    sourceRefs: [],
+    firstSeen: null,
+    lastSeen: null,
+  };
+  const event = {
+    sessionId,
+    type: "synthetic",
+    sourceKind: "codex-session-jsonl",
+    timestamp: null,
+  };
+
+  analyzer.discoverSourceRoots = async () => [];
+  analyzer.readSession = async () => new Array(eventCount).fill(event);
+
+  const result = await analyzer.analyze({
+    home: path.join(os.tmpdir(), "better-harness-codex-large-home"),
+    workspace,
+    command: "facets",
+    sessionInventory: [session],
+  });
+
+  assert.equal(result.sessions[0].eventCounts.synthetic, eventCount);
+  assert.equal(result.facets.topEventTypes.find((item) => item.name === "synthetic")?.count, eventCount);
+});
+
 test("Codex insights summarize function calls and inferred skill reads", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "better-harness-codex-session-analysis-"));
   const workspace = path.join(root, "workspace", "better-harness");