harnery 0.29.0 → 0.31.0

package/dist/commands/agents.js

@@ -17,15 +17,16 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync,
 import { homedir, tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 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";
@@ -63,11 +64,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 +99,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 +156,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 +196,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 +228,6 @@ export function registerAgentsCommand(program, emitParam) {
         .action((opts) => {
         runHeal(opts);
     });
-    registerCouncilCommands(cmd);
     registerIdentityCommands(cmd);
 }
 function registerIdentityCommands(parent) {
@@ -368,7 +369,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 +454,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 +468,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")
@@ -1023,7 +1024,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",
@@ -1122,11 +1123,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;
@@ -1254,7 +1255,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 +1722,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 +1751,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 +2509,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 +2528,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 +2574,7 @@ function runHarnessProbe(id, opts) {
         walkPid = ppid;
     }
     const data = {
-        harness,
+        adapter,
         anchor_pid: anchorPid,
         hook_pid: String(process.pid),
         resolved_owner: resolveOwner() ?? "",
@@ -2581,13 +2582,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 +2597,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 +2637,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 +2653,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 +2674,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 +2712,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 +2750,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 +2758,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 +2894,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" });
@@ -3109,7 +3110,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 +3215,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 +3224,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 +3647,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 +3680,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 +3750,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
@@ -3936,7 +3937,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 +4143,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 +4157,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 +4173,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"}

package/dist/commands/artifacts.js

@@ -0,0 +1,143 @@
+import { monorepoRoot, readHeartbeat, resolveOwner } from "../core/agents/index.js";
+import { cleanArtifacts, createArtifact, inventoryArtifacts, releaseArtifact, renewArtifact, showArtifact, } from "../core/artifacts/index.js";
+import { artifactDefaultRetentionDays, coordFreshnessSeconds } from "../core/config.js";
+export function registerArtifactsCommand(program, emit, context) {
+    const root = program
+        .command("artifacts")
+        .alias("artifact")
+        .description("Manage repository-local working artifacts under .harnery/artifacts/");
+    root
+        .command("create <slug>")
+        .description("Create one managed artifact workspace and print its path.")
+        .requiredOption("--purpose <text>", "What the files are for")
+        .option("--days <n>", "Retention in days (default from artifacts.default_retention_days)")
+        .action((slug, opts) => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            const actor = currentActor();
+            const retentionDays = opts.days
+                ? parseDays(opts.days)
+                : artifactDefaultRetentionDays(repoRoot);
+            const created = createArtifact(repoRoot, {
+                slug,
+                purpose: opts.purpose,
+                retentionDays,
+                actor,
+            });
+            emit.data({
+                path: created.path,
+                artifact_id: created.manifest.artifact_id,
+                expires_at: created.manifest.retention.expires_at,
+                owner_instance_id: actor?.instance_id ?? null,
+            });
+        });
+    });
+    root
+        .command("list")
+        .description("Inventory every artifact workspace with its cleanup classification.")
+        .action(() => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            const rows = inventoryArtifacts(repoRoot, {
+                freshnessSeconds: coordFreshnessSeconds(repoRoot),
+            });
+            emit.data({ rows, meta: summarize(rows) });
+        });
+    });
+    root
+        .command("show <ref>")
+        .description("Show one artifact by id, directory name, or direct-child path.")
+        .action((ref) => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            emit.data(showArtifact(repoRoot, ref, {
+                freshnessSeconds: coordFreshnessSeconds(repoRoot),
+            }));
+        });
+    });
+    root
+        .command("renew <ref>")
+        .description("Set a new retention window. Renewal does not mark the artifact active.")
+        .requiredOption("--days <n>", "Days from now")
+        .requiredOption("--reason <text>", "Why the extra retention is needed")
+        .action((ref, opts) => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            const manifest = renewArtifact(repoRoot, ref, parseDays(opts.days), opts.reason, {
+                actor: currentActor(),
+            });
+            emit.data(manifest);
+        });
+    });
+    root
+        .command("release <ref>")
+        .description("Release active-owner protection without shortening retention.")
+        .action((ref) => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            emit.data(releaseArtifact(repoRoot, ref, { actor: currentActor() }));
+        });
+    });
+    root
+        .command("clean")
+        .description("Preview expired artifact deletion; pass --yes to delete.")
+        .option("--yes", "Permanently delete entries classified managed-expired")
+        .action((opts) => {
+        run(emit, () => {
+            const repoRoot = requireRepoRoot(context);
+            const rows = cleanArtifacts(repoRoot, {
+                yes: opts.yes,
+                freshnessSeconds: coordFreshnessSeconds(repoRoot),
+            });
+            emit.data({ rows, meta: summarize(rows) });
+        });
+    });
+}
+function currentActor() {
+    const instanceId = resolveOwner();
+    if (!instanceId)
+        return undefined;
+    const hb = readHeartbeat(instanceId);
+    return {
+        instance_id: instanceId,
+        session_id: hb?.session_id,
+        name: hb?.name,
+    };
+}
+function requireRepoRoot(context) {
+    const root = context?.repoRoot ?? monorepoRoot();
+    if (!root)
+        throw new Error("not inside a Git repository");
+    return root;
+}
+function parseDays(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 3650) {
+        throw new Error("--days must be between 1 and 3650");
+    }
+    return parsed;
+}
+function summarize(rows) {
+    const classifications = {};
+    for (const row of rows) {
+        classifications[row.classification] = (classifications[row.classification] ?? 0) + 1;
+    }
+    return {
+        total: rows.length,
+        classifications,
+        would_delete: rows.filter((row) => row.action === "would-delete").length,
+        deleted: rows.filter((row) => row.action === "deleted").length,
+    };
+}
+function run(emit, fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        emit.error({
+            code: "artifact_failed",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        emit.setExitCode(1);
+    }
+}

package/dist/commands/backup.d.ts

@@ -6,7 +6,7 @@
  * paths and are init'd on first `harn backup init`. Subcommands:
  *
  *   init      restic init the repo (one-time)
- *   snapshot  restic backup .harnery/
+ *   snapshot  restic backup .harnery/ (working artifacts excluded)
  *   list      restic snapshots
  *   restore   restic restore <id>
  *   prune     restic forget --keep-daily 7 --keep-weekly 4 --prune

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

@@ -1 +1 @@
-{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA4EnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAuM/E"}
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA4EnD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAqN/E"}

package/dist/commands/backup.js

@@ -6,7 +6,7 @@
  * paths and are init'd on first `harn backup init`. Subcommands:
  *
  *   init      restic init the repo (one-time)
- *   snapshot  restic backup .harnery/
+ *   snapshot  restic backup .harnery/ (working artifacts excluded)
  *   list      restic snapshots
  *   restore   restic restore <id>
  *   prune     restic forget --keep-daily 7 --keep-weekly 4 --prune
@@ -109,12 +109,13 @@ export function registerBackupCommand(program, emit) {
     backup
         .command("snapshot")
         .description("Take a restic snapshot of .harnery/ (excluding events.ndjson and " +
-        ".lock files by default). Pass --target to back up a different path.")
+        ".lock files and artifacts/ by default). Pass --target to back up a different path.")
         .option("--target <path>", "Path to snapshot (default: .harnery/ from cwd walk-up)")
         .option("--tag <tag>", "Restic tag (repeatable)", collect, [])
         .option("--repo <path>", "Repository path")
         .option("--password-file <path>", "Password file")
         .option("--include-events", "Don't exclude events.ndjson (default: excluded; large + machine-local)")
+        .option("--include-artifacts", "Include managed working artifacts (default: excluded; potentially large + ephemeral)")
         .action((opts) => {
         if (!checkRestic(emit)) {
             emit.setExitCode(1);
@@ -135,6 +136,8 @@ export function registerBackupCommand(program, emit) {
             passThrough.push("--exclude", ".lock");
             passThrough.push("--exclude", ".log.lock");
         }
+        if (!opts.includeArtifacts)
+            passThrough.push("--exclude", "artifacts");
         for (const t of opts.tag) {
             passThrough.push("--tag", t);
         }

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

@@ -1 +1 @@
-{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiJ1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAiQN"}
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAuL1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAoWN"}