harnery 0.29.0 → 0.31.0

package/dist/lib/council/index.js

@@ -1,7 +1,7 @@
 /**
  * Council manifest helpers: file-based multi-agent coordination primitives.
  *
- * Lives under .harnery/councils/ alongside heartbeats + scratchpads. Council
+ * Lives under .harnery/councils/ alongside heartbeats + journals. Council
  * lifecycle commands serialize manifest mutations through a shared flock;
  * round contribution files are per-member and don't need shared locking.
  */
@@ -176,7 +176,7 @@ export function setCouncilSteward(councilId, steward) {
  * next-app's same-named constant. */
 const KNOWN_AGENT_STALE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 /**
- * Active heartbeats + recently-archived scratchpads, deduped by name.
+ * Active heartbeats + recently-archived journals, deduped by name.
  * Used by `agents council set-steward` to refuse arbitrary names;
  * pass `--allow-unknown` to bypass when bootstrapping a new agent.
  */
@@ -185,7 +185,7 @@ export function listKnownAgents() {
     if (!root)
         return [];
     const activeDir = resolve(root, ".harnery", "active");
-    const archiveDir = resolve(root, ".harnery", "scratch", "archived");
+    const archiveDir = resolve(root, ".harnery", "journal", "archived");
     const byName = new Map();
     if (existsSync(activeDir)) {
         for (const f of readdirSync(activeDir)) {
@@ -220,7 +220,7 @@ export function listKnownAgents() {
                 continue;
             try {
                 const head = readFileSync(resolve(archiveDir, f), "utf8").slice(0, 200);
-                const nameMatch = head.match(/^#\s+Scratchpad:\s+(agent-[A-Za-z][A-Za-z0-9_-]*)/m);
+                const nameMatch = head.match(/^#\s+Journal:\s+(agent-[A-Za-z][A-Za-z0-9_-]*)/m);
                 if (!nameMatch)
                     continue;
                 const name = nameMatch[1];
@@ -504,7 +504,7 @@ export function writeContribution(councilId, round, memberName, body) {
  * Path to the round-N prompts directory: `.harnery/councils/<id>/round-N/prompts/`.
  * Sibling to the contribution files. Holds one `<member>.md` per non-self
  * council member, drafted by the steward, read by the operator (copy-paste
- * into each agent harness) and the web UI (per-member panel).
+ * into each agent adapter) and the web UI (per-member panel).
  */
 export function promptsDir(councilId, round) {
     const rd = roundDir(councilId, round);
@@ -549,9 +549,9 @@ const SUBMIT_FOOTER_MARKER = "<!-- council-submit-footer -->";
  * Build the submit footer appended to every steward-drafted prompt. This is the
  * load-bearing instruction that a contribution composed in chat is NOT recorded;
  * the agent must run the command below. It rides on the prompt (the one
- * artifact the operator always pastes) so it reaches every harness regardless of
+ * artifact the operator always pastes) so it reaches every adapter regardless of
  * whether the convene-time invitation was delivered or a `/council` skill is
- * available. Without it, agents (esp. non-Claude harnesses with no skill) write
+ * available. Without it, agents (esp. non-Claude adapters with no skill) write
  * their take as a reply and end the turn, leaving the council showing them as
  * still-pending. Visible markdown (not an HTML comment) so the agent reads it.
  */
@@ -567,7 +567,7 @@ export function buildSubmitFooter(councilId) {
         `# longer write-up? ${bin} agents council contribute ${councilId} --file <path>`,
         "```",
         "",
-        '_(Or invoke the `council` skill in your harness: `/council contribute` in Claude Code, `$council` / "use the council skill" in Codex/Cursor, for the same flow with routing guards.)_',
+        '_(Or invoke the `council` skill in your adapter: `/council contribute` in Claude Code, `$council` / "use the council skill" in Codex/Cursor, for the same flow with routing guards.)_',
     ].join("\n");
 }
 /** Strip an appended submit footer from a prompt body, if present. */

package/dist/lib/exec.d.ts

@@ -14,6 +14,13 @@ export interface ExecResult {
      * child that handles the signal cleanly still exits 0, so the exit code alone
      * cannot distinguish a kill from an ordinary finish. */
     timedOut?: boolean;
+    /** The `code` from a spawn-level failure (`proc` "error" event), e.g.
+     * "ENOENT" when the binary is absent. Absent for an ordinary process exit.
+     * We collapse such failures to exitCode 127 so callers' exit-code branches
+     * still fire, but a shell can legitimately exit 127 too; only this field
+     * distinguishes "the binary was never there" from "the process ran and exited
+     * 127". The process that knows reports it (as ADR 0044 did for `timedOut`). */
+    spawnErrno?: string;
 }
 export interface ExecOpts {
     cwd?: string;

package/dist/lib/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/lib/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB;;4DAEwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAwC5E;AAED,sEAAsE;AACtE,wBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEhG"}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/lib/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB;;4DAEwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;mFAK+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CA2C5E;AAED,sEAAsE;AACtE,wBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAEhG"}

package/dist/lib/exec.js

@@ -34,7 +34,7 @@ export function exec(cmd, opts = {}) {
             timedOut = true;
             proc.kill();
         }, timeout);
-        const finish = (exitCode, errOverride) => {
+        const finish = (exitCode, errOverride, spawnErrno) => {
             clearTimeout(timer);
             const stdout = Buffer.concat(out).toString("utf-8");
             const stderr = errOverride ?? Buffer.concat(err).toString("utf-8");
@@ -44,12 +44,15 @@ export function exec(cmd, opts = {}) {
                 stderr: shouldTrim ? stderr.trim() : stderr.replace(/\n$/, ""),
                 exitCode,
                 ...(timedOut ? { timedOut: true } : {}),
+                ...(spawnErrno ? { spawnErrno } : {}),
             });
         };
         // ENOENT (binary not found) and similar spawn failures surface here rather
         // than throwing: resolve with 127 + the message so callers' exitCode
-        // branches handle it instead of crashing on an unhandled rejection.
-        proc.on("error", (e) => finish(127, e.message));
+        // branches handle it instead of crashing on an unhandled rejection. The
+        // errno (e.g. "ENOENT") is carried through so a real missing binary is
+        // distinguishable from a shell that merely exited 127.
+        proc.on("error", (e) => finish(127, e.message, e.code));
         proc.on("close", (code) => finish(code ?? 1));
     });
 }

package/dist/lib/identities/assume.d.ts

@@ -8,7 +8,7 @@
  *
  * Local collision policy: a fresh heartbeat alone is not enough to block.
  * If the namesake has no live pid-map process (crashed session, healed
- * zombie, or abandoned harness), reclaim that heartbeat and continue.
+ * zombie, or abandoned adapter), reclaim that heartbeat and continue.
  * Refuse only when another process is still alive, or when cached remote
  * presence reports the name.
  */
@@ -40,7 +40,7 @@ export interface IdentityAssumeResult {
  * presence. No network call occurs; absent presence degrades to local-only. */
 export declare function findIdentityConflict(coordRoot: string, instanceId: string, name: string, nowMs?: number): IdentityConflict | null;
 /**
- * Drop a local namesake whose harness process is gone. Fresh heartbeats can
+ * Drop a local namesake whose adapter process is gone. Fresh heartbeats can
  * linger after a crash (or after heartbeat heal without a live pid-map), and
  * `identity assume` is the supported takeover path — operators should not
  * need a separate kill/sweep step.

package/dist/lib/identities/assume.js

@@ -8,7 +8,7 @@
  *
  * Local collision policy: a fresh heartbeat alone is not enough to block.
  * If the namesake has no live pid-map process (crashed session, healed
- * zombie, or abandoned harness), reclaim that heartbeat and continue.
+ * zombie, or abandoned adapter), reclaim that heartbeat and continue.
  * Refuse only when another process is still alive, or when cached remote
  * presence reports the name.
  */
@@ -78,7 +78,7 @@ export function findIdentityConflict(coordRoot, instanceId, name, nowMs = Date.n
     return null;
 }
 /**
- * Drop a local namesake whose harness process is gone. Fresh heartbeats can
+ * Drop a local namesake whose adapter process is gone. Fresh heartbeats can
  * linger after a crash (or after heartbeat heal without a live pid-map), and
  * `identity assume` is the supported takeover path — operators should not
  * need a separate kill/sweep step.
@@ -89,13 +89,13 @@ export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
     if (instanceHasLivePid(coordRoot, conflict.instance_id))
         return false;
     const hbPath = join(coordRoot, ".harnery", "active", `${conflict.instance_id}.json`);
-    let harness = "claude-code";
+    let adapter = "claude-code";
     let sessionId = conflict.instance_id;
     let ageSecs;
     if (existsSync(hbPath)) {
         try {
             const hb = JSON.parse(readFileSync(hbPath, "utf8"));
-            harness = harnessOf(hb.platform);
+            adapter = adapterOf(hb.platform);
             sessionId = hb.session_id || conflict.instance_id;
             const ts = Date.parse(hb.last_heartbeat);
             if (Number.isFinite(ts))
@@ -117,7 +117,7 @@ export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
             event_type: "health.heartbeat_swept",
             instance_id: conflict.instance_id,
             session_id: sessionId,
-            harness,
+            adapter,
             source: "agent-coord",
             data: {
                 reason: "stale",
@@ -186,7 +186,7 @@ function acquireLock(coordRoot) {
     }
     throw new IdentityAssumeError("identity_busy", "another identity assumption is in progress; retry in a moment");
 }
-function harnessOf(platform) {
+function adapterOf(platform) {
     if (platform === "cursor")
         return "cursor";
     if (platform === "codex")
@@ -239,7 +239,7 @@ export function assumeIdentity(coordRoot, instanceId, target) {
             event_type: "identity.assumed",
             instance_id: instanceId,
             session_id: hb.session_id,
-            harness: harnessOf(hb.platform),
+            adapter: adapterOf(hb.platform),
             data: {
                 name: identity.name,
                 agent_id: identity.agent_id,

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

@@ -21,7 +21,7 @@
 export declare function readSkillsExclude(projectRoot: string): Set<string>;
 interface ApplyOpts {
     binName: string;
-    harness: string;
+    adapter: string;
     dryRun: boolean;
 }
 export interface ApplyResult {
@@ -35,7 +35,7 @@ export interface ApplyResult {
  */
 export declare function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyResult;
 interface RemoveOpts {
-    harness: string;
+    adapter: string;
     dryRun: boolean;
 }
 /**
@@ -57,7 +57,7 @@ export interface CheckResult {
  */
 export declare function checkInstructions(projectRoot: string, opts: {
     binName: string;
-    harness: string;
+    adapter: string;
 }): CheckResult;
 export {};
 //# sourceMappingURL=apply.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4CH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAiBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA4EnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAmErF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAqCb"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA8CH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAiBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA8GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAiFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAiDb"}

package/dist/lib/instructions/apply.js

@@ -20,8 +20,9 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { stripJsonComments } from "../../core/config.js";
+import { readHostAddendum } from "./host-addendum.js";
 import { checkOwnedSkill, checkRegion, isOwnedFile, removeRegion, spliceRegion, } from "./splice.js";
-import { IMPORT_REGION, INSTRUCTIONS_REGION, renderInstructionsBlock, SKILLS, } from "./templates.js";
+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");
@@ -54,8 +55,8 @@ export function readSkillsExclude(projectRoot) {
  * 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.
  */
-function blockSkills(projectRoot, harness) {
-    const claudeCode = harness === "claude-code";
+function blockSkills(projectRoot, adapter) {
+    const claudeCode = adapter === "claude-code";
     const exclude = readSkillsExclude(projectRoot);
     return {
         decide: claudeCode && !exclude.has("harn-decide"),
@@ -70,28 +71,57 @@ function blockSkills(projectRoot, harness) {
 export function applyInstructions(projectRoot, opts) {
     const actions = [];
     const warnings = [];
-    const claudeCode = opts.harness === "claude-code";
+    const claudeCode = opts.adapter === "claude-code";
     // 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
+    // aborts the whole run instead of leaving AGENTS.md half-updated.
+    const addendum = readHostAddendum(projectRoot);
     // ── AGENTS.md orientation block ─────────────────────────────────────────
     const agentsPath = join(projectRoot, AGENTS_FILE);
     const agentsExisted = existsSync(agentsPath);
     const agentsBefore = agentsExisted ? readFileSync(agentsPath, "utf8") : "";
-    const body = renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.harness));
+    const body = renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.adapter));
     const spliced = spliceRegion(agentsBefore, INSTRUCTIONS_REGION, body);
     if (!spliced.changed) {
         actions.push(`· ${AGENTS_FILE} instructions block already current`);
     }
+    else if (!agentsExisted) {
+        actions.push(`+ ${verbed("create", "created")} ${AGENTS_FILE} with the instructions block`);
+    }
+    else if (!spliced.had) {
+        actions.push(`+ ${verbed("inject", "injected")} the instructions block into ${AGENTS_FILE}`);
+    }
     else {
-        if (!opts.dryRun)
-            writeFileSync(agentsPath, spliced.text);
-        if (!agentsExisted)
-            actions.push(`+ ${verbed("create", "created")} ${AGENTS_FILE} with the instructions block`);
-        else if (!spliced.had)
-            actions.push(`+ ${verbed("inject", "injected")} the instructions block into ${AGENTS_FILE}`);
-        else
-            actions.push(`~ ${verbed("update", "updated")} the instructions block in ${AGENTS_FILE}`);
+        actions.push(`~ ${verbed("update", "updated")} the instructions block in ${AGENTS_FILE}`);
     }
+    // ── host addendum (a second region, content the host owns) ──────────────
+    // Harnery places and versions it; what it says is none of harnery's business.
+    // No configured source means any region left behind belongs to a config entry
+    // that has since been deleted, so init takes it back out.
+    let agentsAfter = spliced.text;
+    if (addendum.configured) {
+        const withAddendum = spliceRegion(agentsAfter, HOST_ADDENDUM_REGION, addendum.body);
+        agentsAfter = withAddendum.text;
+        if (!withAddendum.changed) {
+            actions.push(`· ${AGENTS_FILE} host addendum already current (${addendum.relPath})`);
+        }
+        else if (!withAddendum.had) {
+            actions.push(`+ ${verbed("splice", "spliced")} the host addendum into ${AGENTS_FILE} (${addendum.relPath})`);
+        }
+        else {
+            actions.push(`~ ${verbed("update", "updated")} the host addendum in ${AGENTS_FILE} (${addendum.relPath})`);
+        }
+    }
+    else {
+        const dropped = removeRegion(agentsAfter, HOST_ADDENDUM_REGION);
+        if (dropped.removed) {
+            agentsAfter = dropped.text;
+            actions.push(`+ ${verbed("remove", "removed")} the host addendum from ${AGENTS_FILE} (no longer configured)`);
+        }
+    }
+    if (!opts.dryRun && agentsAfter !== agentsBefore)
+        writeFileSync(agentsPath, agentsAfter);
     // ── CLAUDE.md import shim (claude-code only) ────────────────────────────
     if (claudeCode) {
         const claudePath = join(projectRoot, CLAUDE_FILE);
@@ -150,23 +180,32 @@ export function applyInstructions(projectRoot, opts) {
 export function removeInstructions(projectRoot, opts) {
     const actions = [];
     const warnings = [];
-    const claudeCode = opts.harness === "claude-code";
-    // ── AGENTS.md block ─────────────────────────────────────────────────────
+    const claudeCode = opts.adapter === "claude-code";
+    // ── AGENTS.md block + host addendum ─────────────────────────────────────
     const agentsPath = join(projectRoot, AGENTS_FILE);
     if (existsSync(agentsPath)) {
-        const { text, removed } = removeRegion(readFileSync(agentsPath, "utf8"), INSTRUCTIONS_REGION);
-        if (!removed) {
-            actions.push(`· no instructions block in ${AGENTS_FILE}`);
+        // Both regions are harnery-placed, so deinit leaves neither behind. The
+        // addendum's *source file* is the host's and stays where it is.
+        const addendumGone = removeRegion(readFileSync(agentsPath, "utf8"), HOST_ADDENDUM_REGION);
+        if (addendumGone.removed) {
+            actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} the host addendum from ${AGENTS_FILE}`);
         }
-        else if (text === "") {
-            if (!opts.dryRun)
-                rmSync(agentsPath);
-            actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} ${AGENTS_FILE} (was block-only)`);
+        const { text, removed } = removeRegion(addendumGone.text, INSTRUCTIONS_REGION);
+        if (removed) {
+            actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} the instructions block from ${AGENTS_FILE}`);
         }
-        else {
-            if (!opts.dryRun)
+        else if (!addendumGone.removed) {
+            actions.push(`· no instructions block in ${AGENTS_FILE}`);
+        }
+        if (removed || addendumGone.removed) {
+            if (text === "") {
+                if (!opts.dryRun)
+                    rmSync(agentsPath);
+                actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} ${AGENTS_FILE} (nothing left but ours)`);
+            }
+            else if (!opts.dryRun) {
                 writeFileSync(agentsPath, text);
-            actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} the instructions block from ${AGENTS_FILE}`);
+            }
         }
     }
     // ── CLAUDE.md import shim (claude-code) ─────────────────────────────────
@@ -233,8 +272,17 @@ export function checkInstructions(projectRoot, opts) {
     try {
         const agentsPath = join(projectRoot, AGENTS_FILE);
         const content = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
-        note(`${AGENTS_FILE} block`, checkRegion(content, INSTRUCTIONS_REGION, renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.harness))));
-        if (opts.harness === "claude-code") {
+        note(`${AGENTS_FILE} block`, checkRegion(content, INSTRUCTIONS_REGION, renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.adapter))));
+        // A configured addendum is checked against its source; an unconfigured one
+        // still sitting in the file is drift too, since init would take it out.
+        const addendum = readHostAddendum(projectRoot);
+        if (addendum.configured) {
+            note(`${AGENTS_FILE} host addendum (${addendum.relPath})`, checkRegion(content, HOST_ADDENDUM_REGION, addendum.body));
+        }
+        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 exclude = readSkillsExclude(projectRoot);
             for (const skill of SKILLS) {
                 if (exclude.has(skill.id))

package/dist/lib/instructions/host-addendum.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The host addendum: a second managed region whose *content* belongs to the
+ * consumer.
+ *
+ * Harnery's orientation block is deliberately generic, because it ships to
+ * every consumer (ADR 0007's portability split, ADR 0008's ~80-line budget). A
+ * project with real coordination policy of its own therefore had nowhere
+ * machine-managed to put it, and ended up hand-maintaining it next to the
+ * block, where nothing kept the two in step.
+ *
+ * The fix is declarative rather than programmatic. A consumer names a file:
+ *
+ *     // .harnery/config.jsonc
+ *     { "instructions": { "hostAddendumFile": ".agents/host-instructions.md" } }
+ *
+ * and harnery gives that file's contents the same lifecycle as its own block:
+ * spliced on `init`, refreshed when the file changes, reported by
+ * `init --check`, removed by `deinit` or by deleting the config entry. Harnery
+ * never parses, renders, or reasons about what the file says, which is what
+ * keeps the arrangement portable: the mechanism is generic even though every
+ * consumer's content is not.
+ *
+ * Exposing the splicer as a public primitive instead would have pushed the
+ * whole lifecycle onto each host, since `init` and `deinit` are registered
+ * inside harnery and every consumer would have had to wrap or replace them and
+ * reimplement apply, check, and remove. The config key keeps one implementation
+ * of all four.
+ *
+ * Every failure here is raised before the caller writes anything.
+ */
+/** Dotted config key naming the addendum source, quoted in every error. */
+export declare const HOST_ADDENDUM_KEY = "instructions.hostAddendumFile";
+/** A host addendum that cannot be used. Callers abort before writing. */
+export declare class HostAddendumError extends Error {
+    constructor(message: string);
+}
+export type HostAddendum = {
+    configured: false;
+} | {
+    configured: true;
+    relPath: string;
+    body: string;
+};
+/**
+ * Resolve the configured addendum, or report that there is none.
+ *
+ * Absent config, absent key, and explicit `null` all mean "not configured",
+ * which is how a consumer turns the addendum off: delete the key and re-run
+ * `init`. Anything else that cannot become a readable file inside the project
+ * throws, because the alternative is an agent-facing instruction file that
+ * quietly lost a section the host believes is still there.
+ */
+export declare function readHostAddendum(projectRoot: string): HostAddendum;
+//# sourceMappingURL=host-addendum.d.ts.map

package/dist/lib/instructions/host-addendum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-addendum.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/host-addendum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,kCAAkC,CAAC;AAEjE,yEAAyE;AACzE,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,UAAU,EAAE,KAAK,CAAA;CAAE,GACrB;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,CAmDlE"}

package/dist/lib/instructions/host-addendum.js

@@ -0,0 +1,107 @@
+/**
+ * The host addendum: a second managed region whose *content* belongs to the
+ * consumer.
+ *
+ * Harnery's orientation block is deliberately generic, because it ships to
+ * every consumer (ADR 0007's portability split, ADR 0008's ~80-line budget). A
+ * project with real coordination policy of its own therefore had nowhere
+ * machine-managed to put it, and ended up hand-maintaining it next to the
+ * block, where nothing kept the two in step.
+ *
+ * The fix is declarative rather than programmatic. A consumer names a file:
+ *
+ *     // .harnery/config.jsonc
+ *     { "instructions": { "hostAddendumFile": ".agents/host-instructions.md" } }
+ *
+ * and harnery gives that file's contents the same lifecycle as its own block:
+ * spliced on `init`, refreshed when the file changes, reported by
+ * `init --check`, removed by `deinit` or by deleting the config entry. Harnery
+ * never parses, renders, or reasons about what the file says, which is what
+ * keeps the arrangement portable: the mechanism is generic even though every
+ * consumer's content is not.
+ *
+ * Exposing the splicer as a public primitive instead would have pushed the
+ * whole lifecycle onto each host, since `init` and `deinit` are registered
+ * inside harnery and every consumer would have had to wrap or replace them and
+ * reimplement apply, check, and remove. The config key keeps one implementation
+ * of all four.
+ *
+ * Every failure here is raised before the caller writes anything.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { stripJsonComments } from "../../core/config.js";
+/** Dotted config key naming the addendum source, quoted in every error. */
+export const HOST_ADDENDUM_KEY = "instructions.hostAddendumFile";
+/** A host addendum that cannot be used. Callers abort before writing. */
+export class HostAddendumError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HostAddendumError";
+    }
+}
+/**
+ * Resolve the configured addendum, or report that there is none.
+ *
+ * Absent config, absent key, and explicit `null` all mean "not configured",
+ * which is how a consumer turns the addendum off: delete the key and re-run
+ * `init`. Anything else that cannot become a readable file inside the project
+ * throws, because the alternative is an agent-facing instruction file that
+ * quietly lost a section the host believes is still there.
+ */
+export function readHostAddendum(projectRoot) {
+    const configured = readConfiguredPath(projectRoot);
+    if (configured === null)
+        return { configured: false };
+    if (typeof configured !== "string" || configured.trim() === "") {
+        throw new HostAddendumError(`${HOST_ADDENDUM_KEY} must be a repo-relative path to a markdown file`);
+    }
+    const relPath = configured.trim();
+    // An absolute path would name one machine's checkout, and this repo is cloned
+    // to a different location on every one of them.
+    if (isAbsolute(relPath)) {
+        throw new HostAddendumError(`${HOST_ADDENDUM_KEY} must be repo-relative, not absolute (got "${relPath}")`);
+    }
+    const root = resolve(projectRoot);
+    const target = resolve(root, relPath);
+    if (target !== root && !target.startsWith(root + sep)) {
+        throw new HostAddendumError(`${HOST_ADDENDUM_KEY} resolves outside the project ("${relPath}"); ` +
+            `the addendum must be a committed file in this repo`);
+    }
+    let body;
+    try {
+        if (statSync(target).isDirectory()) {
+            throw new HostAddendumError(`${HOST_ADDENDUM_KEY} points at a directory ("${relPath}")`);
+        }
+        body = readFileSync(target, "utf8");
+    }
+    catch (err) {
+        if (err instanceof HostAddendumError)
+            throw err;
+        throw new HostAddendumError(`${HOST_ADDENDUM_KEY} not found or unreadable ("${relPath}"): ${err.message}`);
+    }
+    // Splicing an empty region is never what anyone meant by configuring one, and
+    // it fails silently: the file looks fine and the policy simply is not there.
+    if (body.trim() === "") {
+        throw new HostAddendumError(`${HOST_ADDENDUM_KEY} is empty ("${relPath}")`);
+    }
+    // Trimmed because the splicer supplies the newlines around a region body;
+    // otherwise a trailing newline in the file shows up as a blank line that
+    // makes every re-render look like a change.
+    return { configured: true, relPath, body: body.trim() };
+}
+/** The raw config value, or null when the file, the section, or the key is absent. */
+function readConfiguredPath(projectRoot) {
+    const configPath = join(projectRoot, ".harnery", "config.jsonc");
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonComments(readFileSync(configPath, "utf8")));
+    }
+    catch {
+        // No config, or one harnery cannot parse. The rest of init already tolerates
+        // that, so the addendum does too rather than blocking an unrelated run.
+        return null;
+    }
+    const value = parsed?.instructions?.hostAddendumFile;
+    return value === undefined || value === null ? null : value;
+}

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

@@ -14,6 +14,13 @@
 export declare const INSTRUCTIONS_REGION = "instructions";
 /** Managed-region name for the CLAUDE.md `@AGENTS.md` import shim. */
 export declare const IMPORT_REGION = "import";
+/**
+ * Managed-region name for the consumer's own coordination policy, spliced from
+ * the file named by `instructions.hostAddendumFile`. Harnery places and
+ * versions the region; the content is the host's and is never rendered here.
+ * See `host-addendum.ts`.
+ */
+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) */
@@ -29,15 +36,15 @@ export interface BlockSkills {
  * `harn-council`) 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 harness with no skill primitive
+ * 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.
  */
 export declare function renderInstructionsBlock(binName: string, skills?: BlockSkills): string;
-/** A shipped skill: its harness-relative file path + a bin-name-aware renderer. */
+/** A shipped skill: its adapter-relative file path + a bin-name-aware renderer. */
 export interface SkillTemplate {
     id: string;
-    /** path under the harness skill dir, e.g. `harn-decide/SKILL.md` */
+    /** path under the adapter skill dir, e.g. `harn-decide/SKILL.md` */
     relPath: string;
     render: (binName: string) => string;
 }

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;AAEtC,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,CA4DR;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,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"}