harnery 0.6.0 → 0.7.1

package/README.md

@@ -7,23 +7,24 @@
 
 # Harnery
 
-> Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.
+> Multi-agent coordination for AI coding agents — Claude Code, Cursor, and Codex.
 
 [![CI](https://github.com/ryanjkelly/harnery/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanjkelly/harnery/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/harnery.svg)](https://www.npmjs.com/package/harnery)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> ⚠️ **Pre-1.0.** API surface is still settling. Pin a specific minor version (`harnery@^0.1.0`) and read the [CHANGELOG](CHANGELOG.md) before each upgrade.
+> ⚠️ **Pre-1.0.** API surface is still settling. Pin a specific minor version (`harnery@^0.7.0`) and read the [CHANGELOG](CHANGELOG.md) before each upgrade.
 
 ## What it is
 
-`harnery` is a utility layer extracted from years of building agent tooling across a multi-project monorepo. It bundles:
+`harnery` keeps multiple AI coding agents from stepping on each other in a shared checkout. It was extracted from years of running several Claude Code / Cursor / Codex sessions at once against the same monorepo:
 
-- **Multi-agent coordination:** per-agent heartbeats in `.harnery/active/`, claim-time and commit-time guards, the canonical event stream, harness adapters for Claude Code / Cursor / Codex.
-- **Portable CLI utilities:** `tokens`, `eml`, `env`, `grep`, `docs`, `repo`, `wip`, `share`, `browse`, `fetch`, `read`, and more. Cross-platform and dependency-light, with sensible defaults out of the box.
-- **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, and per-project state. Ships with the git clone, not the npm package (see [Install](#install)).
+- **Multi-agent coordination:** per-agent heartbeats in `.harnery/active/`, claim-time and commit-time guards, the canonical event stream, councils, a decision docket, per-agent scratchpads, and harness adapters for Claude Code / Cursor / Codex.
+- **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, per-project state, and a local coding-agent status view (Claude Code / Codex / Cursor usage, backed by `harn devtools`). Ships with the git clone, not the npm package (see [Install](#install)).
 - **Backup + sync:** `harn backup` snapshots `.harnery/` via [restic](https://restic.net/); `harn sync` keeps a curated subset live across machines via [rclone](https://rclone.org/) (Google Drive or any rclone remote).
 
+The CLI also ships batteries: portable utility commands (`tokens`, `eml`, `env`, `grep`, `docs`, `browse`, `fetch`, `read`, `devtools`, and more) plus the library toolkit they're built from. Useful, cross-platform, dependency-light — and deliberately not the headline. Coordination is why harnery exists; the toolkit exists because the CLI needed it (see [Public surface tiers](#public-surface-tiers)).
+
 ## Install
 
 ```bash
@@ -80,6 +81,15 @@ await program.parseAsync(process.argv);
 
 `mycli agents status` then resolves to **the same code** as `harn agents status`, loaded as a library. See [examples/extending-with-commander.ts](examples/extending-with-commander.ts) for the full pattern.
 
+### Public surface tiers
+
+The exports map draws the line between what harnery *is* and what it *ships with*:
+
+- **Product tier** — `harnery`, `harnery/commander`, `harnery/core/*`: the coordination layer and CLI composition. This is the API to build against, and the reason to install harnery.
+- **Toolkit tier** — every `harnery/lib/*` subpath (`http`, `cookies`, `format`, `readability`, `browser`, `machine`, …): the supporting utilities harnery's own CLI is built from, exposed for embedding hosts that want to lean on them. Supported, but secondary: it can evolve faster than the product tier, and it isn't a reason to adopt harnery on its own.
+
+The boundary is enforced, not aspirational: CI verifies that no `harnery/lib/*` export imports the coordination core, directly or transitively (`scripts/check-layering.ts`), so pulling a toolkit module never drags in coordination state. Details: [Embedding + surface tiers](https://harnery.com/concepts/embedding/).
+
 ## Documentation
 
 Full docs at **[harnery.com](https://harnery.com)**:

package/dist/commander.d.ts

@@ -42,6 +42,18 @@ export interface HarneryContextOpts {
      */
     skipCommands?: readonly string[];
 }
+/** One row in a `harn env` section report. */
+export interface EnvCheck {
+    label: string;
+    value: string;
+    status?: "ok" | "missing" | "warn" | "info";
+}
+/**
+ * A `harn env` section: an async probe returning its rows. Hosts register extra
+ * sections (e.g. cloud-provider connectivity) via `context.envSections`; harnery
+ * core ships only the generic sections (runtimes, docker, git).
+ */
+export type EnvSection = () => Promise<EnvCheck[]>;
 export interface HarneryProgramContext {
     /** Project name (e.g., "my-monorepo"). Used in user-facing log lines + telemetry tags. */
     projectName?: string;
@@ -59,6 +71,13 @@ export interface HarneryProgramContext {
      * submodule row.
      */
     submodules?: readonly string[];
+    /**
+     * Extra `harn env` sections keyed by name (e.g. `{ gcp, bq }`). Merged into
+     * the built-in generic sections (runtimes, docker, git), so a host can expose
+     * `harn env <name>` for its own environment probes without harnery core
+     * carrying provider-specific checks. harn standalone ships none.
+     */
+    envSections?: Record<string, EnvSection>;
     /**
      * Optional callback that returns extra HTTP headers to attach to outbound
      * `fetch` calls based on the target URL. Useful for consumers that need

package/dist/commander.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEhC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IACrF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACpE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,eAAO,MAAM,WAAW,EAAE,WAkCzB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CA4C3E"}
+{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"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"}

package/dist/commander.js

@@ -28,6 +28,7 @@ import { registerContextCommand } from "./commands/context.js";
 import { registerCookiesCommand } from "./commands/cookies.js";
 import { registerDecisionCommand } from "./commands/decision.js";
 import { registerDeinitCommand } from "./commands/deinit.js";
+import { registerDevtoolsCommand } from "./commands/devtools.js";
 import { registerDocsCommand } from "./commands/docs.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerEditBatchCommand } from "./commands/edit-batch.js";
@@ -112,6 +113,7 @@ export function createHarneryProgram(opts = {}) {
     registerContextCommand(program, emit, opts.context);
     registerScratchCommand(program, emit);
     registerDecisionCommand(program, emit);
+    registerDevtoolsCommand(program, emit);
     registerTunnelCommand(program, emit, opts.context);
     registerDocsCommand(program, emit, opts.context);
     registerAgentsCommand(program, emit);

package/dist/commands/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAuFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA6OpF"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAwFnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA4OpF"}

package/dist/commands/agents.js

@@ -17,16 +17,16 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync,
 import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { readStreamTailBounded } from "../core/agents/events/consume.js";
-import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerWithSource, } from "../core/agents/index.js";
+import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, } from "../core/agents/index.js";
 import { resolveBinName } from "../core/config.js";
 /** Cap for CLI scans of the unbounded event ledger (`trace` / `health`). Well
  * under V8's ~512MB max string length so a `readFileSync` of the whole file can
  * never throw; covers ample recent history for a diagnostic scan. */
 const STREAM_SCAN_CAP_BYTES = 128 * 1024 * 1024; // 128 MiB
 import { parsePsChainLine } from "../core/hooks/resolve/anchor.js";
+import { appendEntry, resolveOwnerByName } from "../core/scratch/index.js";
 import { buildCouncilId, buildInviteMarkdown, COUNCIL_SCHEMA_VERSION, contributorsInRound, councilBodyDir, councilsArchiveDir, deleteArchivedCouncil, effectiveSteward, findManifestByPartialId, listKnownAgents, listManifests, moveFromArchive, moveToArchive, normalizeAgentName, pendingCouncilsForMember, readArchivedManifest, readManifest, readRoundPrompts, roundDir, setCouncilSteward, writeContribution, writeManifest, writePrompt, } from "../lib/council/index.js";
 import { displayName as displayAgentName, ensureIdentity, listIdentities, lookupById as lookupIdentityById, lookupByName as lookupIdentityByName, } from "../lib/identities/index.js";
-import { appendEntry, resolveOwnerByName } from "../lib/scratch/index.js";
 const FRESHNESS_SECS = 600; // 10-minute heartbeat-freshness window.
 const SUBAGENT_NOTE = "Bash identity is process-level in v1; if you're running inside a subagent, " +
     "this resolves to the parent group's name, not the subagent's. A subagent-aware " +
@@ -80,8 +80,7 @@ export function registerAgentsCommand(program, emitParam) {
     });
     cmd
         .command("show <name>")
-        .description("Deep-dive on one peer agent: registry state (files held, last tool, task) " +
-        "plus claude-sessions history (latest title, recent prompts, recent tools, tool-usage tallies). " +
+        .description("Deep-dive on one peer agent: registry state (files held, last tool, task, turn summary). " +
         "Disambiguates name → instance_id via prefix match.")
         .option("--json", "JSON envelope output")
         .action(async (name, opts) => {
@@ -435,6 +434,7 @@ function runWhoami(opts) {
         });
         process.exit(1);
     }
+    ensureCursorSession(root);
     const resolved = resolveOwnerWithSource();
     const myOwner = resolved.owner;
     if (!myOwner) {
@@ -873,6 +873,49 @@ function formatLocalShort(iso) {
         timeZone: "America/Chicago",
     }).format(d);
 }
+function cursorEnvSessionId() {
+    const raw = process.env.CURSOR_SESSION_ID?.trim() || process.env.CURSOR_CONVERSATION_ID?.trim();
+    if (!raw)
+        return null;
+    return raw.startsWith("bc-") && raw.length > 3 ? raw.slice(3) : raw;
+}
+function shouldBootstrapCursorSession() {
+    return process.env.CURSOR_AGENT === "1" && cursorEnvSessionId() !== null;
+}
+function ensureCursorSession(root) {
+    if (!shouldBootstrapCursorSession())
+        return;
+    if (resolveOwnerBySessionEnv(root))
+        return;
+    const sessionId = cursorEnvSessionId();
+    if (!sessionId)
+        return;
+    const agentHook = resolve(root, "harnery", "bin", "agent-hook");
+    if (!existsSync(agentHook))
+        return;
+    const payload = JSON.stringify({
+        conversation_id: sessionId,
+        session_id: sessionId,
+        hook_event_name: "sessionStart",
+        workspace_roots: [root],
+        cwd: root,
+        composer_mode: "agent",
+        is_background_agent: false,
+    });
+    spawnSync("bash", [agentHook, "session-start", "--harness", "cursor"], {
+        input: payload,
+        cwd: root,
+        encoding: "utf8",
+        timeout: 3000,
+        env: {
+            ...process.env,
+            HARNERY_AGENT_COORD_PLATFORM: "cursor",
+            HARNERY_COORD_ROOT_OVERRIDE: root,
+            CURSOR_SESSION_ID: sessionId,
+            CURSOR_CONVERSATION_ID: sessionId,
+        },
+    });
+}
 function runReleaseClaim(path) {
     const root = monorepoRoot();
     if (!root) {
@@ -920,6 +963,8 @@ function runSetTask(task, opts) {
     // Identity: prefer explicit --session-id (the ppid-walk-free escape hatch,
     // mirrors `status`), fall back to the ppid walk. Cursor shell tool calls
     // don't descend from a pid-map-registered anchor, so the walk can miss there.
+    if (!opts?.sessionId)
+        ensureCursorSession(root);
     const myOwner = opts?.sessionId ?? resolveOwner();
     if (!myOwner) {
         emit.error({
@@ -966,6 +1011,8 @@ function runStatus(opts) {
     }
     // Identity resolution: prefer explicit --session-id (hook-friendly), fall
     // back to ppid walk for interactive shell usage.
+    if (!opts.sessionId)
+        ensureCursorSession(root);
     const myOwner = opts.sessionId ?? resolveOwner();
     if (!myOwner) {
         emit.error({

package/dist/commands/deinit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deinit.d.ts","sourceRoot":"","sources":["../../src/commands/deinit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA2GjG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}
+{"version":3,"file":"deinit.d.ts","sourceRoot":"","sources":["../../src/commands/deinit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAanD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA+GjG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/commands/deinit.js

@@ -31,6 +31,7 @@ import { relative, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { DEFAULT_BIN_NAME } from "../core/config.js";
 import { HARNESS_SPECS } from "../core/hooks/harness/events.js";
+import { removeInstructions } from "../lib/instructions/apply.js";
 import { unwireHooks } from "./init.js";
 export function registerDeinitCommand(program, emit, binName) {
     // The interactive prompt + engine-removal hint are standalone-harn niceties.
@@ -113,6 +114,9 @@ export function registerDeinitCommand(program, emit, binName) {
                     `(${remaining} other hook(s) kept)`);
             }
         }
+        // ── 1b. agent-facing instructions block + skills ───────────────────────
+        const removed = removeInstructions(projectRoot, { harness, dryRun });
+        actions.push(...removed.actions, ...removed.warnings.map((w) => `! ${w}`));
         // ── 2. coord root (opt-in; destructive) ────────────────────────────────
         if (purgeState) {
             if (!coordExists) {

package/dist/commands/devtools.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerDevtoolsCommand(program: Command, emit: EmitContext): void;
+//# sourceMappingURL=devtools.d.ts.map

package/dist/commands/devtools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.d.ts","sourceRoot":"","sources":["../../src/commands/devtools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAkCnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAsDjF"}

package/dist/commands/devtools.js

@@ -0,0 +1,239 @@
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { cursorApiKeyPath, enrichFromApi, probeEndpoints, readDevtools, resolveCursorApiKey, } from "../lib/devtools.js";
+/**
+ * `devtools`: report the local state of the AI coding agents harnery supports
+ * — Claude Code, Codex, and Cursor — in one place: logged-in status, plan/seat
+ * tier, auth expiry, session counts, and (where the tool keeps them locally)
+ * rate-limit / quota windows.
+ *
+ * Reads files on disk by default (no network). When a Cursor API key is
+ * configured (`devtools cursor-key set`), it additionally verifies the key and
+ * pulls Cloud Agent activity. `--usage` adds an opt-in windowed scan of local
+ * transcripts for approximate token totals.
+ */
+const VALID = ["claude-code", "codex", "cursor"];
+export function registerDevtoolsCommand(program, emit) {
+    const cmd = program
+        .command("devtools")
+        .description("Local status of the AI coding agents (Claude Code, Codex, Cursor)")
+        .option("--tool <name>", "Restrict to a tool (repeatable): claude-code | codex | cursor", collect, [])
+        .option("--usage", "Also scan local transcripts for approximate token totals (slower)")
+        .option("--window-days <n>", "With --usage: only count transcripts modified within N days", (v) => Number.parseInt(v, 10), 7)
+        .option("--no-api", "Skip the Cursor API enrichment even when a key is configured")
+        .option("--format <type>", "Output format: table, json", "table")
+        .action(async (opts) => {
+        const only = (opts.tool ?? []).filter((t) => VALID.includes(t));
+        const bad = (opts.tool ?? []).filter((t) => !VALID.includes(t));
+        if (bad.length) {
+            emit.error({
+                code: "bad_tool",
+                message: `unknown --tool: ${bad.join(", ")}`,
+                hint: `valid: ${VALID.join(", ")}`,
+            });
+            return;
+        }
+        const report = readDevtools({
+            usage: opts.usage,
+            windowDays: opts.windowDays,
+            only: only.length ? only : undefined,
+        });
+        // Auto-enrich when a Cursor key is configured (the user opted in by
+        // storing one); --no-api forces pure-local.
+        if (opts.noApi !== true)
+            await enrichFromApi(report);
+        if (opts.format === "json") {
+            emit.config({ format: "json" });
+            emit.data({ ok: true, ...report });
+            return;
+        }
+        emit.text(renderTable(report.tools));
+    });
+    registerCursorKeyCommand(cmd, emit);
+    registerDoctorCommand(cmd, emit);
+}
+/**
+ * `devtools doctor` — one live call per usage endpoint to check the integrations
+ * still work. Surfaces `auth_rejected` (our headers/token stopped being
+ * accepted) and `shape_changed` (response schema drifted) distinctly from a
+ * mere rate limit. Bypasses the cache; run occasionally, by hand.
+ */
+function registerDoctorCommand(parent, emit) {
+    parent
+        .command("doctor")
+        .description("Probe the usage endpoints once each to detect header/schema drift")
+        .option("--tool <name>", "Restrict to a tool (repeatable): claude-code | cursor", collect, [])
+        .option("--format <type>", "Output format: table, json", "table")
+        .action(async (opts) => {
+        const only = (opts.tool ?? []).filter((t) => VALID.includes(t));
+        const results = await probeEndpoints({ only: only.length ? only : undefined });
+        if (opts.format === "json") {
+            emit.config({ format: "json" });
+            emit.data({
+                ok: results.every((r) => r.outcome === "ok" || r.outcome === "rate_limited"),
+                results,
+            });
+            return;
+        }
+        emit.text(renderDoctor(results));
+    });
+}
+const DOCTOR_MARK = {
+    ok: "✓",
+    rate_limited: "~",
+    no_credential: "-",
+    auth_rejected: "✗",
+    shape_changed: "✗",
+    unreachable: "✗",
+};
+function renderDoctor(results) {
+    if (!results.length)
+        return "no probeable endpoints (Codex is local-only)";
+    const lines = [];
+    for (const r of results) {
+        lines.push(`${DOCTOR_MARK[r.outcome]} ${r.tool.padEnd(12)} ${r.outcome.padEnd(14)} ${r.detail}`);
+        lines.push(`   ${r.endpoint}${r.clientVersion ? `  (client ${r.clientVersion})` : ""}`);
+    }
+    lines.push("");
+    lines.push("✗ auth_rejected / shape_changed = the client's request contract likely changed — review the headers/parser.");
+    return lines.join("\n");
+}
+/** `devtools cursor-key set|clear|status` — store the machine-local Cursor API key. */
+function registerCursorKeyCommand(parent, emit) {
+    const key = parent
+        .command("cursor-key")
+        .description("Manage the Cursor API key used for the Cloud Agent enrichment");
+    key
+        .command("set [value]")
+        .description("Store a Cursor API key (reads stdin when [value] is omitted)")
+        .action(async (value) => {
+        const raw = value ?? (await readStdin());
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            emit.error({ code: "empty_key", message: "no key provided (arg or stdin)" });
+            return;
+        }
+        const path = cursorApiKeyPath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, trimmed, { mode: 0o600 });
+        chmodSync(path, 0o600);
+        emit.file(path, { stored: true, length: trimmed.length });
+    });
+    key
+        .command("clear")
+        .description("Remove the stored Cursor API key")
+        .action(() => {
+        try {
+            rmSync(cursorApiKeyPath());
+        }
+        catch {
+            // already absent
+        }
+        emit.data({ ok: true, cleared: true });
+    });
+    key
+        .command("status")
+        .description("Report whether a Cursor key is configured (env or file)")
+        .action(() => {
+        const fromEnv = Boolean(process.env.CURSOR_API_KEY?.trim());
+        const resolved = resolveCursorApiKey();
+        emit.data({
+            ok: true,
+            configured: Boolean(resolved),
+            source: fromEnv ? "env" : resolved ? "file" : null,
+            path: cursorApiKeyPath(),
+        });
+    });
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        if (process.stdin.isTTY) {
+            resolve("");
+            return;
+        }
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => {
+            data += c;
+        });
+        process.stdin.on("end", () => resolve(data));
+    });
+}
+function collect(value, prev) {
+    return [...prev, value];
+}
+function renderTable(tools) {
+    const lines = [];
+    for (const t of tools) {
+        lines.push(`── ${t.tool} ${"─".repeat(Math.max(0, 40 - t.tool.length))}`);
+        if (!t.installed) {
+            lines.push("   not installed");
+            lines.push("");
+            continue;
+        }
+        lines.push(`   logged in    ${fmtBool(t.loggedIn)}`);
+        if (t.account)
+            lines.push(`   account      ${t.account}`);
+        if (t.plan)
+            lines.push(`   plan         ${t.plan}`);
+        if (t.rateLimitTier)
+            lines.push(`   rate tier    ${t.rateLimitTier}`);
+        if (t.authExpiresAt)
+            lines.push(`   auth expires ${fmtDate(t.authExpiresAt)}`);
+        if (t.sessions != null)
+            lines.push(`   sessions     ${t.sessions}`);
+        if (t.lastActivity)
+            lines.push(`   last active  ${fmtDate(t.lastActivity)}`);
+        if (t.quota?.length) {
+            for (const q of t.quota) {
+                const pct = q.usedPercent != null ? `${q.usedPercent}% used` : "usage unknown";
+                const reset = q.resetsAt ? `resets ${fmtDate(q.resetsAt)}` : "";
+                lines.push(`   quota (${q.window})   ${pct}${reset ? ` · ${reset}` : ""}`);
+            }
+        }
+        if (t.tokensUsed != null) {
+            lines.push(`   tokens       ${t.tokensUsed.toLocaleString()}`);
+        }
+        if (t.usage) {
+            const u = t.usage;
+            if (u.cycleEnd) {
+                const days = Math.round((Date.parse(u.cycleEnd) - Date.now()) / 86_400_000);
+                lines.push(`   plan resets  ${fmtDate(u.cycleEnd)} (${days}d)`);
+            }
+            const pct = (label, v) => (v != null ? `${label} ${v}%` : null);
+            const bars = [
+                pct("total", u.totalPercentUsed),
+                pct("api", u.apiPercentUsed),
+                pct("first-party", u.firstPartyPercentUsed),
+            ].filter((s) => s != null);
+            if (bars.length)
+                lines.push(`   usage        ${bars.join(" · ")}`);
+        }
+        if (t.spend?.limitCents != null) {
+            const label = t.spend.label.toLowerCase().padEnd(12).slice(0, 12);
+            lines.push(`   ${label} ${fmtUsd(t.spend.usedCents ?? 0)} / ${fmtUsd(t.spend.limitCents)}`);
+        }
+        if (t.api?.ok && t.api.cloudAgents) {
+            lines.push(`   cloud agents ${t.api.cloudAgents.total} (${t.api.cloudAgents.active} active)`);
+        }
+        for (const n of t.notes)
+            lines.push(`   · ${n}`);
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+function fmtBool(v) {
+    if (v === true)
+        return "yes";
+    if (v === false)
+        return "no";
+    return "unknown";
+}
+function fmtDate(iso) {
+    // Keep the machine-readable ISO but drop milliseconds for readability.
+    return iso.replace(/\.\d{3}Z$/, "Z");
+}
+/** Cents → "$X.XX". */
+function fmtUsd(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}

package/dist/commands/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA2B1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+EN"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/commands/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiC1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8GN"}

package/dist/commands/docs.js

@@ -1,6 +1,8 @@
 import { initDocsContext as initDocs, scanDocs } from "../lib/docs.js";
+import { initDocsMigrationContext, runFrontmatterMigration, } from "../lib/docs-frontmatter-migrate.js";
 import { initDocsContext as initDocsIndex, runIndex } from "../lib/docs-index.js";
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.js";
+import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.js";
 import { countColdHandoffs, initDocsContext as initDocsSweep, runSweep, } from "../lib/docs-sweep.js";
 function ensureContext(context) {
     if (!context?.repoRoot || !context?.submodules) {
@@ -8,6 +10,7 @@ function ensureContext(context) {
     }
     const opts = { repoRoot: context.repoRoot, submodules: context.submodules };
     initDocs(opts);
+    initDocsMigrationContext(opts);
     initDocsIndex(opts);
     initDocsLint({
         ...opts,
@@ -21,7 +24,7 @@ export function registerDocsCommand(program, emitParam, context) {
     emit = emitParam;
     const docs = program
         .command("docs")
-        .description("Documentation tooling: freshness report, lint, sweep, index")
+        .description("Documentation tooling: freshness report, metadata, lint, sweep, index")
         // Options on the group itself back the default (no-subcommand) behavior.
         // See handleDocs below.
         .option("--stale <days>", "Only show files not committed in N+ days", Number.parseInt)
@@ -39,6 +42,37 @@ export function registerDocsCommand(program, emitParam, context) {
             emit.error({ code: "docs_error", message: msg });
         }
     });
+    docs
+        .command("meta")
+        .description("Read YAML frontmatter from a documentation file")
+        .argument("<path>", "Markdown file path, relative to the project root or absolute")
+        .argument("[key]", "Optional top-level frontmatter key")
+        .option("--json", "Emit a requested key as JSON even in an interactive terminal")
+        .action(async (path, key, opts) => {
+        try {
+            ensureContext(context);
+            handleMeta(context.repoRoot, path, key, opts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit.error({ code: "docs_error", message: msg });
+        }
+    });
+    docs
+        .command("frontmatter-migrate")
+        .description("Convert lifecycle docs from bold metadata headers to YAML frontmatter")
+        .option("--repo <name>", "Limit to one submodule or '.' for parent")
+        .option("--yes", "Apply changes; without this flag the command is a dry-run")
+        .action(async (opts) => {
+        try {
+            ensureContext(context);
+            handleFrontmatterMigration(opts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit.error({ code: "docs_error", message: msg });
+        }
+    });
     docs
         .command("lint")
         .description("Verify every repo matches the documentation contract (directory layout + naming rules)")
@@ -86,6 +120,40 @@ export function registerDocsCommand(program, emitParam, context) {
         }
     });
 }
+// --- `harn docs frontmatter-migrate` ---
+function handleFrontmatterMigration(opts) {
+    const rows = runFrontmatterMigration({ repo: opts.repo, apply: !!opts.yes });
+    const counts = {
+        would_update: rows.filter((row) => row.status === "would-update").length,
+        updated: rows.filter((row) => row.status === "updated").length,
+        skipped: rows.filter((row) => row.status === "skipped").length,
+        errors: rows.filter((row) => row.status === "error").length,
+    };
+    emit.data({
+        dry_run: !opts.yes,
+        applied: !!opts.yes && counts.errors === 0,
+        aborted: !!opts.yes && counts.errors > 0,
+        repo: opts.repo ?? null,
+        counts,
+        rows,
+    });
+    if (counts.errors > 0)
+        emit.setExitCode(1);
+}
+// --- `harn docs meta` ---
+function handleMeta(repoRoot, path, key, opts) {
+    const metadata = readDocsMetadata(repoRoot, path).data;
+    if (!key) {
+        emit.data(metadata);
+        return;
+    }
+    const value = readDocsMetadataKey(metadata, key, path);
+    if (opts.json || !process.stdout.isTTY || typeof value === "object") {
+        emit.data(value);
+        return;
+    }
+    emit.text(String(value));
+}
 // --- Default `harn docs` (freshness report) ---
 async function handleDocs(opts) {
     if (opts.format === "json")

package/dist/commands/doctor.js

@@ -220,17 +220,25 @@ function checkHarnessHooks() {
     const bin = resolveBinName(root);
     const parts = drift.map((d) => {
         const bits = [];
+        if (d.parseError)
+            bits.push(`invalid JSON (${d.parseError})`);
         if (d.missing.length > 0) {
             bits.push(`${d.missing.length} missing (${d.missing.map((m) => m.subcommand).join(", ")})`);
         }
         if (d.orphans.length > 0)
             bits.push(`${d.orphans.length} orphaned (${d.orphans.join(", ")})`);
+        if (d.invalidTopLevelKeys.length > 0) {
+            bits.push(`invalid fields (${d.invalidTopLevelKeys.join(", ")})`);
+        }
+        if (d.invalidEventKeys.length > 0) {
+            bits.push(`unsupported events (${d.invalidEventKeys.join(", ")})`);
+        }
         return `${d.settingsFile}: ${bits.join("; ")}`;
     });
-    const hasOrphans = drift.some((d) => d.orphans.length > 0);
-    const hint = hasOrphans
-        ? `run \`${bin} init\` to wire missing hooks; remove orphaned entries (renamed/dropped events) with \`${bin} deinit\` then \`${bin} init\``
-        : `run \`${bin} init\` to wire the new hook(s) (idempotent)`;
+    const needsManualRepair = drift.some((d) => d.parseError || d.invalidTopLevelKeys.length > 0 || d.invalidEventKeys.length > 0);
+    const hint = needsManualRepair
+        ? `repair the invalid harness settings, then run \`${bin} init\` to migrate harnery hooks`
+        : `run \`${bin} init\` to migrate the hook set (idempotent)`;
     return { name: "harness hooks", severity: "warn", detail: parts.join("  |  "), hint };
 }
 function macOrLinux(mac, linux) {

package/dist/commands/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/commands/env.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAqB1E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAaN"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/commands/env.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAwB,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAqBhG,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAaN"}