harnery 0.40.0 → 0.42.0

package/src/commands/artifacts.ts

@@ -6,9 +6,13 @@ import {
   type ArtifactActor,
   type ArtifactDeliveryManifest,
   adoptUnmanagedArtifactFiles,
+  allowBigArtifact,
   artifactCapabilities,
+  artifactQuickUsage,
   artifactReviewGuidance,
   artifactsRoot,
+  artifactUsageReport,
+  assertArtifactDiskFloor,
   autoCleanArtifacts,
   cleanArtifacts,
   createArtifact,
@@ -17,7 +21,9 @@ import {
   inventoryArtifacts,
   migrateArtifacts,
   parseArtifactDeliverySpec,
+  readArtifactDeletions,
   releaseArtifact,
+  removeArtifact,
   renderArtifactDeliveryCard,
   renewArtifact,
   repairArtifactActivity,
@@ -28,7 +34,10 @@ import {
 } from "../core/artifacts/index.ts";
 import {
   artifactDefaultRetentionDays,
+  artifactIdleGraceHours,
+  artifactMaxUnitBytes,
   coordFreshnessSeconds,
+  resolveBinName,
   reviewPackAutoCleanEnabled,
 } from "../core/config.ts";
 import { deleteExpiredPacks } from "../lib/browser/page-review-pack.ts";
@@ -50,8 +59,16 @@ export function registerArtifactsCommand(
     .option("--days <n>", "Retention in days (default from artifacts.default_retention_days)")
     .option("--minutes <n>", "Retention in minutes; cannot be combined with --days")
     .option("--big", "Acknowledge that this workspace may exceed the per-bundle size ceiling")
+    .option(
+      "--allow-low-disk",
+      "Create a --big workspace even though free disk is below artifacts.min_free_bytes",
+    )
     .option("--hold <id>", "Create the workspace with this hold already present")
     .option("--hold-reason <text>", "Why the initial hold is required")
+    .option(
+      "--hold-persistent",
+      "Make the initial hold persistent: it never lapses and counts toward the held budget. Only for a hold that mirrors an external lease, such as an open checkout with unsynchronized work",
+    )
     .option("--actor <instance-id>", "Stable owner identity for the initial hold")
     .action(
       (
@@ -61,8 +78,10 @@ export function registerArtifactsCommand(
           days?: string;
           minutes?: string;
           big?: boolean;
+          allowLowDisk?: boolean;
           hold?: string;
           holdReason?: string;
+          holdPersistent?: boolean;
           actor?: string;
         },
       ) => {
@@ -73,6 +92,8 @@ export function registerArtifactsCommand(
           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");
+          if (opts.holdPersistent && !opts.hold)
+            throw new Error("--hold-persistent requires --hold");
           const retentionDays = opts.days
             ? parseDays(opts.days)
             : artifactDefaultRetentionDays(repoRoot);
@@ -86,6 +107,7 @@ export function registerArtifactsCommand(
               "warn",
             );
           }
+          if (opts.big && !opts.allowLowDisk) assertArtifactDiskFloor(repoRoot);
           const created = createArtifact(repoRoot, {
             slug,
             purpose: opts.purpose,
@@ -93,7 +115,15 @@ export function registerArtifactsCommand(
             retentionMinutes,
             actor,
             big: opts.big,
-            holds: opts.hold ? [{ id: opts.hold, reason: opts.holdReason! }] : [],
+            holds: opts.hold
+              ? [
+                  {
+                    id: opts.hold,
+                    reason: opts.holdReason!,
+                    ...(opts.holdPersistent ? { persistent: true } : {}),
+                  },
+                ]
+              : [],
           });
           emit.data({
             path: created.path,
@@ -101,6 +131,13 @@ export function registerArtifactsCommand(
             expires_at: created.manifest.retention.expires_at,
             owner_instance_id: actor?.instance_id ?? null,
             holds: created.manifest.holds,
+            ...usageFields(emit, repoRoot),
+            ...(opts.big
+              ? {}
+              : {
+                  size_ceiling_bytes: artifactMaxUnitBytes(repoRoot),
+                  size_note: `Cleanup deletes this workspace before it expires if it grows past ${artifactMaxUnitBytes(repoRoot)} bytes on disk and then sits idle for ${artifactIdleGraceHours(repoRoot)}h. Create it with --big, or run ${resolveBinName(repoRoot)} artifacts allow-big later, if it will grow that large.`,
+                }),
             after_review: artifactReviewGuidance(repoRoot, created.manifest.artifact_id),
           });
         });
@@ -144,7 +181,14 @@ export function registerArtifactsCommand(
         const rows = inventoryArtifacts(repoRoot, {
           freshnessSeconds: coordFreshnessSeconds(repoRoot),
         });
-        emit.data({ rows, meta: summarize(rows) });
+        const recentDeletions = readArtifactDeletions(repoRoot, {
+          since: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+        });
+        emit.data({
+          rows,
+          meta: inventoryMeta(emit, repoRoot, rows),
+          recent_deletions: recentDeletions,
+        });
       });
     });
 
@@ -154,11 +198,21 @@ export function registerArtifactsCommand(
     .action((ref: string) => {
       run(emit, () => {
         const repoRoot = requireRepoRoot(context);
-        emit.data(
-          showArtifact(repoRoot, ref, {
-            freshnessSeconds: coordFreshnessSeconds(repoRoot),
-          }),
-        );
+        try {
+          emit.data(
+            showArtifact(repoRoot, ref, {
+              freshnessSeconds: coordFreshnessSeconds(repoRoot),
+            }),
+          );
+        } catch (error) {
+          const deleted = readArtifactDeletions(repoRoot)
+            .reverse()
+            .find((record) => [record.artifact_id, record.name].includes(ref));
+          if (!deleted) throw error;
+          throw new Error(
+            `artifact "${ref}" was deleted by cleanup at ${deleted.deleted_at} as ${deleted.classification}: ${deleted.reason}`,
+          );
+        }
       });
     });
 
@@ -221,6 +275,18 @@ export function registerArtifactsCommand(
       });
     });
 
+  root
+    .command("allow-big <ref>")
+    .description(
+      "Exempt an existing workspace from the per-bundle size ceiling, as create --big would; expiry still applies.",
+    )
+    .action((ref: string) => {
+      run(emit, () => {
+        const repoRoot = requireRepoRoot(context);
+        emit.data(allowBigArtifact(repoRoot, ref, { actor: currentActor(repoRoot) }));
+      });
+    });
+
   root
     .command("release <ref>")
     .description("Release active-owner protection without shortening retention.")
@@ -251,6 +317,20 @@ export function registerArtifactsCommand(
       });
     });
 
+  root
+    .command("remove <ref>")
+    .description("Preview immediate removal of one owned artifact; --yes permanently deletes it.")
+    .requiredOption("--reason <text>", "Why these reviewed files are no longer needed")
+    .option("--yes", "Permanently delete this one workspace after safety checks")
+    .action((ref: string, opts: { reason: string; yes?: boolean }) => {
+      run(emit, () => {
+        const repoRoot = requireRepoRoot(context);
+        emit.data(
+          removeArtifact(repoRoot, ref, opts.reason, { ...opts, actor: currentActor(repoRoot) }),
+        );
+      });
+    });
+
   root
     .command("capabilities")
     .description("Report artifact schema and hold capabilities for embedding clients.")
@@ -278,21 +358,46 @@ export function registerArtifactsCommand(
 
   root
     .command("hold <ref>")
-    .description("Protect an artifact from cleanup until its owner removes this exact hold.")
+    .description(
+      "Protect an artifact from cleanup until the hold lapses or its owner removes it; repeating the same id and reason renews it.",
+    )
     .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, {
+    .option("--days <n>", "Hold lifetime in days, 1 to 365 (default from artifacts.hold_days)")
+    .option("--minutes <n>", "Hold lifetime in minutes; cannot be combined with --days")
+    .option(
+      "--persistent",
+      "Never lapse; counts toward the held budget. Only for a hold that mirrors an external lease, such as an open checkout with unsynchronized work",
+    )
+    .action(
+      (
+        ref: string,
+        opts: {
+          id: string;
+          reason: string;
+          actor?: string;
+          days?: string;
+          minutes?: string;
+          persistent?: boolean;
+        },
+      ) =>
+        run(emit, () => {
+          const repoRoot = requireRepoRoot(context);
+          if (opts.days !== undefined && opts.minutes !== undefined)
+            throw new Error("choose either --days or --minutes");
+          if (opts.persistent && (opts.days !== undefined || opts.minutes !== undefined))
+            throw new Error("--persistent cannot be combined with --days or --minutes");
+          const manifest = holdArtifact(repoRoot, ref, {
             id: opts.id,
             reason: opts.reason,
             actor: requireHoldActor(repoRoot, opts.actor),
-          }),
-        );
-      }),
+            ...(opts.days !== undefined ? { days: parseHoldDays(opts.days) } : {}),
+            ...(opts.minutes !== undefined ? { minutes: parseHoldMinutes(opts.minutes) } : {}),
+            ...(opts.persistent ? { persistent: true } : {}),
+          });
+          emit.data({ ...manifest, ...usageFields(emit, repoRoot) });
+        }),
     );
 
   root
@@ -325,7 +430,7 @@ export function registerArtifactsCommand(
           : undefined;
         emit.data({
           rows,
-          meta: summarize(rows),
+          meta: inventoryMeta(emit, repoRoot, rows),
           ...(reviewPacks ? { review_packs: reviewPacks } : {}),
         });
       });
@@ -370,20 +475,67 @@ function parseMinutes(value: string): number {
   return parsed;
 }
 
+function parseHoldDays(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 365)
+    throw new Error("--days must be between 1 and 365 for a hold");
+  return parsed;
+}
+
+function parseHoldMinutes(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 525600)
+    throw new Error("--minutes must be between 1 and 525600 for a hold");
+  return parsed;
+}
+
+/** Cheap usage for create and hold: cached held bytes plus live free disk. */
+function usageFields(
+  emit: EmitContext,
+  repoRoot: string,
+): { usage: ReturnType<typeof artifactQuickUsage>["usage"]; warnings: string[] } {
+  const quick = artifactQuickUsage(repoRoot);
+  for (const warning of quick.warnings) emit.log(warning, "warn");
+  return { usage: quick.usage, warnings: quick.warnings };
+}
+
+/** Summary plus held budget and free disk for a full inventory; warnings also go to stderr. */
+function inventoryMeta(
+  emit: EmitContext,
+  repoRoot: string,
+  rows: Parameters<typeof artifactUsageReport>[1],
+): Record<string, unknown> {
+  const report = artifactUsageReport(repoRoot, rows);
+  for (const warning of report.warnings) emit.log(warning, "warn");
+  return { ...summarize(rows), ...report };
+}
+
 function collect(value: string, previous: string[]): string[] {
   return [...previous, value];
 }
 
 function summarize(
-  rows: { classification: string; action: string; bytes?: number | null }[],
+  rows: {
+    classification: string;
+    action: string;
+    bytes?: number | null;
+    apparent_bytes?: number | null;
+    warning?: string | null;
+  }[],
 ): Record<string, unknown> {
   const classifications: Record<string, number> = {};
   for (const row of rows) {
     classifications[row.classification] = (classifications[row.classification] ?? 0) + 1;
   }
+  const bytes = rows.reduce((sum, row) => sum + (row.bytes ?? 0), 0);
   return {
     total: rows.length,
-    bytes: rows.reduce((sum, row) => sum + (row.bytes ?? 0), 0),
+    // Disk use. `apparent_bytes` is the sum of file lengths; a large gap
+    // between the two means sparse or hard-linked files.
+    bytes,
+    apparent_bytes: rows.reduce((sum, row) => sum + (row.apparent_bytes ?? 0), 0),
+    // Rows carrying a per-row `warning`; `warnings` holds store-level sentences.
+    row_warnings: rows.filter((row) => row.warning).length,
     classifications,
     would_delete: rows.filter((row) => row.action === "would-delete").length,
     deleted: rows.filter((row) => row.action === "deleted").length,

package/src/commands/browse-ai.ts

@@ -4,6 +4,7 @@ import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { AgentBrowser, type ExecResult } from "../lib/agent-browser/index.ts";
 import { applyExtraCookies, CookieJar } from "../lib/cookies/index.ts";
+import { commandPaceGate } from "../lib/pace/index.ts";
 
 // Module-scoped emit assigned by registerBrowseAiCommand. Same pattern as
 // cookies/read/browse: helper functions close over `emit` so action
@@ -46,6 +47,7 @@ interface BrowseAiOpts {
   networkHar?: string;
   store?: string;
   cookies?: boolean;
+  pace?: boolean;
   json?: boolean;
   timeout: string;
 }
@@ -85,6 +87,11 @@ export function registerBrowseAiCommand(
     )
     .option("--network-har <path>", "Record a HAR file from open() through end of run")
     .option("--no-cookies", "Skip cookie-jar attach and persist")
+    .option(
+      "--no-pace",
+      "Skip the human-pace gap (3 to 9 s) between page loads of the same site for this run. " +
+        "HARNERY_PACE=off disables it machine-wide; local and private hosts never wait.",
+    )
     .option("--store <path>", `Cookie store path (default ${DEFAULT_STORE})`)
     .option("--json", "Emit a JSON envelope (snapshot, screenshot path, step results)")
     .option("--timeout <ms>", "Per-step timeout in ms", "60000")
@@ -108,6 +115,7 @@ function runBrowseAi(url: string, opts: BrowseAiOpts, context?: HarneryProgramCo
   const ab = new AgentBrowser({
     jar,
     timeoutMs: Number.parseInt(opts.timeout, 10),
+    pace: commandPaceGate(opts.pace !== false, (message) => emit.log(message, "info")),
   });
 
   const stepLog: { step: string; ok: boolean; output: string }[] = [];