harnery 0.35.0 → 0.37.0

package/src/commands/files.ts

@@ -0,0 +1,243 @@
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { resolveCoordRoot } from "../core/agents/coord-client.ts";
+import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
+import { coordRootId, localCoordRootIdUrl } from "../lib/coord-root-id.ts";
+import { localFilesOriginUrl, localFileViewerUrl } from "../lib/local-file-url.ts";
+
+export { FILES_ORIGIN_HOST } from "../lib/local-file-url.ts";
+
+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 class DashboardRootError extends Error {
+  constructor(
+    readonly code: DashboardRootErrorCode,
+    message: string,
+    readonly hint: string,
+  ) {
+    super(message);
+    this.name = "DashboardRootError";
+  }
+}
+
+interface DashboardRootPayload {
+  root_id?: unknown;
+}
+
+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 async function verifyDashboardRoot(
+  coordRoot: string,
+  port: number,
+  fetchImpl: DashboardRootFetch = fetch,
+): Promise<void> {
+  const url = localCoordRootIdUrl(port);
+  let response: 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: DashboardRootPayload;
+  try {
+    payload = (await response.json()) as DashboardRootPayload;
+  } 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: string): boolean {
+  return relPath === "" || relPath === ".." || relPath.startsWith(`..${path.sep}`);
+}
+
+function canonicalRepoPath(input: string, coordRoot: string): string {
+  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: string;
+  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: string;
+  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: string): boolean {
+  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: string, options: LocalFileUrlOptions): LocalFileUrl {
+  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: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  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: string,
+        opts: {
+          port?: string;
+          coordRoot?: string;
+          raw?: boolean;
+          viewer?: boolean;
+          verify?: boolean;
+        },
+      ) => {
+        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: number;
+        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/src/commands/governor.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
@@ -8,6 +8,7 @@ import {
   probeBinaryVersion,
   readAttestation,
 } from "../core/adapters/index.ts";
+import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { workflowSubscriptionOnly } from "../core/config.ts";
 import { inspectAdapterSpread } from "../core/governor/adapter-spread.ts";
 import {
@@ -22,7 +23,6 @@ import {
   type GovernorRunReport,
   type GovernorServiceConfig,
   type GovernorServiceStatus,
-  governorServiceLogPath,
   listGovernorsWithWarnings,
   readGovernor,
   readGovernorPlan,
@@ -35,7 +35,7 @@ import {
   runGovernorServiceDaemon,
   spawnGovernorService,
 } from "../core/governor/index.ts";
-import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
+import { readGovernorServiceLogs } from "../core/governor/service-read.ts";
 import type { PolicyIsolation } from "../core/policy/index.ts";
 import { loadPolicyFile } from "../core/policy/index.ts";
 import type { WorkflowSpecialistProfile } from "../core/workflow/index.ts";
@@ -62,6 +62,7 @@ interface CreateOpts {
 interface RunOpts {
   adapter?: string;
   cwd?: string;
+  observePressure?: boolean;
   subscriptionOnly?: boolean;
   allowApiBilling?: boolean;
   policy?: string;
@@ -401,16 +402,17 @@ function registerServiceCommand(
       withGovernorRoot(emit, (coordRoot) => {
         const lines = integer(opts.lines) ?? 50;
         if (lines > 10_000) throw new Error("service log lines must not exceed 10000");
-        const path = governorServiceLogPath(coordRoot);
-        if (!existsSync(path)) {
+        const result = readGovernorServiceLogs(coordRoot, {
+          max_bytes: 512 * 1024,
+          max_records: 10_000,
+        });
+        if (result.lines.length === 0) {
           emit.text("no governor service log\n");
           return;
         }
-        const selected = readFileSync(path, "utf8")
-          .split("\n")
-          .slice(-(lines + 1))
-          .join("\n");
-        emit.text(selected.endsWith("\n") ? selected : `${selected}\n`);
+        emit.text(`${result.lines.slice(-lines).join("\n")}\n`);
+        if (result.truncated)
+          emit.log("governor service log read stopped at its bounded budget", "warn");
       });
     });
 
@@ -437,6 +439,10 @@ function addServiceOptions(command: Command): Command {
     .option("--error-backoff-max-ms <n>", "Maximum service-error backoff (default 300000)")
     .option("--adapter <name>", "Fallback adapter for agent calls without a specialist")
     .option("--cwd <dir>", "Working directory for child agents")
+    .option(
+      "--observe-pressure",
+      "Record observer-only local pressure before each workflow's first real child dispatch",
+    )
     .option("--subscription-only", "Require stored adapter-login billing")
     .option("--allow-api-billing", "Permit API-key override billing")
     .option("--policy <file>", "Host policy JSON/JSONC")
@@ -595,6 +601,9 @@ function registerRunCommand(
             spawners: registry.spawners(),
             defaultAdapter: opts.adapter,
             cwd: opts.cwd,
+            diagnosticAdmission: opts.observePressure
+              ? { schema_version: 1, mode: "shadow" }
+              : undefined,
             subscriptionOnly:
               opts.subscriptionOnly === true ? true : workflowSubscriptionOnly(coordRoot),
             allowApiBilling: opts.allowApiBilling,
@@ -922,7 +931,7 @@ function delay(ms: number): Promise<void> {
 }
 
 function withGovernorRoot(emit: EmitContext, fn: (coordRoot: string) => void): void {
-  const coordRoot = findCoordRoot();
+  const coordRoot = resolveCoordRoot();
   if (!coordRoot) {
     emit.error({
       code: "no_coord_root",
@@ -943,7 +952,7 @@ async function withGovernorRootAsync(
   emit: EmitContext,
   fn: (coordRoot: string) => Promise<void>,
 ): Promise<void> {
-  const coordRoot = findCoordRoot();
+  const coordRoot = resolveCoordRoot();
   if (!coordRoot) {
     emit.error({
       code: "no_coord_root",

package/src/commands/inbox.ts

@@ -0,0 +1,61 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import type { HarneryInboxService } from "../core/inbox/service.ts";
+
+export function registerInboxCommand(
+  program: Command,
+  emit: EmitContext,
+  service?: HarneryInboxService,
+): void {
+  const inbox = program.command("inbox").description("Inspect private coordination inbox state");
+  inbox
+    .command("list <recipient>")
+    .option("--json", "Emit stable JSON")
+    .action((recipient: string, options: { json?: boolean }) => {
+      run(emit, () => {
+        const rows = requireInboxService(service)
+          .pending(recipient)
+          .map((record) => ({
+            message_id: record.message_id,
+            sender_instance_id: record.sender_instance_id,
+            sender_display_name: record.sender_display_name,
+            created_at: record.created_at,
+            body_bytes: record.body_bytes,
+            body: record.body,
+          }));
+        if (options.json) {
+          emit.config({ format: "json" });
+          emit.data({ schema: "harnery.inbox-list/v1", recipient_instance_id: recipient, rows });
+        } else emit.rows(rows);
+      });
+    });
+  inbox
+    .command("status <recipient>")
+    .option("--json", "Emit stable JSON")
+    .action((recipient: string, options: { json?: boolean }) => {
+      run(emit, () => {
+        const status = requireInboxService(service).status(recipient);
+        if (options.json) {
+          emit.config({ format: "json" });
+          emit.data(status);
+        } else emit.rows([status as unknown as Record<string, unknown>]);
+      });
+    });
+}
+
+function requireInboxService(service?: HarneryInboxService): HarneryInboxService {
+  if (!service) throw new Error("coordination inbox is not configured by this host");
+  return service;
+}
+
+function run(emit: EmitContext, action: () => void): void {
+  try {
+    action();
+  } catch (error) {
+    emit.error({
+      code: "inbox_failed",
+      message: error instanceof Error ? error.message : String(error),
+    });
+    emit.setExitCode(1);
+  }
+}

package/src/commands/init.ts

@@ -33,7 +33,6 @@ import {
   readEventV3ControlState,
   sha256V3,
 } from "../core/events/v3/index.ts";
-import { liveEventV3BuildId } from "../core/events/v3/live-routing.ts";
 import { ADAPTER_SPECS, type AdapterId, type AdapterSpec } from "../core/hooks/adapter/events.ts";
 import {
   agentHookPathForProject,
@@ -46,6 +45,7 @@ import {
   makeEntry,
   type SettingsFile,
 } from "../core/hooks/adapter/wiring.ts";
+import { applyIndexerExclusions } from "../lib/indexer-exclusions.ts";
 import {
   type ApplyResult,
   applyInstructions,
@@ -61,6 +61,7 @@ interface InitOpts {
   adapter: string;
   dryRun?: boolean;
   check?: boolean;
+  instructionsOnly?: boolean;
   projectRoot?: string;
 }
 
@@ -75,7 +76,11 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
     )
     .option("--adapter <id>", "claude-code | cursor | codex", "claude-code")
     .option("--dry-run", "Show what would change without writing")
-    .option("--check", "Report instructions/skills drift without writing; exit 0/2/1")
+    .option("--check", "Report managed-surface drift without writing; exit 0/2/1")
+    .option(
+      "--instructions-only",
+      "Refresh only AGENTS.md regions and Harnery-owned skills; leave runtime wiring untouched",
+    )
     .option("--project-root <path>", "Project root (default: git toplevel, else cwd)")
     .action((opts: InitOpts) => {
       const adapter = opts.adapter as AdapterId;
@@ -94,6 +99,44 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
       // CLI re-stamps the host's name into committed agent-facing surfaces.
       const bin = pinnedBinName(projectRoot) ?? (binName?.trim() ? binName : DEFAULT_BIN_NAME);
 
+      // ── --instructions-only: committed guidance, never runtime wiring ────
+      // Some hosts consume Harnery's managed instruction bundle without
+      // enabling local adapter hooks or an event ledger. Keep this branch
+      // before every coord-root, config, ledger, adapter-settings, and Git-hook
+      // operation so its no-runtime-writes contract is structural.
+      if (opts.instructionsOnly === true) {
+        if (opts.check === true) {
+          const { status, issues } = checkInstructions(projectRoot, { binName: bin, adapter });
+          const head =
+            status === "fresh"
+              ? `${bin} init --instructions-only --check: instructions + skills are current`
+              : status === "drift"
+                ? `${bin} init --instructions-only --check: drift found (re-run \`init --instructions-only\` to refresh)`
+                : `${bin} init --instructions-only --check: error`;
+          const lines = issues.length
+            ? `\n${issues.map((issue) => `  ✗ ${issue}`).join("\n")}`
+            : "";
+          emit.text(`${head}${lines}`);
+          emit.setExitCode(status === "fresh" ? 0 : status === "drift" ? 2 : 1);
+          return;
+        }
+
+        const dryRun = opts.dryRun === true;
+        let applied: ApplyResult;
+        try {
+          applied = applyInstructions(projectRoot, { binName: bin, adapter, dryRun });
+        } catch (err) {
+          if (!(err instanceof HostAddendumError)) throw err;
+          emit.text(`${bin} init --instructions-only: ${err.message}`);
+          emit.setExitCode(1);
+          return;
+        }
+        emit.text(
+          renderInstructionsOnly(projectRoot, bin, dryRun, applied.actions, applied.warnings),
+        );
+        return;
+      }
+
       // ── --check: read-only drift report on every init-managed surface ─────
       if (opts.check === true) {
         const { status, issues } = checkInstructions(projectRoot, { binName: bin, adapter });
@@ -158,7 +201,7 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
         if (gitHooks.status !== "fresh") issues.push(...gitHooks.issues);
         const ledger = readEventV3ControlState(projectRoot);
         if (ledger.state !== "active") issues.push(`event ledger V3 is ${ledger.state}`);
-        const ledgerRuntimeIssues = eventLedgerV3RuntimeIssues(ledger, gitBuild(HARNERY_ROOT));
+        const ledgerRuntimeIssues = eventLedgerV3RuntimeIssues(ledger);
         if (ledgerRuntimeIssues.length > 0) {
           issues.push(`event ledger V3 is runtime-stale (${ledgerRuntimeIssues.join(", ")})`);
         }
@@ -199,6 +242,13 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
         actions.push("+ created .harnery/ (+ .harnery/.gitignore)");
       }
 
+      // ── 1a′. editor indexer exclusions ─────────────────────────────────────
+      // .harnery/.gitignore keeps git-aware tools out, but Cursor's codebase
+      // indexer and the VS Code/Cursor file watcher do not respect gitignore.
+      // A busy coord root holds enough ledger events and artifacts to become a
+      // boot-time indexing storm, so exclude it from both here.
+      actions.push(...applyIndexerExclusions(projectRoot, dryRun));
+
       // ── 1b. stamp the host bin name ────────────────────────────────────────
       // The coord binaries (agent-hook/agent-coord) and web UI run as harnery
       // itself, so they can't see a consumer CLI's name; they read it back from
@@ -225,7 +275,7 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
       // ── 1d. universal V3 event ledger ────────────────────────────────────
       if (dryRun) {
         const ledger = readEventV3ControlState(projectRoot);
-        const runtimeIssues = eventLedgerV3RuntimeIssues(ledger, gitBuild(HARNERY_ROOT));
+        const runtimeIssues = eventLedgerV3RuntimeIssues(ledger);
         actions.push(
           ledger.state === "active" && runtimeIssues.length === 0
             ? "· event ledger V3 is active"
@@ -236,7 +286,7 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
       } else {
         const harneryBuild = gitBuild(HARNERY_ROOT);
         const ledgerBefore = readEventV3ControlState(projectRoot);
-        const runtimeIssues = eventLedgerV3RuntimeIssues(ledgerBefore, harneryBuild);
+        const runtimeIssues = eventLedgerV3RuntimeIssues(ledgerBefore);
         const initialized = initializeEventLedgerV3({
           coordRoot: projectRoot,
           harneryBuild,
@@ -337,23 +387,16 @@ function digestConfig(path: string): `sha256:${string}` {
 }
 
 /**
- * Runtime gates bound into an immutable V3 epoch. `init` is the explicit
- * upgrade boundary: when code or capability profiles change, it archives the
- * old epoch intact and activates a compatible one instead of letting upgraded
- * hooks fail closed against stale approvals.
+ * Runtime contracts bound into an immutable V3 epoch. `init` replaces the
+ * epoch only when the schema or adapter capability contract changed. A new
+ * Harnery build alone keeps the current epoch and its live session generations.
  */
-export function eventLedgerV3RuntimeIssues(
-  control: EventV3ControlState,
-  harneryBuild: string,
-): string[] {
+export function eventLedgerV3RuntimeIssues(control: EventV3ControlState): string[] {
   if (control.state !== "active") return [];
   const issues: string[] = [];
   const profile = control.genesis.profile;
   if (profile.initial_schema_digest !== EVENT_V3_SCHEMA_DIGEST) issues.push("schema digest");
   if (profile.contract_source_digest !== EVENT_V3_SCHEMA_DIGEST) issues.push("contract digest");
-  if (!profile.producer_build_ids.includes(liveEventV3BuildId(harneryBuild))) {
-    issues.push("producer build");
-  }
   const expectedCapabilities = Object.values(ADAPTER_CAPABILITY_PROFILES_V3).map((value) =>
     sha256V3(canonicalJsonV3(value)),
   );
@@ -699,6 +742,25 @@ function render(
   return `${head}\n  root: ${projectRoot}\n${actions.map((a) => `  ${a}`).join("\n")}${warnBlock}${tail}`;
 }
 
+function renderInstructionsOnly(
+  projectRoot: string,
+  binName: string,
+  dryRun: boolean,
+  actions: string[],
+  warnings: string[] = [],
+): string {
+  const head = dryRun
+    ? `${binName} init --instructions-only (dry run): no changes written`
+    : `${binName} init --instructions-only`;
+  const warnBlock = warnings.length
+    ? `\n${warnings.map((warning) => `  ! ${warning}`).join("\n")}`
+    : "";
+  const tail = dryRun
+    ? "\nRe-run without --dry-run to apply."
+    : "\nDone. Adapter hooks, managed Git hooks, configuration, and event ledger state were left unchanged.";
+  return `${head}\n  root: ${projectRoot}\n${actions.map((action) => `  ${action}`).join("\n")}${warnBlock}${tail}`;
+}
+
 function gitTopLevel(): string | null {
   const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
   const out = r.status === 0 ? r.stdout.trim() : "";