harnery 0.9.0 → 0.11.0

package/src/commands/claude-desktop.ts

@@ -0,0 +1,215 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import {
+  applyMirror,
+  type DesktopAccount,
+  findDesktopDataDirs,
+  listAccounts,
+  planMirror,
+  readCliAccount,
+} from "../lib/claude-desktop.ts";
+
+/**
+ * `claude-desktop`: make Claude desktop-app sessions survive account
+ * switches.
+ *
+ * The desktop app scopes its Claude Code session sidebar per signed-in
+ * account (plain JSON entry files under
+ * `<dataDir>/claude-code-sessions/<account-uuid>/<env-id>/`), while the
+ * transcripts live account-agnostically under `~/.claude/projects/`. A user
+ * who hops accounts (e.g. when one hits its usage limit) loses sidebar
+ * access to every session the other account created — even though the data
+ * is all still on disk. `mirror` copies the entry files across account
+ * directories so each account's sidebar lists the union; restarting the
+ * desktop app picks the copies up, and opening one resumes with full
+ * history.
+ */
+export function registerClaudeDesktopCommand(program: Command, emit: EmitContext): void {
+  const cmd = program
+    .command("claude-desktop")
+    .description(
+      "Claude desktop-app session index: list accounts/sessions, mirror sessions across accounts",
+    )
+    .action(() => {
+      const dirs = requireDataDirs(emit, undefined);
+      for (const dir of dirs) {
+        emit.data({
+          data_dir: dir,
+          accounts: listAccounts(dir).map((a) => accountSummary(a)),
+          cli_account: readCliAccount(),
+        });
+      }
+    });
+
+  cmd
+    .command("accounts")
+    .description("List account directories + session counts (labels the CLI's account when known)")
+    .option("--data-dir <path>", "Explicit desktop-app data directory")
+    .action((opts: { dataDir?: string }) => {
+      const dirs = requireDataDirs(emit, opts.dataDir);
+      const cli = readCliAccount();
+      emit.data(
+        dirs.map((dir) => ({
+          data_dir: dir,
+          accounts: listAccounts(dir).map((a) => ({
+            ...accountSummary(a),
+            is_cli_account: cli !== null && a.accountUuid === cli.accountUuid,
+            cli_email: cli !== null && a.accountUuid === cli.accountUuid ? cli.email : null,
+          })),
+        })),
+      );
+    });
+
+  cmd
+    .command("sessions")
+    .description("List session entries across every account (newest activity first)")
+    .option("--data-dir <path>", "Explicit desktop-app data directory")
+    .option("--account <uuid-prefix>", "Only this account (uuid prefix match)")
+    .option("--archived", "Include archived entries")
+    .action((opts: { dataDir?: string; account?: string; archived?: boolean }) => {
+      const dirs = requireDataDirs(emit, opts.dataDir);
+      const rows = [];
+      for (const dir of dirs) {
+        for (const account of listAccounts(dir)) {
+          if (opts.account && !account.accountUuid.startsWith(opts.account)) continue;
+          for (const e of account.entries) {
+            if (e.isArchived && !opts.archived) continue;
+            rows.push({
+              account_uuid: account.accountUuid,
+              cli_session_id: e.cliSessionId,
+              title: e.title,
+              cwd: e.cwd,
+              model: e.model,
+              archived: e.isArchived,
+              last_activity_at: e.lastActivityAt,
+            });
+          }
+        }
+      }
+      rows.sort((a, b) => (b.last_activity_at ?? 0) - (a.last_activity_at ?? 0));
+      emit.data(rows);
+    });
+
+  cmd
+    .command("mirror")
+    .description(
+      "Copy session entries across accounts so each sidebar lists the union. " +
+        "Dry-run by default; --yes applies. Restart the desktop app afterward to pick up copies.",
+    )
+    .option("--data-dir <path>", "Explicit desktop-app data directory")
+    .option(
+      "--session <id-or-title>",
+      "Only sessions matching this cliSessionId or title substring (repeatable)",
+      collect,
+      [] as string[],
+    )
+    .option("--all", "Mirror every (non-archived) session")
+    .option(
+      "--to <uuid-prefix>",
+      "Only copy INTO accounts matching this prefix (repeatable)",
+      collect,
+      [] as string[],
+    )
+    .option(
+      "--from <uuid-prefix>",
+      "Only copy FROM accounts matching this prefix (repeatable)",
+      collect,
+      [] as string[],
+    )
+    .option("--include-archived", "Also mirror archived entries")
+    .option("--yes", "Apply the plan (default is dry-run)")
+    .action(
+      (opts: {
+        dataDir?: string;
+        session: string[];
+        all?: boolean;
+        to: string[];
+        from: string[];
+        includeArchived?: boolean;
+        yes?: boolean;
+      }) => {
+        if (!opts.all && opts.session.length === 0) {
+          emit.error({
+            code: "no_selection",
+            message: "pass --session <id-or-title> (repeatable) or --all",
+          });
+          process.exit(2);
+        }
+        const dirs = requireDataDirs(emit, opts.dataDir);
+        for (const dir of dirs) {
+          const accounts = listAccounts(dir);
+          if (accounts.length < 2) {
+            emit.error({
+              code: "single_account",
+              message: `only ${accounts.length} account dir(s) under ${dir} — nothing to mirror across`,
+            });
+            process.exit(2);
+          }
+          const plan = planMirror(accounts, {
+            to: opts.to,
+            from: opts.from,
+            sessions: opts.all ? undefined : opts.session,
+            includeArchived: opts.includeArchived,
+          });
+          const planned = plan.actions.map((a) => ({
+            title: a.entry.title,
+            cli_session_id: a.entry.cliSessionId,
+            to_account: a.targetAccountUuid,
+            to_file: a.to,
+          }));
+          if (!opts.yes) {
+            emit.data({
+              data_dir: dir,
+              dry_run: true,
+              planned,
+              skipped_existing: plan.skippedExisting,
+              skipped_archived: plan.skippedArchived,
+              hint: plan.actions.length > 0 ? "re-run with --yes to apply" : "nothing to copy",
+            });
+            continue;
+          }
+          const { copied } = applyMirror(plan);
+          emit.data({
+            data_dir: dir,
+            dry_run: false,
+            copied,
+            planned,
+            skipped_existing: plan.skippedExisting,
+            skipped_archived: plan.skippedArchived,
+            hint:
+              copied > 0
+                ? "fully quit the Claude desktop app (tray icon, not the X) and relaunch to see the sessions"
+                : "nothing to copy",
+          });
+        }
+      },
+    );
+}
+
+function collect(value: string, previous: string[]): string[] {
+  return previous.concat([value]);
+}
+
+function accountSummary(a: DesktopAccount) {
+  return {
+    account_uuid: a.accountUuid,
+    sessions: a.entries.length,
+    archived: a.entries.filter((e) => e.isArchived).length,
+    latest_title: a.entries[0]?.title ?? null,
+    latest_activity_at: a.entries[0]?.lastActivityAt ?? null,
+  };
+}
+
+function requireDataDirs(emit: EmitContext, explicit: string | undefined): string[] {
+  const dirs = findDesktopDataDirs(explicit);
+  if (dirs.length === 0) {
+    emit.error({
+      code: "not_found",
+      message:
+        "no Claude desktop-app data directory with a claude-code-sessions/ index found " +
+        "(is the desktop app installed? pass --data-dir or set HARNERY_CLAUDE_DESKTOP_DIR)",
+    });
+    process.exit(2);
+  }
+  return dirs;
+}

package/src/commands/context.ts

@@ -1,5 +1,13 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { monorepoRoot, readHeartbeat, resolveOwner } from "../core/agents/index.ts";
+import {
+  type CheckpointReason,
+  checkpointContext,
+  readContextState,
+  readLatestCapsule,
+} from "../core/context/index.ts";
+import type { Harness } from "../core/hooks/events/schema.ts";
 import {
   buildContext,
   type ContextReport,
@@ -20,7 +28,7 @@ export function registerContextCommand(
   emit: EmitContext,
   context?: HarneryProgramContext,
 ): void {
-  program
+  const command = program
     .command("context")
     .description(
       `One-shot orientation snapshot: self, repo, submodules, peers, recent commits. Default sections: ${DEFAULT_SECTIONS.join(" / ")}. Opt-in: ${OPT_IN_SECTIONS.join(" / ")}.`,
@@ -68,6 +76,171 @@ export function registerContextCommand(
         }
       },
     );
+
+  command
+    .command("status")
+    .description("Show context-continuity phase, generation, and latest telemetry")
+    .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
+    .option("--instance <id>", "Agent instance id (defaults to the current owner)")
+    .option("--json", "Structured JSON output")
+    .action((opts: { session?: string; instance?: string; json?: boolean }) => {
+      try {
+        const json = opts.json || Boolean(command.opts().json);
+        const identity = resolveContinuityIdentity(context, opts);
+        const state = readContextState(identity.coordRoot, identity.sessionId);
+        if (json) {
+          emit.config({ format: "json" });
+          emit.data({ state, identity });
+          return;
+        }
+        if (!state) {
+          emit.text(`No context continuity state for session ${identity.sessionId}.\n`);
+          return;
+        }
+        const sample = state.latest_context;
+        const usage = sample
+          ? `${sample.used_tokens ?? "?"}/${sample.window_tokens ?? "?"} tokens${sample.used_percent === undefined ? "" : ` (${sample.used_percent}%)`}`
+          : "not reported by harness";
+        emit.text(
+          `${[
+            `Session:    ${state.session_id}`,
+            `Phase:      ${state.phase}`,
+            `Generation: ${state.generation}`,
+            `Telemetry:  ${usage}`,
+            `Capsule:    ${state.latest_capsule ?? "none"}`,
+            state.degraded_reason ? `Degraded:   ${state.degraded_reason}` : "",
+          ]
+            .filter(Boolean)
+            .join("\n")}\n`,
+        );
+      } catch (err) {
+        emitCommandError(emit, "context_status_failed", err);
+      }
+    });
+
+  command
+    .command("checkpoint")
+    .description("Create a durable context-continuity capsule for the current work")
+    .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
+    .option("--instance <id>", "Agent instance id (defaults to the current owner)")
+    .option("--harness <id>", "claude-code, codex, or cursor (inferred from heartbeat)")
+    .option("--reason <reason>", "manual, pressure, pre_compact, or session_end", "manual")
+    .option("--note <text>", "Short continuation note for the recovered agent")
+    .option("--json", "Structured JSON output")
+    .action(
+      (opts: {
+        session?: string;
+        instance?: string;
+        harness?: string;
+        reason: string;
+        note?: string;
+        json?: boolean;
+      }) => {
+        try {
+          const json = opts.json || Boolean(command.opts().json);
+          const reason = parseCheckpointReason(opts.reason);
+          const identity = resolveContinuityIdentity(context, opts);
+          if (!identity.harness) {
+            throw new Error("could not infer the harness; pass --harness claude-code|codex|cursor");
+          }
+          const result = checkpointContext(identity.coordRoot, {
+            sessionId: identity.sessionId,
+            instanceId: identity.instanceId,
+            harness: identity.harness,
+            cwd: context?.repoRoot ?? process.cwd(),
+            reason,
+            continuationNote: opts.note,
+          });
+          const output = {
+            capsule_id: result.capsule.capsule_id,
+            generation: result.capsule.generation,
+            path: result.state.latest_capsule,
+            phase: result.state.phase,
+            reused: result.reused,
+          };
+          if (json) {
+            emit.config({ format: "json" });
+            emit.data(output);
+            return;
+          }
+          emit.text(
+            `Checkpointed context generation ${output.generation}: ${output.path ?? result.path}\n`,
+          );
+        } catch (err) {
+          emitCommandError(emit, "context_checkpoint_failed", err);
+        }
+      },
+    );
+
+  command
+    .command("show")
+    .description("Show the latest durable context-continuity capsule")
+    .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
+    .option("--instance <id>", "Agent instance id (defaults to the current owner)")
+    .option("--json", "Structured JSON output")
+    .action((opts: { session?: string; instance?: string; json?: boolean }) => {
+      try {
+        const json = opts.json || Boolean(command.opts().json);
+        const identity = resolveContinuityIdentity(context, opts);
+        const capsule = readLatestCapsule(identity.coordRoot, identity.sessionId);
+        if (!capsule) {
+          throw new Error(`no context capsule exists for session ${identity.sessionId}`);
+        }
+        if (json) emit.config({ format: "json" });
+        emit.data(capsule);
+      } catch (err) {
+        emitCommandError(emit, "context_show_failed", err);
+      }
+    });
+}
+
+function resolveContinuityIdentity(
+  context: HarneryProgramContext | undefined,
+  opts: { session?: string; instance?: string; harness?: string },
+): { coordRoot: string; instanceId: string; sessionId: string; harness: Harness | null } {
+  const coordRoot = context?.resolveCoordRoot?.() ?? context?.repoRoot ?? monorepoRoot();
+  if (!coordRoot) throw new Error("could not resolve a project containing .harnery/");
+  const instanceId = opts.instance ?? resolveOwner();
+  if (!instanceId) {
+    throw new Error("could not resolve the current agent; pass --instance and --session");
+  }
+  const heartbeat = readHeartbeat(instanceId);
+  const sessionId = opts.session ?? heartbeat?.session_id ?? instanceId;
+  const harness = opts.harness
+    ? parseHarness(opts.harness)
+    : harnessFromPlatform(heartbeat?.platform);
+  return { coordRoot, instanceId, sessionId, harness };
+}
+
+function harnessFromPlatform(platform: string | undefined): Harness | null {
+  if (platform === "claude_code" || platform === "claude-code") return "claude-code";
+  if (platform === "cursor") return "cursor";
+  if (platform === "codex") return "codex";
+  return null;
+}
+
+function parseHarness(value: string): Harness {
+  if (value === "claude-code" || value === "codex" || value === "cursor") return value;
+  throw new Error(`invalid harness "${value}"; expected claude-code, codex, or cursor`);
+}
+
+function parseCheckpointReason(value: string): CheckpointReason {
+  if (
+    value === "manual" ||
+    value === "pressure" ||
+    value === "pre_compact" ||
+    value === "session_end"
+  ) {
+    return value;
+  }
+  throw new Error(
+    `invalid reason "${value}"; expected manual, pressure, pre_compact, or session_end`,
+  );
+}
+
+function emitCommandError(emit: EmitContext, code: string, err: unknown): void {
+  emit.error({ code, message: err instanceof Error ? err.message : String(err) });
+  emit.setExitCode(1);
 }
 
 function collectSections(value: string, prev: SectionName[]): SectionName[] {

package/src/commands/doctor.ts

@@ -18,6 +18,7 @@ import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
+import { BUILTIN_HARNESS_IDS } from "../core/harnesses/index.ts";
 import { loadHarnessWiring } from "../core/hooks/harness/wiring.ts";
 import { probeBilling } from "../core/workflow/billing.ts";
 import {
@@ -103,9 +104,7 @@ export function runChecks(): Check[] {
     checkRipgrep(),
     checkHarneryDir(),
     checkHarnessHooks(),
-    checkWorkflowHarness("claude-code"),
-    checkWorkflowHarness("codex"),
-    checkWorkflowHarness("cursor"),
+    ...BUILTIN_HARNESS_IDS.map(checkWorkflowHarness),
     checkRestic(),
     checkRclone(),
     checkPlaywright(),

package/src/commands/eml.ts

@@ -27,7 +27,7 @@ export function registerEmlCommand(program: Command, emit: EmitContext): void {
     .argument("<file>", "Path to the .eml file")
     .option("-o, --output <path>", "Write output to a file instead of stdout")
     .option("--format <type>", "Output format: markdown, json", "markdown")
-    .option("--headers", "Include full email headers per message")
+    .option("--headers", "Include the source message's full email headers")
     .option("--attachments", "List attachment filenames and sizes")
     .action(async (file: string, opts: EmlOpts) => {
       try {
@@ -40,7 +40,7 @@ export function registerEmlCommand(program: Command, emit: EmitContext): void {
     });
 }
 
-interface EmlOpts {
+export interface EmlOpts {
   output?: string;
   format: string;
   headers?: boolean;
@@ -88,7 +88,7 @@ async function handleEml(file: string, opts: EmlOpts, emit: EmitContext): Promis
  * Extract individual messages from the parsed email.
  * Strategy: use HTML body (Gmail quote structure) first, fall back to plain text.
  */
-function extractThread(parsed: ParsedMail): ThreadMessage[] {
+export function extractThread(parsed: ParsedMail): ThreadMessage[] {
   if (parsed.html && typeof parsed.html === "string") {
     const messages = extractFromHtml(parsed.html, parsed);
     if (messages.length > 0) return messages;
@@ -451,7 +451,11 @@ function formatAddress(addr: ParsedMail["from"]): string {
 /**
  * Render the thread as markdown.
  */
-function renderMarkdown(parsed: ParsedMail, messages: ThreadMessage[], opts: EmlOpts): string {
+export function renderMarkdown(
+  parsed: ParsedMail,
+  messages: ThreadMessage[],
+  opts: EmlOpts,
+): string {
   const subject = parsed.subject ?? "Untitled Thread";
   const participants = new Map<string, boolean>();
   for (const m of messages) {
@@ -471,6 +475,20 @@ function renderMarkdown(parsed: ParsedMail, messages: ThreadMessage[], opts: Eml
   lines.push(`**Date range:** ${minDate} to ${maxDate}`);
   lines.push(`**Messages:** ${messages.length}`);
 
+  if (opts.headers && parsed.headerLines?.length) {
+    // A Gmail thread export is a SINGLE .eml (older messages are quoted HTML,
+    // not separate MIME parts), so there is one real header set — the source
+    // message's. Render it verbatim.
+    lines.push("");
+    lines.push("**Source headers:**");
+    lines.push("");
+    lines.push("```");
+    for (const h of parsed.headerLines) {
+      lines.push(h.line);
+    }
+    lines.push("```");
+  }
+
   if (opts.attachments && parsed.attachments?.length) {
     lines.push("");
     lines.push("**Attachments:**");

package/src/commands/harness.ts

@@ -0,0 +1,147 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import {
+  type BenchResult,
+  createBuiltinHarnessRegistry,
+  type HarnessBenchReport,
+  runHarnessBench,
+} from "../core/harnesses/index.ts";
+import type { HarnessProfile } from "../core/harnesses/types.ts";
+
+interface FormatOpts {
+  json?: boolean;
+}
+
+interface BenchOpts extends FormatOpts {
+  requireInstalled?: boolean;
+}
+
+const registry = createBuiltinHarnessRegistry();
+
+export function registerHarnessCommand(program: Command, emit: EmitContext): void {
+  const command = program
+    .command("harness")
+    .description("Inspect registered harness capabilities and run their conformance bench.");
+
+  command
+    .command("list")
+    .description("List registered harness adapters and their high-signal capability claims.")
+    .option("--json", "Machine-readable profile catalog")
+    .action((opts: FormatOpts) => {
+      const profiles = registry.list().map((adapter) => adapter.profile);
+      if (opts.json) {
+        emit.config({ format: "json" });
+        emit.data({ harnesses: profiles });
+      } else {
+        emit.text(renderProfileTable(profiles));
+      }
+    });
+
+  command
+    .command("show <id>")
+    .description("Show one harness's complete capability declaration.")
+    .option("--json", "Machine-readable profile")
+    .action((id: string, opts: FormatOpts) => {
+      const adapter = registry.get(id);
+      if (!adapter) {
+        emit.error({
+          code: "unknown_harness",
+          message: `unknown harness ${JSON.stringify(id)} (registered: ${registry.ids().join(", ")})`,
+        });
+        emit.setExitCode(1);
+        return;
+      }
+      if (opts.json) {
+        emit.config({ format: "json" });
+        emit.data(adapter.profile);
+      } else {
+        emit.text(renderProfile(adapter.profile));
+      }
+    });
+
+  command
+    .command("bench [harnesses...]")
+    .description("Run the offline adapter-contract bench (no model calls); drift exits non-zero.")
+    .option("--require-installed", "Also fail when a registered vendor CLI is missing")
+    .option("--json", "Machine-readable conformance report")
+    .action((harnesses: string[], opts: BenchOpts) => {
+      try {
+        const report = runHarnessBench(registry, { harnesses });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(report);
+        } else {
+          emit.text(renderBenchReport(report));
+        }
+        emit.setExitCode(report.drift || (opts.requireInstalled && report.skipped) ? 1 : 0);
+      } catch (error) {
+        emit.error({ code: "harness_bench_failed", message: (error as Error).message });
+        emit.setExitCode(1);
+      }
+    });
+}
+
+export function renderProfileTable(profiles: readonly HarnessProfile[]): string {
+  const rows = profiles.map((profile) => [
+    profile.id,
+    profile.binary,
+    profile.capabilities.modelSelection.support,
+    profile.capabilities.effortSelection.support,
+    profile.capabilities.sessionId.support,
+    profile.capabilities.cost.support,
+  ]);
+  return renderTable(["HARNESS", "BINARY", "MODEL", "EFFORT", "SESSION", "COST"], rows);
+}
+
+export function renderProfile(profile: HarnessProfile): string {
+  const lines = [
+    `${profile.displayName} (${profile.id})`,
+    `binary: ${profile.binary}`,
+    `integration: ${profile.integrationMode}`,
+    `auth: ${profile.authModel}`,
+    `model family: ${profile.modelFamily}`,
+    `effort values: ${profile.effortValues.join(", ") || "none"}`,
+    profile.verified
+      ? `verified: ${profile.verified.date} (${profile.verified.version})`
+      : "verified: not recorded",
+    "",
+    "capabilities:",
+  ];
+  for (const [dimension, claim] of Object.entries(profile.capabilities)) {
+    lines.push(`  ${dimension.padEnd(18)} ${claim.support}${claim.note ? ` — ${claim.note}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderBenchReport(report: HarnessBenchReport): string {
+  const rows = report.results.map((result) => [
+    result.harness,
+    result.dimension,
+    result.declared,
+    result.observed,
+    result.verdict,
+  ]);
+  const table = renderTable(["HARNESS", "DIMENSION", "DECLARED", "OBSERVED", "VERDICT"], rows);
+  const summary = Object.entries(report.summary)
+    .filter(([, count]) => count > 0)
+    .map(([verdict, count]) => `${verdict}=${count}`)
+    .join(", ");
+  return `${table}\n\nmode: ${report.mode} (no model calls)\n${summary}`;
+}
+
+function renderTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)),
+  );
+  const line = (cells: string[]) =>
+    cells
+      .map((cell, index) => cell.padEnd(widths[index]))
+      .join("  ")
+      .trimEnd();
+  return [line(headers), line(widths.map((width) => "-".repeat(width))), ...rows.map(line)].join(
+    "\n",
+  );
+}
+
+/** Kept exported so command tests can assert row semantics without model calls. */
+export type { BenchResult };