harnery 0.30.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/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"}

package/dist/lib/instructions/templates.js

@@ -10,12 +10,19 @@
  * files), so they compile into `dist/` and resolve identically under Bun and
  * Node — no `files`-field copy or package-path guesswork.
  */
-import { SCRATCH_CATEGORIES } from "../../core/scratch/index.js";
+import { JOURNAL_CATEGORIES } from "../../core/journal/index.js";
 import { buildOwnedSkill } from "./splice.js";
 /** Managed-region name for the AGENTS.md orientation block. */
 export const INSTRUCTIONS_REGION = "instructions";
 /** Managed-region name for the CLAUDE.md `@AGENTS.md` import shim. */
 export 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 const HOST_ADDENDUM_REGION = "host-addendum";
 /**
  * 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
@@ -24,7 +31,7 @@ export const IMPORT_REGION = "import";
  * `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.
  */
@@ -33,24 +40,25 @@ export function renderInstructionsBlock(binName, skills = { decide: true, counci
     const named = [skills.decide && "`harn-decide`", skills.council && "`harn-council`"].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} council --help\` for the deeper procedures.`;
+        : `See \`${b} decision --help\` and \`${b} agents council --help\` for the deeper procedures.`;
     const decidePointer = skills.decide
         ? "The `harn-decide` skill has the file / claim / resolve-with-evidence procedure."
         : `See \`${b} decision --help\` for the file / claim / resolve-with-evidence procedure.`;
     const councilPointer = skills.council
         ? "The `harn-council` skill has the steward and member flow."
-        : `See \`${b} council --help\` for the steward and member flow.`;
-    // Render the scratch categories from the canonical enum so this prose can
-    // never drift from what `scratch add` actually accepts (the "note, plan…" list
+        : `See \`${b} agents council --help\` for the steward and member flow.`;
+    // 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).
-    const scratchCats = SCRATCH_CATEGORIES.length > 1
-        ? `${SCRATCH_CATEGORIES.slice(0, -1).join(", ")}, or ${SCRATCH_CATEGORIES.at(-1)}`
-        : SCRATCH_CATEGORIES[0];
+    const journalCats = JOURNAL_CATEGORIES.length > 1
+        ? `${JOURNAL_CATEGORIES.slice(0, -1).join(", ")}, or ${JOURNAL_CATEGORIES.at(-1)}`
+        : JOURNAL_CATEGORIES[0];
     return `## harnery coordination
 
 This project runs [harnery](https://harnery.com) for multi-agent coordination.
 You share this checkout with other agents; the surfaces below keep you oriented
-and out of each other's way. Run \`${b} <command> --help\` for any command's full
+and out of each other's way, and let you dispatch a team of your own when a job
+is bigger than one session. Run \`${b} <command> --help\` for any command's full
 surface. ${deeper}
 
 **Identity + peers.** You are one of several agents in this repo.
@@ -59,6 +67,20 @@ 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.
 
+**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:
+plain JS stages fan out to headless subagents that are born
+coordination-registered, with deterministic code deciding the routing between
+stages. \`${b} work create <title> <workflow>\` wraps an objective that has to
+survive many such passes, holding it across retries, failures, and review.
+\`${b} governor create\` drives a whole graph of work toward a goal, choosing
+what runs next and how much it may settle without asking a human. Reach for the
+first when one pass will do, the second when the objective must outlive the
+attempt, and the third when a human would otherwise have to babysit the loop. A
+run that needs authorization parks durably instead of failing, so check
+\`${b} approval list\` when one appears to be waiting rather than stuck.
+
 **Durable role handoff.** When you are replacing a prior session in the same
 named role, run \`${b} agents identity assume <name>\` before declaring your task.
 It reclaims an abandoned namesake (no live process) and refuses only when another
@@ -70,11 +92,18 @@ coordination ledger. Lead a shell command with a \`# intent: <why>\` comment (or
 the tool's description) so the recorded event carries a reason instead of
 \`(no intent)\`.
 
-**Scratch journal.** \`${b} scratch add <category> "<text>"\` (category = ${scratchCats})
+**Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
-\`${b} scratch read\` reads yours, \`${b} scratch read --name <peer>\` reads a peer's.
+\`${b} journal read\` reads yours, \`${b} journal read --name <peer>\` reads a peer's.
 Use it for anything future-you or a peer will need to pick up your thread.
 
+**Working artifacts.** For screenshots, exports, audit dumps, rollback inputs,
+and other untracked files that must survive a session, create a managed workspace
+with \`${b} artifacts create <slug> --purpose "<why>"\`. Write files under the
+returned path, then run \`${b} artifacts release <id>\` when active work is done.
+Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
+expired cleanup and requires \`--yes\` to delete anything.
+
 **Decision docket.** When you would otherwise stop to ask a human a decision you
 can't resolve from the repo, file it instead. \`${b} decision file "<question>"\`
 records it and lets you proceed on a stated default; \`${b} decision search "<terms>"\`