harnery 0.43.0 → 0.45.0

package/src/commands/browse.ts

@@ -134,6 +134,7 @@ import {
 import {
   harvestDomain,
   harvestWindowsChromeCookies,
+  keepWindowsChromeSession,
   stopWindowsChromeProfile,
   windowsChromePath,
   windowsLocalAppData,
@@ -3465,15 +3466,18 @@ function useWindowsPlainLogin(): boolean {
 
 /**
  * The WSL form of `--login`: the person signs in through the Windows
- * Chrome on a dedicated Windows profile with nothing attached. When the window
- * closes, the profile's cookies for the sign-in site are read and merged into
- * the shared cookie store, which later `browse` runs attach.
+ * Chrome on a dedicated Windows profile with nothing attached. Before the
+ * window opens, the profile is set to continue where it left off, so Chrome
+ * keeps browser-session cookies when the window closes. When the window
+ * closes, the profile's cookies for the sign-in site are read and merged
+ * into the shared cookie store, which later `browse` runs attach, and the
+ * last page open on that site is reported so an agent can resume from it.
  */
 async function runWindowsPlainLogin(
   url: string,
   storePath: string,
   loginCloseFile: string | null,
-  emit: { log: (message: string, level: "info" | "warn" | "error" | "debug") => void },
+  emit: Pick<EmitContext, "log" | "data">,
 ): Promise<void> {
   const chromeLinux = windowsChromePath();
   const localAppData = windowsLocalAppData();
@@ -3484,6 +3488,13 @@ async function runWindowsPlainLogin(
   }
   const chromeWindows = wslPathToWindows(chromeLinux);
   const profileWindows = windowsPlainProfile(localAppData);
+  const keep = keepWindowsChromeSession({ chromeWindows, profileWindows });
+  if (!keep.kept) {
+    emit.log(
+      "[--login] Could not set the sign-in profile to keep browser-session cookies. A sign-in that relies on them survives only if you end it from the terminal instead of closing the window.",
+      "warn",
+    );
+  }
   const child = spawn(
     chromeLinux,
     [`--user-data-dir=${profileWindows}`, "--no-first-run", "--no-default-browser-check", url],
@@ -3507,24 +3518,49 @@ async function runWindowsPlainLogin(
   );
   await Promise.race(waits);
   lifecycleAbort.abort();
-  stopWindowsChromeProfile(profileWindows);
+  const stop = stopWindowsChromeProfile(profileWindows);
+  if (stop.forced > 0) {
+    emit.log(
+      "[--login] Chrome did not close when asked and was stopped. Cookies set in its last 30 seconds may be missing; run the sign-in again if later pages are signed out.",
+      "warn",
+    );
+  }
   await Promise.race([exited, new Promise((r) => setTimeout(r, 5000))]);
   const domain = harvestDomain(url);
-  const cookies = harvestWindowsChromeCookies({ chromeWindows, profileWindows, domain });
+  const { cookies, pages } = harvestWindowsChromeCookies({ chromeWindows, profileWindows, domain });
+  const lastPage = pages[0] ?? null;
+  const names = [...new Set(cookies.map((cookie) => cookie.name))].sort();
+  const sessionCookies = cookies.filter((cookie) => cookie.expires <= 0).length;
   if (cookies.length === 0) {
     emit.log(
       `[--login] No ${domain} cookies were found in the Windows profile; the sign-in may not have completed.`,
       "warn",
     );
-    return;
+  } else {
+    const jar = new CookieJar({ path: storePath, source: "harn-browse" });
+    jar.save(mergeCookies(jar.load(), cookies));
+    emit.log(
+      `[--login] Copied ${cookies.length} ${domain} cookies (${sessionCookies} browser-session) into ${storePath}: ${names.join(", ")}.`,
+      "info",
+    );
   }
-  const jar = new CookieJar({ path: storePath, source: "harn-browse" });
-  jar.save(mergeCookies(jar.load(), cookies));
-  const names = [...new Set(cookies.map((cookie) => cookie.name))].sort().join(", ");
-  emit.log(
-    `[--login] Copied ${cookies.length} ${domain} cookies into ${storePath}: ${names}.`,
-    "info",
-  );
+  if (lastPage) {
+    emit.log(
+      `[--login] Last page: ${lastPage} (the last page you had open on ${domain}; open it to continue where the sign-in left off, since its address may carry a sign-in token that cookies alone do not replace).`,
+      "info",
+    );
+  }
+  emit.data({
+    login: {
+      domain,
+      store: storePath,
+      cookies: cookies.length,
+      sessionCookies,
+      names,
+      lastPage,
+      pages,
+    },
+  });
 }
 
 async function waitForLoginCloseFile(path: string, signal?: AbortSignal): Promise<void> {

package/src/commands/diagnostics.ts

@@ -50,6 +50,7 @@ export function registerDiagnosticsCommand(
           findings,
           bundles,
           capability,
+          supervisor: readSupervisorStatus(repoRoot),
           total_findings: findings.length,
           total_bundles: bundles.length,
         });
@@ -68,6 +69,7 @@ export function registerDiagnosticsCommand(
             schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
             kind: "diagnostic_finding",
             finding,
+            supervisor: readSupervisorStatus(repoRoot),
             timeline:
               readSupervisorTimeline(repoRoot, finding.id) ?? buildSupervisorTimeline(finding),
             explanation:
@@ -118,6 +120,7 @@ export function registerDiagnosticsCommand(
           schema_version: DIAGNOSTIC_COMMAND_SCHEMA_VERSION,
           kind: "diagnostic_advice",
           source: { mode: "live" },
+          supervisor: readSupervisorStatus(repoRoot),
           advice: buildDiagnosticAdvice({
             assessment: published.assessment,
             priorHysteresis: published.prior_hysteresis,
@@ -204,6 +207,13 @@ function liveFindingsCapability(repoRoot: string, reportPresent: boolean): Super
   }
   const status = readSupervisorStatus(repoRoot);
   if (status.running) return { source_kind: "supervisor.findings", state: "supported" };
+  if (status.liveness === "unknown")
+    return {
+      source_kind: "supervisor.findings",
+      state: "error",
+      reason_code: "supervisor_generation_unknown",
+      detail: status.build_status,
+    };
   return {
     source_kind: "supervisor.findings",
     state: "expired",

package/src/commands/doctor.ts

@@ -421,15 +421,34 @@ function checkWorkflowAdapter(adapter: AdapterName): { check: Check; installed:
 }
 
 function checkNode(): Check {
-  const v = process.versions.node;
+  return nodeCheck(whichVersion("node"), process.versions);
+}
+
+/**
+ * Report the `node` on PATH, which is what Node-based tools run. Under Bun,
+ * `process.versions.node` is the Node version Bun emulates, not an installed
+ * Node, so it is used only when doctor itself runs on Node and PATH has none.
+ */
+export function nodeCheck(
+  onPath: { ok: boolean; out: string },
+  runtime: { node: string; bun?: string },
+): Check {
+  const hint = "https://nodejs.org/en/download";
+  let v = onPath.ok ? onPath.out.replace(/^v/, "") : "";
+  if (!v) {
+    if (runtime.bun) {
+      return {
+        name: "node",
+        severity: "warn",
+        detail: "not on PATH (Bun runs harnery; Node-based tools need it)",
+        hint,
+      };
+    }
+    v = runtime.node;
+  }
   const major = Number.parseInt(v.split(".")[0], 10);
   if (Number.isNaN(major) || major < 20) {
-    return {
-      name: "node",
-      severity: "fail",
-      detail: `${v} (need ≥ 20)`,
-      hint: "https://nodejs.org/en/download",
-    };
+    return { name: "node", severity: "fail", detail: `${v} (need ≥ 20)`, hint };
   }
   return { name: "node", severity: "ok", detail: v };
 }

package/src/commands/files.ts

@@ -4,6 +4,7 @@ import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
+import { createTunnelReadinessVerifier } from "../core/servers/index.ts";
 import { coordRootId, localCoordRootIdUrl } from "../lib/coord-root-id.ts";
 import {
   encodedRepoPath,
@@ -14,10 +15,10 @@ import {
 } from "../lib/local-file-url.ts";
 import { isPathAllowed } from "../lib/tunnel/path-scope.ts";
 import {
-  isTunnelStateLive,
   listStates,
-  type ProcessAliveCheck,
+  type TunnelReadinessVerifier,
   type TunnelState,
+  tunnelReadiness,
   tunnelTargetPort,
 } from "../lib/tunnel/state.ts";
 
@@ -208,10 +209,10 @@ export function tunnelFileUrl(
   local: LocalFileUrl,
   port: number,
   states: TunnelState[],
-  processAlive?: ProcessAliveCheck,
+  verifier: TunnelReadinessVerifier,
 ): string {
   const live = states.filter(
-    (state) => tunnelTargetPort(state) === port && isTunnelStateLive(state, processAlive),
+    (state) => tunnelTargetPort(state) === port && tunnelReadiness(state, verifier) === "ready",
   );
   if (local.mode === "raw") {
     const path = `/${encodedRepoPath(local.relPath)}`;
@@ -309,7 +310,14 @@ export function registerFilesCommand(
             mode: opts.raw ? "raw" : opts.viewer ? "viewer" : "auto",
           });
           if (opts.verify !== false) await verifyDashboardRoot(coordRoot, port);
-          const url = opts.tunnel ? tunnelFileUrl(result, port, listStates(coordRoot)) : result.url;
+          const url = opts.tunnel
+            ? tunnelFileUrl(
+                result,
+                port,
+                listStates(coordRoot),
+                createTunnelReadinessVerifier({ coordRoot }),
+              )
+            : result.url;
           emit.text(`${url}\n`);
         } catch (error) {
           if (error instanceof TunnelLinkError) {

package/src/commands/governor.ts

@@ -385,12 +385,13 @@ function registerServiceCommand(
     .action(async (opts: { json?: boolean }) => {
       await withGovernorRootAsync(emit, async (coordRoot) => {
         let status = requestGovernorServiceStop(coordRoot);
+        const signal = { signal_sent: status.signal_sent, signal_verdict: status.signal_verdict };
         const deadline = Date.now() + 5_000;
         while (status.running && Date.now() < deadline) {
           await delay(50);
           status = readGovernorServiceStatus(coordRoot);
         }
-        emitServiceStatus(status, opts.json, emit);
+        emitServiceStatus({ ...status, ...signal }, opts.json, emit);
       });
     });
 
@@ -534,19 +535,31 @@ function emitServiceStatus(
     emit.data(status);
     return;
   }
-  if (!status.config && !status.record) {
-    emit.text("governor service: unconfigured\n");
-    return;
-  }
-  const state = status.running
-    ? (status.record?.state ?? "running")
-    : status.stale
-      ? "stale"
-      : "stopped";
+  const state =
+    status.liveness === "unknown"
+      ? "unknown"
+      : !status.config && !status.record
+        ? "unconfigured"
+        : status.running
+          ? (status.record?.state ?? "running")
+          : status.stale
+            ? "stale"
+            : "stopped";
   const lines = [
     `governor service: ${state}`,
+    `generation: ${status.generation}`,
+    `liveness: ${status.liveness}`,
+    `running build: ${status.running_build ? `${status.running_build.version} (${status.running_build.revision})` : "unknown"}`,
+    `installed build: ${status.installed_build.version} (${status.installed_build.revision})`,
+    `build: ${status.build_status}`,
     `goals: ${status.config?.goal_ids.join(", ") || "none"}`,
   ];
+  if (status.signal_sent !== undefined) {
+    lines.push(`signal sent: ${status.signal_sent ? "yes" : "no"} (${status.signal_verdict})`);
+    if (!status.signal_sent && status.record?.state !== "stopped") {
+      lines.push("The durable stop request remains for the service to read.");
+    }
+  }
   if (status.record) {
     lines.push(`pid: ${status.record.pid} on ${status.record.host}`);
     lines.push(`heartbeat: ${status.record.heartbeat_at}`);

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

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { hostname } from "node:os";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
@@ -111,22 +110,13 @@ export function registerServersCommand(
           const preview = Boolean(options.type) && !options.yes;
           const results: Array<StopResult | { id: string; would_stop: true }> = [];
           for (const stray of strays) {
-            results.push(
-              await stopServer(
-                {
-                  schema_version: 1,
-                  id: `pid-${stray.pid}`,
-                  kind: "session",
-                  type: "unregistered",
-                  label: stray.command,
-                  pid: stray.pid,
-                  host: hostname(),
-                  started_at: new Date().toISOString(),
-                  registered_at: new Date().toISOString(),
-                },
-                { coordRoot },
-              ),
-            );
+            const receipt = adoptServer(stray.pid, {
+              coordRoot,
+              type: "unregistered",
+              owner: "none",
+              dependencies: { listServers: () => report },
+            });
+            results.push(await stopServer(receipt, { coordRoot }));
           }
           for (const view of selected) {
             if (preview && !ids.includes(view.record.id))
@@ -207,10 +197,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 +218,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);
         }
@@ -396,14 +397,14 @@ export function registerServersCommand(
 
   cmd
     .command("unregister <id>")
-    .description("Remove a server's record (with --pid, only if the record still names that pid)")
+    .description("Remove the exact observed server registration (optionally require --pid)")
     .option("--pid <pid>", "Only remove when the record names this pid")
     .action((id: string, options: { pid?: string }) => {
       try {
-        const removed = unregisterServer(id, {
-          coordRoot: root(),
-          ...(options.pid ? { pid: integer(options.pid, "--pid") } : {}),
-        });
+        const coordRoot = root();
+        const record = readServer(id, { coordRoot });
+        const matchesPid = !options.pid || record?.pid === integer(options.pid, "--pid");
+        const removed = !!record && matchesPid && unregisterServer(record, { coordRoot });
         emit.config({ format: "json" });
         emit.data({ id, removed });
       } catch (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.`,