harnery 0.33.0 → 0.34.0

package/src/commands/web.ts

@@ -1,9 +1,11 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { createServer } from "node:net";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
 import { lazyFetchWebRoot, webRunner } from "./web-fetch.ts";
 
 /**
@@ -88,13 +90,55 @@ function resolveWebRoot(emit: EmitContext, allowFetch: boolean): string | null {
 }
 
 interface UpOpts {
-  port: string;
+  port?: string;
   coordRoot?: string;
   prod?: boolean;
   fetch?: boolean;
   maxOldSpace?: string;
 }
 
+/**
+ * Probe the exact localhost socket Next will claim. This is deliberately a
+ * check-and-report step, not an alternate-port allocator: Harnery keeps one
+ * memorable URL and asks the caller to resolve a real conflict explicitly.
+ */
+export async function isWebPortAvailable(port: number): Promise<boolean> {
+  return await new Promise<boolean>((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", (error: NodeJS.ErrnoException) => {
+      if (error.code === "EADDRINUSE" || error.code === "EACCES") {
+        resolve(false);
+        return;
+      }
+      reject(error);
+    });
+    server.listen({ host: "127.0.0.1", port, exclusive: true }, () => {
+      server.close((error) => (error ? reject(error) : resolve(true)));
+    });
+  });
+}
+
+function reportInvalidPort(emit: EmitContext, error: unknown): void {
+  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}.`,
+  });
+  process.exitCode = 1;
+}
+
+async function requireAvailablePort(emit: EmitContext, port: number): Promise<boolean> {
+  if (await isWebPortAvailable(port)) return true;
+  emit.error({
+    code: "web_port_in_use",
+    message: `port ${port} is already in use`,
+    hint: `Stop the process using ${port}, or choose a deliberate override with \`harn web up --port <port>\`.`,
+  });
+  process.exitCode = 1;
+  return false;
+}
+
 export function registerWebCommand(program: Command, emit: EmitContext): void {
   const web = program
     .command("web")
@@ -106,7 +150,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       "Start the dashboard. Default: dev mode (HMR, no build needed). With " +
         "--prod, runs next start (requires a prior `harn web build`).",
     )
-    .option("-p, --port <port>", "Listen port", "9000")
+    .option("-p, --port <port>", `Listen port (default ${DEFAULT_WEB_PORT})`)
     .option(
       "--coord-root <dir>",
       "Override the coord root (default: cwd; web walks up looking for .harnery/)",
@@ -125,7 +169,13 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
       }
 
       const coordRoot = opts.coordRoot ?? process.cwd();
-      const port = String(opts.port);
+      let port: number;
+      try {
+        port = resolveWebPort(opts.port, opts.coordRoot);
+      } catch (error) {
+        reportInvalidPort(emit, error);
+        return;
+      }
       const mode = opts.prod ? "start" : "dev";
 
       if (opts.prod) {
@@ -141,6 +191,8 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         }
       }
 
+      if (!(await requireAvailablePort(emit, port))) return;
+
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
       emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
       emit.log(`files origin · http://harnery-files.localhost:${port}`, "info");
@@ -152,7 +204,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         env: {
           ...process.env,
           HARNERY_COORD_ROOT: coordRoot,
-          HARNERY_WEB_PORT: port,
+          HARNERY_WEB_PORT: String(port),
           ...(nodeOptionsWithHeapCap(heapMb)
             ? { NODE_OPTIONS: nodeOptionsWithHeapCap(heapMb) as string }
             : {}),
@@ -197,14 +249,14 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
   web
     .command("start")
     .description("Start the production server (next start). Requires prior `harn web build`.")
-    .option("-p, --port <port>", "Listen port", "9000")
+    .option("-p, --port <port>", `Listen port (default ${DEFAULT_WEB_PORT})`)
     .option("--coord-root <dir>", "Override the coord root")
     .option("--no-fetch", "Don't auto-fetch the dashboard if it's missing (npm installs)")
     .option(
       "--max-old-space <mb>",
       `V8 old-space ceiling in MB; 0 restores Next's own sizing (default ${DEFAULT_MAX_OLD_SPACE_MB}, env HARNERY_WEB_MAX_OLD_SPACE)`,
     )
-    .action((opts: { port: string; coordRoot?: string; fetch?: boolean; maxOldSpace?: string }) => {
+    .action(async (opts: UpOpts) => {
       const root = resolveWebRoot(emit, opts.fetch !== false);
       if (!root) {
         process.exitCode = 1;
@@ -221,7 +273,14 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         return;
       }
       const coordRoot = opts.coordRoot ?? process.cwd();
-      const port = String(opts.port);
+      let port: number;
+      try {
+        port = resolveWebPort(opts.port, opts.coordRoot);
+      } catch (error) {
+        reportInvalidPort(emit, error);
+        return;
+      }
+      if (!(await requireAvailablePort(emit, port))) return;
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
       emit.log(`harn web · http://localhost:${port} (start)`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
@@ -232,7 +291,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         env: {
           ...process.env,
           HARNERY_COORD_ROOT: coordRoot,
-          HARNERY_WEB_PORT: port,
+          HARNERY_WEB_PORT: String(port),
           ...(nodeOptionsWithHeapCap(heapMb)
             ? { NODE_OPTIONS: nodeOptionsWithHeapCap(heapMb) as string }
             : {}),

package/src/commands/work.ts

@@ -15,7 +15,7 @@ import {
   acceptWorkItem,
   cancelWorkItem,
   createWorkItem,
-  listWorkItems,
+  listWorkItemsWithWarnings,
   readWorkItem,
   reconcileAllWorkItems,
   reconcileWorkItem,
@@ -114,16 +114,27 @@ export function registerWorkCommand(program: Command, emit: EmitContext): void {
     .option("--json", "Emit complete work records as JSON")
     .action((opts: { state?: string; json?: boolean }) => {
       withWorkRoot(emit, (coordRoot) => {
-        const records = listWorkItems(coordRoot).filter(
+        const result = listWorkItemsWithWarnings(coordRoot);
+        const records = result.records.filter(
           (record) => !opts.state || record.projection.state === opts.state,
         );
         if (opts.json) {
           emit.config({ format: "json" });
           emit.data(records);
-        } else if (records.length === 0) {
+          for (const warning of result.warnings) {
+            emit.log(renderWorkListWarning(warning.work_id, warning.reason), "warn");
+          }
+        } else if (records.length === 0 && result.warnings.length === 0) {
           emit.text("no durable work\n");
         } else {
-          emit.text(`${records.map(renderWorkRow).join("\n")}\n`);
+          emit.text(
+            `${[
+              ...records.map(renderWorkRow),
+              ...result.warnings.map((warning) =>
+                renderWorkListWarning(warning.work_id, warning.reason),
+              ),
+            ].join("\n")}\n`,
+          );
         }
       });
     });
@@ -326,7 +337,11 @@ function registerGovernanceCommand(
       // dispatch. Resolve the goal BEFORE touching the work item so a refusal leaves
       // nothing half-done.
       const goalId =
-        name === "reopen" ? findCompletedMissionGoverning(coordRoot, workId) : undefined;
+        name === "reopen"
+          ? findCompletedMissionGoverning(coordRoot, workId, (warning) => {
+              emit.log(renderGovernorEnumerationWarning(warning.goal_id, warning.reason), "warn");
+            })
+          : undefined;
       const record = fn(coordRoot, workId, {
         ...opts,
         ...(opts.finding?.length ? { findings: opts.finding } : {}),
@@ -432,6 +447,14 @@ function renderWorkRow(record: WorkRecord): string {
   return `${record.intent.id}  ${projection.state.padEnd(17)}  ${renderAttemptBudget(record).padEnd(18)}  ${projection.next_action.padEnd(21)}  ${record.intent.title}`;
 }
 
+function renderWorkListWarning(workId: string, reason: string): string {
+  return `warning  ${workId}  unreadable: ${reason}`;
+}
+
+function renderGovernorEnumerationWarning(goalId: string, reason: string): string {
+  return `skipped unreadable governor ${goalId}: ${reason}`;
+}
+
 // `max_attempts` budgets CHARGED attempts (ADR 0046), so the budget is
 // charged/max, not the raw attempt count. When uncharged environment/upstream
 // attempts happened, surface them as a suffix rather than folding them into the

package/src/core/adapter.ts

@@ -0,0 +1,5 @@
+/** First-party harness adapters supported by Harnery's canonical V3 ledger. */
+export type Adapter = "claude-code" | "cursor" | "codex";
+
+/** Canonical producer classes used by V3 provenance. */
+export type EventSource = "agent-hooks" | "agent-coord" | "user" | "system";

package/src/core/adapters/attest.ts

@@ -1,9 +1,11 @@
 /**
  * The opt-in live probe that produces an attestation (ADR 0038).
  *
- * One bounded turn per adapter, through the same `spawn` the workflow engine
+ * One bounded probe per adapter, through the same `spawn` the workflow engine
  * uses, so what gets attested is the path production takes rather than a
- * parallel test rig.
+ * parallel test rig. The probe permits a small tool-iteration budget because
+ * repository instructions can require workflow children to register before
+ * replying; a one-iteration ceiling made a healthy Claude CLI look unreachable.
  */
 
 import type { SpawnResult } from "../workflow/types.ts";
@@ -24,6 +26,9 @@ import type { AdapterId, CapabilitySupport } from "./types.ts";
 export const ATTESTATION_PROMPT = "Reply with the single word: ok";
 
 export const DEFAULT_ATTESTATION_TIMEOUT_MS = 120_000;
+// Claude may consume three iterations on repository-required set-task,
+// identity recovery, and end-turn status before it can return the probe word.
+export const ATTESTATION_MAX_TURNS = 4;
 
 /** Vendor failures arrive as whole console transcripts, banner and prompt echo
  * included. Reports are bounded evidence, so the reason is collapsed to one
@@ -123,7 +128,7 @@ export async function runAdapterAttestation(
         : await adapter.spawn({
             prompt: ATTESTATION_PROMPT,
             timeoutMs,
-            maxTurns: 1,
+            maxTurns: ATTESTATION_MAX_TURNS,
             cwd,
             subscriptionOnly,
           });

package/src/core/adapters/profiles.ts

@@ -44,7 +44,7 @@ export const BUILTIN_ADAPTER_PROFILES = {
     authModel: "own-auth",
     modelFamily: "claude",
     effortValues: ["low", "medium", "high", "xhigh", "max"],
-    verified: { date: "2026-07-25", version: "2.1.197 (Claude Code)" },
+    verified: { date: "2026-08-18", version: "2.1.233 (Claude Code)" },
     capabilities: capabilities({
       effortSelection: supported("Mapped to `--effort <level>`."),
       maxTurns: supported("Mapped to `--max-turns <n>`."),
@@ -70,7 +70,7 @@ export const BUILTIN_ADAPTER_PROFILES = {
     authModel: "own-auth",
     modelFamily: "gpt",
     effortValues: ["none", "minimal", "low", "medium", "high", "xhigh"],
-    verified: { date: "2026-07-25", version: "codex-cli 0.144.5" },
+    verified: { date: "2026-08-04", version: "codex-cli 0.144.5" },
     // Verified against codex-cli 0.144.5: `--sandbox <mode>` plus
     // `sandbox_workspace_write.writable_roots`. Without the writable-root entry
     // a workspace-write child still cannot write a repository's .git directory.
@@ -106,7 +106,7 @@ export const BUILTIN_ADAPTER_PROFILES = {
     authModel: "own-auth",
     modelFamily: "multi",
     effortValues: [],
-    verified: { date: "2026-07-25", version: "2026.07.23-e383d2b" },
+    verified: { date: "2026-08-18", version: "2026.08.11-e8db854" },
     capabilities: capabilities({
       effortSelection: unsupported(
         "Cursor embeds effort in some parameterized model ids; Harnery does not rewrite model ids.",
@@ -115,9 +115,7 @@ export const BUILTIN_ADAPTER_PROFILES = {
       sessionId: supported("Read from the JSON result envelope."),
       cost: unsupported("The JSON result envelope carries no cost."),
       contextTelemetry: unknown("No stable Cursor context-usage payload has been certified."),
-      preCompactionSignal: unsupported(
-        "Harnery does not wire an unverified Cursor preCompact hook.",
-      ),
+      preCompactionSignal: supported("Cursor preCompact is wired to a durable checkpoint."),
       postCompactionSignal: unsupported(
         "Harnery does not wire an unverified Cursor postCompact hook.",
       ),

package/src/core/agents/canonical-emit.ts

@@ -1,43 +1,48 @@
 /**
- * Emit canonical events by spawning `agent-coord emit-event`. Used by every
- * `agents …` / `journal` / `presence` write that has a canonical state event.
+ * Emit canonical V3 observations by spawning `agent-coord emit-event`. Used by
+ * coordination commands whose durable state change also has a V3 audit event.
  *
  * Soft-fails: never throws into the caller. A failed emit logs to stderr
  * (visible to operators in their terminal) but never breaks the CLI flow.
  *
- * Synchronous spawn: the projector runs before the CLI returns. ~20ms
- * latency budget per call.
+ * Synchronous spawn: the projector runs before the CLI returns. The child has
+ * a 15-second safety budget; loaded-host checks normally finish in a few
+ * seconds and record the observation before the parent command exits.
  */
 
 import { spawnSync } from "node:child_process";
+import type { LiveCoordinationObservationV3 } from "../events/v3/live-observation.ts";
 import { coordBinPath } from "./coord-bin.ts";
 import { resolveCoordRoot } from "./coord-client.ts";
 
-export interface CanonicalEmitInput {
-  type: string;
+export type EventV3EmitObservation =
+  | LiveCoordinationObservationV3
+  | {
+      event_type: "coord.lifecycle_changed";
+      new_state: "active" | "blocked" | "done";
+      reason?: string;
+      suggested_session_name?: string;
+    };
+
+export interface EventV3EmitInput {
   owner: string;
   session: string;
   adapter: "claude-code" | "cursor" | "codex";
-  data: Record<string, unknown>;
-  turnId?: string;
-  parentSessionId?: string;
-  parentTurnId?: string;
+  observation: EventV3EmitObservation;
 }
 
 /**
  * Resolve the coord root for a canonical emit.
  *
  * Delegates to `resolveCoordRoot()`, the single resolution the hooks and the
- * CLI's reads also use. An emit resolved any other way is an emit the Stop hook
- * cannot see: the hook reads `state.status_checked` from the stream under ITS
- * root, so a divergent emit root blocks rule 1/3 on a turn that did run
- * `agents status`, and no sequence of CLI commands can satisfy it.
+ * CLI's reads also use. An observation resolved any other way can disappear
+ * from the live V3 generation even though the command itself succeeded.
  */
 export function resolveEmitRoot(start: string = process.cwd()): string | null {
   return resolveCoordRoot(start);
 }
 
-export function emitCanonical(input: CanonicalEmitInput): boolean {
+export function emitEventV3(input: EventV3EmitInput): boolean {
   const root = resolveEmitRoot();
   if (!root) return false;
   const binary = coordBinPath("agent-coord", root);
@@ -46,31 +51,35 @@ export function emitCanonical(input: CanonicalEmitInput): boolean {
     const args = [
       "emit-event",
       "--type",
-      input.type,
+      input.observation.event_type,
       "--owner",
       input.owner,
       "--session",
       input.session,
       "--adapter",
       input.adapter,
-      "--data-json",
-      JSON.stringify(input.data),
+      "--data-stdin",
     ];
-    if (input.turnId) args.push("--turn-id", input.turnId);
-    if (input.parentSessionId) args.push("--parent-session-id", input.parentSessionId);
-    if (input.parentTurnId) args.push("--parent-turn-id", input.parentTurnId);
     // Pin cwd + HARNERY_COORD_ROOT_OVERRIDE so the child writes to the SAME
     // stream we resolved, regardless of where the caller's shell is cd'd.
     const result = spawnSync(binary, args, {
       encoding: "utf8",
-      stdio: "ignore",
-      timeout: 3000,
+      stdio: ["pipe", "ignore", "pipe"],
+      input: JSON.stringify(input.observation),
+      // Budget the append generously. Under multi-agent contention a single
+      // `agent-coord emit-event` has been measured at 3.4-4.1s on a loaded
+      // host, so a 3s cap timed out every emit and blocked end-of-turn checks
+      // -- exactly the failure this module's doc warns about.
+      timeout: 15000,
       cwd: root,
       env: { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: root },
     });
     if (result.error || result.status !== 0) {
-      const why = result.error ? result.error.message : `exit ${result.status}`;
-      process.stderr.write(`emitCanonical: ${input.type} emit failed (${why})\n`); // lint-ok-emission: soft-fail diagnostic promised by the module doc; silent drops cost blocked turns
+      const detail = typeof result.stderr === "string" ? result.stderr.trim() : "";
+      const why = result.error
+        ? result.error.message
+        : `exit ${result.status}${detail ? `: ${detail}` : ""}`;
+      process.stderr.write(`emitEventV3: ${input.observation.event_type} emit failed (${why})\n`); // lint-ok-emission: soft-fail diagnostic promised by the module doc; silent drops cost blocked turns
       return false;
     }
     return true;