harnery 0.30.0 → 0.31.1

package/dist/commands/agents.js

@@ -16,16 +16,18 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
+import { coordBinPath } from "../core/agents/coord-bin.js";
 import { readStreamTailBounded } from "../core/agents/events/consume.js";
-import { emitCanonical, monorepoRoot, normalizeHarness, readHeartbeat, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, } from "../core/agents/index.js";
+import { emitCanonical, monorepoRoot, normalizeAdapter, readHeartbeat, resolveOwner, resolveOwnerBySessionEnv, resolveOwnerWithSource, } from "../core/agents/index.js";
 import { coordFreshnessSeconds, resolveBinName } from "../core/config.js";
 import { readRemoteMachines } from "../core/presence/index.js";
+import { registerContextCommand } from "./context.js";
 /** Cap for CLI scans of the unbounded event ledger (`trace` / `health`). Well
  * under V8's ~512MB max string length so a `readFileSync` of the whole file can
  * never throw; covers ample recent history for a diagnostic scan. */
 const STREAM_SCAN_CAP_BYTES = 128 * 1024 * 1024; // 128 MiB
 import { parsePsChainLine } from "../core/hooks/resolve/anchor.js";
-import { appendEntry, resolveOwnerByName } from "../core/scratch/index.js";
+import { appendEntry, resolveOwnerByName } from "../core/journal/index.js";
 import { buildCouncilId, buildInviteMarkdown, COUNCIL_SCHEMA_VERSION, contributorsInRound, councilBodyDir, councilsArchiveDir, deleteArchivedCouncil, effectiveSteward, findManifestByPartialId, listKnownAgents, listManifests, moveFromArchive, moveToArchive, normalizeAgentName, pendingCouncilsForMember, readArchivedManifest, readManifest, readRoundPrompts, roundDir, setCouncilSteward, writeContribution, writeManifest, writePrompt, } from "../lib/council/index.js";
 import { assumeIdentity, IdentityAssumeError } from "../lib/identities/assume.js";
 import { displayName as displayAgentName, ensureIdentity, listIdentities, lookupById as lookupIdentityById, lookupByName as lookupIdentityByName, } from "../lib/identities/index.js";
@@ -55,6 +57,41 @@ const SUBAGENT_NOTE = "Bash identity is process-level in v1; if you're running i
 export function coordHelperOpts(root) {
     return { cwd: root, env: { ...process.env, HARNERY_COORD_ROOT_OVERRIDE: root } };
 }
+/**
+ * Resolve the bundled `agent-coord` helper, or exit with an error that names the
+ * problem. Every heartbeat mutation goes through that binary, so a caller who
+ * cannot find it has nothing useful to do — but it has to SAY so, because the
+ * alternative was spawning a path that did not exist and then crashing on the
+ * result (see `spawnFailureMessage`).
+ */
+function agentCoordOrExit(root) {
+    const binary = coordBinPath("agent-coord", root);
+    if (!binary) {
+        emit.error({
+            code: "coord_helper_missing",
+            message: `agent-coord helper not found for coord root ${root}; reinstall or rebuild harnery`,
+        });
+        process.exit(1);
+    }
+    return binary;
+}
+/**
+ * Describe a failed `spawnSync` without assuming it ran.
+ *
+ * When the binary cannot be executed at all (ENOENT, EACCES) node reports
+ * `status: null` AND `stderr: null`, so the obvious `result.stderr.trim()`
+ * threw "null is not an object" — replacing a legible "helper not found" with a
+ * crash that pointed at the wrong layer entirely. `error` carries the real
+ * cause on that path, so prefer it.
+ */
+function spawnFailureMessage(result, what) {
+    if (result.error)
+        return `${what}: ${result.error.message}`;
+    const stderr = result.stderr?.trim();
+    if (stderr)
+        return stderr;
+    return result.status === null ? `${what}: did not run` : `${what} exited ${result.status}`;
+}
 function formatPlatformLabel(platform) {
     if (platform === "cursor")
         return "Cursor";
@@ -63,11 +100,12 @@ function formatPlatformLabel(platform) {
     return "CC";
 }
 let emit;
-export function registerAgentsCommand(program, emitParam) {
+export function registerAgentsCommand(program, emitParam, programContext) {
     emit = emitParam;
     const cmd = program
         .command("agents")
-        .description("Query the multi-agent coordination layer (whoami / list / status / health)");
+        .description("The live agent sessions in this project: who is running now, what they hold, and their coordination state (whoami / list / status / health).");
+    registerContextCommand(cmd, emitParam, programContext);
     cmd
         .command("whoami")
         .description("Print the current agent's name + instance_id + files claimed")
@@ -97,7 +135,7 @@ export function registerAgentsCommand(program, emitParam) {
     cmd
         .command("suggest-name [description...]")
         .description('Reprint a session name ("Agent <you> - <description>") for the operator to set as their ' +
-        "harness tab title. With no arg, derives it from your current task. The primary naming path " +
+        "adapter tab title. With no arg, derives it from your current task. The primary naming path " +
         "is set-task (it suggests a name on the first focus declaration); reach for this to reprint " +
         "or re-suggest after a topic pivot. Read-only.")
         .option("--json", "JSON output instead of the bare name")
@@ -154,7 +192,7 @@ export function registerAgentsCommand(program, emitParam) {
     });
     cmd
         .command("ping <name> <message...>")
-        .description("Append a 'handoff' entry to a peer agent's scratchpad. Body prefixed with " +
+        .description("Append a 'handoff' entry to a peer agent's journal. Body prefixed with " +
         "`from agent-<me>:`. Use to leave actionable coordination notes for peers " +
         "currently holding files you need.")
         .option("--json", "JSON output")
@@ -194,17 +232,17 @@ export function registerAgentsCommand(program, emitParam) {
         runHealth(opts);
     });
     cmd
-        .command("harness-probe <id>")
-        .description("Harness wiring probe: ppid chain, comm names, pid-map anchor, sample payload paths. " +
+        .command("adapter-probe <id>")
+        .description("Adapter wiring probe: ppid chain, comm names, pid-map anchor, sample payload paths. " +
         "With --replay-samples, also replays every checked-in sample payload against the live " +
         "adapter in an isolated sandbox to catch adapter / payload-shape drift. " +
         "Complements heal-events (drift telemetry). Id: claude_code | cursor.")
         .option("--json", "JSON envelope output")
-        .option("--replay-samples", "Replay docs/api/<harness>-hooks/samples/*.json against the live adapter in an isolated sandbox. " +
+        .option("--replay-samples", "Replay docs/api/<adapter>-hooks/samples/*.json against the live adapter in an isolated sandbox. " +
         "Exits non-zero if any sample crashes the adapter.")
         .option("--sample <path>", "Replay only the named sample file (basename match). Implies --replay-samples.")
         .action((id, opts) => {
-        runHarnessProbe(id, opts);
+        runAdapterProbe(id, opts);
     });
     cmd
         .command("heal")
@@ -226,7 +264,6 @@ export function registerAgentsCommand(program, emitParam) {
         .action((opts) => {
         runHeal(opts);
     });
-    registerCouncilCommands(cmd);
     registerIdentityCommands(cmd);
 }
 function registerIdentityCommands(parent) {
@@ -368,7 +405,7 @@ function runIdentityAssume(target, opts) {
         process.exit(1);
     }
 }
-function registerCouncilCommands(parent) {
+export function registerCouncilCommands(parent) {
     const council = parent
         .command("council")
         .description("Multi-agent deliberation: convene a temporary group around an " +
@@ -453,7 +490,7 @@ function registerCouncilCommands(parent) {
         "(or omit [steward]) to drop the field and revert to the default " +
         "(the convener). Refuses to mutate archived councils. By default, " +
         "rejects names not in the known-agents list (active heartbeats + " +
-        "scratchpads archived in the last 30 days); pass --allow-unknown " +
+        "journals archived in the last 30 days); pass --allow-unknown " +
         "to bypass when bootstrapping.")
         .option("--clear", "Clear the steward field, reverting to created_by default")
         .option("--allow-unknown", "Skip the known-agents check (bootstrap an agent that hasn't run yet)")
@@ -467,7 +504,7 @@ function registerCouncilCommands(parent) {
         "Pass either --message <inline> or --file <path>. Writes to " +
         ".harnery/councils/<id>/round-<N>/<agent-Name>.md. Pass --as <member> " +
         "to contribute under a council seat name that differs from the running " +
-        "agent's heartbeat name (useful for cross-harness councils where each " +
+        "agent's heartbeat name (useful for cross-adapter councils where each " +
         "reviewer has a different auto-generated session name).")
         .option("--message <text>", "Inline contribution text (caps at 4KB)")
         .option("--file <path>", "Path to a file containing the contribution")
@@ -536,7 +573,7 @@ function runWhoami(opts) {
     if (!hb) {
         emit.error({
             code: "no_heartbeat",
-            message: `pid-map resolved owner=${myOwner.slice(0, 8)} but no heartbeat exists`,
+            message: noHeartbeatMessage(myOwner),
         });
         process.exit(1);
     }
@@ -720,6 +757,42 @@ function normalizeKind(kind) {
         return "unknown";
     return kind;
 }
+/**
+ * The `no_heartbeat` diagnostic, quoting the owner id in FULL.
+ *
+ * This id is actionable: the reader's next move is `agents heal --kind
+ * heartbeat --owner <id>`, and heartbeats are keyed by the whole
+ * `instance_id` (`.harnery/active/<instance_id>.json`). An abbreviated id
+ * here reads as complete, so it gets copy-pasted into `--owner` and mints a
+ * heartbeat at a filename no reader resolves — an orphan that leaves the
+ * session looking unhealable. Abbreviate ids for display elsewhere, never in
+ * a message whose whole purpose is to hand the reader an id to pass back.
+ */
+function noHeartbeatMessage(owner) {
+    return `resolved owner=${owner} but no heartbeat exists at .harnery/active/${owner}.json`;
+}
+/**
+ * The instance_id of a live heartbeat that `prefix` strictly prefixes, or null.
+ *
+ * Used to recognize an abbreviated id handed back by a reader when the caller
+ * supplied no canonical id of their own. Ambiguity is treated as "no answer":
+ * two live sessions sharing the prefix means we cannot name the one intended,
+ * and refusing with the wrong id in the message would be worse than the orphan.
+ */
+function liveIdWithPrefix(root, prefix) {
+    const activeDir = resolve(root, ".harnery", "active");
+    if (!existsSync(activeDir))
+        return null;
+    const matches = new Set();
+    for (const file of readdirSync(activeDir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        const id = file.slice(0, -".json".length);
+        if (id !== prefix && id.startsWith(prefix))
+            matches.add(id);
+    }
+    return matches.size === 1 ? matches.values().next().value : null;
+}
 async function runWatch(pollMs) {
     const root = monorepoRoot();
     if (!root) {
@@ -1011,8 +1084,8 @@ function ensureCursorSession(root) {
     const sessionId = cursorEnvSessionId();
     if (!sessionId)
         return;
-    const agentHook = resolve(root, "harnery", "bin", "agent-hook");
-    if (!existsSync(agentHook))
+    const agentHook = coordBinPath("agent-hook", root);
+    if (!agentHook)
         return;
     const payload = JSON.stringify({
         conversation_id: sessionId,
@@ -1023,7 +1096,7 @@ function ensureCursorSession(root) {
         composer_mode: "agent",
         is_background_agent: false,
     });
-    spawnSync("bash", [agentHook, "session-start", "--harness", "cursor"], {
+    spawnSync("bash", [agentHook, "session-start", "--adapter", "cursor"], {
         input: payload,
         cwd: root,
         encoding: "utf8",
@@ -1059,7 +1132,7 @@ function runReleaseClaim(path) {
     let canonical = path;
     if (path.startsWith(`${root}/`))
         canonical = path.slice(root.length + 1);
-    const helper = resolve(root, "harnery", "bin", "agent-coord");
+    const helper = agentCoordOrExit(root);
     const result = spawnSync(helper, ["release-claim", myOwner, canonical], {
         encoding: "utf8",
         ...coordHelperOpts(root),
@@ -1067,7 +1140,7 @@ function runReleaseClaim(path) {
     if (result.status !== 0) {
         emit.error({
             code: "release_claim_failed",
-            message: result.stderr.trim() || `agent-coord exited ${result.status}`,
+            message: spawnFailureMessage(result, "agent-coord"),
         });
         process.exit(1);
     }
@@ -1105,7 +1178,7 @@ function runSetTask(task, opts) {
     const priorHb = readHeartbeat(myOwner);
     const firstOfSession = !priorHb?.task_updated_at;
     // Heartbeat mutation goes through agent-coord (atomic temp+rename).
-    const helper = resolve(root, "harnery", "bin", "agent-coord");
+    const helper = agentCoordOrExit(root);
     const result = spawnSync(helper, ["set-task", myOwner, task], {
         encoding: "utf8",
         ...coordHelperOpts(root),
@@ -1113,7 +1186,7 @@ function runSetTask(task, opts) {
     if (result.status !== 0) {
         emit.error({
             code: "set_task_failed",
-            message: result.stderr.trim() || `agent-coord exited ${result.status}`,
+            message: spawnFailureMessage(result, "agent-coord"),
         });
         process.exit(1);
     }
@@ -1122,11 +1195,11 @@ function runSetTask(task, opts) {
         type: "state.task_set",
         owner: myOwner,
         session: hb?.session_id ?? myOwner,
-        harness: normalizeHarness(hb?.platform),
+        adapter: normalizeAdapter(hb?.platform),
         data: { task, cleared: !task || task.length === 0 },
     });
     // On the first focus declaration of a session, surface a suggested session
-    // name for the operator to set as their harness tab title. Read the result
+    // name for the operator to set as their adapter tab title. Read the result
     // (`suggested_session_name`) and reproduce it in a fenced code block so the
     // UI's Copy button hands over the exact string. null on every later call.
     const built = firstOfSession && !opts?.sessionId ? buildSuggestedName(hb?.name ?? "unknown", [task]) : null;
@@ -1231,7 +1304,7 @@ function runStatus(opts) {
     if (!hb) {
         emit.error({
             code: "no_heartbeat",
-            message: `pid-map resolved owner=${myOwner.slice(0, 8)} but no heartbeat exists`,
+            message: noHeartbeatMessage(myOwner),
         });
         process.exit(1);
     }
@@ -1240,7 +1313,7 @@ function runStatus(opts) {
     // populated for back-compat with consumers reading v1 directly. The stamp
     // goes through agent-coord (atomic write).
     try {
-        const helper = resolve(root, "harnery", "bin", "agent-coord");
+        const helper = agentCoordOrExit(root);
         spawnSync(helper, ["stamp-status-call", myOwner], {
             encoding: "utf8",
             timeout: 2000,
@@ -1254,7 +1327,7 @@ function runStatus(opts) {
         type: "state.status_checked",
         owner: myOwner,
         session: hb.session_id ?? myOwner,
-        harness: normalizeHarness(hb.platform),
+        adapter: normalizeAdapter(hb.platform),
         data: {
             format: opts.json ? "json" : "box",
             agent_count: 0, // computed below, not yet available here; Phase 5 verdict reads owner-scope only
@@ -1721,14 +1794,14 @@ function readCanonicalEventsInWindow(root, cutoffMs) {
     }
     return out;
 }
-/** harness ("claude-code") → legacy platform label ("claude_code") so the
+/** adapter ("claude-code") → legacy platform label ("claude_code") so the
  * existing formatPlatformLabel rendering keeps working unchanged. */
-function harnessToPlatform(harness) {
-    if (harness === "claude-code")
+function adapterToPlatform(adapter) {
+    if (adapter === "claude-code")
         return "claude_code";
-    if (harness === "cursor")
+    if (adapter === "cursor")
         return "cursor";
-    if (harness === "codex")
+    if (adapter === "codex")
         return "codex";
     return "claude_code";
 }
@@ -1750,7 +1823,7 @@ function canonicalToHealEvent(ev, nameById) {
         agent,
         kind,
         reason,
-        platform: harnessToPlatform(ev.harness),
+        platform: adapterToPlatform(ev.adapter),
     };
     if (kind === "pidmap" && data.pid !== undefined && data.pid !== null) {
         out.pid = String(data.pid);
@@ -2508,14 +2581,14 @@ function renderHealthBox(report) {
         }
     }
 }
-function runHarnessProbe(id, opts) {
+function runAdapterProbe(id, opts) {
     if (opts.json)
         emit.config({ format: "json" });
-    const harness = id.trim();
-    if (harness !== "claude_code" && harness !== "cursor") {
+    const adapter = id.trim();
+    if (adapter !== "claude_code" && adapter !== "cursor") {
         emit.error({
-            code: "bad_harness",
-            message: "harness id must be claude_code or cursor",
+            code: "bad_adapter",
+            message: "adapter id must be claude_code or cursor",
         });
         process.exit(1);
     }
@@ -2527,13 +2600,13 @@ function runHarnessProbe(id, opts) {
         });
         process.exit(1);
     }
-    const subagentDir = harness === "cursor" ? ".harnery/.cursor-subagent-map" : `.harnery/.subagent-map/${harness}`;
-    const sampleDir = harness === "cursor" ? "docs/api/cursor-hooks/samples" : "docs/api/claude-code-hooks/samples";
-    const dispatchEntry = harness === "cursor"
-        ? "harnery/bin/agent-hook session-start --harness cursor"
-        : "harnery/bin/agent-hook session-start --harness claude-code";
+    const subagentDir = adapter === "cursor" ? ".harnery/.cursor-subagent-map" : `.harnery/.subagent-map/${adapter}`;
+    const sampleDir = adapter === "cursor" ? "docs/api/cursor-hooks/samples" : "docs/api/claude-code-hooks/samples";
+    const dispatchEntry = adapter === "cursor"
+        ? "harnery/bin/agent-hook session-start --adapter cursor"
+        : "harnery/bin/agent-hook session-start --adapter claude-code";
     // TS-native probe. The owner + anchor-pid resolution it reports lives in
-    // `findHarnessAnchorPid` (core/hooks/cli.ts, the /proc walk mirrored below)
+    // `findAdapterAnchorPid` (core/hooks/cli.ts, the /proc walk mirrored below)
     // and `resolveOwner` here, so the probe reports exactly what the live hot
     // path resolves.
     const anchorTokens = new Set(["claude", "claude-code", "cursor", "codex"]);
@@ -2573,7 +2646,7 @@ function runHarnessProbe(id, opts) {
         walkPid = ppid;
     }
     const data = {
-        harness,
+        adapter,
         anchor_pid: anchorPid,
         hook_pid: String(process.pid),
         resolved_owner: resolveOwner() ?? "",
@@ -2581,13 +2654,13 @@ function runHarnessProbe(id, opts) {
         subagent_map_dir: subagentDir,
         sample_ref: sampleDir,
         dispatch_entry: dispatchEntry,
-        note: "heal-events counts drift; harness-probe answers wiring",
+        note: "heal-events counts drift; adapter-probe answers wiring",
     };
     const wantReplay = opts.replaySamples || !!opts.sample;
     let samples = [];
     let replayExitCode = 0;
     if (wantReplay) {
-        const result = replayHarnessSamples(harness, root, sampleDir, opts.sample);
+        const result = replayAdapterSamples(adapter, root, sampleDir, opts.sample);
         samples = result.samples;
         replayExitCode = result.exitCode;
         data.samples = samples;
@@ -2596,7 +2669,7 @@ function runHarnessProbe(id, opts) {
     emit.data(data);
     if (process.stdout.isTTY && !opts.json) {
         const lines = [
-            `Harness probe: ${harness}`,
+            `Adapter probe: ${adapter}`,
             `  anchor_pid:    ${String(data.anchor_pid) || "(empty, expected in sandbox/non-IDE)"}`,
             `  hook_pid:      ${String(data.hook_pid)}`,
             `  resolved_owner: ${String(data.resolved_owner) || "(none)"}`,
@@ -2636,11 +2709,11 @@ function runHarnessProbe(id, opts) {
     }
 }
 /**
- * Replay every JSON fixture in <root>/<sampleDir> against the live harness
+ * Replay every JSON fixture in <root>/<sampleDir> against the live adapter
  * dispatcher in an isolated sandbox.
  *
  * Sandbox isolation strategy:
- *   - mkdtempSync(tmpdir(), "harn-harness-probe-") creates a non-git tmp dir.
+ *   - mkdtempSync(tmpdir(), "harn-adapter-probe-") creates a non-git tmp dir.
  *   - The dispatcher's coord-root resolution falls back to
  *     `HARNERY_COORD_ROOT_OVERRIDE` when git rev-parse fails. We set it to the sandbox.
  *   - We rewrite the payload's `cwd` field (Cursor cds to it) to the sandbox,
@@ -2652,7 +2725,7 @@ function runHarnessProbe(id, opts) {
  * payload with `.hook_event_name`. Event name resolution falls back to the
  * filename (without `.json`) when neither field exists.
  */
-function replayHarnessSamples(harness, root, relativeSampleDir, filter) {
+function replayAdapterSamples(adapter, root, relativeSampleDir, filter) {
     const sampleDir = resolve(root, relativeSampleDir);
     if (!existsSync(sampleDir)) {
         return {
@@ -2673,7 +2746,7 @@ function replayHarnessSamples(harness, root, relativeSampleDir, filter) {
         };
     }
     // agent-hook is the single entry point. Replay sample payloads against it,
-    // mapping the harness-native hook_event_name to the agent-hook CLI subcommand.
+    // mapping the adapter-native hook_event_name to the agent-hook CLI subcommand.
     const agentHook = resolve(root, "harnery/bin/agent-hook");
     if (!existsSync(agentHook)) {
         return {
@@ -2711,8 +2784,8 @@ function replayHarnessSamples(harness, root, relativeSampleDir, filter) {
         stopFailure: "stop-failure",
         StopFailure: "stop-failure",
     };
-    const harnessFlag = harness === "claude_code" ? "claude-code" : harness;
-    const sandbox = mkdtempSync(join(tmpdir(), "harn-harness-probe-"));
+    const adapterFlag = adapter === "claude_code" ? "claude-code" : adapter;
+    const sandbox = mkdtempSync(join(tmpdir(), "harn-adapter-probe-"));
     const results = [];
     try {
         for (const file of fixtures) {
@@ -2749,7 +2822,7 @@ function replayHarnessSamples(harness, root, relativeSampleDir, filter) {
                 payloadObj.workspace_roots = [sandbox];
             }
             const subcommand = EVENT_SUBCOMMAND[event] ?? event;
-            const dispatch = spawnSync("bash", [agentHook, subcommand, "--harness", harnessFlag], {
+            const dispatch = spawnSync("bash", [agentHook, subcommand, "--adapter", adapterFlag], {
                 cwd: sandbox,
                 encoding: "utf8",
                 input: JSON.stringify(payloadObj),
@@ -2757,8 +2830,8 @@ function replayHarnessSamples(harness, root, relativeSampleDir, filter) {
                 env: {
                     ...process.env,
                     HARNERY_COORD_ROOT_OVERRIDE: sandbox,
-                    HARNERY_AGENT_COORD_HARNESS: harness,
-                    HARNERY_AGENT_COORD_PLATFORM: harness,
+                    HARNERY_AGENT_COORD_ADAPTER: adapter,
+                    HARNERY_AGENT_COORD_PLATFORM: adapter,
                     HARNERY_AGENT_COORD_OFF: "0",
                 },
             });
@@ -2893,8 +2966,8 @@ function runPing(name, message, opts) {
         peer_instance_id: peerOwner,
         from: fromName,
         body,
-        scratch_path: doc.path,
-        scratch_bytes: doc.bytes,
+        journal_path: doc.path,
+        journal_bytes: doc.bytes,
     };
     if (opts.json) {
         emit.config({ format: "json" });
@@ -3024,6 +3097,41 @@ function runHeal(opts) {
         process.exit(1);
     }
     const action = kind === "pidmap" ? "heal-pidmap" : kind === "heartbeat" ? "heal-heartbeat" : "kill-heartbeat";
+    // Refuse to mint a heartbeat at a TRUNCATED owner id.
+    //
+    // Heartbeats are keyed by the whole instance_id, so healing at an
+    // abbreviated id writes `.harnery/active/<prefix>.json` while every reader
+    // (`status`, `set-task`, `whoami`) resolves `<instance_id>.json`. The heal
+    // reports success, the session stays broken, and an orphan file is left
+    // behind that the singleton fallback can then mis-resolve other callers to.
+    //
+    // A distinct instance_id (subagent, workflow child) is never a prefix of its
+    // own session_id, so a strict prefix is unambiguously an abbreviated id
+    // rather than a legitimately different owner. Only guard the create path: an
+    // existing heartbeat at `owner` means the id is real, whatever its shape.
+    //
+    // Two sources for the canonical id, because the reported failure arrives
+    // without `--session-id`: someone copies a truncated id out of a diagnostic
+    // and passes it as `--owner` alone. Comparing against `--session-id` alone
+    // therefore misses the exact path that produced the orphan; a live heartbeat
+    // whose instance_id this id is a prefix of settles it just as well, and is
+    // present in precisely the case that matters (the session the reader was
+    // trying to heal is registered, just not under the abbreviated name).
+    if (kind === "heartbeat" && !readHeartbeat(owner)) {
+        const canonical = opts.sessionId && opts.sessionId.trim() !== owner && opts.sessionId.trim().startsWith(owner)
+            ? opts.sessionId.trim()
+            : liveIdWithPrefix(root, owner);
+        if (canonical) {
+            const source = opts.sessionId?.trim() === canonical ? "--session-id" : "a live heartbeat";
+            emit.error({
+                code: "truncated_owner",
+                message: `--owner ${owner} is a prefix of ${canonical} (${source}), and no heartbeat exists ` +
+                    `at .harnery/active/${owner}.json. Healing here would create a heartbeat no reader ` +
+                    `resolves. Re-run with --owner ${canonical}.`,
+            });
+            process.exit(1);
+        }
+    }
     // Build positional args. agent-coord's arg layout:
     //   heal-pidmap <instance_id> [<pid>]
     //   heal-heartbeat <instance_id> [<session_id>]
@@ -3034,8 +3142,8 @@ function runHeal(opts) {
     if (kind === "heartbeat" && opts.sessionId)
         helperArgs.push(opts.sessionId);
     // heal-pidmap / heal-heartbeat / kill-heartbeat are handled by the
-    // agent-coord binary at harnery/bin/agent-coord.
-    const helper = `${root}/harnery/bin/agent-coord`;
+    // bundled agent-coord binary.
+    const helper = agentCoordOrExit(root);
     const proc = spawnSync(helper, helperArgs, {
         encoding: "utf8",
         ...coordHelperOpts(root),
@@ -3043,7 +3151,7 @@ function runHeal(opts) {
     if (proc.status !== 0) {
         emit.error({
             code: "heal_failed",
-            message: proc.stderr?.trim() || `agent-coord ${action} exited non-zero`,
+            message: spawnFailureMessage(proc, `agent-coord ${action}`),
         });
         process.exit(1);
     }
@@ -3078,7 +3186,10 @@ function runHeal(opts) {
         ],
         meta: {
             kind,
-            helper: "harnery/bin/agent-coord",
+            // The path actually spawned, not a guess at the layout: the helper is
+            // resolved from harnery's own package location, which differs between a
+            // submodule, an installed dependency, and a standalone checkout.
+            helper,
         },
     });
     if (!opts.json) {
@@ -3109,7 +3220,7 @@ function emitCouncilStateEvent(type, manifest, extraData) {
         type,
         owner: myOwner,
         session: hb?.session_id ?? myOwner,
-        harness: normalizeHarness(hb?.platform),
+        adapter: normalizeAdapter(hb?.platform),
         data: { council_id: manifest.council_id, ...extraData },
     });
 }
@@ -3214,7 +3325,7 @@ function runCouncilCreate(objective, opts) {
             type: "council.open",
             owner: myOwner,
             session: myHbForEmit?.session_id ?? myOwner,
-            harness: normalizeHarness(myHbForEmit?.platform),
+            adapter: normalizeAdapter(myHbForEmit?.platform),
             data: {
                 council_id: councilId,
                 topic: trimmedObjective,
@@ -3223,7 +3334,7 @@ function runCouncilCreate(objective, opts) {
             },
         });
     }
-    // Best-effort: ping each currently-active member's scratchpad with a
+    // Best-effort: ping each currently-active member's journal with a
     // handoff entry pointing them at the council. Members not currently active
     // get nothing here; the Phase 2 SessionStart adapter will surface the
     // invite on their next session.
@@ -3646,7 +3757,7 @@ function runCouncilSetSteward(id, stewardArg, opts) {
                 const known_names = known.map((a) => a.name).join(", ") || "(none)";
                 emit.error({
                     code: "steward_not_known",
-                    message: `'${steward}' is not a known agent (active heartbeats + scratchpads archived in the last 30 days). Pass --allow-unknown to bootstrap. Known: ${known_names}`,
+                    message: `'${steward}' is not a known agent (active heartbeats + journals archived in the last 30 days). Pass --allow-unknown to bootstrap. Known: ${known_names}`,
                 });
                 process.exit(1);
             }
@@ -3679,7 +3790,7 @@ function runCouncilSetSteward(id, stewardArg, opts) {
         emit.text(`council ${next.council_id} steward set to ${label}.\n`);
     }
 }
-/** Build a markdown transcript of every round's contributions on disk. */
+/** Build a markdown journal of every round's contributions on disk. */
 function buildTranscript(manifest) {
     const body = councilBodyDir(manifest.council_id);
     const out = [];
@@ -3749,7 +3860,7 @@ function runCouncilContribute(id, opts) {
     }
     // Resolve the contributor name. Two paths:
     // 1. --as <member> override: caller explicitly names the council seat. Used
-    //    for cross-harness councils where each reviewer agent has a different
+    //    for cross-adapter councils where each reviewer agent has a different
     //    auto-generated session name from a different name pool; they can
     //    contribute under a fixed seat name without renaming the session.
     // 2. Heartbeat-derived (default): resolve owner via ppid walk + read the
@@ -3792,7 +3903,7 @@ function runCouncilContribute(id, opts) {
         if (!myHb?.name) {
             emit.error({
                 code: "no_self_name",
-                message: `resolved owner ${myOwner.slice(0, 8)} has no name on heartbeat (pass --as <member> to override)`,
+                message: `resolved owner ${myOwner} has no name on heartbeat (pass --as <member> to override)`,
             });
             process.exit(1);
         }
@@ -3936,7 +4047,7 @@ function runCouncilPrompt(id, member, opts) {
         process.exit(1);
     }
     // Resolve caller identity (steward authority check). Same --as override
-    // shape as `contribute` for cross-harness scripting.
+    // shape as `contribute` for cross-adapter scripting.
     let callerName;
     let actualName = null;
     if (opts.as) {
@@ -4142,7 +4253,7 @@ function runCouncilAdvance(id, opts) {
  * Shared advance helper used by both `advance` and auto-advance from
  * `contribute`. Increments current_round, flips round_status back to open,
  * creates the new round directory, writes the manifest, and pings each
- * member's scratchpad with the advance notification.
+ * member's journal with the advance notification.
  */
 function advanceCouncil(manifest, force) {
     const nextRound = manifest.current_round + 1;
@@ -4156,7 +4267,7 @@ function advanceCouncil(manifest, force) {
     if (rd && !existsSync(rd))
         mkdirSync(rd, { recursive: true });
     writeManifest(next);
-    // Ping each member's scratchpad with the advance notification.
+    // Ping each member's journal with the advance notification.
     // (Convener already knows; we skip pinging them if they convened it from
     // their own session.)
     const myOwner = resolveOwner();
@@ -4172,7 +4283,7 @@ function advanceCouncil(manifest, force) {
             appendEntry(memberOwner, "handoff", `from council advance (${manifest.council_id}): round ${nextRound} is now open${force ? " (advanced with --force; some round-N members dropped)" : ""}. Run 'harn agents council show ${manifest.council_id}' to read prior round + 'harn agents council contribute ${manifest.council_id}' to weigh in.`);
         }
         catch {
-            /* best-effort; member scratchpad may not exist yet */
+            /* best-effort; member journal may not exist yet */
         }
     }
     return next;

package/dist/commands/artifacts.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export declare function registerArtifactsCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=artifacts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/commands/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAa1E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAmGN"}