@ask-llm/plugin 0.13.0

package/scripts/codex-pair-log.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// codex-pair-log — standalone CLI viewer for .codex-pair/log.jsonl written
+// by the codex-pair PostToolUse hook. Walks up from cwd to find the
+// .codex-pair/context.md marker (same gate as the hook), then reads and
+// renders the sibling log file.
+//
+// Subcommands:
+//   --latest [N]      Show last N entries (default 10). DEFAULT subcommand.
+//   --summary         Aggregate stats: verdict breakdown, top files, durations.
+//   --file <path>     Filter to one file's history.
+//   --since <dur>     Filter to entries within the last <dur>. Examples: 24h, 7d, 30m.
+//
+// Zero workspace imports — distributed via marketplace `git-subdir` install,
+// no node_modules at runtime. Same constraint as codex-pair-watch.mjs (ADR-078).
+// Path constants come from the sibling lib/state.mjs so the layout stays
+// consistent with the hook (ADR-092).
+
+import { readFileSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { CONTEXT_FILENAME, logPath as resolveLogPath, PAIR_ROOT_DIR } from "./lib/state.mjs";
+
+const MARKER_FILE = join(PAIR_ROOT_DIR, CONTEXT_FILENAME);
+
+// Returns the project ROOT (the directory holding `.codex-pair/`) or null.
+async function findMarkerUp(startDir) {
+  const home = homedir();
+  let current = resolve(startDir);
+  for (let depth = 0; depth < 20; depth++) {
+    const candidate = join(current, MARKER_FILE);
+    try {
+      await access(candidate);
+      return current;
+    } catch {
+      // not found here
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    if (current === home) return null;
+    current = parent;
+  }
+  return null;
+}
+
+function parseDuration(s) {
+  const m = s.match(/^(\d+)([smhd])$/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const unit = m[2];
+  if (unit === "s") return n * 1000;
+  if (unit === "m") return n * 60 * 1000;
+  if (unit === "h") return n * 60 * 60 * 1000;
+  if (unit === "d") return n * 24 * 60 * 60 * 1000;
+  return null;
+}
+
+function parseArgs(argv) {
+  const args = { cmd: "latest", n: 10, file: null, sinceMs: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--latest") {
+      args.cmd = "latest";
+      const next = argv[i + 1];
+      if (next && /^\d+$/.test(next)) {
+        args.n = Number(next);
+        i++;
+      }
+    } else if (a === "--summary") {
+      args.cmd = "summary";
+    } else if (a === "--file") {
+      args.cmd = "file";
+      args.file = argv[i + 1] ?? null;
+      i++;
+    } else if (a === "--since") {
+      const next = argv[i + 1];
+      const ms = next ? parseDuration(next) : null;
+      if (ms === null) {
+        process.stderr.write(`codex-pair-log: invalid --since duration "${next ?? ""}"\n`);
+        process.exit(2);
+      }
+      args.sinceMs = ms;
+      i++;
+    } else if (a === "--help" || a === "-h") {
+      args.cmd = "help";
+    } else {
+      process.stderr.write(`codex-pair-log: unknown arg "${a}"\n`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function loadEntries(logPath) {
+  let content;
+  try {
+    content = readFileSync(logPath, "utf8");
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const line of content.split("\n")) {
+    if (line.length === 0) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // skip malformed lines silently
+    }
+  }
+  return entries;
+}
+
+function applySinceFilter(entries, sinceMs) {
+  if (sinceMs == null) return entries;
+  const cutoff = Date.now() - sinceMs;
+  return entries.filter((e) => {
+    if (!e.timestamp) return false;
+    const t = new Date(e.timestamp).getTime();
+    return Number.isFinite(t) && t >= cutoff;
+  });
+}
+
+function formatCounts(entry) {
+  if (entry.counts) {
+    return `${entry.counts.high}H/${entry.counts.med}M/${entry.counts.low}L`;
+  }
+  return "—";
+}
+
+function formatDuration(ms) {
+  if (ms == null) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function showLatest(entries, n) {
+  const slice = entries.slice(-n);
+  for (const e of slice) {
+    const verdict = (e.verdict || (e.level ? `[${e.level}]` : "?")).padEnd(13);
+    const file = (e.file || "—").padEnd(50);
+    const counts = formatCounts(e).padEnd(11);
+    const dur = formatDuration(e.durationMs);
+    const ts = e.timestamp || "—";
+    process.stdout.write(`${ts}  ${verdict} ${file} ${counts} ${dur}\n`);
+  }
+}
+
+function showFile(entries, filePath) {
+  const filtered = entries.filter((e) => e.file === filePath);
+  if (filtered.length === 0) {
+    process.stdout.write(`codex-pair-log: no entries for file ${filePath}\n`);
+    return;
+  }
+  showLatest(filtered, filtered.length);
+}
+
+function showSummary(entries) {
+  const verdictCounts = {};
+  const fileCounts = {};
+  let durationSum = 0;
+  let durationCount = 0;
+  let fallbackCount = 0;
+  let cachedCount = 0;
+  let runCount = 0;
+  for (const e of entries) {
+    if (e.verdict) {
+      verdictCounts[e.verdict] = (verdictCounts[e.verdict] || 0) + 1;
+    }
+    if (e.file) {
+      fileCounts[e.file] = (fileCounts[e.file] || 0) + 1;
+    }
+    if (e.fellBack) fallbackCount++;
+    if (e.verdict === "cached") cachedCount++;
+    if (
+      e.verdict === "none" ||
+      e.verdict === "concerns" ||
+      e.verdict === "cached"
+    ) {
+      runCount++;
+    }
+    if (
+      e.durationMs != null &&
+      (e.verdict === "none" || e.verdict === "concerns")
+    ) {
+      durationSum += e.durationMs;
+      durationCount++;
+    }
+  }
+  const topFiles = Object.entries(fileCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5);
+  process.stdout.write(`codex-pair log summary\n`);
+  process.stdout.write(`Total entries:    ${entries.length}\n`);
+  process.stdout.write(`Verdict breakdown:\n`);
+  for (const [v, c] of Object.entries(verdictCounts).sort((a, b) => b[1] - a[1])) {
+    process.stdout.write(`  ${v.padEnd(15)} ${c}\n`);
+  }
+  process.stdout.write(`Top 5 files by entry count:\n`);
+  for (const [f, c] of topFiles) {
+    process.stdout.write(`  ${String(c).padStart(4)}  ${f}\n`);
+  }
+  if (durationCount > 0) {
+    const avg = durationSum / durationCount;
+    process.stdout.write(
+      `Average codex duration (uncached runs only): ${formatDuration(avg)} over ${durationCount} runs\n`,
+    );
+  }
+  if (runCount > 0) {
+    const cacheRate = ((cachedCount / runCount) * 100).toFixed(1);
+    process.stdout.write(`Cache hit rate: ${cachedCount} / ${runCount} (${cacheRate}%)\n`);
+  }
+  if (fallbackCount > 0) {
+    process.stdout.write(`Fallback model used: ${fallbackCount} time(s)\n`);
+  }
+}
+
+function showHelp() {
+  process.stdout.write(
+    [
+      "codex-pair-log — view .codex-pair/log.jsonl written by the codex-pair hook",
+      "",
+      "Usage: codex-pair-log [SUBCOMMAND] [--since DURATION]",
+      "",
+      "Subcommands:",
+      "  --latest [N]      Show last N entries (default 10). Default subcommand.",
+      "  --summary         Aggregate stats over the log.",
+      "  --file <path>     Filter to one file's history.",
+      "  --since <dur>     Filter to entries within the last <dur>. Examples: 30m, 24h, 7d.",
+      "  --help, -h        Show this help.",
+      "",
+    ].join("\n"),
+  );
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.cmd === "help") {
+    showHelp();
+    return;
+  }
+  const markerDir = await findMarkerUp(process.cwd());
+  if (!markerDir) {
+    process.stderr.write(
+      `codex-pair-log: no .codex-pair/context.md marker found in cwd or parents\n`,
+    );
+    process.exit(1);
+  }
+  const logPath = resolveLogPath(markerDir);
+  let entries = loadEntries(logPath);
+  if (entries.length === 0) {
+    process.stdout.write(`codex-pair-log: no entries in ${logPath}\n`);
+    return;
+  }
+  entries = applySinceFilter(entries, args.sinceMs);
+  if (args.cmd === "latest") {
+    showLatest(entries, args.n);
+  } else if (args.cmd === "summary") {
+    showSummary(entries);
+  } else if (args.cmd === "file") {
+    if (!args.file) {
+      process.stderr.write(`codex-pair-log: --file requires a path argument\n`);
+      process.exit(2);
+    }
+    showFile(entries, args.file);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`codex-pair-log: ${err?.message ?? String(err)}\n`);
+  process.exit(1);
+});

package/scripts/codex-pair-prompt-drain.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// UserPromptSubmit drain hook (design 2026-06-03 + plan red-team 2026-06-04).
+//
+// Surfaces any verdict a debounce worker queued, at the START of the next user
+// turn — closing the gap where a single edit (with no following edit) leaves
+// its review in the log but never in Claude's context. Cheap no-op when nothing
+// is pending. MUST exit 0 on every path (ADR-077).
+//
+// findMarkerUp is duplicated from codex-pair-watch/session.mjs by design:
+// zero-workspace-imports (marketplace git-subdir install has no node_modules)
+// and the helper is too small to extract (15 LOC).
+
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { CONTEXT_FILENAME, PAIR_ROOT_DIR } from "./lib/state.mjs";
+import { drainPending, joinPendingForSurface } from "./lib/debounce-state.mjs";
+import { collectSessionMarkers } from "./lib/session-registry.mjs";
+
+const MARKER_FILE = join(PAIR_ROOT_DIR, CONTEXT_FILENAME);
+
+async function findMarkerUp(startDir) {
+  const home = homedir();
+  let current = resolve(startDir);
+  for (let depth = 0; depth < 20; depth++) {
+    try {
+      await access(join(current, MARKER_FILE));
+      return current;
+    } catch {
+      // not here
+    }
+    const parent = dirname(current);
+    if (parent === current || current === home) return null;
+    current = parent;
+  }
+  return null;
+}
+
+async function readStdin() {
+  return new Promise((r) => {
+    let data = "";
+    process.stdin.on("data", (c) => {
+      data += c.toString();
+    });
+    process.stdin.on("end", () => r(data));
+    process.stdin.on("error", () => r(""));
+  });
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  if (payload?.hook_event_name !== "UserPromptSubmit") process.exit(0);
+
+  // ADR-131 (#209): drain EVERY repo active this session, not just cwd's. The
+  // watch hook registers each edited repo under session_id; union it with the
+  // cwd marker so single-repo behavior is unchanged when no session_id is present.
+  const cwdMarker = await findMarkerUp(process.cwd());
+  const markers = collectSessionMarkers(cwdMarker, payload?.session_id);
+  if (markers.length === 0) process.exit(0);
+
+  const messages = markers.flatMap((m) => drainPending(m));
+  if (messages.length === 0) process.exit(0);
+
+  // UserPromptSubmit context-injection contract: additionalContext is added to
+  // the model's context for the upcoming turn.
+  const out = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: joinPendingForSurface(messages),
+    },
+  });
+  process.stdout.write(`${out}\n`, () => process.exit(0));
+}
+
+main().catch(() => process.exit(0));

package/scripts/codex-pair-session.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// SessionStart / SessionEnd hook for the codex-pair app-server broker
+// (ADR-090, milestones implemented per ADR-093). SessionStart spawns
+// the broker + handshake + descriptor write (Milestone 2 PR 2);
+// SessionEnd teardown remains TODO (Milestone 2 PR 3).
+//
+// The hook MUST exit 0 on every path. A broker spawn failure is logged
+// silently to broker.log but doesn't break the session — the per-edit
+// path keeps working via per-edit codex spawns (ADR-077).
+
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { bootstrapBroker, clearStaleBrokerState, teardownBroker } from "./lib/broker-lifecycle.mjs";
+import { clearAllDebounceState } from "./lib/debounce-state.mjs";
+import {
+  appendLog,
+  clearAutoPause,
+  CONTEXT_FILENAME,
+  PAIR_ROOT_DIR,
+  readPauseInfo,
+  readPluginVersion,
+  resolveAutoResume,
+} from "./lib/state.mjs";
+import { clearSession } from "./lib/session-registry.mjs";
+
+const MARKER_FILE = join(PAIR_ROOT_DIR, CONTEXT_FILENAME);
+
+// Walk up from startDir looking for `.codex-pair/context.md`. Returns
+// the marker directory (the directory CONTAINING `.codex-pair/`) or
+// null. Mirrors codex-pair-watch.mjs and codex-pair-log.mjs — duplicated
+// because zero-workspace-imports + the helper is too small to extract
+// (15 LOC × 3 callers).
+async function findMarkerUp(startDir) {
+  const home = homedir();
+  let current = resolve(startDir);
+  for (let depth = 0; depth < 20; depth++) {
+    const candidate = join(current, MARKER_FILE);
+    try {
+      await access(candidate);
+      return current;
+    } catch {
+      // not found here
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    if (current === home) return null;
+    current = parent;
+  }
+  return null;
+}
+
+async function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.on("data", (c) => {
+      data += c.toString();
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(""));
+  });
+}
+
+async function handleSessionStart() {
+  const cwd = process.cwd();
+  const markerDir = await findMarkerUp(cwd);
+  if (!markerDir) return; // no opt-in marker, nothing to do
+  // Recover from a prior-session crash before launching fresh.
+  // clearStaleBrokerState returns "live" if a still-usable broker
+  // exists — in that case we skip spawning a new one. "absent" or
+  // "stale" both result in a clean slate; bootstrapBroker handles
+  // the spawn + handshake from there.
+  const state = clearStaleBrokerState(markerDir);
+  if (state === "live") return;
+  await bootstrapBroker(markerDir);
+}
+
+async function handleSessionEnd() {
+  const cwd = process.cwd();
+  const markerDir = await findMarkerUp(cwd);
+  if (!markerDir) return;
+  // teardownBroker reads the descriptor, SIGTERMs the pid with a grace
+  // window, escalates to SIGKILL via terminateProcessTree if needed,
+  // unlinks the descriptor + socket + lock. Returns the descriptor
+  // that was torn down (or null if none existed) — we ignore it; the
+  // hook just needs to exit 0 either way per ADR-077.
+  await teardownBroker(markerDir);
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const event = payload?.hook_event_name;
+  if (event !== "SessionStart" && event !== "SessionEnd") {
+    process.exit(0);
+  }
+
+  // SessionStart pause visibility (2026-07-02 seamless-pairing design; un-gated
+  // by the broker flag). An auto-pause used to be notify-ONCE and manual-resume-
+  // only — miss that single message and pairing is silently dead forever (the
+  // dogfood repo spent 18 days that way). Now: an expired auto-pause self-heals
+  // right here; a still-active pause gets a reminder the model actually sees
+  // (SessionStart supports additionalContext; it does NOT support systemMessage).
+  if (event === "SessionStart") {
+    try {
+      const markerDir = await findMarkerUp(process.cwd());
+      const pauseInfo = markerDir ? readPauseInfo(markerDir) : null;
+      if (pauseInfo) {
+        const decision = resolveAutoResume(pauseInfo, {
+          now: Date.now(),
+          currentVersion: readPluginVersion(),
+        });
+        let context = null;
+        // clearAutoPause aborts (false) when the sentinel changed since we
+        // read it — either a concurrent SessionStart already resumed (sentinel
+        // gone → say nothing; reviews are live) or a new pause raced in
+        // (render the reminder from CURRENT state, not the stale pauseInfo).
+        if (decision.resume && clearAutoPause(markerDir, pauseInfo)) {
+          await appendLog(markerDir, {
+            timestamp: new Date().toISOString(),
+            verdict: "auto_resumed",
+            reason: `${decision.why} (paused ${pauseInfo.at ?? "unknown"}, kind: ${pauseInfo.kind})`,
+          });
+          context = `codex-pair auto-resumed (${decision.why}): was ${pauseInfo.kind}-paused since ${pauseInfo.at ?? "unknown"}. Reviews are live again.`;
+        } else {
+          const current = decision.resume ? readPauseInfo(markerDir) : pauseInfo;
+          if (current) {
+            const since = current.manual ? "" : ` since ${current.at}`;
+            const kind = current.manual ? "manually" : `auto (${current.kind})`;
+            const reason = current.manual ? "" : ` Reason: ${current.reason}.`;
+            context = `codex-pair is paused — ${kind}${since}.${reason} Edits are NOT being reviewed. Resume with /codex-pair-resume.`;
+          }
+        }
+        if (context) {
+          await new Promise((resolveWrite) => {
+            const out = JSON.stringify({
+              hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context },
+            });
+            process.stdout.write(`${out}\n`, () => resolveWrite());
+          });
+        }
+      }
+    } catch {
+      // best-effort (ADR-077) — pause visibility must never break the session
+    }
+  }
+
+  // Edit-debounce cleanup runs on SessionEnd only (un-gated by the broker flag,
+  // since debounce is not broker-gated): a sleeping worker wakes to a missing
+  // record and self-cancels. NOT on SessionStart — that would wipe a verdict
+  // queued just before a new session begins; crash-orphaned state is reclaimed
+  // by the TTL sweep (sweepStaleDebounce) instead.
+  if (event === "SessionEnd") {
+    const dbMarkerDir = await findMarkerUp(process.cwd());
+    if (dbMarkerDir) {
+      try {
+        clearAllDebounceState(dbMarkerDir);
+      } catch {
+        // best-effort (ADR-077)
+      }
+    }
+    // ADR-131 (#209): drop this session's cross-repo marker registry. Keyed by
+    // session_id, not cwd — so it cleans up regardless of which repo cwd is.
+    try {
+      clearSession(payload?.session_id);
+    } catch {
+      // best-effort (ADR-077)
+    }
+  }
+
+  // Broker is disabled until ASK_CODEX_BROKER=1. Production behavior
+  // unchanged: SessionStart/SessionEnd are silent no-ops.
+  if (process.env.ASK_CODEX_BROKER !== "1") {
+    process.exit(0);
+  }
+
+  try {
+    if (event === "SessionStart") await handleSessionStart();
+    else if (event === "SessionEnd") await handleSessionEnd();
+  } catch {
+    // ADR-077 silent-on-error: a failed bootstrap MUST NOT break the
+    // session. bootstrapBroker already catches internally, but defense
+    // in depth.
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));