harnery 0.37.0 → 0.38.0

package/src/commands/agents.ts

@@ -56,6 +56,7 @@ import {
   queueMailboxMessage,
   suggestNames,
 } from "../core/agents/mailbox.ts";
+import { qaSignalStatusRow } from "../core/agents/qa-signal.ts";
 import { reconcileCoordinationV3 } from "../core/agents/reconcile-coordination-v3.ts";
 import {
   listSessionFinalizationRequestsV3,
@@ -91,7 +92,10 @@ import {
 } from "../core/config.ts";
 import type { EventTypeV3 } from "../core/events/v3/contract.ts";
 import { readEventV3ControlState } from "../core/events/v3/control.ts";
-import { projectCoordinationViewV3 } from "../core/events/v3/coordination-view.ts";
+import {
+  projectCoordinationViewV3,
+  readCoordinationViewV3,
+} from "../core/events/v3/coordination-view.ts";
 import { liveInstanceIdV3 } from "../core/events/v3/live-routing.ts";
 import {
   countSummarizedSinceV3,
@@ -2399,6 +2403,12 @@ function runStatus(opts: {
     /* non-fatal: status box should not fail on council errors */
   }
 
+  // Latest page-QA verdict for this session, with the RUNNER's clock. Session
+  // age is not QA time; without this row an operator reads "session 58m" as if
+  // the QA run took 58 minutes. Best-effort by contract — no pointer, a
+  // malformed one, or any read failure renders no row.
+  const qaSignal = qaSignalStatusRow({ coordRoot: root, instanceId: hb.instance_id });
+
   const data = {
     name: displayName,
     instance_id: hb.instance_id,
@@ -2436,6 +2446,7 @@ function runStatus(opts: {
     timestamp_iso: new Date().toISOString(),
     timestamp_local: timeStr,
     ...(quality ? { quality } : {}),
+    ...(qaSignal ? { qa: qaSignal.pointer } : {}),
     ...(finalization ? { finalization } : {}),
     ...(sessionEnd ? { session_end: sessionEnd } : {}),
   };
@@ -2474,6 +2485,10 @@ function runStatus(opts: {
     const idx = rows.findIndex((row) => row[0] === "time");
     rows.splice(idx, 0, ["quality", formatRunQuality(quality.status, quality.signal_ids)]);
   }
+  if (qaSignal) {
+    const idx = rows.findIndex((row) => row[0] === "time");
+    rows.splice(idx, 0, ["qa", qaSignal.value]);
+  }
   if (sessionEnd) {
     const idx = rows.findIndex((row) => row[0] === "time");
     rows.splice(idx, 0, [
@@ -3101,6 +3116,13 @@ export type EventLedgerHealthV3 =
         /** Times the summary gate failed open (loose write proceeded). */
         mitigation_fail_open: number;
       };
+      coordination_authority: {
+        safe: boolean;
+        global_diagnostics: number;
+        isolated_diagnostics: number;
+        affected_generations: string[];
+        codes: string[];
+      };
       span_pressure: Array<{ instance_id: string; generation_id: string; span_count: number }>;
       collection_errors: string[];
     };
@@ -3280,6 +3302,57 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
     collectionErrors.push(`diagnostic summaries unreadable: ${errorText(error)}`);
   }
 
+  let coordinationAuthority: Extract<
+    EventLedgerHealthV3,
+    { state: "live" }
+  >["coordination_authority"] = {
+    safe: false,
+    global_diagnostics: 0,
+    isolated_diagnostics: 0,
+    affected_generations: [],
+    codes: [],
+  };
+  try {
+    const view = readCoordinationViewV3(root);
+    const globalDiagnostics = view.global_diagnostics.filter(
+      (diagnostic) => diagnostic.authority_blocking,
+    );
+    const isolatedDiagnostics = new Map<string, (typeof globalDiagnostics)[number]>();
+    const affectedGenerations: string[] = [];
+    for (const [generationId, diagnostics] of Object.entries(view.diagnostics_by_generation)) {
+      const blocking = diagnostics.filter((diagnostic) => diagnostic.authority_blocking);
+      if (blocking.length === 0) continue;
+      affectedGenerations.push(generationId);
+      for (const diagnostic of blocking) {
+        isolatedDiagnostics.set(
+          [
+            diagnostic.code,
+            diagnostic.source_code ?? "",
+            diagnostic.event_id ?? "",
+            diagnostic.generation_id ?? "",
+            diagnostic.subject_instance_id ?? "",
+          ].join("\0"),
+          diagnostic,
+        );
+      }
+    }
+    coordinationAuthority = {
+      safe: view.authority_safe,
+      global_diagnostics: globalDiagnostics.length,
+      isolated_diagnostics: isolatedDiagnostics.size,
+      affected_generations: affectedGenerations.sort(),
+      codes: [
+        ...new Set(
+          [...globalDiagnostics, ...isolatedDiagnostics.values()].map(
+            (diagnostic) => diagnostic.source_code ?? diagnostic.code,
+          ),
+        ),
+      ].sort(),
+    };
+  } catch (error) {
+    collectionErrors.push(`coordination authority unreadable: ${errorText(error)}`);
+  }
+
   return {
     state: "live",
     mode: control.state,
@@ -3303,6 +3376,7 @@ export function collectEventLedgerHealthV3(root: string, nowMs = Date.now()): Ev
       recent_by_category: recentByCategory,
       mitigation_fail_open: mitigationFailOpen,
     },
+    coordination_authority: coordinationAuthority,
     span_pressure: spanPressure,
     collection_errors: collectionErrors,
   };
@@ -4058,6 +4132,17 @@ function runHealth(opts: { since: string; json?: boolean }): void {
     );
   }
   if (eventLedger.state === "live") {
+    const authority = eventLedger.coordination_authority;
+    if (authority.global_diagnostics > 0) {
+      findings.push(
+        `${authority.global_diagnostics} global coordination authority diagnostic(s): ${authority.codes.join(", ")}`,
+      );
+    }
+    if (authority.isolated_diagnostics > 0) {
+      findings.push(
+        `${authority.isolated_diagnostics} coordination authority diagnostic(s) isolated to ${authority.affected_generations.length} generation(s): ${authority.codes.join(", ")}`,
+      );
+    }
     // Open spans whose generation has no open turn: the turn ended without its
     // tool spans closing, so an explicit end can only queue, never finalize.
     const orphanGenerations = eventLedger.open_spans.generations.filter(
@@ -4198,6 +4283,7 @@ function renderHealthBox(report: HealthReport): void {
       )
       .join(", ");
     ledgerStr = [
+      `authority ${ledger.coordination_authority.safe ? "safe" : "unsafe"}${ledger.coordination_authority.isolated_diagnostics > 0 ? ` (${ledger.coordination_authority.isolated_diagnostics} isolated)` : ""}`,
       `open spans ${ledger.open_spans.total}${orphanGenerations > 0 ? ` (${orphanGenerations} gen turn-closed)` : ""}`,
       `pending ends ${ledger.pending_finalizations.length}${pendingAges ? ` (${pendingAges})` : ""}`,
       `intake ${ledger.intake_spool.total}`,

package/src/commands/artifacts.ts

@@ -5,12 +5,16 @@ import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-
 import {
   type ArtifactActor,
   adoptUnmanagedArtifactFiles,
+  artifactCapabilities,
   cleanArtifacts,
   createArtifact,
+  holdArtifact,
   inventoryArtifacts,
+  migrateArtifacts,
   releaseArtifact,
   renewArtifact,
   showArtifact,
+  unholdArtifact,
 } from "../core/artifacts/index.ts";
 import { artifactDefaultRetentionDays, coordFreshnessSeconds } from "../core/config.ts";
 
@@ -30,28 +34,47 @@ export function registerArtifactsCommand(
     .requiredOption("--purpose <text>", "What the files are for")
     .option("--days <n>", "Retention in days (default from artifacts.default_retention_days)")
     .option("--big", "Acknowledge that this workspace may exceed the per-bundle size ceiling")
-    .action((slug: string, opts: { purpose: string; days?: string; big?: boolean }) => {
-      run(emit, () => {
-        const repoRoot = requireRepoRoot(context);
-        const actor = currentActor(repoRoot);
-        const retentionDays = opts.days
-          ? parseDays(opts.days)
-          : artifactDefaultRetentionDays(repoRoot);
-        const created = createArtifact(repoRoot, {
-          slug,
-          purpose: opts.purpose,
-          retentionDays,
-          actor,
-          big: opts.big,
-        });
-        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,
+    .option("--hold <id>", "Create the workspace with this hold already present")
+    .option("--hold-reason <text>", "Why the initial hold is required")
+    .option("--actor <instance-id>", "Stable owner identity for the initial hold")
+    .action(
+      (
+        slug: string,
+        opts: {
+          purpose: string;
+          days?: string;
+          big?: boolean;
+          hold?: string;
+          holdReason?: string;
+          actor?: string;
+        },
+      ) => {
+        run(emit, () => {
+          const repoRoot = requireRepoRoot(context);
+          const actor = opts.actor ? { instance_id: opts.actor } : currentActor(repoRoot);
+          if (!!opts.hold !== !!opts.holdReason)
+            throw new Error("--hold and --hold-reason must be used together");
+          const retentionDays = opts.days
+            ? parseDays(opts.days)
+            : artifactDefaultRetentionDays(repoRoot);
+          const created = createArtifact(repoRoot, {
+            slug,
+            purpose: opts.purpose,
+            retentionDays,
+            actor,
+            big: opts.big,
+            holds: opts.hold ? [{ id: opts.hold, reason: opts.holdReason! }] : [],
+          });
+          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,
+            holds: created.manifest.holds,
+          });
         });
-      });
-    });
+      },
+    );
 
   root
     .command("adopt-unmanaged")
@@ -133,6 +156,53 @@ export function registerArtifactsCommand(
       });
     });
 
+  root
+    .command("capabilities")
+    .description("Report artifact schema and hold capabilities for embedding clients.")
+    .option("--json", "Emit the capability document as JSON")
+    .action(() => emit.data(artifactCapabilities()));
+
+  root
+    .command("migrate")
+    .description("Preview the explicit v1 to v2 manifest migration, preserving preimages.")
+    .option("--yes", "Apply the migration to valid v1 manifests")
+    .action((opts: { yes?: boolean }) =>
+      run(emit, () => emit.data({ rows: migrateArtifacts(requireRepoRoot(context), opts) })),
+    );
+
+  root
+    .command("hold <ref>")
+    .description("Protect an artifact from cleanup until its owner removes this exact hold.")
+    .requiredOption("--id <id>", "Unique hold id within this artifact")
+    .requiredOption("--reason <text>", "Why cleanup must retain these files")
+    .option("--actor <instance-id>", "Stable hold owner; defaults to the current agent")
+    .action((ref: string, opts: { id: string; reason: string; actor?: string }) =>
+      run(emit, () => {
+        const repoRoot = requireRepoRoot(context);
+        emit.data(
+          holdArtifact(repoRoot, ref, {
+            id: opts.id,
+            reason: opts.reason,
+            actor: requireHoldActor(repoRoot, opts.actor),
+          }),
+        );
+      }),
+    );
+
+  root
+    .command("unhold <ref>")
+    .description("Remove one exact hold belonging to the supplied owner.")
+    .requiredOption("--id <id>", "Exact hold id to remove")
+    .option("--actor <instance-id>", "Stable hold owner; defaults to the current agent")
+    .action((ref: string, opts: { id: string; actor?: string }) =>
+      run(emit, () => {
+        const repoRoot = requireRepoRoot(context);
+        emit.data(
+          unholdArtifact(repoRoot, ref, opts.id, { actor: requireHoldActor(repoRoot, opts.actor) }),
+        );
+      }),
+    );
+
   root
     .command("clean")
     .description("Preview expired artifact deletion; pass --yes to delete.")
@@ -149,6 +219,12 @@ export function registerArtifactsCommand(
     });
 }
 
+function requireHoldActor(repoRoot: string, explicit?: string): ArtifactActor {
+  const actor = explicit ? { instance_id: explicit } : currentActor(repoRoot);
+  if (!actor) throw new Error("hold operations require --actor or a current agent identity");
+  return actor;
+}
+
 function currentActor(repoRoot: string): ArtifactActor | undefined {
   const instanceId = resolveOwner();
   if (!instanceId) return undefined;

package/src/commands/browse-ai.ts

@@ -1,9 +1,9 @@
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import type { Command } from "commander";
-import type { EmitContext } from "../commander.ts";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { AgentBrowser, type ExecResult } from "../lib/agent-browser/index.ts";
-import { CookieJar } from "../lib/cookies/index.ts";
+import { applyExtraCookies, CookieJar } from "../lib/cookies/index.ts";
 
 // Module-scoped emit assigned by registerBrowseAiCommand. Same pattern as
 // cookies/read/browse: helper functions close over `emit` so action
@@ -50,7 +50,11 @@ interface BrowseAiOpts {
   timeout: string;
 }
 
-export function registerBrowseAiCommand(program: Command, emitParam: EmitContext): void {
+export function registerBrowseAiCommand(
+  program: Command,
+  emitParam: EmitContext,
+  context?: HarneryProgramContext,
+): void {
   emit = emitParam;
   program
     .command("browse-ai <url>")
@@ -86,7 +90,7 @@ export function registerBrowseAiCommand(program: Command, emitParam: EmitContext
     .option("--timeout <ms>", "Per-step timeout in ms", "60000")
     .action((url: string, opts: BrowseAiOpts) => {
       try {
-        runBrowseAi(url, opts);
+        runBrowseAi(url, opts, context);
       } catch (err: unknown) {
         const msg = err instanceof Error ? err.message : String(err);
         emit.error({ code: "browse_ai_error", message: msg });
@@ -95,11 +99,12 @@ export function registerBrowseAiCommand(program: Command, emitParam: EmitContext
     });
 }
 
-function runBrowseAi(url: string, opts: BrowseAiOpts): void {
+function runBrowseAi(url: string, opts: BrowseAiOpts, context?: HarneryProgramContext): void {
   const jar =
     opts.cookies === false
       ? null
       : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-browse-ai" });
+  if (jar) applyExtraCookies(url, jar, context?.extraCookies);
   const ab = new AgentBrowser({
     jar,
     timeoutMs: Number.parseInt(opts.timeout, 10),