harnery 0.32.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

@@ -0,0 +1,33 @@
+import type { Adapter } from "../../core/adapter.js";
+export type InstructionComponentRole = "always_loaded" | "just_in_time" | "runtime_config";
+export interface InstructionBundleComponent {
+    path: string;
+    role: InstructionComponentRole;
+    bytes: number;
+    sha256: string;
+}
+export interface InstructionBundle {
+    schema_version: 1;
+    adapter: Adapter;
+    coord_root: string;
+    profile_root: string;
+    instruction_roots: string[];
+    instruction_bundle_id: string;
+    canonical_source_id: string;
+    components: InstructionBundleComponent[];
+    canonical_sources: InstructionBundleComponent[];
+}
+interface BuildBundleOptions {
+    coordRoot: string;
+    cwd: string;
+    adapter: Adapter;
+}
+/**
+ * Build the content identity for the repo-authored instruction surface an
+ * adapter can load at one working path. The identity intentionally excludes
+ * timestamps and git revisions: two checkouts with byte-identical effective
+ * instructions belong to the same cohort.
+ */
+export declare function buildInstructionBundle(options: BuildBundleOptions): InstructionBundle;
+export {};
+//# sourceMappingURL=bundle.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+/**
+ * Build the content identity for the repo-authored instruction surface an
+ * adapter can load at one working path. The identity intentionally excludes
+ * timestamps and git revisions: two checkouts with byte-identical effective
+ * instructions belong to the same cohort.
+ */
+export function buildInstructionBundle(options) {
+    const coordRoot = resolve(options.coordRoot);
+    const cwd = resolve(options.cwd);
+    const roots = resolveInstructionRoots(coordRoot, cwd);
+    const profileRoot = roots.at(-1) ?? coordRoot;
+    const components = dedupeCandidates(roots.flatMap((root) => adapterCandidates(root, options.adapter)), coordRoot);
+    const canonicalSources = dedupeCandidates(roots.flatMap((root) => canonicalCandidates(root)), coordRoot);
+    return {
+        schema_version: 1,
+        adapter: options.adapter,
+        coord_root: coordRoot,
+        profile_root: relativePath(coordRoot, profileRoot),
+        instruction_roots: roots.map((root) => relativePath(coordRoot, root)),
+        instruction_bundle_id: identity("instruction-bundle-v1", options.adapter, components),
+        canonical_source_id: identity("instruction-source-v1", null, canonicalSources),
+        components,
+        canonical_sources: canonicalSources,
+    };
+}
+function resolveInstructionRoots(coordRoot, cwd) {
+    const roots = [coordRoot];
+    if (!isWithin(coordRoot, cwd))
+        return roots;
+    const ancestors = [];
+    let cursor = cwd;
+    while (cursor !== coordRoot) {
+        if (existsSync(join(cursor, "AGENTS.md")) || existsSync(join(cursor, "CLAUDE.md"))) {
+            ancestors.push(cursor);
+        }
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    roots.push(...ancestors.reverse().filter((root) => root !== coordRoot));
+    return roots;
+}
+function adapterCandidates(root, adapter) {
+    const candidates = [];
+    const addFile = (path, role) => {
+        if (existsSync(path) && lstatSync(path).isFile())
+            candidates.push({ absolutePath: path, role });
+    };
+    const addTree = (path, role) => {
+        for (const file of walkFiles(path))
+            candidates.push({ absolutePath: file, role });
+    };
+    if (adapter === "claude-code") {
+        addFile(join(root, "CLAUDE.md"), "always_loaded");
+        addTree(join(root, ".claude", "rules"), "always_loaded");
+        addTree(join(root, ".claude", "skills"), "just_in_time");
+        addFile(join(root, ".claude", "settings.json"), "runtime_config");
+        addFile(join(root, ".claude", "settings.local.json"), "runtime_config");
+    }
+    else if (adapter === "cursor") {
+        addFile(join(root, "AGENTS.md"), "always_loaded");
+        addTree(join(root, ".cursor", "rules"), "always_loaded");
+        addTree(join(root, ".agents", "skills"), "just_in_time");
+        addTree(join(root, ".cursor", "skills"), "just_in_time");
+        addFile(join(root, ".cursor", "hooks.json"), "runtime_config");
+    }
+    else {
+        addFile(join(root, "AGENTS.md"), "always_loaded");
+        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.
+    addFile(join(root, ".harnery", "config.jsonc"), "runtime_config");
+    return candidates;
+}
+function canonicalCandidates(root) {
+    const candidates = [];
+    const agents = join(root, "AGENTS.md");
+    if (existsSync(agents) && lstatSync(agents).isFile()) {
+        candidates.push({ absolutePath: agents, role: "always_loaded" });
+    }
+    for (const file of walkFiles(join(root, ".agents"))) {
+        candidates.push({ absolutePath: file, role: "just_in_time" });
+    }
+    return candidates;
+}
+function walkFiles(root) {
+    if (!existsSync(root) || !lstatSync(root).isDirectory())
+        return [];
+    const files = [];
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else if (entry.isFile())
+                files.push(path);
+        }
+    };
+    visit(root);
+    return files;
+}
+function dedupeCandidates(candidates, coordRoot) {
+    const byPath = new Map();
+    for (const candidate of candidates) {
+        const key = resolve(candidate.absolutePath);
+        const prior = byPath.get(key);
+        if (!prior || roleRank(candidate.role) < roleRank(prior.role))
+            byPath.set(key, candidate);
+    }
+    return [...byPath.values()]
+        .map(({ absolutePath, role }) => {
+        const bytes = readFileSync(absolutePath);
+        return {
+            path: relativePath(coordRoot, absolutePath),
+            role,
+            bytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        };
+    })
+        .sort((a, b) => a.path.localeCompare(b.path) || a.role.localeCompare(b.role));
+}
+function identity(prefix, adapter, components) {
+    const body = components.map(({ path, role, sha256 }) => ({ path, role, sha256 }));
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify({ prefix, ...(adapter ? { adapter } : {}), components: body }))
+        .digest("hex")}`;
+}
+function relativePath(root, path) {
+    const rel = relative(root, path);
+    return rel === "" ? "." : rel.split(sep).join("/");
+}
+function isWithin(root, path) {
+    if (!isAbsolute(root) || !isAbsolute(path))
+        return false;
+    const rel = relative(root, path);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== "..");
+}
+function roleRank(role) {
+    if (role === "always_loaded")
+        return 0;
+    if (role === "runtime_config")
+        return 1;
+    return 2;
+}

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),
+        }),
+    },
 ];