harnery 0.32.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -92,6 +92,16 @@
       "types": "./dist/core/governor/read.d.ts",
       "import": "./dist/core/governor/read.js"
     },
+    "./core/guard": {
+      "bun": "./src/core/guard/index.ts",
+      "types": "./dist/core/guard/index.d.ts",
+      "import": "./dist/core/guard/index.js"
+    },
+    "./core/events/v3": {
+      "bun": "./src/core/events/v3/index.ts",
+      "types": "./dist/core/events/v3/index.d.ts",
+      "import": "./dist/core/events/v3/index.js"
+    },
     "./core/governor/plans": {
       "bun": "./src/core/governor/plan-read.ts",
       "types": "./dist/core/governor/plan-read.d.ts",
@@ -122,6 +132,11 @@
       "types": "./dist/lib/format.d.ts",
       "import": "./dist/lib/format.js"
     },
+    "./lib/headless": {
+      "bun": "./src/lib/headless/index.ts",
+      "types": "./dist/lib/headless/index.d.ts",
+      "import": "./dist/lib/headless/index.js"
+    },
     "./lib/http": {
       "bun": "./src/lib/http/index.ts",
       "types": "./dist/lib/http/index.d.ts",
@@ -175,9 +190,9 @@
   },
   "packageManager": "bun@1.3.3",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/rewrite-dts-extensions.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/rewrite-dts-extensions.mjs",
     "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build",
+    "prepublishOnly": "npm run build",
     "typecheck": "bun x tsc --noEmit",
     "lint": "bun x @biomejs/biome check src",
     "check:portability": "bun run scripts/check-portability.ts",
@@ -185,7 +200,7 @@
     "check:layering": "bun run scripts/check-layering.ts",
     "lint:fix": "bun x @biomejs/biome check --write src",
     "format": "bun x @biomejs/biome format --write src",
-    "test": "bun test src tests",
+    "test": "bun run scripts/test.mjs",
     "test:web": "cd web && bun install && bun test",
     "test:integration": "bash tests/integration/run.sh",
     "smoke": "node scripts/smoke-test.mjs",
@@ -193,10 +208,15 @@
     "docs:build": "bun run --cwd docs build",
     "brand:showcase": "node scripts/build-brand-showcase.mjs",
     "verify:contracts": "bun run scripts/sync-verified-contracts.ts",
-    "verify:contracts:check": "bun run scripts/sync-verified-contracts.ts --check"
+    "verify:contracts:check": "bun run scripts/sync-verified-contracts.ts --check",
+    "generate:event-v3": "bun run scripts/generate-event-v3-contract.ts",
+    "check:event-v3": "bun run scripts/generate-event-v3-contract.ts --check && bun run scripts/check-event-v3-reader-boundary.ts",
+    "generate:docs-metadata-v2": "bun run scripts/generate-docs-metadata-v2-schema.ts",
+    "check:docs-metadata-v2": "bun run scripts/generate-docs-metadata-v2-schema.ts --check"
   },
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
+    "@sinclair/typebox": "^0.34.52",
     "axe-core": "^4.12.1",
     "commander": "^14.0.3",
     "gpt-tokenizer": "^3.4.0",
@@ -207,7 +227,8 @@
     "playwright": "^1.59.1",
     "pngjs": "^7.0.0",
     "turndown": "^7.2.4",
-    "turndown-plugin-gfm": "^1.0.2"
+    "turndown-plugin-gfm": "^1.0.2",
+    "uuid": "^14.0.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",

package/schemas/config.schema.json

@@ -64,6 +64,124 @@
           "minimum": 30,
           "default": 600,
           "description": "How stale a peer heartbeat can get before the sweeper prunes it. Env override: HARNERY_AGENT_COORD_FRESHNESS."
+        },
+        "finalization": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Grace periods for converging independent lifecycle observations on the canonical V3 session finalizer.",
+          "properties": {
+            "archive_grace_seconds": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 86400,
+              "default": 600
+            },
+            "idle_observe_seconds": {
+              "type": "integer",
+              "minimum": 60,
+              "maximum": 2592000,
+              "default": 259200
+            },
+            "idle_finalize_seconds": {
+              "type": "integer",
+              "minimum": 60,
+              "maximum": 7776000,
+              "default": 604800
+            },
+            "cascade_grace_seconds": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 86400,
+              "default": 3600
+            },
+            "reconcile_interval_seconds": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 86400,
+              "default": 900
+            }
+          }
+        },
+        "run_quality": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "description": "Report-only run-quality observation. Invalid objects disable evaluation as one unit.",
+          "properties": {
+            "mode": { "type": "string", "enum": ["off", "shadow", "report"], "default": "off" },
+            "evaluation_interval_seconds": {
+              "type": "integer",
+              "minimum": 5,
+              "maximum": 3600,
+              "default": 30
+            },
+            "snapshot_ttl_seconds": {
+              "type": "integer",
+              "minimum": 10,
+              "maximum": 86400,
+              "default": 120
+            },
+            "max_tail_bytes": {
+              "type": "integer",
+              "minimum": 65536,
+              "maximum": 67108864,
+              "default": 2097152
+            },
+            "evaluation_timeout_seconds": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 30,
+              "default": 30
+            },
+            "lock_stale_seconds": {
+              "type": "integer",
+              "minimum": 5,
+              "maximum": 3600,
+              "default": 60
+            },
+            "supervised_roots_per_sweep": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 8
+            },
+            "thresholds": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "repeated_tool_calls": {
+                  "type": "integer",
+                  "minimum": 2,
+                  "maximum": 10000,
+                  "default": 8
+                },
+                "consecutive_failures": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 10000,
+                  "default": 5
+                },
+                "context_growth_per_minute": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 10000000,
+                  "default": 60000
+                },
+                "compaction_grace_seconds": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 86400,
+                  "default": 300
+                },
+                "no_progress_evaluations": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 10000,
+                  "default": 2
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -89,7 +207,7 @@
           "type": "integer",
           "minimum": 1024,
           "maximum": 65535,
-          "default": 9000,
+          "default": 4276,
           "description": "Port that `harn web up` binds to."
         },
         "bind": {
@@ -155,7 +273,7 @@
           "type": "array",
           "items": { "type": "string" },
           "default": [],
-          "description": "Shipped harnery skills this repo suppresses (e.g. because it maintains richer host-specific versions)."
+          "description": "Shipped Harnery skills this repo suppresses. Installed skill IDs are harn-decide, harn-council, and harn-end."
         }
       }
     },

package/schemas/docs-metadata-v2.schema.json

@@ -0,0 +1,441 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harnery.com/schemas/docs-metadata-v2.schema.json",
+  "title": "Harnery Markdown metadata v2",
+  "type": "object",
+  "required": [
+    "schema",
+    "type",
+    "created_at",
+    "updated_at",
+    "summary"
+  ],
+  "properties": {
+    "schema": {
+      "const": "harnery-doc/v2"
+    },
+    "type": {
+      "enum": [
+        "plan",
+        "issue",
+        "handoff",
+        "runbook",
+        "topic",
+        "audit",
+        "book",
+        "entity",
+        "concept",
+        "query",
+        "page",
+        "inquiry",
+        "quote-sheet",
+        "weekly-post",
+        "synced-page"
+      ]
+    },
+    "created_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "updated_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "owner": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+      },
+      "uniqueItems": true
+    },
+    "relations": {
+      "type": "object",
+      "properties": {
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "supersedes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "superseded_by": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "continues": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "related": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "access": {
+      "type": "object",
+      "properties": {
+        "roles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "viewers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "status": {
+      "type": "string"
+    },
+    "status_changed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "status_note": {
+      "type": "string",
+      "minLength": 1
+    },
+    "severity": {
+      "enum": [
+        "low",
+        "medium",
+        "high",
+        "critical"
+      ]
+    },
+    "resolved_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "affected": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "resolution": {
+      "type": "object",
+      "required": [
+        "outcome"
+      ],
+      "properties": {
+        "outcome": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commits": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "audience": {
+      "type": "string",
+      "minLength": 1
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1
+    },
+    "reviewed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "review_due_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "category": {
+      "type": "string",
+      "minLength": 1
+    },
+    "aliases": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "source_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "provenance": {
+      "type": "object",
+      "required": [
+        "sources"
+      ],
+      "properties": {
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "primary_entity": {
+      "type": "string"
+    },
+    "source_pages": {},
+    "source_tokens": {},
+    "top_entities": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "handle": {
+      "type": "string",
+      "minLength": 1
+    },
+    "published": {
+      "type": "boolean"
+    },
+    "source_updated_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "source_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "source_template": {
+      "type": "string",
+      "minLength": 1
+    },
+    "product": {},
+    "variant": {},
+    "sku": {},
+    "manufacturer": {},
+    "customer": {},
+    "bid_id": {},
+    "drive_file_id": {},
+    "drive_title": {},
+    "quote_date": {},
+    "revision": {},
+    "batch_size": {},
+    "order_size": {},
+    "price": {},
+    "source_pdf": {},
+    "claims": {},
+    "week": {},
+    "coverage": {}
+  },
+  "patternProperties": {
+    "^x_": {}
+  },
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "plan"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "status",
+          "status_changed_at",
+          "owner"
+        ],
+        "properties": {
+          "status": {
+            "enum": [
+              "proposed",
+              "in-progress",
+              "shipped",
+              "abandoned"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "issue"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "status",
+          "status_changed_at",
+          "owner",
+          "severity"
+        ],
+        "properties": {
+          "status": {
+            "enum": [
+              "open",
+              "resolved",
+              "wontfix"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "handoff"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "status",
+          "status_changed_at",
+          "owner"
+        ],
+        "properties": {
+          "status": {
+            "enum": [
+              "open",
+              "resolved",
+              "abandoned"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "runbook"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "owner",
+          "reviewed_at",
+          "review_due_at"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "enum": [
+              "book",
+              "entity",
+              "concept",
+              "query",
+              "page"
+            ]
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "title",
+          "category",
+          "source_count",
+          "provenance"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "synced-page"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "title",
+          "handle",
+          "published",
+          "source",
+          "source_updated_at"
+        ]
+      }
+    }
+  ]
+}