harnery 0.33.0 → 0.34.0

package/dist/lib/instructions/apply.js

@@ -14,8 +14,9 @@
  *     so a fresh consumer gets a CLAUDE.md whose managed region imports
  *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
  *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
- *   - `.claude/skills/<skill>/SKILL.md` — claude-code only; fully-owned files,
- *     honoring `skills.exclude` in `.harnery/config.jsonc`.
+ *   - `<adapter-skill-dir>/<skill>/SKILL.md` — fully-owned files, honoring
+ *     `skills.exclude` in `.harnery/config.jsonc`. Claude Code uses
+ *     `.claude/skills/`; Cursor and Codex use `.agents/skills/`.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
@@ -25,7 +26,14 @@ import { checkOwnedSkill, checkRegion, isOwnedFile, removeRegion, spliceRegion,
 import { HOST_ADDENDUM_REGION, IMPORT_REGION, INSTRUCTIONS_REGION, renderInstructionsBlock, SKILLS, } from "./templates.js";
 const AGENTS_FILE = "AGENTS.md";
 const CLAUDE_FILE = "CLAUDE.md";
-const CLAUDE_SKILLS_DIR = join(".claude", "skills");
+const ADAPTER_SKILLS_DIR = {
+    "claude-code": join(".claude", "skills"),
+    cursor: join(".agents", "skills"),
+    codex: join(".agents", "skills"),
+};
+function adapterSkillsDir(adapter) {
+    return ADAPTER_SKILLS_DIR[adapter] ?? null;
+}
 /** CLAUDE.md import-shim body: points Claude Code (which reads CLAUDE.md, not AGENTS.md) at AGENTS.md. */
 function importBody() {
     return "This project's agent instructions live in AGENTS.md.\n@AGENTS.md";
@@ -51,27 +59,29 @@ export function readSkillsExclude(projectRoot) {
 }
 /**
  * Which shipped skills exist for this project, so the block references only the
- * ones actually present: claude-code writes skills (unless excluded); cursor and
- * codex get the block but no skill files, so both read false there. Kept in one
- * place so `applyInstructions` and `checkInstructions` render byte-identical blocks.
+ * ones actually present for every supported adapter, unless excluded. Kept in
+ * one place so `applyInstructions` and `checkInstructions` render byte-identical
+ * blocks.
  */
 function blockSkills(projectRoot, adapter) {
-    const claudeCode = adapter === "claude-code";
+    const supported = adapterSkillsDir(adapter) !== null;
     const exclude = readSkillsExclude(projectRoot);
     return {
-        decide: claudeCode && !exclude.has("harn-decide"),
-        council: claudeCode && !exclude.has("harn-council"),
+        decide: supported && !exclude.has("harn-decide"),
+        council: supported && !exclude.has("harn-council"),
+        end: supported && !exclude.has("harn-end"),
     };
 }
 /**
  * Inject / refresh the instructions block, the CLAUDE.md import shim (claude-code),
- * and the shipped skills (claude-code). Idempotent: a re-run on current content
+ * and the adapter-native shipped skills. Idempotent: a re-run on current content
  * writes nothing. `dryRun` reports without touching the fs.
  */
 export function applyInstructions(projectRoot, opts) {
     const actions = [];
     const warnings = [];
     const claudeCode = opts.adapter === "claude-code";
+    const skillsDir = adapterSkillsDir(opts.adapter);
     // dry-run narrates the future ("would create"); a real run narrates the past.
     const verbed = (base, past) => (opts.dryRun ? `would ${base}` : past);
     // Resolve the host addendum before touching a single file, so a bad path
@@ -146,15 +156,15 @@ export function applyInstructions(projectRoot, opts) {
             }
         }
     }
-    // ── shipped skills (claude-code only) ───────────────────────────────────
-    if (claudeCode) {
+    // ── shipped skills ───────────────────────────────────────────────────────
+    if (skillsDir) {
         const exclude = readSkillsExclude(projectRoot);
         for (const skill of SKILLS) {
             if (exclude.has(skill.id)) {
                 actions.push(`· skipped skill ${skill.id} (skills.exclude)`);
                 continue;
             }
-            const skillPath = join(projectRoot, CLAUDE_SKILLS_DIR, skill.relPath);
+            const skillPath = join(projectRoot, skillsDir, skill.relPath);
             const content = skill.render(opts.binName);
             const before = existsSync(skillPath) ? readFileSync(skillPath, "utf8") : null;
             if (before === content) {
@@ -181,6 +191,7 @@ export function removeInstructions(projectRoot, opts) {
     const actions = [];
     const warnings = [];
     const claudeCode = opts.adapter === "claude-code";
+    const skillsDir = adapterSkillsDir(opts.adapter);
     // ── AGENTS.md block + host addendum ─────────────────────────────────────
     const agentsPath = join(projectRoot, AGENTS_FILE);
     if (existsSync(agentsPath)) {
@@ -227,10 +238,10 @@ export function removeInstructions(projectRoot, opts) {
             }
         }
     }
-    // ── shipped skills (claude-code) ────────────────────────────────────────
-    if (claudeCode) {
+    // ── shipped skills ───────────────────────────────────────────────────────
+    if (skillsDir) {
         for (const skill of SKILLS) {
-            const skillPath = join(projectRoot, CLAUDE_SKILLS_DIR, skill.relPath);
+            const skillPath = join(projectRoot, skillsDir, skill.relPath);
             if (!existsSync(skillPath))
                 continue;
             if (!isOwnedFile(readFileSync(skillPath, "utf8"))) {
@@ -239,7 +250,7 @@ export function removeInstructions(projectRoot, opts) {
             }
             if (!opts.dryRun) {
                 rmSync(skillPath);
-                // drop the now-empty skill dir (harn-decide/), leaving .claude/skills/ intact
+                // Drop the now-empty harn-* dir, leaving the adapter skills root intact.
                 const dir = dirname(skillPath);
                 try {
                     if (readdirSync(dir).length === 0)
@@ -256,7 +267,7 @@ export function removeInstructions(projectRoot, opts) {
 }
 /**
  * Read-only drift report for `init --check`: the AGENTS.md block and each
- * shipped skill (claude-code). Fresh → exit 0; any stale / missing / hand-edit
+ * shipped skill for the selected adapter. Fresh → exit 0; stale / missing / hand-edit
  * → drift (exit 2); an unreadable file → error (exit 1). Mirrors the wiki-theme
  * `--check-only` contract the first host wires into pre-commit.
  */
@@ -282,12 +293,13 @@ export function checkInstructions(projectRoot, opts) {
         else if (checkRegion(content, HOST_ADDENDUM_REGION, "") !== "missing") {
             issues.push(`${AGENTS_FILE} host addendum: present but no longer configured (re-run init)`);
         }
-        if (opts.adapter === "claude-code") {
+        const skillsDir = adapterSkillsDir(opts.adapter);
+        if (skillsDir) {
             const exclude = readSkillsExclude(projectRoot);
             for (const skill of SKILLS) {
                 if (exclude.has(skill.id))
                     continue;
-                const skillPath = join(projectRoot, CLAUDE_SKILLS_DIR, skill.relPath);
+                const skillPath = join(projectRoot, skillsDir, skill.relPath);
                 const c = existsSync(skillPath) ? readFileSync(skillPath, "utf8") : "";
                 note(`skill ${skill.id}`, checkOwnedSkill(c, skillBody(skill.render, opts.binName)));
             }

package/dist/lib/instructions/bundle.d.ts

@@ -1,4 +1,4 @@
-import type { Adapter } from "../../core/hooks/events/schema.js";
+import type { Adapter } from "../../core/adapter.js";
 export type InstructionComponentRole = "always_loaded" | "just_in_time" | "runtime_config";
 export interface InstructionBundleComponent {
     path: string;

package/dist/lib/instructions/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/bundle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AAEjE,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAE3F,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,wBAAwB,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,0BAA0B,EAAE,CAAC;IACzC,iBAAiB,EAAE,0BAA0B,EAAE,CAAC;CACjD;AAED,UAAU,kBAAkB;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;CAClB;AAOD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAyBrF"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/bundle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAE3F,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,wBAAwB,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,0BAA0B,EAAE,CAAC;IACzC,iBAAiB,EAAE,0BAA0B,EAAE,CAAC;CACjD;AAED,UAAU,kBAAkB;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;CAClB;AAOD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAyBrF"}

package/dist/lib/instructions/bundle.js

@@ -70,7 +70,7 @@ function adapterCandidates(root, adapter) {
     }
     else {
         addFile(join(root, "AGENTS.md"), "always_loaded");
-        addTree(join(root, ".harnery", "skills"), "just_in_time");
+        addTree(join(root, ".agents", "skills"), "just_in_time");
         addFile(join(root, ".codex", "hooks.json"), "runtime_config");
     }
     // Harnery's host configuration governs hook enforcement for all adapters.

package/dist/lib/instructions/splice.d.ts

@@ -70,7 +70,6 @@ export declare function isOwnedFile(content: string): boolean;
 export declare function buildOwnedSkill(opts: {
     name: string;
     description: string;
-    argumentHint?: string;
     binName: string;
     body: string;
 }): string;

package/dist/lib/instructions/splice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"splice.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAMD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAiB3C,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,YAAqB,GAAG,MAAM,CAI9F;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAqB,GAC3B,YAAY,CAad;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,YAAqB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CASpC;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAqB,GAC3B,aAAa,CAIf;AAMD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAcT;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAKjF"}
+{"version":3,"file":"splice.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAwBD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAiB3C,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,YAAqB,GAAG,MAAM,CAI9F;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAqB,GAC3B,YAAY,CAad;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,YAAqB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAOpC;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAqB,GAC3B,aAAa,CAIf;AAMD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAaT;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAKjF"}

package/dist/lib/instructions/splice.js

@@ -28,6 +28,25 @@ export function shortHash(s) {
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function trimHorizontalWhitespaceBeforeNewlines(content) {
+    const chunks = [];
+    let segmentStart = 0;
+    for (let index = 0; index < content.length; index++) {
+        if (content.charCodeAt(index) !== 10)
+            continue;
+        let segmentEnd = index;
+        while (segmentEnd > segmentStart) {
+            const code = content.charCodeAt(segmentEnd - 1);
+            if (code !== 32 && code !== 9)
+                break;
+            segmentEnd--;
+        }
+        chunks.push(content.slice(segmentStart, segmentEnd), "\n");
+        segmentStart = index + 1;
+    }
+    chunks.push(content.slice(segmentStart));
+    return chunks.join("");
+}
 function markerPair(style) {
     return style === "hash" ? { open: "#", close: "" } : { open: "<!--", close: "-->" };
 }
@@ -62,7 +81,7 @@ export function spliceRegion(content, region, body, style = "html") {
         const text = content.replace(re, () => fresh);
         return { text, changed: text !== content, had: true, stale };
     }
-    const trimmed = content.replace(/\s+$/, "");
+    const trimmed = content.trimEnd();
     const text = trimmed ? `${trimmed}\n\n${fresh}\n` : `${fresh}\n`;
     return { text, changed: true, had: false, stale: false };
 }
@@ -76,9 +95,7 @@ export function removeRegion(content, region, style = "html") {
     const re = regionRe(region, style);
     if (!re.test(content))
         return { text: content, removed: false };
-    const stripped = content
-        .replace(re, "")
-        .replace(/[ \t]+\n/g, "\n")
+    const stripped = trimHorizontalWhitespaceBeforeNewlines(content.replace(re, ""))
         .replace(/\n{3,}/g, "\n\n")
         .trim();
     return { text: stripped ? `${stripped}\n` : "", removed: true };
@@ -106,8 +123,7 @@ export function buildOwnedSkill(opts) {
     const fm = [
         "---",
         `name: ${opts.name}`,
-        `description: ${opts.description}`,
-        ...(opts.argumentHint ? [`argument-hint: ${JSON.stringify(opts.argumentHint)}`] : []),
+        `description: ${JSON.stringify(opts.description)}`,
         "---",
     ].join("\n");
     const body = opts.body.trim();

package/dist/lib/instructions/templates.d.ts

@@ -23,22 +23,24 @@ export declare const IMPORT_REGION = "import";
 export declare const HOST_ADDENDUM_REGION = "host-addendum";
 /** Which shipped skills exist in the project the block is rendered for. */
 export interface BlockSkills {
-    /** the `harn-decide` skill file is present (claude-code, not excluded) */
+    /** the `harn-decide` skill file is present */
     decide: boolean;
     /** the `harn-council` skill file is present */
     council: boolean;
+    /** the `harn-end` skill file is present */
+    end: boolean;
 }
 /**
  * The always-on orientation spliced into `AGENTS.md`. Target ≤ 80 rendered
  * lines: it costs every agent context on every turn, so it states that each
  * surface *exists* and gives one line of *when* — the *how* lives in the skills
  * and each command's `--help`. Skill names are fixed (`harn-decide`,
- * `harn-council`) even for a renamed bin; only command strings track `binName`.
+ * `harn-council`, `harn-end`) even for a renamed bin; only command strings
+ * track `binName`.
  *
  * The block only points at a skill that actually exists here: a host that
- * excludes one via `skills.exclude`, or a adapter with no skill primitive
- * (cursor/codex get the block but no skill files), gets a `--help` pointer
- * instead of a dangling reference to a skill it doesn't have.
+ * excludes one via `skills.exclude` gets a CLI pointer instead of a dangling
+ * reference to a skill it doesn't have.
  */
 export declare function renderInstructionsBlock(binName: string, skills?: BlockSkills): string;
 /** A shipped skill: its adapter-relative file path + a bin-name-aware renderer. */

package/dist/lib/instructions/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAA6C,GACpD,MAAM,CAkFR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAsKD,eAAO,MAAM,MAAM,EAAE,aAAa,EA4BjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAwD,GAC/D,MAAM,CA+FR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAsND,eAAO,MAAM,MAAM,EAAE,aAAa,EAqCjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -28,16 +28,20 @@ export const HOST_ADDENDUM_REGION = "host-addendum";
  * lines: it costs every agent context on every turn, so it states that each
  * surface *exists* and gives one line of *when* — the *how* lives in the skills
  * and each command's `--help`. Skill names are fixed (`harn-decide`,
- * `harn-council`) even for a renamed bin; only command strings track `binName`.
+ * `harn-council`, `harn-end`) even for a renamed bin; only command strings
+ * track `binName`.
  *
  * The block only points at a skill that actually exists here: a host that
- * excludes one via `skills.exclude`, or a adapter with no skill primitive
- * (cursor/codex get the block but no skill files), gets a `--help` pointer
- * instead of a dangling reference to a skill it doesn't have.
+ * excludes one via `skills.exclude` gets a CLI pointer instead of a dangling
+ * reference to a skill it doesn't have.
  */
-export function renderInstructionsBlock(binName, skills = { decide: true, council: true }) {
+export function renderInstructionsBlock(binName, skills = { decide: true, council: true, end: true }) {
     const b = binName;
-    const named = [skills.decide && "`harn-decide`", skills.council && "`harn-council`"].filter(Boolean);
+    const named = [
+        skills.decide && "`harn-decide`",
+        skills.council && "`harn-council`",
+        skills.end && "`harn-end`",
+    ].filter(Boolean);
     const deeper = named.length > 0
         ? `Procedures for the deeper flows live in the ${named.join(" and ")} skill${named.length > 1 ? "s" : ""}.`
         : `See \`${b} decision --help\` and \`${b} agents council --help\` for the deeper procedures.`;
@@ -47,6 +51,9 @@ export function renderInstructionsBlock(binName, skills = { decide: true, counci
     const councilPointer = skills.council
         ? "The `harn-council` skill has the steward and member flow."
         : `See \`${b} agents council --help\` for the steward and member flow.`;
+    const endPointer = skills.end
+        ? "When the whole session is genuinely finished, use the `harn-end` skill as the final workflow."
+        : `When the whole session is genuinely finished, run \`${b} agents status --end-turn --end-session\` as the final tool action.`;
     // Render the journal categories from the canonical enum so this prose can
     // never drift from what `journal add` actually accepts (the "note, plan…" list
     // silently lagged the tool by two categories before this).
@@ -67,6 +74,14 @@ active peers and the files they've claimed; \`${b} agents set-task "<focus>"\`
 declares your current focus so peers can see it. Check for peers before editing
 widely-shared files.
 
+**Task lifecycle.** Beside the activity peers already see, declare whether your
+objective is still open: \`${b} agents lifecycle blocked --reason "<why>"\` when
+it cannot proceed, \`${b} agents lifecycle done\` when it is complete, and
+\`${b} agents lifecycle active\` to reopen. \`done\` requires a current task and
+a passing Git finalization check (dirty or unpushed work refuses, and nothing is
+written). Ordinary \`set-task\` calls never change lifecycle, and a transition
+that re-mints the session title tells you the new name to copy. ${endPointer}
+
 **Dispatching a team.** Everything else here coordinates the agents already
 present. These three start new ones, and they differ by how long the objective
 outlives a single execution. \`${b} run <script>\` is one bounded pass:
@@ -219,7 +234,7 @@ The web UI is the member + steward picker; don't create from the CLI (that skips
 the steward choice). Emit the link with the objective URL-encoded:
 
 \`\`\`
-http://localhost:9000/councils/new?objective=<encoded>
+http://localhost:4276/councils/new?objective=<encoded>
 \`\`\`
 
 If the dev server isn't up, start it with \`${b} web up\`.
@@ -274,6 +289,53 @@ that triggered the refusal (member list, contributors, prompt absence, route
 mismatch), and offer the right next step. Don't propose a workaround that bypasses
 the guard.`;
 }
+function endBody(b) {
+    return `Finalize only after the work is genuinely complete. This is the deliberate,
+high-confidence escape hatch for adapters that do not provide a trustworthy
+native session-end callback.
+
+## Workflow
+
+1. Finish all in-scope work, tests, documentation, commits, pushes, and
+   user-facing reporting first.
+2. Confirm no tool call, open turn, delegated child, file claim, or uncommitted
+   session write remains. Do not fabricate completion or use this skill to hide
+   unfinished work.
+3. Run the closing status and end request as the final tool action:
+
+   \`\`\`bash
+   ${b} agents status --end-turn --end-session
+   \`\`\`
+
+   When automatic identity resolution is unavailable, pass the current native
+   adapter session ID with \`--session-id <id>\`. The command durably queues the
+   authoritative end while it is still running. The adapter's stop hook records
+   \`session.ended\` only after this command, its tool span, and the current turn
+   have closed.
+4. Do not run another tool after a successful request. Reproduce the status
+   output, tell the operator the end is queued, and yield. The terminal event ID
+   becomes available after the response completes and can be verified from a
+   later session or the web UI.
+
+## Refusals and recovery
+
+- If the command reports delegated work, finish or explicitly cancel those
+  children, then try again.
+- If Git finalization fails, complete the repository's required commit and push
+  workflow before retrying.
+- If the V3 ledger is unavailable or unsafe, do not fall back to deleting a
+  projection or writing a synthetic ledger row. Report the failure.
+- Starting a new turn or tool after the request cancels the pending end. Run the
+  workflow again when the session is actually finished.
+- On a manual \`${b} agents end\` call, use \`--outcome failed\`, \`cancelled\`,
+  \`interrupted\`, or \`unknown\` only when that describes the completed session
+  honestly.
+
+Never use this skill to end another operator's session unless the operator
+explicitly identifies it. Use the web control or \`${b} agents end --instance-id
+<id>\` for that operator action; it records immediately for an idle session or
+durably queues the end for its current turn.`;
+}
 export const SKILLS = [
     {
         id: "harn-decide",
@@ -281,7 +343,6 @@ export const SKILLS = [
         render: (binName) => buildOwnedSkill({
             name: "harn-decide",
             description: "File a decision into the docket instead of blocking on a human: search precedent, file it, and proceed on a reversible default; or pick up and resolve an open decision with cited evidence. Use whenever you're about to ask a human a decision-shaped question you could resolve yourself.",
-            argumentHint: "[<the decision / question you're facing> | resolve <id> | review]",
             binName,
             body: decideBody(binName),
         }),
@@ -292,9 +353,18 @@ export const SKILLS = [
         render: (binName) => buildOwnedSkill({
             name: "harn-council",
             description: "Interact with the multi-agent council system: list / create / show / prompts (steward) / contribute (member). Guards against misrouting: refuses to contribute when you aren't a member, have already contributed, or weren't routed a prompt.",
-            argumentHint: "[<id-or-fragment> | create <objective> | contribute <id> | prompts <id> | show <id>]",
             binName,
             body: councilBody(binName),
         }),
     },
+    {
+        id: "harn-end",
+        relPath: "harn-end/SKILL.md",
+        render: (binName) => buildOwnedSkill({
+            name: "harn-end",
+            description: "Safely finalize the current Harnery agent session with an authoritative V3 session-ended event. Use when the operator says /harn-end, asks to end or close the current session, or when all work is complete and the session should stop counting as live.",
+            binName,
+            body: endBody(binName),
+        }),
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.33.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",
@@ -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."
         }
       }
     },