harnery 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -137,6 +137,11 @@
       "types": "./dist/core/supervisor/index.d.ts",
       "import": "./dist/core/supervisor/index.js"
     },
+    "./core/servers": {
+      "bun": "./src/core/servers/index.ts",
+      "types": "./dist/core/servers/index.d.ts",
+      "import": "./dist/core/servers/index.js"
+    },
     "./core/diagnostics": {
       "bun": "./src/core/diagnostics/index.ts",
       "types": "./dist/core/diagnostics/index.d.ts",

package/schemas/config.schema.json

@@ -240,6 +240,53 @@
           "maximum": 3650,
           "default": 3,
           "description": "Retention for `harn artifacts create` when --days is absent. Env override: HARNERY_ARTIFACT_RETENTION_DAYS."
+        },
+        "auto_clean": {
+          "type": "boolean",
+          "default": true,
+          "description": "Run the throttled artifact cleanup at session start and before new artifact work. Env override: HARNERY_ARTIFACT_AUTO_CLEAN."
+        },
+        "max_bytes": {
+          "type": "integer",
+          "minimum": 67108864,
+          "maximum": 1099511627776,
+          "default": 21474836480,
+          "description": "Soft repository budget in bytes of disk use for unheld managed workspaces. Env override: HARNERY_ARTIFACT_MAX_BYTES."
+        },
+        "max_unit_bytes": {
+          "type": "integer",
+          "minimum": 16777216,
+          "maximum": 1099511627776,
+          "default": 1073741824,
+          "description": "Per-workspace ceiling in bytes of disk use; a workspace created with --big is exempt. Env override: HARNERY_ARTIFACT_MAX_UNIT_BYTES."
+        },
+        "idle_grace_hours": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8760,
+          "default": 24,
+          "description": "Hours an unexpired workspace must be idle (no file change, no owner heartbeat) before a size rule may delete it. Env override: HARNERY_ARTIFACT_IDLE_GRACE_HOURS."
+        },
+        "hold_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "default": 14,
+          "description": "Days a hold protects a workspace before it lapses unless renewed with `harn artifacts hold` (same id and reason). Env override: HARNERY_ARTIFACT_HOLD_DAYS."
+        },
+        "max_held_bytes": {
+          "type": "integer",
+          "minimum": 67108864,
+          "maximum": 1099511627776,
+          "default": 21474836480,
+          "description": "Advisory budget in bytes of disk use for held workspaces. Exceeding it produces warnings; held work is never deleted. Env override: HARNERY_ARTIFACT_MAX_HELD_BYTES."
+        },
+        "min_free_bytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1125899906842624,
+          "default": 21474836480,
+          "description": "Free-disk floor for the artifact store. Below it, artifact commands warn and `artifacts create --big` refuses without --allow-low-disk. 0 disables the floor. Env override: HARNERY_ARTIFACT_MIN_FREE_BYTES."
         }
       }
     },
@@ -306,6 +353,37 @@
           "type": "boolean",
           "default": false,
           "description": "Pin `workflow run` to subscription billing: API-key vars are scrubbed from every child env. Stamped true by `harn init` when the key is absent. Env override: HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=1|0."
+        },
+        "workerFullAccess": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Let qualifying workflow workers launch without their vendor sandbox (ADR 0192). A launch qualifies only when this is enabled, the launching session itself can be shown to run with full access, and the worker's exact model and effort meet a floor listed here. Anything else keeps the ordinary sandboxed projection. Project config only; a user-global file cannot grant it. HARNERY_WORKFLOW_WORKER_FULL_ACCESS=0 turns it off for one process. An invalid value disables it entirely.",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "floors": {
+              "type": "object",
+              "description": "Per-adapter list of models a worker may run unsandboxed on. Keys are adapter ids.",
+              "additionalProperties": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["model"],
+                  "properties": {
+                    "model": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Exact model id the worker must name. Aliases and the adapter's default model never match."
+                    },
+                    "minEffort": {
+                      "type": "string",
+                      "description": "Lowest qualifying effort on the adapter's declared effort scale. Required for an adapter with an effort scale; not allowed for one that encodes effort in the model id."
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -349,6 +427,19 @@
               "default": 65536
             }
           }
+        },
+        "codexWindowsBridge": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["entryPoint"],
+          "description": "Route Windows-native Codex hooks through a resident WSL bridge (decision record 0197). init writes a commandWindows on each Codex hook that calls entryPoint when it is on PATH and the working directory is a WSL path, and otherwise runs the usual command. Project config only.",
+          "properties": {
+            "entryPoint": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+              "description": "Windows command name the bridge installs, for example codex-wsl-hook. Only a bridge that implements the decision record 0197 contract should install it."
+            }
+          }
         }
       }
     },

package/src/commander.ts

@@ -320,6 +320,12 @@ function harneryCommandBundles({
   binName,
 }: CommandBundleContext): LazyCommandBundle[] {
   return [
+    lazy(
+      "disk [path]",
+      "Measure checkout disk usage, including nested repositories and ignored files",
+      async (program) => (await import("./commands/disk.ts")).registerDiskCommand(program, emit),
+      { hasOptions: true },
+    ),
     lazy(
       "tokens <files...>",
       "Count tokens in text/markdown files (offline, uses o200k_base as Claude proxy)",
@@ -596,6 +602,13 @@ function harneryCommandBundles({
       async (program) =>
         (await import("./commands/storage.ts")).registerStorageCommand(program, emit, context),
     ),
+    lazy(
+      "rm <paths...>",
+      "Preview guarded removal of untracked files; --yes applies permanent deletion",
+      async (program) =>
+        (await import("./commands/rm.ts")).registerRmCommand(program, emit, context),
+      { hasOptions: true },
+    ),
     lazy("logs", "List and query bounded Harnery log families", async (program) =>
       (await import("./commands/logs.ts")).registerLogsCommand(program, emit, context),
     ),
@@ -661,6 +674,12 @@ function harneryCommandBundles({
       async (program) =>
         (await import("./commands/tunnel.ts")).registerTunnelCommand(program, emit, context),
     ),
+    lazy(
+      "servers",
+      "Every local server started in this project: list, stop, clean up idle session servers, read logs",
+      async (program) =>
+        (await import("./commands/servers.ts")).registerServersCommand(program, emit, context),
+    ),
     lazy(
       "docs",
       "Documentation tooling: freshness report, metadata, lint, sweep, index",

package/src/commands/agents.ts

@@ -78,6 +78,9 @@ import {
   readHeartbeat as readHeartbeatCache,
 } from "../core/agents/state/heartbeat-writer.ts";
 import {
+  describeLiveAuthorityBlockV3,
+  liveAuthorityBlockHintV3,
+  liveAuthorityBlockV3,
   readLiveCoordinationRow,
   readLiveCoordinationRows,
 } from "../core/agents/state/live-coordination-view.ts";
@@ -1486,6 +1489,10 @@ function normalizeKind(kind: string | undefined | null): string {
  * command refuses in turn and the caller has no way to guess the path back.
  */
 function noLiveGenerationMessage(root: string, owner: string): string {
+  const block = liveAuthorityBlockV3(root, owner);
+  if (block) {
+    return `resolved owner=${owner}; ${describeLiveAuthorityBlockV3(block)}; ${liveAuthorityBlockHintV3(resolveBinName(root))}`;
+  }
   return `resolved owner=${owner} but no authority-safe live V3 generation exists for it; ${lifecycleReopenHint(root)}`;
 }
 
@@ -5230,6 +5237,13 @@ function runHeal(opts: {
   }
 
   if (proc.status !== 0) {
+    const block = liveAuthorityBlockV3(root, owner);
+    if (block) {
+      emitHealFailure(
+        "authority_blocked",
+        `${describeLiveAuthorityBlockV3(block)}; a cache rebuild cannot restore authority the ledger withholds; ${liveAuthorityBlockHintV3(resolveBinName(root))}`,
+      );
+    }
     emitHealFailure(
       healFailureReason(root, owner, sessionId, healAdapter),
       spawnFailureMessage(proc, `agent-coord ${action}`),

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,