harnery 0.35.0 → 0.37.0

package/src/commands/diagnostics.ts

@@ -0,0 +1,271 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { monorepoRoot, resolveOwner } from "../core/agents/index.ts";
+import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
+import type { ArtifactActor } from "../core/artifacts/index.ts";
+import {
+  buildDiagnosticAdvice,
+  captureDiagnosticBundle,
+  compareDiagnosticBundles,
+  DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+  listDiagnosticBundles,
+  renderDiagnosticBundleComparison,
+  replayDiagnosticBundle,
+  showDiagnosticBundle,
+} from "../core/diagnostics/index.ts";
+import {
+  buildSupervisorTimeline,
+  explainSupervisorFinding,
+  readSupervisorExplanation,
+  readSupervisorFindings,
+  readSupervisorStatus,
+  readSupervisorTimeline,
+  type SupervisorCapability,
+  type SupervisorFinding,
+} from "../core/supervisor/index.ts";
+
+export function registerDiagnosticsCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const root = program
+    .command("diagnostics")
+    .description("Capture, inspect, and replay sanitized local diagnostic bundles.");
+
+  root
+    .command("list")
+    .description("List live findings and managed diagnostic bundles.")
+    .action(() => {
+      run(emit, () => {
+        const repoRoot = requireRepoRoot(context);
+        const report = readSupervisorFindings(repoRoot);
+        const findings = mergeFindings(report?.active ?? [], report?.transitions ?? []);
+        const bundles = listDiagnosticBundles(repoRoot);
+        const capability = liveFindingsCapability(repoRoot, report !== undefined);
+        emit.data({
+          schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+          kind: "diagnostic_list",
+          findings,
+          bundles,
+          capability,
+          total_findings: findings.length,
+          total_bundles: bundles.length,
+        });
+      });
+    });
+
+  root
+    .command("show <ref>")
+    .description("Show one finding or validate one diagnostic bundle.")
+    .action((ref: string) => {
+      run(emit, () => {
+        const repoRoot = requireRepoRoot(context);
+        const finding = findFinding(repoRoot, ref);
+        if (finding) {
+          emit.data({
+            schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+            kind: "diagnostic_finding",
+            finding,
+            timeline:
+              readSupervisorTimeline(repoRoot, finding.id) ?? buildSupervisorTimeline(finding),
+            explanation:
+              readSupervisorExplanation(repoRoot, finding.id) ?? explainSupervisorFinding(finding),
+          });
+          return;
+        }
+        const bundle = showDiagnosticBundle(repoRoot, ref);
+        emit.data({
+          schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+          kind: "diagnostic_bundle",
+          bundle: {
+            path: bundle.path,
+            manifest: bundle.manifest,
+            summary: bundle.summary,
+          },
+        });
+      });
+    });
+
+  root
+    .command("explain")
+    .description("Report bounded local pressure advice without taking action.")
+    .option("--bundle <artifact-ref>", "Use a frozen diagnostic bundle instead of live state")
+    .option("--json", "Emit structured JSON")
+    .action((opts: { bundle?: string; json?: boolean }) => {
+      run(emit, () => {
+        if (opts.json) emit.config({ format: "json" });
+        const repoRoot = requireRepoRoot(context);
+        if (opts.bundle) {
+          const bundle = showDiagnosticBundle(repoRoot, opts.bundle);
+          emit.data({
+            schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+            kind: "diagnostic_advice",
+            source: {
+              mode: "frozen",
+              artifact_id: bundle.manifest.artifact_id,
+              captured_at: bundle.manifest.captured_at,
+            },
+            advice: bundle.expected.advice,
+          });
+          return;
+        }
+        const report = readSupervisorFindings(repoRoot);
+        const findings = mergeFindings(report?.active ?? [], report?.transitions ?? []);
+        const sourceCapability = liveFindingsCapability(repoRoot, report !== undefined);
+        emit.data({
+          schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+          kind: "diagnostic_advice",
+          source: { mode: "live" },
+          advice: buildDiagnosticAdvice({
+            findings,
+            sourceCapability,
+            evaluatedAt: new Date().toISOString(),
+          }),
+        });
+      });
+    });
+
+  root
+    .command("capture")
+    .description("Capture sanitized supervisor inputs into a frozen managed bundle.")
+    .option("--finding <id>", "Capture the time range for one finding")
+    .option("--from <timestamp>", "Capture observations from this ISO timestamp")
+    .option("--to <timestamp>", "Capture observations through this ISO timestamp")
+    .option("--days <n>", "Managed artifact retention in days")
+    .action((opts: { finding?: string; from?: string; to?: string; days?: string }) => {
+      run(emit, () => {
+        const repoRoot = requireRepoRoot(context);
+        const captured = captureDiagnosticBundle(repoRoot, {
+          findingId: opts.finding,
+          startAt: opts.from,
+          endAt: opts.to,
+          retentionDays: opts.days === undefined ? undefined : parseDays(opts.days),
+          actor: currentActor(repoRoot),
+        });
+        emit.data({
+          schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+          kind: "diagnostic_bundle_capture",
+          bundle: {
+            path: captured.path,
+            artifact_id: captured.manifest.artifact_id,
+            captured_at: captured.manifest.captured_at,
+            finding_id: captured.manifest.finding_id,
+            summary: captured.summary,
+          },
+        });
+      });
+    });
+
+  root
+    .command("replay <artifact-ref>")
+    .description("Replay a frozen bundle without reading live supervisor state.")
+    .action((ref: string) => {
+      run(emit, () => {
+        emit.data({
+          schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+          kind: "diagnostic_bundle_replay",
+          replay: replayDiagnosticBundle(requireRepoRoot(context), ref),
+        });
+      });
+    });
+
+  root
+    .command("compare <before> <after>")
+    .description("Compare two frozen bundles without reading live supervisor state.")
+    .option("--json", "Emit structured JSON")
+    .action((before: string, after: string, opts: { json?: boolean }) => {
+      run(emit, () => {
+        const comparison = compareDiagnosticBundles(requireRepoRoot(context), before, after);
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data({
+            schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
+            kind: "diagnostic_bundle_comparison",
+            comparison,
+          });
+          return;
+        }
+        emit.text(renderDiagnosticBundleComparison(comparison));
+      });
+    });
+}
+
+function liveFindingsCapability(repoRoot: string, reportPresent: boolean): SupervisorCapability {
+  if (!reportPresent) {
+    return {
+      source_kind: "supervisor.findings",
+      state: "unsupported",
+      reason_code: "source_missing",
+    };
+  }
+  const status = readSupervisorStatus(repoRoot);
+  if (status.running) return { source_kind: "supervisor.findings", state: "supported" };
+  return {
+    source_kind: "supervisor.findings",
+    state: "expired",
+    reason_code: status.stale
+      ? "supervisor_status_stale"
+      : status.record
+        ? "supervisor_not_running"
+        : "supervisor_status_missing",
+  };
+}
+
+function findFinding(repoRoot: string, id: string): SupervisorFinding | undefined {
+  const report = readSupervisorFindings(repoRoot);
+  return mergeFindings(report?.active ?? [], report?.transitions ?? []).find(
+    (finding) => finding.id === id,
+  );
+}
+
+function mergeFindings(
+  active: readonly SupervisorFinding[],
+  transitions: readonly SupervisorFinding[],
+): SupervisorFinding[] {
+  const byId = new Map<string, SupervisorFinding>();
+  for (const finding of transitions) byId.set(finding.id, finding);
+  for (const finding of active) byId.set(finding.id, finding);
+  return [...byId.values()].sort(
+    (left, right) =>
+      Date.parse(right.observed_at) - Date.parse(left.observed_at) ||
+      left.id.localeCompare(right.id),
+  );
+}
+
+function currentActor(repoRoot: string): ArtifactActor | undefined {
+  const instanceId = resolveOwner();
+  if (!instanceId) return undefined;
+  const heartbeat = readLiveCoordinationRow(repoRoot, instanceId);
+  return {
+    instance_id: instanceId,
+    session_id: heartbeat?.session_id,
+    name: heartbeat?.name,
+  };
+}
+
+function requireRepoRoot(context?: HarneryProgramContext): string {
+  const root = context?.repoRoot ?? monorepoRoot();
+  if (!root) throw new Error("not inside a Git repository");
+  return root;
+}
+
+function parseDays(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 3_650) {
+    throw new Error("--days must be between 1 and 3650");
+  }
+  return parsed;
+}
+
+function run(emit: EmitContext, fn: () => void): void {
+  try {
+    fn();
+  } catch (error) {
+    emit.error({
+      code: "diagnostics_failed",
+      message: error instanceof Error ? error.message : String(error),
+    });
+    emit.setExitCode(1);
+  }
+}

package/src/commands/docs.ts

@@ -92,10 +92,14 @@ export function registerDocsCommand(
     .command("validate")
     .description("Validate every managed Markdown file against harnery-doc/v2")
     .option("--repo <name>", "Limit to one submodule or '.' for parent")
-    .action(async (opts: { repo?: string }) => {
+    .option("--cached", "Read paths and contents from the Git index")
+    .action(async (opts: { repo?: string; cached?: boolean }) => {
       try {
         ensureContext(context);
-        const rows = await runDocsMetadataAudit(opts);
+        const rows = await runDocsMetadataAudit({
+          repo: opts.repo,
+          source: opts.cached ? "index" : "worktree",
+        });
         const errors = rows
           .flatMap((row) => row.issues)
           .filter((issue) => issue.severity === "error");
@@ -128,9 +132,13 @@ export function registerDocsCommand(
     .argument("[files...]", "Explicit repository-relative Markdown files; defaults to staged files")
     .option("--repo <name>", "Limit to one submodule or '.' for parent")
     .option("--check", "Report timestamp drift without writing")
+    .option("--cached", "Read current contents from the Git index (requires --check)")
     .option("--reviewed", "Record an explicit runbook review and move its due date")
     .action(
-      async (files: string[], opts: { repo?: string; check?: boolean; reviewed?: boolean }) => {
+      async (
+        files: string[],
+        opts: { repo?: string; check?: boolean; cached?: boolean; reviewed?: boolean },
+      ) => {
         try {
           ensureContext(context);
           const rows = await runDocsMetadataSync({ ...opts, files });
@@ -194,8 +202,9 @@ export function registerDocsCommand(
     )
     .option("--fast", "Skip content-reading checks; filename/structure only (for pre-commit)")
     .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--cached", "Read paths and contents from the Git index")
     .option("--format <type>", "Output format: human, json", "human")
-    .action(async (opts: { fast?: boolean; repo?: string; format: string }) => {
+    .action(async (opts: { fast?: boolean; repo?: string; cached?: boolean; format: string }) => {
       try {
         ensureContext(context);
         await handleLint(opts);
@@ -311,8 +320,17 @@ async function handleDocs(opts: {
 
 // --- `harn docs lint` ---
 
-async function handleLint(opts: { fast?: boolean; repo?: string; format: string }): Promise<void> {
-  const violations = await runLint({ fast: opts.fast, repo: opts.repo });
+async function handleLint(opts: {
+  fast?: boolean;
+  repo?: string;
+  cached?: boolean;
+  format: string;
+}): Promise<void> {
+  const violations = await runLint({
+    fast: opts.fast,
+    repo: opts.repo,
+    source: opts.cached ? "index" : "worktree",
+  });
   const errors = violations.filter((v) => v.severity === "error");
   const warnings = violations.filter((v) => v.severity === "warning");
   const cold = await countColdHandoffs();
@@ -320,6 +338,7 @@ async function handleLint(opts: { fast?: boolean; repo?: string; format: string
   emit.data({
     fast: !!opts.fast,
     repo: opts.repo ?? null,
+    source: opts.cached ? "index" : "worktree",
     error_count: errors.length,
     warning_count: warnings.length,
     cold_handoffs: cold,

package/src/commands/doctor.ts

@@ -12,13 +12,17 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.ts";
 import { resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
+import {
+  countSummarizedSinceV3,
+  listDiagnosticSummariesV3,
+} from "../core/events/v3/producers/diagnostic-summaries.ts";
 import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
 import { loadAdapterWiring, summarizeAdapterWiring } from "../core/hooks/adapter/wiring.ts";
 import {
@@ -107,8 +111,10 @@ export function registerDoctorCommand(program: Command, emit: EmitContext): void
 }
 
 export async function runChecks(): Promise<Check[]> {
+  const root = findCoordProjectRoot();
   const codexWslStatus = inspectCodexWslBridge();
-  const codexWslBridge = checkCodexWslBridge(codexWslStatus);
+  const recentCodexMidFlightCount = root ? countRecentCodexMidFlightOnboardings(root) : 0;
+  const codexWslBridge = codexWslBridgeCheck(codexWslStatus, recentCodexMidFlightCount);
   // Probe the adapter CLIs before the hook check runs, not in output order:
   // an unwired adapter only matters if its CLI is actually installed, and
   // probing once here keeps that join to one spawn per CLI.
@@ -163,18 +169,78 @@ function checkGitHookRegions(): Check {
   }
 }
 
-function checkCodexWslBridge(status: CodexWslBridgeStatus | null): Check | null {
-  if (!status) return null;
+export function codexWslBridgeCheck(
+  status: CodexWslBridgeStatus | null,
+  recentMidFlightCount = 0,
+): Check | null {
+  if (!status && recentMidFlightCount === 0) return null;
+  const historical =
+    recentMidFlightCount === 0
+      ? null
+      : `${recentMidFlightCount} Codex mid-flight onboarding${recentMidFlightCount === 1 ? "" : "s"} recorded in the last 48h`;
   return {
     name: "codex:WSL bridge",
-    severity: status.ok ? "ok" : "warn",
-    detail: status.detail,
-    hint: status.ok
-      ? undefined
-      : "forward CODEX_THREAD_ID through WSLENV in the Codex shell environment policy, then start a fresh task",
+    severity: status?.ok && !historical ? "ok" : "warn",
+    detail: [status?.detail, historical].filter(Boolean).join("; "),
+    hint:
+      status?.ok && !historical
+        ? undefined
+        : "forward CODEX_THREAD_ID through WSLENV in the Codex shell environment policy, then start a fresh task",
   };
 }
 
+const CODEX_MID_FLIGHT_HISTORY_WINDOW_MS = 48 * 60 * 60 * 1000;
+
+/** Count bounded, privacy-safe recovery diagnostics so a healthy environment
+ * now does not hide an intermittent Codex-to-WSL identity drop. */
+export function countRecentCodexMidFlightOnboardings(
+  coordRoot: string,
+  nowMs = Date.now(),
+  windowMs = CODEX_MID_FLIGHT_HISTORY_WINDOW_MS,
+): number {
+  // Occurrences past the producer's loose-exemplar bound live in summary
+  // files instead of loose diagnostics; count them too so the mitigation
+  // cannot hide an active Codex identity drop from this warning.
+  let count = 0;
+  try {
+    const listing = listDiagnosticSummariesV3(coordRoot);
+    count += countSummarizedSinceV3(
+      listing.summaries,
+      nowMs - windowMs,
+      (summary) =>
+        summary.category === "mid_flight_onboarding" && summary.metadata.adapter === "codex",
+      nowMs,
+    );
+  } catch {
+    // Summary reads are best-effort; loose diagnostics below still count.
+  }
+  const directory = path.join(coordRoot, ".harnery", "ledgers", "v3", "diagnostics");
+  if (!existsSync(directory)) return count;
+  for (const name of readdirSync(directory)) {
+    if (!name.startsWith("mid_flight_onboarding-") || !name.endsWith(".json")) continue;
+    try {
+      const row = JSON.parse(readFileSync(path.join(directory, name), "utf8")) as {
+        recorded_at?: unknown;
+        category?: unknown;
+        adapter?: unknown;
+      };
+      const recordedAt = typeof row.recorded_at === "string" ? Date.parse(row.recorded_at) : NaN;
+      if (
+        row.category === "mid_flight_onboarding" &&
+        row.adapter === "codex" &&
+        Number.isFinite(recordedAt) &&
+        recordedAt <= nowMs &&
+        nowMs - recordedAt <= windowMs
+      ) {
+        count += 1;
+      }
+    } catch {
+      // A malformed best-effort diagnostic cannot make doctor fail.
+    }
+  }
+  return count;
+}
+
 export function codexAuthorizationCheck(result: CodexHookAuthorizationResult): Check {
   const reviewHint =
     "terminal UI: run `/hooks`; Codex Desktop: open Settings > Hooks; after approval, start a fresh task";

package/src/commands/fetch.ts

@@ -86,7 +86,7 @@ async function runFetch(
   const timeoutMs = Number.parseInt(opts.timeout, 10);
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), timeoutMs);
-  let result: Awaited<ReturnType<typeof fetchWithJar>>;
+  let result: Awaited<ReturnType<typeof fetchWithJar<"bytes">>>;
   try {
     result = await fetchWithJar(url, {
       method: opts.method,
@@ -96,13 +96,14 @@ async function runFetch(
       redirect: opts.redirect as RequestRedirect,
       signal: ac.signal,
       extraHeaders: context?.extraHeaders,
+      responseType: "bytes",
     });
   } finally {
     clearTimeout(timer);
   }
 
   if (opts.json) {
-    emit.data(result as unknown as Record<string, unknown>);
+    emit.data({ ...result, body: new TextDecoder().decode(result.body) });
     return;
   }
   if (opts.status) {
@@ -117,14 +118,14 @@ async function runFetch(
   if (opts.output) {
     writeFileSync(opts.output, result.body);
     emit.file(opts.output, {
-      bytes: result.body.length,
+      bytes: result.body.byteLength,
       status: result.status,
       status_text: result.statusText,
     });
   } else {
-    // Body is potentially binary; route as text since most fetch responses
-    // are text/HTML/JSON. Binary callers should use --output.
-    emit.text(result.body);
+    // Text destinations decode at the presentation boundary. File output
+    // above keeps the response bytes intact regardless of MIME type.
+    emit.text(new TextDecoder().decode(result.body));
   }
 
   if (jar && result.cookiesSaved > 0) {