harnery 0.32.0 → 0.34.0

package/dist/commands/decision.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { emitCanonical, monorepoRoot, normalizeAdapter, readHeartbeat, resolveOwner, } from "../core/agents/index.js";
+import { emitEventV3, monorepoRoot, normalizeAdapter, resolveOwner } from "../core/agents/index.js";
+import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.js";
 import { resolveBinName } from "../core/config.js";
 import { archiveDecision, claimDecision, DECISION_STAKES, fileDecision, isStakes, isStatus, isTier, isVerdict, listDecisions, reopenDecision, resolveDecision, reviewDecision, searchDecisions, showDecision, supersedeDecision, triageDecision, wontfixDecision, } from "../lib/decision/index.js";
 /**
@@ -43,7 +44,7 @@ export function registerDecisionCommand(program, emitParam) {
             brief = readFileSync(opts.brief, "utf8");
         }
         const owner = resolveOwner();
-        const hb = owner ? readHeartbeat(owner) : null;
+        const hb = owner ? readLiveCoordinationRow(coordRoot, owner) : null;
         const r = fileDecision(coordRoot, {
             question: question.join(" "),
             tier,
@@ -56,11 +57,7 @@ export function registerDecisionCommand(program, emitParam) {
         });
         if (!r.ok)
             return fail("file_failed", r.reason);
-        emitDecisionEvent("decision.filed", {
-            decision_id: r.manifest.decision_id,
-            tier,
-            stakes,
-        });
+        emitDecisionEvent("filed", r.manifest);
         emit.data(r.manifest);
     });
     // ── list ─────────────────────────────────────────────────────────────────
@@ -162,7 +159,7 @@ export function registerDecisionCommand(program, emitParam) {
         .action((id, opts) => {
         const coordRoot = coordRootOrExit();
         const owner = resolveOwner();
-        const resolvedBy = opts.resolvedBy ?? (owner ? readHeartbeat(owner)?.name : undefined);
+        const resolvedBy = opts.resolvedBy ?? (owner ? readLiveCoordinationRow(coordRoot, owner)?.name : undefined);
         if (!resolvedBy) {
             return fail("no_resolver", "pass --resolved-by (no agent session to infer it from)");
         }
@@ -177,12 +174,7 @@ export function registerDecisionCommand(program, emitParam) {
         });
         if (!r.ok)
             return fail("resolve_failed", r.reason);
-        emitDecisionEvent("decision.resolved", {
-            decision_id: id,
-            tier: r.manifest.tier,
-            stakes: r.manifest.stakes,
-            confidence: opts.confidence ?? null,
-        });
+        emitDecisionEvent("resolved", r.manifest);
         emit.data(r.manifest);
     });
     // ── review ───────────────────────────────────────────────────────────────
@@ -202,11 +194,7 @@ export function registerDecisionCommand(program, emitParam) {
         });
         if (!r.ok)
             return fail("review_failed", r.reason);
-        emitDecisionEvent("decision.reviewed", {
-            decision_id: id,
-            verdict: opts.verdict,
-            tier: r.manifest.tier,
-        });
+        emitDecisionEvent("reviewed", r.manifest);
         emit.data(r.manifest);
     });
     // ── triage ─────────────────────────────────────────────────────────────────
@@ -243,11 +231,7 @@ export function registerDecisionCommand(program, emitParam) {
         const r = archiveDecision(coordRoot, id, opts.graduatedTo);
         if (!r.ok)
             return fail("archive_failed", r.reason);
-        emitDecisionEvent("decision.archived", {
-            decision_id: id,
-            tier: r.manifest.tier,
-            graduated_to: opts.graduatedTo ?? null,
-        });
+        emitDecisionEvent("archived", r.manifest);
         emit.data(r.manifest);
     });
     // ── reopen ───────────────────────────────────────────────────────────────────
@@ -263,7 +247,7 @@ export function registerDecisionCommand(program, emitParam) {
         const r = reopenDecision(coordRoot, id);
         if (!r.ok)
             return fail("reopen_failed", r.reason);
-        emitDecisionEvent("decision.reopened", { decision_id: id, tier: r.manifest.tier });
+        emitDecisionEvent("reviewed", r.manifest, "archived");
         emit.data(r.manifest);
     });
     // ── supersede ────────────────────────────────────────────────────────────────
@@ -276,10 +260,7 @@ export function registerDecisionCommand(program, emitParam) {
         const r = supersedeDecision(coordRoot, id, opts.by);
         if (!r.ok)
             return fail("supersede_failed", r.reason);
-        emitDecisionEvent("decision.superseded", {
-            decision_id: id,
-            superseded_by: opts.by ?? null,
-        });
+        emitDecisionEvent("superseded", r.manifest);
         emit.data(r.manifest);
     });
     // ── wontfix ──────────────────────────────────────────────────────────────────
@@ -292,10 +273,7 @@ export function registerDecisionCommand(program, emitParam) {
         const r = wontfixDecision(coordRoot, id, opts.reason);
         if (!r.ok)
             return fail("wontfix_failed", r.reason);
-        emitDecisionEvent("decision.wontfix", {
-            decision_id: id,
-            reason: opts.reason ?? null,
-        });
+        emitDecisionEvent("wontfix", r.manifest);
         emit.data(r.manifest);
     });
 }
@@ -363,16 +341,22 @@ function summarize(m) {
  * session to attribute it to (operator-side filing). Powers the docket metrics
  * without new telemetry plumbing.
  */
-function emitDecisionEvent(type, data) {
+function emitDecisionEvent(newState, manifest, priorState) {
     const owner = resolveOwner();
     if (!owner)
         return;
-    const hb = readHeartbeat(owner);
-    emitCanonical({
-        type,
+    const root = monorepoRoot();
+    const hb = root ? readLiveCoordinationRow(root, owner) : null;
+    emitEventV3({
         owner,
         session: hb?.session_id ?? owner,
         adapter: normalizeAdapter(hb?.platform),
-        data,
+        observation: {
+            event_type: "decision.state_changed",
+            decision_id: manifest.decision_id,
+            ...(priorState ? { prior_state: priorState } : {}),
+            new_state: newState,
+            record: manifest,
+        },
     });
 }

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;AAmC1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA0IN"}
+{"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;AAmC1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAkON"}

package/dist/commands/docs.js

@@ -1,9 +1,11 @@
 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 initDocsLinks, runLinks } from "../lib/docs-links.js";
 import { initDocsContext as initDocsLint, runLint } from "../lib/docs-lint.js";
 import { readDocsMetadata, readDocsMetadataKey } from "../lib/docs-meta.js";
+import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "../lib/docs-metadata-audit.js";
+import { initDocsMetadataSyncContext, runDocsMetadataSync } from "../lib/docs-metadata-sync.js";
+import { createDocsFile } from "../lib/docs-new.js";
 import { countColdHandoffs, initDocsContext as initDocsSweep, runSweep, } from "../lib/docs-sweep.js";
 function ensureContext(context) {
     if (!context?.repoRoot || !context?.submodules) {
@@ -11,7 +13,6 @@ function ensureContext(context) {
     }
     const opts = { repoRoot: context.repoRoot, submodules: context.submodules };
     initDocs(opts);
-    initDocsMigrationContext(opts);
     initDocsIndex(opts);
     initDocsLint({
         ...opts,
@@ -19,6 +20,8 @@ function ensureContext(context) {
         docsRootAllowlist: context.docsRootAllowlist,
     });
     initDocsLinks({ ...opts, extraExcludedPrefixes: context.extraDocsExcludedPrefixes });
+    initDocsMetadataAuditContext(opts);
+    initDocsMetadataSyncContext(opts);
     initDocsSweep(opts);
 }
 let emit;
@@ -60,21 +63,101 @@ export function registerDocsCommand(program, emitParam, context) {
             emit.error({ code: "docs_error", message: msg });
         }
     });
-    docs
-        .command("frontmatter-migrate")
-        .description("Convert lifecycle docs from bold metadata headers to YAML frontmatter")
+    const metadata = docs
+        .command("metadata")
+        .description("Validate and maintain the versioned markdown metadata contract");
+    metadata
+        .command("validate")
+        .description("Validate every managed Markdown file against harnery-doc/v2")
         .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);
+            const rows = await runDocsMetadataAudit(opts);
+            const errors = rows
+                .flatMap((row) => row.issues)
+                .filter((issue) => issue.severity === "error");
+            const warnings = rows
+                .flatMap((row) => row.issues)
+                .filter((issue) => issue.severity === "warning");
+            emit.data({
+                repo: opts.repo ?? null,
+                counts: {
+                    files: rows.length,
+                    valid: rows.filter((row) => row.state === "valid").length,
+                    invalid: rows.filter((row) => row.state === "invalid").length,
+                    legacy: rows.filter((row) => row.state === "legacy").length,
+                    missing: rows.filter((row) => row.state === "missing").length,
+                    errors: errors.length,
+                    warnings: warnings.length,
+                },
+                rows,
+            });
+            if (errors.length > 0)
+                emit.setExitCode(1);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             emit.error({ code: "docs_error", message: msg });
         }
     });
+    metadata
+        .command("sync")
+        .description("Synchronize semantic and lifecycle timestamps on staged v2 documents")
+        .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("--reviewed", "Record an explicit runbook review and move its due date")
+        .action(async (files, opts) => {
+        try {
+            ensureContext(context);
+            const rows = await runDocsMetadataSync({ ...opts, files });
+            emit.data({
+                check: !!opts.check,
+                counts: {
+                    files: rows.length,
+                    updated: rows.filter((row) => row.status === "updated").length,
+                    drift: rows.filter((row) => row.status === "drift").length,
+                    invalid: rows.filter((row) => row.status === "invalid").length,
+                },
+                rows,
+            });
+            if (rows.some((row) => row.status === "drift" || row.status === "invalid")) {
+                emit.setExitCode(1);
+            }
+        }
+        catch (err) {
+            emit.error({
+                code: "docs_error",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+    docs
+        .command("new")
+        .description("Create a document with canonical harnery-doc/v2 metadata")
+        .argument("<type>", "plan, issue, handoff, runbook, or topic")
+        .argument("<path>", "Repository-relative Markdown path")
+        .requiredOption("--summary <text>", "One-sentence document summary")
+        .requiredOption("--owner <id>", "Canonical lowercase kebab-case owner id")
+        .option("--status <status>", "Initial lifecycle status")
+        .option("--severity <severity>", "Issue severity", "medium")
+        .action((type, path, opts) => {
+        try {
+            ensureContext(context);
+            if (!["plan", "issue", "handoff", "runbook", "topic"].includes(type)) {
+                throw new Error(`unsupported document type '${type}'`);
+            }
+            const file = createDocsFile(context.repoRoot, { type, path, ...opts });
+            emit.data({ path: file, schema: "harnery-doc/v2", type });
+        }
+        catch (err) {
+            emit.error({
+                code: "docs_error",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
     docs
         .command("lint")
         .description("Verify every repo matches the documentation contract (directory layout + naming rules)")
@@ -129,7 +212,7 @@ export function registerDocsCommand(program, emitParam, context) {
         .command("index")
         .description("Regenerate index READMEs for docs/audits/ and docs/issues/ directories")
         .option("--dry-run", "Show what would change, don't write files")
-        .option("--repo <name>", "Limit to one submodule or '.' for parent")
+        .option("--repo <name>", "Limit to one package (in-tree or submodule) or '.' for parent")
         .action(async (opts) => {
         try {
             ensureContext(context);
@@ -141,26 +224,6 @@ 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;

package/dist/commands/doctor.d.ts

@@ -12,14 +12,16 @@
  */
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
+import { type CodexHookAuthorizationResult } from "../core/hooks/codex-authorization.js";
 type Severity = "ok" | "warn" | "fail";
-interface Check {
+export interface Check {
     name: string;
     severity: Severity;
     detail: string;
     hint?: string;
 }
 export declare function registerDoctorCommand(program: Command, emit: EmitContext): void;
-export declare function runChecks(): Check[];
+export declare function runChecks(): Promise<Check[]>;
+export declare function codexAuthorizationCheck(result: CodexHookAuthorizationResult): Check;
 export {};
 //# sourceMappingURL=doctor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAgBnD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmD/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAsBnC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,EACL,KAAK,4BAA4B,EAElC,MAAM,sCAAsC,CAAC;AAe9C,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmD/E;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAyBlD;AA4CD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAoBnF"}

package/dist/commands/doctor.js

@@ -18,7 +18,8 @@ import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.js";
 import { resolveBinName, ripgrepAutoInstall } from "../core/config.js";
 import { ADAPTER_SPECS } from "../core/hooks/adapter/events.js";
 import { loadAdapterWiring, summarizeAdapterWiring } from "../core/hooks/adapter/wiring.js";
-import { inspectCodexWslBridge } from "../core/hooks/codex-wsl-bridge.js";
+import { probeCodexHookAuthorization, } from "../core/hooks/codex-authorization.js";
+import { inspectCodexWslBridge, } from "../core/hooks/codex-wsl-bridge.js";
 import { ADAPTER_BINARIES, ADAPTER_INSTALL_HINTS, ADAPTER_LOGIN_HINTS, } from "../core/workflow/adapters.js";
 import { probeBilling } from "../core/workflow/billing.js";
 import { checkGitHooks, gitHooksInstalled } from "../lib/instructions/git-hooks.js";
@@ -39,7 +40,7 @@ export function registerDoctorCommand(program, emit) {
                 emit.text(`ripgrep install failed: ${err.message}\n`);
             }
         }
-        const checks = runChecks();
+        const checks = await runChecks();
         const requiredFailed = checks.some((c) => c.severity === "fail");
         if (opts.json) {
             emit.data({
@@ -67,13 +68,15 @@ export function registerDoctorCommand(program, emit) {
         emit.setExitCode(requiredFailed ? 1 : 0);
     });
 }
-export function runChecks() {
-    const codexWslBridge = checkCodexWslBridge();
+export async function runChecks() {
+    const codexWslStatus = inspectCodexWslBridge();
+    const codexWslBridge = checkCodexWslBridge(codexWslStatus);
     // 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.
     const workflow = BUILTIN_ADAPTER_IDS.map((id) => ({ id, ...checkWorkflowAdapter(id) }));
     const installed = workflow.filter((w) => w.installed).map((w) => w.id);
+    const codexAuthorization = await checkCodexHookAuthorization(installed, codexWslStatus);
     return [
         checkNode(),
         checkGit(),
@@ -81,6 +84,7 @@ export function runChecks() {
         checkRipgrep(),
         checkHarneryDir(),
         checkAdapterHooks(installed),
+        ...(codexAuthorization ? [codexAuthorization] : []),
         checkGitHookRegions(),
         ...(codexWslBridge ? [codexWslBridge] : []),
         ...workflow.map((w) => w.check),
@@ -119,8 +123,7 @@ function checkGitHookRegions() {
         };
     }
 }
-function checkCodexWslBridge() {
-    const status = inspectCodexWslBridge();
+function checkCodexWslBridge(status) {
     if (!status)
         return null;
     return {
@@ -132,6 +135,42 @@ function checkCodexWslBridge() {
             : "forward CODEX_THREAD_ID through WSLENV in the Codex shell environment policy, then start a fresh task",
     };
 }
+export function codexAuthorizationCheck(result) {
+    const reviewHint = "terminal UI: run `/hooks`; Codex Desktop: open Settings > Hooks; after approval, start a fresh task";
+    if (result.status === "runnable") {
+        return { name: "codex:hook authorization", severity: "ok", detail: result.detail };
+    }
+    if (result.status === "review_required" || result.status === "disabled") {
+        return {
+            name: "codex:hook authorization",
+            severity: "warn",
+            detail: result.detail,
+            hint: reviewHint,
+        };
+    }
+    return {
+        name: "codex:hook authorization",
+        severity: "warn",
+        detail: `authorization unverified: ${result.detail}`,
+        hint: reviewHint,
+    };
+}
+async function checkCodexHookAuthorization(installedAdapters, codexWslStatus) {
+    const root = findCoordProjectRoot();
+    if (!root || !summarizeAdapterWiring(root).wired.includes("codex"))
+        return null;
+    if (codexWslStatus) {
+        return {
+            name: "codex:hook authorization",
+            severity: "warn",
+            detail: "unverified from WSL; the Windows-native Codex runtime owns this workspace's trust state",
+            hint: "run the host's Windows bridge doctor, or open Codex Desktop Settings > Hooks; start a fresh task after approval",
+        };
+    }
+    if (!installedAdapters.includes("codex"))
+        return null;
+    return codexAuthorizationCheck(await probeCodexHookAuthorization({ cwd: root }));
+}
 function checkRipgrep() {
     const found = findRg();
     if (found) {
@@ -340,7 +379,7 @@ function checkHarneryDir() {
         name: ".harnery/",
         severity: "warn",
         detail: "no .harnery/ found above cwd",
-        hint: "create one with `mkdir -p .harnery/active` from your monorepo root",
+        hint: "initialize the project with `harn init` from the repository root",
     };
 }
 /**
@@ -378,6 +417,15 @@ function checkAdapterHooks(installedAdapters = []) {
         }
         if (d.orphans.length > 0)
             bits.push(`${d.orphans.length} orphaned (${d.orphans.join(", ")})`);
+        if (d.duplicates.length > 0) {
+            bits.push(`${d.duplicates.length} duplicated (${d.duplicates.map((e) => e.settingsKey).join(", ")})`);
+        }
+        if (d.misplaced.length > 0) {
+            bits.push(`${d.misplaced.length} misplaced (${d.misplaced.map((e) => e.subcommand).join(", ")})`);
+        }
+        if (d.stale.length > 0) {
+            bits.push(`${d.stale.length} stale (${d.stale.map((e) => e.settingsKey).join(", ")})`);
+        }
         if (d.invalidTopLevelKeys.length > 0) {
             bits.push(`invalid fields (${d.invalidTopLevelKeys.join(", ")})`);
         }

package/dist/commands/events.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+/** Read-only projections over the canonical Event Ledger V3 stream. */
+export declare function registerEventsCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/commands/events.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAkC1E,uEAAuE;AACvE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+CN"}

package/dist/commands/events.js

@@ -0,0 +1,189 @@
+import { resolve } from "node:path";
+import { projectEconomicsV3, projectLatencyV3, readLedgerV3, } from "../core/events/v3/index.js";
+/** Read-only projections over the canonical Event Ledger V3 stream. */
+export function registerEventsCommand(program, emit, context) {
+    const command = program.command("events").description("Inspect the canonical event ledger");
+    command
+        .command("latency")
+        .description("Project turn latency, token economics, and attribution from Event Ledger V3")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--candidate", "Read a pre-activation candidate ledger instead of active authority")
+        .option("--by-tool", "Aggregate inclusive tool latency")
+        .option("--by-generation", "Aggregate latency by generation")
+        .option("--json", "Emit the complete projections and selected view as JSON")
+        .action((options) => {
+        try {
+            if (options.byTool && options.byGeneration) {
+                throw new Error("--by-tool and --by-generation are mutually exclusive");
+            }
+            const root = resolve(options.root ?? coordRoot(context));
+            const authority = options.candidate ? "candidate" : "active";
+            const read = readLedgerV3(root, { authority });
+            if (!read.complete) {
+                const diagnostics = read.diagnostics.map(({ code }) => code).join(", ") || "unknown";
+                throw new Error(`V3 ledger read is incomplete: ${diagnostics}`);
+            }
+            const latency = projectLatencyV3(read);
+            const economics = projectEconomicsV3(read);
+            const view = options.byTool
+                ? { kind: "tool", rows: summarizeByTool(latency.turns) }
+                : options.byGeneration
+                    ? { kind: "generation", rows: summarizeByGeneration(latency.turns) }
+                    : { kind: "turn", rows: latency.turns };
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data({ root, authority, view, latency, economics });
+                return;
+            }
+            if (view.kind === "tool")
+                emit.text(renderTools(view.rows));
+            else if (view.kind === "generation")
+                emit.text(renderGenerations(view.rows));
+            else
+                emit.text(renderTurns(view.rows));
+        }
+        catch (error) {
+            emit.error({
+                code: "event_v3_latency_failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    });
+}
+function coordRoot(context) {
+    return resolve(context?.resolveCoordRoot?.() ??
+        context?.repoRoot ??
+        process.env.HARNERY_COORD_ROOT ??
+        process.cwd());
+}
+function summarizeByGeneration(turns) {
+    const groups = new Map();
+    for (const turn of turns) {
+        const group = groups.get(turn.generation_id) ?? [];
+        group.push(turn);
+        groups.set(turn.generation_id, group);
+    }
+    return [...groups.entries()]
+        .map(([generationId, group]) => ({
+        generation_id: generationId,
+        turns: group.length,
+        wall_ms: sumMetrics(group.map(({ wall_ms }) => wall_ms)),
+        tool_ms: sumMetrics(group.map(({ tool_ms }) => tool_ms)),
+        command_ms: sumMetrics(group.map(({ command_exclusive_ms }) => command_exclusive_ms)),
+        wait_ms: sumMetrics(group.map(({ wait_ms }) => wait_ms)),
+        inference_ms: sumMetrics(group.map(({ inference_ms }) => inference_ms)),
+        harness_ms: sumMetrics(group.map(({ harness_ms }) => harness_ms)),
+        residual_ms: sumMetrics(group.map(({ residual_ms }) => residual_ms)),
+    }))
+        .sort((left, right) => left.generation_id.localeCompare(right.generation_id));
+}
+function summarizeByTool(turns) {
+    const groups = new Map();
+    for (const turn of turns) {
+        for (const tool of turn.tool_breakdown) {
+            const key = `${tool.namespace}\0${tool.name}`;
+            const group = groups.get(key) ?? [];
+            group.push(tool);
+            groups.set(key, group);
+        }
+    }
+    const rows = [...groups.entries()].map(([key, group]) => {
+        const [namespace, name] = key.split("\0");
+        return {
+            namespace: namespace ?? "",
+            name: name ?? "",
+            count: group.reduce((total, tool) => total + tool.count, 0),
+            duration_ms: sumMetrics(group.map(({ duration_ms }) => duration_ms)),
+            coverage: "complete",
+        };
+    });
+    const incomplete = turns.filter(({ tool_ms }) => tool_ms.state === "unknown");
+    if (incomplete.length > 0) {
+        rows.push({
+            namespace: "?",
+            name: "unattributed",
+            count: 0,
+            duration_ms: {
+                state: "unknown",
+                known_ms: 0,
+                reasons: unique(incomplete.flatMap(({ tool_ms }) => (tool_ms.state === "unknown" ? tool_ms.reasons : []))),
+            },
+            coverage: "partial",
+        });
+    }
+    return rows.sort((left, right) => left.namespace.localeCompare(right.namespace) || left.name.localeCompare(right.name));
+}
+function sumMetrics(metrics) {
+    const known = metrics.reduce((total, metric) => total + metricValue(metric), 0);
+    const reasons = unique(metrics.flatMap((metric) => (metric.state === "unknown" ? metric.reasons : [])));
+    return reasons.length === 0
+        ? { state: "observed", value_ms: known }
+        : { state: "unknown", known_ms: known, reasons };
+}
+function renderTurns(turns) {
+    return renderTable([
+        "GENERATION",
+        "TURN",
+        "WALL",
+        "TOOL",
+        "COMMAND",
+        "WAIT",
+        "INFERENCE",
+        "HARNESS",
+        "RESIDUAL",
+        "CONTEXT",
+    ], turns.map((turn) => [
+        turn.generation_id,
+        turn.turn_id,
+        formatMetric(turn.wall_ms),
+        formatMetric(turn.tool_ms),
+        formatMetric(turn.command_exclusive_ms),
+        formatMetric(turn.wait_ms),
+        formatMetric(turn.inference_ms),
+        formatMetric(turn.harness_ms),
+        formatMetric(turn.residual_ms),
+        turn.context_percent === null ? "?" : `${turn.context_percent.toFixed(1)}%`,
+    ]));
+}
+function renderGenerations(rows) {
+    return renderTable(["GENERATION", "TURNS", "WALL", "TOOL", "COMMAND", "WAIT", "INFERENCE", "HARNESS", "RESIDUAL"], rows.map((row) => [
+        row.generation_id,
+        String(row.turns),
+        formatMetric(row.wall_ms),
+        formatMetric(row.tool_ms),
+        formatMetric(row.command_ms),
+        formatMetric(row.wait_ms),
+        formatMetric(row.inference_ms),
+        formatMetric(row.harness_ms),
+        formatMetric(row.residual_ms),
+    ]));
+}
+function renderTools(rows) {
+    return renderTable(["NAMESPACE", "TOOL", "CALLS", "INCLUSIVE", "COVERAGE"], rows.map((row) => [
+        row.namespace,
+        row.name,
+        String(row.count),
+        formatMetric(row.duration_ms),
+        row.coverage,
+    ]));
+}
+function renderTable(headers, rows) {
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)));
+    const line = (row) => row
+        .map((cell, index) => cell.padEnd(widths[index] ?? cell.length))
+        .join("  ")
+        .trimEnd();
+    return `${[line(headers), line(widths.map((width) => "-".repeat(width))), ...rows.map(line)].join("\n")}\n`;
+}
+function formatMetric(metric) {
+    if (metric.state === "observed")
+        return `${metric.value_ms}ms`;
+    return metric.known_ms > 0 ? `>=${metric.known_ms}ms?` : "?";
+}
+function metricValue(metric) {
+    return metric.state === "observed" ? metric.value_ms : metric.known_ms;
+}
+function unique(values) {
+    return [...new Set(values)].sort();
+}

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

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