harnery 0.35.0 → 0.37.0

package/dist/commands/diagnostics.js

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

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,CAkON"}
+{"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,CA2ON"}

package/dist/commands/docs.js

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

package/dist/commands/doctor.d.ts

@@ -13,6 +13,7 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
 import { type CodexHookAuthorizationResult } from "../core/hooks/codex-authorization.js";
+import { type CodexWslBridgeStatus } from "../core/hooks/codex-wsl-bridge.js";
 type Severity = "ok" | "warn" | "fail";
 export interface Check {
     name: string;
@@ -22,6 +23,10 @@ export interface Check {
 }
 export declare function registerDoctorCommand(program: Command, emit: EmitContext): void;
 export declare function runChecks(): Promise<Check[]>;
+export declare function codexWslBridgeCheck(status: CodexWslBridgeStatus | null, recentMidFlightCount?: number): Check | null;
+/** Count bounded, privacy-safe recovery diagnostics so a healthy environment
+ * now does not hide an intermittent Codex-to-WSL identity drop. */
+export declare function countRecentCodexMidFlightOnboardings(coordRoot: string, nowMs?: number, windowMs?: number): number;
 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;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"}
+{"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;AASnD,OAAO,EACL,KAAK,4BAA4B,EAElC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,mCAAmC,CAAC;AAW3C,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,CA2BlD;AAgCD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,GAAG,IAAI,EACnC,oBAAoB,SAAI,GACvB,KAAK,GAAG,IAAI,CAed;AAID;mEACmE;AACnE,wBAAgB,oCAAoC,CAClD,SAAS,EAAE,MAAM,EACjB,KAAK,SAAa,EAClB,QAAQ,SAAqC,GAC5C,MAAM,CA0CR;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAoBnF"}

package/dist/commands/doctor.js

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

package/dist/commands/fetch.js

@@ -63,13 +63,14 @@ async function runFetch(url, opts, emit, context) {
             redirect: opts.redirect,
             signal: ac.signal,
             extraHeaders: context?.extraHeaders,
+            responseType: "bytes",
         });
     }
     finally {
         clearTimeout(timer);
     }
     if (opts.json) {
-        emit.data(result);
+        emit.data({ ...result, body: new TextDecoder().decode(result.body) });
         return;
     }
     if (opts.status) {
@@ -83,15 +84,15 @@ async function runFetch(url, opts, emit, context) {
     if (opts.output) {
         writeFileSync(opts.output, result.body);
         emit.file(opts.output, {
-            bytes: result.body.length,
+            bytes: result.body.byteLength,
             status: result.status,
             status_text: result.statusText,
         });
     }
     else {
-        // Body is potentially binary; route as text since most fetch responses
-        // are text/HTML/JSON. Binary callers should use --output.
-        emit.text(result.body);
+        // Text destinations decode at the presentation boundary. File output
+        // above keeps the response bytes intact regardless of MIME type.
+        emit.text(new TextDecoder().decode(result.body));
     }
     if (jar && result.cookiesSaved > 0) {
         emit.log(`saved ${result.cookiesSaved} cookie${result.cookiesSaved === 1 ? "" : "s"} to ${jar.path}`, "info");

package/dist/commands/files.d.ts

@@ -0,0 +1,34 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export { FILES_ORIGIN_HOST } from "../lib/local-file-url.js";
+export type LocalFileUrlMode = "auto" | "raw" | "viewer";
+export interface LocalFileUrlOptions {
+    coordRoot: string;
+    port: number;
+    mode?: LocalFileUrlMode;
+}
+export interface LocalFileUrl {
+    url: string;
+    relPath: string;
+    mode: Exclude<LocalFileUrlMode, "auto">;
+}
+export type DashboardRootErrorCode = "dashboard_unreachable" | "dashboard_identity_unavailable" | "dashboard_root_mismatch";
+export declare class DashboardRootError extends Error {
+    readonly code: DashboardRootErrorCode;
+    readonly hint: string;
+    constructor(code: DashboardRootErrorCode, message: string, hint: string);
+}
+export type DashboardRootFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Prove that the dashboard on the selected port serves the same canonical
+ * coordination root used to mint the file URL.
+ */
+export declare function verifyDashboardRoot(coordRoot: string, port: number, fetchImpl?: DashboardRootFetch): Promise<void>;
+/**
+ * Mint the local browser URL for a file under the dashboard's coord root.
+ * HTML defaults to the isolated files origin so scripts and relative assets
+ * work. Other files default to the dashboard viewer.
+ */
+export declare function mintLocalFileUrl(input: string, options: LocalFileUrlOptions): LocalFileUrl;
+export declare function registerFilesCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/commands/files.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAM1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,gCAAgC,GAChC,yBAAyB,CAAC;AAE9B,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,sBAAsB;IAErC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAFZ,IAAI,EAAE,sBAAsB,EACrC,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,MAAM;CAKxB;AAMD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,kBAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAmDf;AAuCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAS1F;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA0EN"}

package/dist/commands/files.js

@@ -0,0 +1,166 @@
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { resolveCoordRoot } from "../core/agents/coord-client.js";
+import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.js";
+import { coordRootId, localCoordRootIdUrl } from "../lib/coord-root-id.js";
+import { localFilesOriginUrl, localFileViewerUrl } from "../lib/local-file-url.js";
+export { FILES_ORIGIN_HOST } from "../lib/local-file-url.js";
+export class DashboardRootError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = "DashboardRootError";
+    }
+}
+/**
+ * Prove that the dashboard on the selected port serves the same canonical
+ * coordination root used to mint the file URL.
+ */
+export async function verifyDashboardRoot(coordRoot, port, fetchImpl = fetch) {
+    const url = localCoordRootIdUrl(port);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(5_000),
+        });
+    }
+    catch {
+        throw new DashboardRootError("dashboard_unreachable", `dashboard is not reachable at http://localhost:${port}`, "Start the dashboard for this repository, then retry.");
+    }
+    if (!response.ok) {
+        throw new DashboardRootError("dashboard_identity_unavailable", `dashboard at http://localhost:${port} cannot report its repository identity (HTTP ${response.status})`, "Update and restart the dashboard, then retry.");
+    }
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch {
+        throw new DashboardRootError("dashboard_identity_unavailable", `dashboard at http://localhost:${port} returned an invalid repository identity`, "Update and restart the dashboard, then retry.");
+    }
+    if (typeof payload.root_id !== "string") {
+        throw new DashboardRootError("dashboard_identity_unavailable", `dashboard at http://localhost:${port} returned an invalid repository identity`, "Update and restart the dashboard, then retry.");
+    }
+    const expected = coordRootId(coordRoot);
+    if (payload.root_id !== expected) {
+        throw new DashboardRootError("dashboard_root_mismatch", `dashboard at http://localhost:${port} serves a different repository`, "Stop that dashboard and start this repository's dashboard, then retry.");
+    }
+}
+function isOutsideRoot(relPath) {
+    return relPath === "" || relPath === ".." || relPath.startsWith(`..${path.sep}`);
+}
+function canonicalRepoPath(input, coordRoot) {
+    if (input.trim() === "")
+        throw new Error("path must not be empty");
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: URL output must stay one clean line
+    if (/[\u0000-\u001f\u007f]/.test(input))
+        throw new Error("path contains control bytes");
+    let root;
+    try {
+        root = realpathSync(coordRoot);
+    }
+    catch {
+        throw new Error(`coord root does not exist: ${coordRoot}`);
+    }
+    const candidate = path.isAbsolute(input) ? input : path.resolve(root, input);
+    let canonical;
+    try {
+        canonical = realpathSync(candidate);
+    }
+    catch {
+        throw new Error(`file does not exist: ${input}`);
+    }
+    const relPath = path.relative(root, canonical);
+    if (isOutsideRoot(relPath) || path.isAbsolute(relPath)) {
+        throw new Error(`file is outside the coord root: ${input}`);
+    }
+    if (!statSync(canonical).isFile())
+        throw new Error(`path is not a file: ${input}`);
+    return relPath.split(path.sep).join("/");
+}
+function isHtmlPath(relPath) {
+    const lower = relPath.toLowerCase();
+    return lower.endsWith(".html") || lower.endsWith(".htm");
+}
+/**
+ * Mint the local browser URL for a file under the dashboard's coord root.
+ * HTML defaults to the isolated files origin so scripts and relative assets
+ * work. Other files default to the dashboard viewer.
+ */
+export function mintLocalFileUrl(input, options) {
+    const relPath = canonicalRepoPath(input, options.coordRoot);
+    const requestedMode = options.mode ?? "auto";
+    const mode = requestedMode === "auto" ? (isHtmlPath(relPath) ? "raw" : "viewer") : requestedMode;
+    const url = mode === "raw"
+        ? localFilesOriginUrl(relPath, options.port)
+        : localFileViewerUrl(relPath, options.port);
+    return { url, relPath, mode };
+}
+export function registerFilesCommand(program, emit, context) {
+    const files = program
+        .command("files")
+        .description("Mint browser links for files served by the local dashboard");
+    files
+        .command("url")
+        .description("Mint the local browser URL for a repo file")
+        .argument("<path>", "Repo-relative path, or an absolute path inside the coord root")
+        .option("-p, --port <port>", `Dashboard port (default ${DEFAULT_WEB_PORT})`)
+        .option("--coord-root <dir>", "Override the coord root")
+        .option("--raw", "Use the isolated files origin, regardless of extension")
+        .option("--viewer", "Use the dashboard file viewer, regardless of extension")
+        .option("--no-verify", "Mint without checking the running dashboard's repository identity")
+        .action(async (filePath, opts) => {
+        if (opts.raw && opts.viewer) {
+            emit.error({
+                code: "conflicting_url_modes",
+                message: "--raw and --viewer cannot be used together",
+            });
+            emit.setExitCode(1);
+            return;
+        }
+        const coordRoot = opts.coordRoot ??
+            context?.resolveCoordRoot?.() ??
+            context?.repoRoot ??
+            resolveCoordRoot(process.cwd()) ??
+            process.cwd();
+        let port;
+        try {
+            port = resolveWebPort(opts.port, coordRoot);
+        }
+        catch (error) {
+            emit.error({
+                code: "invalid_web_port",
+                message: error instanceof Error ? error.message : "invalid web port",
+                hint: `Use an integer from 1024 through 65535; the default is ${DEFAULT_WEB_PORT}.`,
+            });
+            emit.setExitCode(1);
+            return;
+        }
+        try {
+            const result = mintLocalFileUrl(filePath, {
+                coordRoot,
+                port,
+                mode: opts.raw ? "raw" : opts.viewer ? "viewer" : "auto",
+            });
+            if (opts.verify !== false)
+                await verifyDashboardRoot(coordRoot, port);
+            emit.text(`${result.url}\n`);
+        }
+        catch (error) {
+            if (error instanceof DashboardRootError) {
+                emit.error({ code: error.code, message: error.message, hint: error.hint });
+                emit.setExitCode(1);
+                return;
+            }
+            emit.error({
+                code: "invalid_local_file",
+                message: error instanceof Error ? error.message : "invalid local file path",
+                hint: "Pass an existing file inside the dashboard coord root.",
+            });
+            emit.setExitCode(1);
+        }
+    });
+}

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,CA6HjF"}
+{"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;AA8EnD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA6HjF"}