harnery 0.30.0 → 0.31.0

package/src/lib/council/index.ts

@@ -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.
  */
@@ -242,7 +242,7 @@ export interface KnownAgent {
   /** `agent-<Name>` canonical handle. */
   name: string;
   /** `active` = currently has a heartbeat in `.harnery/active/`. `stale` =
-   * recently ended (scratchpad archived within the lookback window). */
+   * recently ended (journal archived within the lookback window). */
   state: "active" | "stale";
   /** ISO timestamp of the most-recent signal. */
   last_seen: string;
@@ -253,7 +253,7 @@ export interface KnownAgent {
 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.
  */
@@ -261,7 +261,7 @@ export function listKnownAgents(): KnownAgent[] {
   const root = monorepoRoot();
   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<string, KnownAgent>();
 
   if (existsSync(activeDir)) {
@@ -296,7 +296,7 @@ export function listKnownAgents(): KnownAgent[] {
       if (Number.isNaN(ts) || ts < cutoff) 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]!;
         const existing = byName.get(name);
@@ -588,7 +588,7 @@ export function writeContribution(
  * 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: string, round: number): string | null {
   const rd = roundDir(councilId, round);
@@ -636,9 +636,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.
  */
@@ -654,7 +654,7 @@ export function buildSubmitFooter(councilId: string): string {
     `# 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");
 }
 

package/src/lib/identities/assume.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.
  */
@@ -126,7 +126,7 @@ export function findIdentityConflict(
 }
 
 /**
- * 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.
@@ -139,13 +139,13 @@ export function reclaimAbandonedLocalConflict(
   if (instanceHasLivePid(coordRoot, conflict.instance_id)) return false;
 
   const hbPath = join(coordRoot, ".harnery", "active", `${conflict.instance_id}.json`);
-  let harness: "claude-code" | "cursor" | "codex" = "claude-code";
+  let adapter: "claude-code" | "cursor" | "codex" = "claude-code";
   let sessionId = conflict.instance_id;
   let ageSecs: number | undefined;
   if (existsSync(hbPath)) {
     try {
       const hb = JSON.parse(readFileSync(hbPath, "utf8")) as Heartbeat;
-      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)) ageSecs = Math.max(0, Math.floor((Date.now() - ts) / 1000));
@@ -164,7 +164,7 @@ export function reclaimAbandonedLocalConflict(
       event_type: "health.heartbeat_swept",
       instance_id: conflict.instance_id,
       session_id: sessionId,
-      harness,
+      adapter,
       source: "agent-coord",
       data: {
         reason: "stale",
@@ -244,7 +244,7 @@ function acquireLock(coordRoot: string): () => void {
   );
 }
 
-function harnessOf(platform: string | undefined): "claude-code" | "cursor" | "codex" {
+function adapterOf(platform: string | undefined): "claude-code" | "cursor" | "codex" {
   if (platform === "cursor") return "cursor";
   if (platform === "codex") return "codex";
   return "claude-code";
@@ -320,7 +320,7 @@ export function assumeIdentity(
         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/src/lib/instructions/apply.ts

@@ -29,6 +29,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { stripJsonComments } from "../../core/config.ts";
+import { readHostAddendum } from "./host-addendum.ts";
 import {
   checkOwnedSkill,
   checkRegion,
@@ -39,6 +40,7 @@ import {
 } from "./splice.ts";
 import {
   type BlockSkills,
+  HOST_ADDENDUM_REGION,
   IMPORT_REGION,
   INSTRUCTIONS_REGION,
   renderInstructionsBlock,
@@ -81,8 +83,8 @@ export function readSkillsExclude(projectRoot: string): Set<string> {
  * 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: string, harness: string): BlockSkills {
-  const claudeCode = harness === "claude-code";
+function blockSkills(projectRoot: string, adapter: string): BlockSkills {
+  const claudeCode = adapter === "claude-code";
   const exclude = readSkillsExclude(projectRoot);
   return {
     decide: claudeCode && !exclude.has("harn-decide"),
@@ -92,7 +94,7 @@ function blockSkills(projectRoot: string, harness: string): BlockSkills {
 
 interface ApplyOpts {
   binName: string;
-  harness: string;
+  adapter: string;
   dryRun: boolean;
 }
 
@@ -109,27 +111,61 @@ export interface ApplyResult {
 export function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyResult {
   const actions: string[] = [];
   const warnings: string[] = [];
-  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: string, past: string) => (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);
@@ -185,7 +221,7 @@ export function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyRe
 }
 
 interface RemoveOpts {
-  harness: string;
+  adapter: string;
   dryRun: boolean;
 }
 
@@ -198,22 +234,36 @@ interface RemoveOpts {
 export function removeInstructions(projectRoot: string, opts: RemoveOpts): ApplyResult {
   const actions: string[] = [];
   const warnings: string[] = [];
-  const claudeCode = opts.harness === "claude-code";
+  const claudeCode = opts.adapter === "claude-code";
 
-  // ── AGENTS.md block ─────────────────────────────────────────────────────
+  // ── 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}`);
-    } else if (text === "") {
-      if (!opts.dryRun) rmSync(agentsPath);
-      actions.push(`+ ${opts.dryRun ? "would remove" : "removed"} ${AGENTS_FILE} (was block-only)`);
-    } else {
-      if (!opts.dryRun) writeFileSync(agentsPath, text);
+    // 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}`,
+      );
+    }
+    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 (!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);
+      }
     }
   }
 
@@ -277,7 +327,7 @@ export interface CheckResult {
  */
 export function checkInstructions(
   projectRoot: string,
-  opts: { binName: string; harness: string },
+  opts: { binName: string; adapter: string },
 ): CheckResult {
   const issues: string[] = [];
   let errored = false;
@@ -295,11 +345,23 @@ export function checkInstructions(
       checkRegion(
         content,
         INSTRUCTIONS_REGION,
-        renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.harness)),
+        renderInstructionsBlock(opts.binName, blockSkills(projectRoot, opts.adapter)),
       ),
     );
 
-    if (opts.harness === "claude-code") {
+    // 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)) continue;

package/src/lib/instructions/host-addendum.ts

@@ -0,0 +1,126 @@
+/**
+ * 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.ts";
+
+/** 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: string) {
+    super(message);
+    this.name = "HostAddendumError";
+  }
+}
+
+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 function readHostAddendum(projectRoot: string): HostAddendum {
+  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: string;
+  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 as Error).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: string): unknown {
+  const configPath = join(projectRoot, ".harnery", "config.jsonc");
+  let parsed: { instructions?: { hostAddendumFile?: unknown } } | null;
+  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/src/lib/instructions/templates.ts

@@ -11,13 +11,20 @@
  * Node — no `files`-field copy or package-path guesswork.
  */
 
-import { SCRATCH_CATEGORIES } from "../../core/scratch/index.ts";
+import { JOURNAL_CATEGORIES } from "../../core/journal/index.ts";
 import { buildOwnedSkill } from "./splice.ts";
 
 /** 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";
 
 /** Which shipped skills exist in the project the block is rendered for. */
 export interface BlockSkills {
@@ -35,7 +42,7 @@ 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.
  */
@@ -51,26 +58,27 @@ export function renderInstructionsBlock(
   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.
@@ -79,6 +87,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
@@ -90,11 +112,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>"\`
@@ -106,10 +135,10 @@ surfaces prior decisions, so check for precedent before re-deciding. ${decidePoi
 
 // ── Skills ──────────────────────────────────────────────────────────────────
 
-/** 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/src/lib/machine.ts

@@ -5,12 +5,12 @@ import { coordEnv } from "./env.ts";
 
 /**
  * Resolve a human-friendly label for the current machine. Used to tag
- * coordination artifacts (scratch-doc headers, session telemetry) by the host
+ * coordination artifacts (journal-doc headers, session telemetry) by the host
  * they originated on.
  *
  * Precedence (first non-empty wins):
  *   1. HARNERY_MACHINE env var:          transient / per-launch / CI override
- *   2. ~/.config/harnery/machine file:   persistent, harness-neutral identity
+ *   2. ~/.config/harnery/machine file:   persistent, adapter-neutral identity
  *   3. os.hostname() (normalized):       automatic floor; never empty
  *
  * The env var sits on top for ad-hoc overrides; the file is the durable home for

package/dist/commands/harness.d.ts

@@ -1,12 +0,0 @@
-import type { Command } from "commander";
-import type { EmitContext } from "../commander.js";
-import { type BenchResult, type HarnessAttestationReport, type HarnessBenchReport } from "../core/harnesses/index.js";
-import type { HarnessProfile } from "../core/harnesses/types.js";
-export declare function registerHarnessCommand(program: Command, emit: EmitContext): void;
-export declare function renderAttestationReport(report: HarnessAttestationReport): string;
-export declare function renderProfileTable(profiles: readonly HarnessProfile[]): string;
-export declare function renderProfile(profile: HarnessProfile): string;
-export declare function renderBenchReport(report: HarnessBenchReport): string;
-/** Kept exported so command tests can assert row semantics without model calls. */
-export type { BenchResult };
-//# sourceMappingURL=harness.d.ts.map

package/dist/commands/harness.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/commands/harness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EAIxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAmBjE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA4JhF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAgBhF;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAU9E;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAkB7D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA6BpE;AAgBD,mFAAmF;AACnF,YAAY,EAAE,WAAW,EAAE,CAAC"}

package/dist/commands/scratch.d.ts

@@ -1,4 +0,0 @@
-import type { Command } from "commander";
-import type { EmitContext } from "../commander.js";
-export declare function registerScratchCommand(program: Command, emitParam: EmitContext): void;
-//# sourceMappingURL=scratch.d.ts.map

package/dist/commands/scratch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scratch.d.ts","sourceRoot":"","sources":["../../src/commands/scratch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA6BnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA2RrF"}

package/dist/commands/session.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/commands/session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsCnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAsDrF"}