harnery 0.42.0 → 0.44.0

package/src/commands/inbox.ts

@@ -1,18 +1,21 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import type { HarneryInboxService } from "../core/inbox/service.ts";
+import { watchInbox } from "../core/inbox/watcher.ts";
 
 export function registerInboxCommand(
   program: Command,
   emit: EmitContext,
   service?: HarneryInboxService,
+  defaultRecipient?: () => string,
 ): void {
   const inbox = program.command("inbox").description("Inspect private coordination inbox state");
   inbox
-    .command("list <recipient>")
+    .command("list [recipient]")
     .option("--json", "Emit stable JSON")
-    .action((recipient: string, options: { json?: boolean }) => {
+    .action((recipient: string | undefined, options: { json?: boolean }) => {
       run(emit, () => {
+        recipient = requireRecipient(recipient, defaultRecipient);
         const rows = requireInboxService(service)
           .pending(recipient)
           .map((record) => ({
@@ -22,6 +25,7 @@ export function registerInboxCommand(
             created_at: record.created_at,
             body_bytes: record.body_bytes,
             body: record.body,
+            state: "pending",
           }));
         if (options.json) {
           emit.config({ format: "json" });
@@ -41,6 +45,52 @@ export function registerInboxCommand(
         } else emit.rows([status as unknown as Record<string, unknown>]);
       });
     });
+  inbox
+    .command("watch [recipient]")
+    .description("Surface pending messages for this instance; poll history until timeout")
+    .option("--timeout <seconds>", "Stop after this many seconds", "60")
+    .option("--json", "Emit one JSON record per surfaced message")
+    .action(async (recipient: string | undefined, options: { json?: boolean; timeout: string }) => {
+      let controller: AbortController | undefined;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const instanceId = requireRecipient(recipient, defaultRecipient);
+        const inboxService = requireInboxService(service);
+        const seconds = Number(options.timeout);
+        if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 3600)
+          throw new Error("--timeout must be greater than 0 and at most 3600 seconds");
+        controller = new AbortController();
+        timer = setTimeout(() => controller!.abort(), seconds * 1000);
+        if (options.json) emit.config({ format: "json" });
+        for await (const message of watchInbox(inboxService, instanceId, {
+          signal: controller.signal,
+        })) {
+          const row = { ...message, state: "surfaced" };
+          if (options.json) emit.data(row);
+          else emit.rows([row]);
+          // An output error leaves this ID pending for prompt recovery.
+          await new Promise<void>((resolve, reject) =>
+            process.stdout.write("", (error) => (error ? reject(error) : resolve())),
+          );
+          inboxService.acknowledgeSurface(instanceId, [message.message_id]);
+        }
+      } catch (error) {
+        emit.error({
+          code: "inbox_failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        emit.setExitCode(1);
+      } finally {
+        if (timer) clearTimeout(timer);
+        controller?.abort();
+      }
+    });
+}
+
+function requireRecipient(recipient: string | undefined, fallback?: () => string): string {
+  const resolved = recipient ?? fallback?.();
+  if (!resolved) throw new Error("recipient instance is required outside an agent session");
+  return resolved;
 }
 
 function requireInboxService(service?: HarneryInboxService): HarneryInboxService {

package/src/commands/rm.ts

@@ -1,9 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
+import { artifactsRoot, parseArtifactManifest } from "../core/artifacts/index.ts";
 import {
   readCoordinationViewV3,
   requireAuthoritySafeCoordinationViewV3,
@@ -25,6 +26,15 @@ export function registerRmCommand(
       "Allowed directory; each target must be strictly inside it",
     )
     .option("-r, --recursive", "Permit directory removal after inspecting its complete contents")
+    .option(
+      "--clean-clone",
+      "Remove only clean standalone clones inside one owned artifact; refuse local-only commits and worktrees",
+    )
+    .option(
+      "--entry-limit <n>",
+      "Maximum inspected entries, 1-100000 (default 10000); larger limits require one current caller-owned managed artifact as --root",
+      (value: string) => Number(value),
+    )
     .option(
       "--allow-protected <path>",
       "Remove this one protected path (Git metadata, credentials, Harnery state, keys) inside a target; repeat per path",
@@ -65,7 +75,34 @@ export function registerRmCommand(
         const liveRoots = [coordRoot, gitTopLevel(process.cwd())].filter((dir): dir is string =>
           Boolean(dir),
         );
-        const report = guardedRemove(paths, { ...options, liveRoots }, checkClaims);
+        const assertOwnedArtifact = (root: string): void => {
+          if (!coordRoot || dirname(root) !== realpathSync(artifactsRoot(coordRoot)))
+            throw new Error("Copied state requires --root to name one owned managed artifact");
+          const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+          const owner = resolveOwner({ payload: null, coordRoot });
+          const ownId = owner ? liveInstanceIdV3(owner.instance_id) : undefined;
+          if (!ownId || !view.instances[ownId]?.authority_eligible)
+            throw new Error("Copied state requires an authenticated current artifact owner");
+          const record = resolve(root, ".harnery-artifact.json");
+          const stat = lstatSync(record);
+          if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error("An owned artifact requires a regular manifest file");
+          const parsed = parseArtifactManifest(JSON.parse(readFileSync(record, "utf8")));
+          if (
+            !parsed.ok ||
+            parsed.manifest.released_at ||
+            !parsed.manifest.created_by?.instance_id ||
+            liveInstanceIdV3(parsed.manifest.created_by.instance_id) !== ownId
+          )
+            throw new Error(
+              "Copied state requires a valid unreleased artifact owned by the caller",
+            );
+        };
+        const report = guardedRemove(
+          paths,
+          { ...options, liveRoots, assertOwnedArtifact },
+          checkClaims,
+        );
         if (options.json) {
           emit.config({ format: "json" });
           emit.data(report);
@@ -76,7 +113,9 @@ export function registerRmCommand(
           ];
           if (report.protected.length)
             lines.push(
-              "Protected paths named with --allow-protected:",
+              options.cleanClone
+                ? "Verified clone metadata:"
+                : "Protected paths named with --allow-protected:",
               ...report.protected.map((path) => `  ${path}`),
             );
           if (report.links.length)

package/src/commands/servers.ts

@@ -120,6 +120,7 @@ export function registerServersCommand(
                   type: "unregistered",
                   label: stray.command,
                   pid: stray.pid,
+                  ...(stray.start_token ? { start_token: stray.start_token } : {}),
                   host: hostname(),
                   started_at: new Date().toISOString(),
                   registered_at: new Date().toISOString(),
@@ -207,10 +208,20 @@ export function registerServersCommand(
             emit.config({ format: "json" });
             emit.data({ applied: Boolean(options.yes), pruned: report.pruned, decisions, results });
           } else {
-            const lines = decisions.map(
-              (d) =>
-                `${d.action === "stop" ? (options.yes ? "stopped" : "would stop") : "keep"}  ${d.id}  ${d.reason}`,
-            );
+            const lines = decisions.map((decision) => {
+              const result = results.find((item) => item.id === decision.id);
+              const action =
+                decision.action === "keep"
+                  ? "keep"
+                  : !options.yes
+                    ? "would stop"
+                    : result?.stopped
+                      ? "stopped"
+                      : result?.method === "not-running"
+                        ? "already stopped"
+                        : "could not stop";
+              return `${action}  ${decision.id}  ${result?.detail ?? decision.reason}`;
+            });
             if (report.pruned.length)
               lines.push(`Removed records of exited servers: ${report.pruned.join(", ")}`);
             if (!decisions.length) lines.push("No registered servers.");
@@ -218,6 +229,7 @@ export function registerServersCommand(
               lines.push("Preview only. Re-run with --yes to stop.");
             emit.text(lines.join("\n"));
           }
+          if (results.some((result) => result.method === "refused")) emit.setExitCode(1);
         } catch (error) {
           fail(error);
         }

package/src/commands/supervisor.ts

@@ -83,11 +83,16 @@ export function registerSupervisorCommand(
     .action(async (options: { root?: string }) => {
       try {
         const root = resolve(options.root ?? coordRoot(context));
-        let status = requestSupervisorStop(root);
+        const requested = requestSupervisorStop(root);
+        let status = requested;
         const deadline = Date.now() + 5_000;
         while (status.running && Date.now() < deadline) {
           await new Promise((done) => setTimeout(done, 50));
-          status = readSupervisorStatus(root);
+          status = {
+            ...readSupervisorStatus(root),
+            signal_sent: requested.signal_sent,
+            signal_verdict: requested.signal_verdict,
+          };
         }
         emit.data(status);
       } catch (error) {

package/src/commands/toc.ts

@@ -172,17 +172,25 @@ function renderToc(r: TocResult): string {
   return lines.join("\n");
 }
 
-async function runSection(file: string, query: string, opts: SectionOpts): Promise<SectionResult> {
+export async function runSection(
+  file: string,
+  query: string,
+  opts: SectionOpts,
+): Promise<SectionResult> {
   if (!query.trim()) throw new Error("header query required");
   const tocResult = await runToc(file, {});
   const absPath = resolve(file);
   const lines = readFileSync(absPath, "utf8").split("\n");
 
-  const matches = tocResult.headers.filter((h) =>
-    opts.caseSensitive
-      ? h.text.includes(query)
-      : h.text.toLowerCase().includes(query.toLowerCase()),
-  );
+  const same = (a: string, b: string) =>
+    opts.caseSensitive ? a === b : a.toLowerCase() === b.toLowerCase();
+  const contains = (a: string, b: string) =>
+    opts.caseSensitive ? a.includes(b) : a.toLowerCase().includes(b.toLowerCase());
+  // A header that equals the query wins over headers that merely contain it,
+  // so "Media" can still select "## Media" beside "## Media recipes".
+  const exact = tocResult.headers.filter((h) => same(h.text, query.trim()));
+  const matches =
+    exact.length > 0 ? exact : tocResult.headers.filter((h) => contains(h.text, query));
   if (matches.length === 0) {
     throw new Error(
       `no header matching "${query}". Run \`${resolveBinName()} toc ${file}\` to list available headers.`,