harnery 0.40.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -137,6 +137,11 @@
       "types": "./dist/core/supervisor/index.d.ts",
       "import": "./dist/core/supervisor/index.js"
     },
+    "./core/servers": {
+      "bun": "./src/core/servers/index.ts",
+      "types": "./dist/core/servers/index.d.ts",
+      "import": "./dist/core/servers/index.js"
+    },
     "./core/diagnostics": {
       "bun": "./src/core/diagnostics/index.ts",
       "types": "./dist/core/diagnostics/index.d.ts",
@@ -187,6 +192,11 @@
       "types": "./dist/lib/http/index.d.ts",
       "import": "./dist/lib/http/index.js"
     },
+    "./lib/pace": {
+      "bun": "./src/lib/pace/index.ts",
+      "types": "./dist/lib/pace/index.d.ts",
+      "import": "./dist/lib/pace/index.js"
+    },
     "./lib/machine": {
       "bun": "./src/lib/machine.ts",
       "types": "./dist/lib/machine.d.ts",
@@ -219,6 +229,8 @@
     "src",
     "dist",
     "schemas",
+    "opencode-plugin/package.json",
+    "opencode-plugin/src/index.ts",
     "README.md",
     "LICENSE",
     "!src/**/*.test.ts",
@@ -242,13 +254,13 @@
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build",
     "typecheck": "bun x tsc --noEmit",
-    "lint": "bun x @biomejs/biome check src openclaw-plugin",
+    "lint": "bun x @biomejs/biome check src openclaw-plugin opencode-plugin",
     "check:portability": "bun run scripts/check-portability.ts",
     "check:public-surface": "bun run scripts/check-public-surface.ts",
     "check:layering": "bun run scripts/check-layering.ts",
     "probe:supervisor-budget": "bun run scripts/probe-supervisor-budget.ts",
-    "lint:fix": "bun x @biomejs/biome check --write src openclaw-plugin",
-    "format": "bun x @biomejs/biome format --write src openclaw-plugin",
+    "lint:fix": "bun x @biomejs/biome check --write src openclaw-plugin opencode-plugin",
+    "format": "bun x @biomejs/biome format --write src openclaw-plugin opencode-plugin",
     "test": "bun run scripts/test.mjs",
     "test:list": "bun run scripts/test.mjs --list",
     "test:web": "cd web && bun install && bun test",

package/schemas/config.schema.json

@@ -216,6 +216,19 @@
         }
       }
     },
+    "storage": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Who can use this project's .harnery/ state. Read from the project file only.",
+      "properties": {
+        "sharing": {
+          "type": "string",
+          "enum": ["private", "group"],
+          "default": "private",
+          "description": "private: state is 0700/0600, owner-only. group: 2770/0660 for several Unix users sharing the project directory's group (the directory must be setgid). Never opens state to other users. Env override: HARNERY_STORAGE_SHARING."
+        }
+      }
+    },
     "artifacts": {
       "type": "object",
       "additionalProperties": false,
@@ -227,6 +240,53 @@
           "maximum": 3650,
           "default": 3,
           "description": "Retention for `harn artifacts create` when --days is absent. Env override: HARNERY_ARTIFACT_RETENTION_DAYS."
+        },
+        "auto_clean": {
+          "type": "boolean",
+          "default": true,
+          "description": "Run the throttled artifact cleanup at session start and before new artifact work. Env override: HARNERY_ARTIFACT_AUTO_CLEAN."
+        },
+        "max_bytes": {
+          "type": "integer",
+          "minimum": 67108864,
+          "maximum": 1099511627776,
+          "default": 21474836480,
+          "description": "Soft repository budget in bytes of disk use for unheld managed workspaces. Env override: HARNERY_ARTIFACT_MAX_BYTES."
+        },
+        "max_unit_bytes": {
+          "type": "integer",
+          "minimum": 16777216,
+          "maximum": 1099511627776,
+          "default": 1073741824,
+          "description": "Per-workspace ceiling in bytes of disk use; a workspace created with --big is exempt. Env override: HARNERY_ARTIFACT_MAX_UNIT_BYTES."
+        },
+        "idle_grace_hours": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8760,
+          "default": 24,
+          "description": "Hours an unexpired workspace must be idle (no file change, no owner heartbeat) before a size rule may delete it. Env override: HARNERY_ARTIFACT_IDLE_GRACE_HOURS."
+        },
+        "hold_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "default": 14,
+          "description": "Days a hold protects a workspace before it lapses unless renewed with `harn artifacts hold` (same id and reason). Env override: HARNERY_ARTIFACT_HOLD_DAYS."
+        },
+        "max_held_bytes": {
+          "type": "integer",
+          "minimum": 67108864,
+          "maximum": 1099511627776,
+          "default": 21474836480,
+          "description": "Advisory budget in bytes of disk use for held workspaces. Exceeding it produces warnings; held work is never deleted. Env override: HARNERY_ARTIFACT_MAX_HELD_BYTES."
+        },
+        "min_free_bytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1125899906842624,
+          "default": 21474836480,
+          "description": "Free-disk floor for the artifact store. Below it, artifact commands warn and `artifacts create --big` refuses without --allow-low-disk. 0 disables the floor. Env override: HARNERY_ARTIFACT_MIN_FREE_BYTES."
         }
       }
     },
@@ -293,6 +353,37 @@
           "type": "boolean",
           "default": false,
           "description": "Pin `workflow run` to subscription billing: API-key vars are scrubbed from every child env. Stamped true by `harn init` when the key is absent. Env override: HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=1|0."
+        },
+        "workerFullAccess": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Let qualifying workflow workers launch without their vendor sandbox (ADR 0192). A launch qualifies only when this is enabled, the launching session itself can be shown to run with full access, and the worker's exact model and effort meet a floor listed here. Anything else keeps the ordinary sandboxed projection. Project config only; a user-global file cannot grant it. HARNERY_WORKFLOW_WORKER_FULL_ACCESS=0 turns it off for one process. An invalid value disables it entirely.",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "floors": {
+              "type": "object",
+              "description": "Per-adapter list of models a worker may run unsandboxed on. Keys are adapter ids.",
+              "additionalProperties": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["model"],
+                  "properties": {
+                    "model": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Exact model id the worker must name. Aliases and the adapter's default model never match."
+                    },
+                    "minEffort": {
+                      "type": "string",
+                      "description": "Lowest qualifying effort on the adapter's declared effort scale. Required for an adapter with an effort scale; not allowed for one that encodes effort in the model id."
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -336,6 +427,19 @@
               "default": 65536
             }
           }
+        },
+        "codexWindowsBridge": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["entryPoint"],
+          "description": "Route Windows-native Codex hooks through a resident WSL bridge (decision record 0197). init writes a commandWindows on each Codex hook that calls entryPoint when it is on PATH and the working directory is a WSL path, and otherwise runs the usual command. Project config only.",
+          "properties": {
+            "entryPoint": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+              "description": "Windows command name the bridge installs, for example codex-wsl-hook. Only a bridge that implements the decision record 0197 contract should install it."
+            }
+          }
         }
       }
     },

package/schemas/event-v3.schema.json

@@ -23775,6 +23775,170 @@
                 }
               }
             },
+            "line_changes": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "type": "object",
+                  "required": [
+                    "state",
+                    "value",
+                    "attestation",
+                    "confidence"
+                  ],
+                  "properties": {
+                    "state": {
+                      "const": "observed",
+                      "type": "string"
+                    },
+                    "value": {
+                      "additionalProperties": false,
+                      "type": "object",
+                      "required": [
+                        "added",
+                        "removed"
+                      ],
+                      "properties": {
+                        "added": {
+                          "minimum": 0,
+                          "type": "integer"
+                        },
+                        "removed": {
+                          "minimum": 0,
+                          "type": "integer"
+                        }
+                      }
+                    },
+                    "attestation": {
+                      "anyOf": [
+                        {
+                          "const": "native",
+                          "type": "string"
+                        },
+                        {
+                          "const": "derived",
+                          "type": "string"
+                        },
+                        {
+                          "const": "inferred",
+                          "type": "string"
+                        }
+                      ]
+                    },
+                    "confidence": {
+                      "anyOf": [
+                        {
+                          "const": "exact",
+                          "type": "string"
+                        },
+                        {
+                          "const": "high",
+                          "type": "string"
+                        },
+                        {
+                          "const": "medium",
+                          "type": "string"
+                        },
+                        {
+                          "const": "low",
+                          "type": "string"
+                        }
+                      ]
+                    }
+                  }
+                },
+                {
+                  "additionalProperties": false,
+                  "type": "object",
+                  "required": [
+                    "state",
+                    "capability"
+                  ],
+                  "properties": {
+                    "state": {
+                      "const": "unsupported",
+                      "type": "string"
+                    },
+                    "capability": {
+                      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$",
+                      "type": "string"
+                    }
+                  }
+                },
+                {
+                  "additionalProperties": false,
+                  "type": "object",
+                  "required": [
+                    "state",
+                    "capability",
+                    "reason"
+                  ],
+                  "properties": {
+                    "state": {
+                      "const": "expected_but_missing",
+                      "type": "string"
+                    },
+                    "capability": {
+                      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$",
+                      "type": "string"
+                    },
+                    "reason": {
+                      "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$",
+                      "type": "string"
+                    }
+                  }
+                },
+                {
+                  "additionalProperties": false,
+                  "type": "object",
+                  "required": [
+                    "state",
+                    "reason"
+                  ],
+                  "properties": {
+                    "state": {
+                      "const": "redacted",
+                      "type": "string"
+                    },
+                    "reason": {
+                      "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$",
+                      "type": "string"
+                    }
+                  }
+                },
+                {
+                  "additionalProperties": false,
+                  "type": "object",
+                  "required": [
+                    "state",
+                    "reason"
+                  ],
+                  "properties": {
+                    "state": {
+                      "const": "unknown",
+                      "type": "string"
+                    },
+                    "reason": {
+                      "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$",
+                      "type": "string"
+                    }
+                  }
+                },
+                {
+                  "additionalProperties": false,
+                  "type": "object",
+                  "required": [
+                    "state"
+                  ],
+                  "properties": {
+                    "state": {
+                      "const": "not_applicable",
+                      "type": "string"
+                    }
+                  }
+                }
+              ]
+            },
             "span": {
               "additionalProperties": false,
               "type": "object",

package/src/commander.ts

@@ -320,6 +320,12 @@ function harneryCommandBundles({
   binName,
 }: CommandBundleContext): LazyCommandBundle[] {
   return [
+    lazy(
+      "disk [path]",
+      "Measure checkout disk usage, including nested repositories and ignored files",
+      async (program) => (await import("./commands/disk.ts")).registerDiskCommand(program, emit),
+      { hasOptions: true },
+    ),
     lazy(
       "tokens <files...>",
       "Count tokens in text/markdown files (offline, uses o200k_base as Claude proxy)",
@@ -507,6 +513,13 @@ function harneryCommandBundles({
         (await import("./commands/browse-ai.ts")).registerBrowseAiCommand(program, emit, context),
       { hasOptions: true },
     ),
+    lazy(
+      "webview <url>",
+      `Lightweight headless page probe through Bun.WebView (experimental, Bun 1.4+). Fresh ephemeral browser per call; use ${binName} browse for login, cookies, HAR, and QA.`,
+      async (program) =>
+        (await import("./commands/webview.ts")).registerWebviewCommand(program, emit, binName),
+      { hasOptions: true },
+    ),
     {
       commands: [
         {
@@ -589,6 +602,13 @@ function harneryCommandBundles({
       async (program) =>
         (await import("./commands/storage.ts")).registerStorageCommand(program, emit, context),
     ),
+    lazy(
+      "rm <paths...>",
+      "Preview guarded removal of untracked files; --yes applies permanent deletion",
+      async (program) =>
+        (await import("./commands/rm.ts")).registerRmCommand(program, emit, context),
+      { hasOptions: true },
+    ),
     lazy("logs", "List and query bounded Harnery log families", async (program) =>
       (await import("./commands/logs.ts")).registerLogsCommand(program, emit, context),
     ),
@@ -654,6 +674,12 @@ function harneryCommandBundles({
       async (program) =>
         (await import("./commands/tunnel.ts")).registerTunnelCommand(program, emit, context),
     ),
+    lazy(
+      "servers",
+      "Every local server started in this project: list, stop, clean up idle session servers, read logs",
+      async (program) =>
+        (await import("./commands/servers.ts")).registerServersCommand(program, emit, context),
+    ),
     lazy(
       "docs",
       "Documentation tooling: freshness report, metadata, lint, sweep, index",

package/src/commands/agents.ts

@@ -78,6 +78,9 @@ import {
   readHeartbeat as readHeartbeatCache,
 } from "../core/agents/state/heartbeat-writer.ts";
 import {
+  describeLiveAuthorityBlockV3,
+  liveAuthorityBlockHintV3,
+  liveAuthorityBlockV3,
   readLiveCoordinationRow,
   readLiveCoordinationRows,
 } from "../core/agents/state/live-coordination-view.ts";
@@ -86,13 +89,18 @@ import {
   foldSessionState,
   type TaskState,
 } from "../core/agents/state/session-state.ts";
+import { turnChangesStatusRow } from "../core/agents/turn-changes.ts";
 import { turnElapsedStatusRow } from "../core/agents/turn-elapsed.ts";
 import {
   coordFreshnessSeconds,
   resolveBinName,
   sessionFinalizationConfig,
 } from "../core/config.ts";
-import { EVENT_ADAPTER_IDS_V3, type EventAdapterIdV3 } from "../core/events/v3/adapter-id.ts";
+import {
+  EVENT_ADAPTER_IDS_V3,
+  type EventAdapterIdV3,
+  normalizeEventAdapterIdV3,
+} from "../core/events/v3/adapter-id.ts";
 import type { EventTypeV3 } from "../core/events/v3/contract.ts";
 import { readEventV3ControlState } from "../core/events/v3/control.ts";
 import {
@@ -611,7 +619,7 @@ export function registerAgentsCommand(
     .option(
       "--adapter <id>",
       "(--kind cache) adapter used to validate the authoritative V3 generation: " +
-        "claude-code | cursor | codex.",
+        "claude-code | cursor | codex | opencode.",
     )
     .option(
       "--pid <pid>",
@@ -1275,7 +1283,7 @@ function runWhoami(opts: { json?: boolean }): void {
   if (!hb) {
     emit.error({
       code: "no_live_generation",
-      message: noLiveGenerationMessage(myOwner),
+      message: noLiveGenerationMessage(root, myOwner),
     });
     process.exit(1);
   }
@@ -1473,9 +1481,23 @@ function normalizeKind(kind: string | undefined | null): string {
  * This id is actionable: the reader may pass it to cache repair or explicit
  * finalization. Abbreviate ids for display elsewhere, never in a diagnostic
  * whose purpose is to hand the caller a canonical identity.
+ *
+ * The message also names the recovery. A session whose generation ended while
+ * it sat idle (a stale sweep, or a `done` it has since outlived) still has a
+ * live process, and `agents lifecycle active` is the one command that opens a
+ * fresh generation for it (ADR 0088). Without the pointer every coordination
+ * command refuses in turn and the caller has no way to guess the path back.
  */
-function noLiveGenerationMessage(owner: string): string {
-  return `resolved owner=${owner} but no authority-safe live V3 generation exists for it`;
+function noLiveGenerationMessage(root: string, owner: string): string {
+  const block = liveAuthorityBlockV3(root, owner);
+  if (block) {
+    return `resolved owner=${owner}; ${describeLiveAuthorityBlockV3(block)}; ${liveAuthorityBlockHintV3(resolveBinName(root))}`;
+  }
+  return `resolved owner=${owner} but no authority-safe live V3 generation exists for it; ${lifecycleReopenHint(root)}`;
+}
+
+function lifecycleReopenHint(root: string): string {
+  return `run \`${resolveBinName(root)} agents lifecycle active\` to open a fresh generation for this continuing session`;
 }
 
 /**
@@ -1750,7 +1772,7 @@ function cursorEnvSessionId(): string | null {
 }
 
 interface CommandSessionBootstrap {
-  adapter: "claude-code" | "cursor" | "codex";
+  adapter: Adapter;
   sessionId: string;
 }
 
@@ -2009,7 +2031,7 @@ function runLifecycle(rawState: string, opts: { reason?: string; sessionId?: str
     if (state !== "active") {
       emit.error({
         code: "no_live_generation",
-        message: `${noLiveGenerationMessage(myOwner)}; run \`${resolveBinName(root)} agents lifecycle active\` to open a fresh generation`,
+        message: noLiveGenerationMessage(root, myOwner),
       });
       process.exitCode = 1;
       return;
@@ -2269,7 +2291,7 @@ function runStatus(opts: {
   if (!hb) {
     emit.error({
       code: "no_live_generation",
-      message: noLiveGenerationMessage(myOwner),
+      message: noLiveGenerationMessage(root, myOwner),
     });
     process.exit(1);
   }
@@ -2421,6 +2443,7 @@ function runStatus(opts: {
   // one inside the same session. Best-effort by contract — no turn evidence,
   // no row.
   const turnElapsed = turnElapsedStatusRow({ coordRoot: root, instanceId: hb.instance_id });
+  const turnChanges = turnChangesStatusRow({ coordRoot: root, instanceId: hb.instance_id });
   const resources = readResourceStatus(root);
 
   const data = {
@@ -2430,6 +2453,7 @@ function runStatus(opts: {
     session_age_secs: ageSecs,
     turn_elapsed_secs: turnElapsed ? turnElapsed.elapsed.secs : null,
     turn_complete: turnElapsed ? turnElapsed.elapsed.complete : null,
+    turn_changes: turnChanges.changes,
     activity: activityOf(hb),
     activity_updated_at: hb.activity_updated_at ?? null,
     activity_source: hb.activity_source ?? null,
@@ -2477,6 +2501,7 @@ function runStatus(opts: {
   const rows: Array<[string, string]> = [
     ["session", formatAge(ageSecs)],
     ...(turnElapsed ? ([["turn", turnElapsed.value]] as Array<[string, string]>) : []),
+    ["changes", turnChanges.value],
     ["activity", activityOf(hb)],
     ["lifecycle", lifecycleLabel(hb)],
     ["context", ctxStr],
@@ -2777,11 +2802,7 @@ export function readAgentDiagnosticEventsInWindow(
 
 /** Normalize adapter event data into the heartbeat platform value. */
 function adapterToPlatform(adapter: string | undefined): string {
-  if (adapter === "claude-code") return "claude-code";
-  if (adapter === "cursor") return "cursor";
-  if (adapter === "codex") return "codex";
-  if (adapter === "openclaw") return "openclaw";
-  return "unknown";
+  return normalizeEventAdapterIdV3(adapter) ?? "unknown";
 }
 
 /** Project a canonical health.* event into the HealEvent shape the aggregators
@@ -5040,11 +5061,12 @@ function runHeal(opts: {
     opts.adapter &&
     opts.adapter !== "claude-code" &&
     opts.adapter !== "cursor" &&
-    opts.adapter !== "codex"
+    opts.adapter !== "codex" &&
+    opts.adapter !== "opencode"
   ) {
     emit.error({
       code: "bad_adapter",
-      message: "--adapter must be one of: claude-code, cursor, codex",
+      message: "--adapter must be one of: claude-code, cursor, codex, opencode",
     });
     process.exit(1);
   }
@@ -5215,6 +5237,13 @@ function runHeal(opts: {
   }
 
   if (proc.status !== 0) {
+    const block = liveAuthorityBlockV3(root, owner);
+    if (block) {
+      emitHealFailure(
+        "authority_blocked",
+        `${describeLiveAuthorityBlockV3(block)}; a cache rebuild cannot restore authority the ledger withholds; ${liveAuthorityBlockHintV3(resolveBinName(root))}`,
+      );
+    }
     emitHealFailure(
       healFailureReason(root, owner, sessionId, healAdapter),
       spawnFailureMessage(proc, `agent-coord ${action}`),
@@ -5293,7 +5322,7 @@ function cacheHealAuthorityRefusal(
   root: string,
   owner: string,
   sessionId: string,
-  adapter: "claude-code" | "cursor" | "codex",
+  adapter: Adapter,
   currentRow: LiveCoordinationRow | null,
 ): HealAuthorityRefusal | null {
   if (currentRow && normalizeAdapter(currentRow.platform) !== adapter) {
@@ -5314,7 +5343,7 @@ function cacheHealAuthorityRefusal(
   if (producer?.terminal) {
     return {
       reason: "terminal_generation",
-      message: "the matching generation is terminal and cannot be repaired or reopened by heal",
+      message: `the matching generation is terminal and cannot be repaired or reopened by heal; ${lifecycleReopenHint(root)}`,
     };
   }
   if (producer && producer.instance_id !== liveInstanceIdV3(owner)) {
@@ -5356,7 +5385,7 @@ function healFailureReason(
   root: string,
   owner: string,
   sessionId: string,
-  adapter: "claude-code" | "cursor" | "codex",
+  adapter: Adapter,
 ): string {
   const refusal = cacheHealAuthorityRefusal(
     root,