harnery 0.45.2 → 0.46.1

package/dist/lib/http/client.d.ts

@@ -44,6 +44,15 @@ export interface FetchOptions<TResponseType extends FetchResponseType = "text">
     extraCookies?: ExtraCookies;
     /** Response body representation. Default `text`; use `bytes` for lossless file output. */
     responseType?: TResponseType;
+    /**
+     * With `redirect: "follow"`, follow redirects in this client instead of the
+     * runtime's fetch. Every hop then gets its own cookie header, `extraHeaders`
+     * call, and Set-Cookie persistence, so a caller that inspects those can stop
+     * a chain between hops. Credential headers are dropped on a cross-origin hop.
+     * Default: on whenever a `jar` is passed (host-only cookies must follow the
+     * jar's exact-host rule on every hop), off without one.
+     */
+    clientRedirects?: boolean;
 }
 type FetchBody<TResponseType extends FetchResponseType> = TResponseType extends "bytes" ? Uint8Array : string;
 export interface FetchResult<TBody = string> {
@@ -55,14 +64,6 @@ export interface FetchResult<TBody = string> {
     /** Number of cookies persisted back into the jar (0 if no jar passed). */
     cookiesSaved: number;
 }
-/**
- * Fetch a URL with optional cookie-jar attach + persist.
- *
- * Returns the response body as text by default (callers handle JSON parsing).
- * Pass `responseType: "bytes"` when the caller must preserve the body exactly.
- * Streams aren't supported; this is a CLI helper, not a streaming HTTP
- * client. Use Bun's `fetch` directly for streaming workloads.
- */
 export declare function fetchWithJar<TResponseType extends FetchResponseType = "text">(url: string, opts?: FetchOptions<TResponseType>): Promise<FetchResult<FetchBody<TResponseType>>>;
 export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/http/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;GASG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM;IAC5E,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0FAA0F;IAC1F,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,KAAK,SAAS,CAAC,aAAa,SAAS,iBAAiB,IAAI,aAAa,SAAS,OAAO,GACnF,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,MAAM;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM,EACjF,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAY,CAAC,aAAa,CAAM,GACrC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CA+EhD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAEd,KAAK,YAAY,EAElB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;GASG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM;IAC5E,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0FAA0F;IAC1F,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,KAAK,SAAS,CAAC,aAAa,SAAS,iBAAiB,IAAI,aAAa,SAAS,OAAO,GACnF,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,MAAM;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAaD,wBAAsB,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM,EACjF,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAY,CAAC,aAAa,CAAM,GACrC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAsChD"}

package/dist/lib/http/client.js

@@ -1,4 +1,4 @@
-import { applyExtraCookies, } from "../cookies/index.js";
+import { applyExtraCookies, domainMatches, violatesCookiePrefix, } from "../cookies/index.js";
 /**
  * Fetch a URL with optional cookie-jar attach + persist.
  *
@@ -7,7 +7,43 @@ import { applyExtraCookies, } from "../cookies/index.js";
  * Streams aren't supported; this is a CLI helper, not a streaming HTTP
  * client. Use Bun's `fetch` directly for streaming workloads.
  */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_CLIENT_REDIRECTS = 20;
 export async function fetchWithJar(url, opts = {}) {
+    // With a jar, redirects are followed here so every hop gets its own Cookie
+    // header from the jar (exact-host for host-only cookies) and its own
+    // Set-Cookie persistence; the runtime would otherwise carry or drop the
+    // first hop's header on its own rules. Pass `clientRedirects: false` to opt out.
+    const clientRedirects = opts.clientRedirects ?? Boolean(opts.jar);
+    if (!clientRedirects || (opts.redirect ?? "follow") !== "follow")
+        return fetchOnce(url, opts);
+    let current = url;
+    let method = opts.method ?? "GET";
+    let body = opts.body;
+    let headers = opts.headers;
+    let cookiesSaved = 0;
+    for (let hop = 0;; hop++) {
+        const result = await fetchOnce(current, { ...opts, method, body, headers, redirect: "manual" });
+        cookiesSaved += result.cookiesSaved;
+        const location = result.headers.location;
+        if (!REDIRECT_STATUSES.has(result.status) || !location)
+            return { ...result, cookiesSaved };
+        if (hop >= MAX_CLIENT_REDIRECTS) {
+            throw new Error(`Too many redirects (more than ${MAX_CLIENT_REDIRECTS}) starting at ${url}`);
+        }
+        const next = new URL(location, current);
+        if (result.status === 303 ||
+            ((result.status === 301 || result.status === 302) && method !== "GET" && method !== "HEAD")) {
+            method = "GET";
+            body = undefined;
+        }
+        if (next.origin !== new URL(current).origin && headers) {
+            headers = Object.fromEntries(Object.entries(headers).filter(([name]) => !["authorization", "cookie"].includes(name.toLowerCase())));
+        }
+        current = next.href;
+    }
+}
+async function fetchOnce(url, opts = {}) {
     const headers = { ...(opts.headers ?? {}) };
     if (opts.jar) {
         applyExtraCookies(url, opts.jar, opts.extraCookies);
@@ -145,7 +181,10 @@ function parseSetCookie(raw, defaultDomain) {
     for (const attr of parts.slice(1)) {
         const lower = attr.toLowerCase();
         if (lower.startsWith("domain=")) {
-            const d = attr.slice(7).trim();
+            const d = attr.slice(7).trim().toLowerCase();
+            // A server may only scope a cookie to its own host or a parent domain.
+            if (!d || !domainMatches(d, defaultDomain))
+                return null;
             cookie.domain = d.startsWith(".") ? d : `.${d}`;
         }
         else if (lower.startsWith("path=")) {
@@ -176,5 +215,8 @@ function parseSetCookie(raw, defaultDomain) {
             cookie.sameSite = v.charAt(0).toUpperCase() + v.slice(1).toLowerCase();
         }
     }
+    // A cookie that breaks its name prefix is dropped, as a browser would.
+    if (violatesCookiePrefix(cookie))
+        return null;
     return cookie;
 }

package/dist/lib/instructions/templates.js

@@ -111,10 +111,10 @@ carries a reason instead of \`(no intent)\`; the [tool-intent
 guide](https://harnery.com/guides/tool-intent/) owns the details.
 
 **Messaging another agent.** \`${b} agents ping <name> "<message>"\` reaches an
-agent by name whether or not they are running: a live agent sees it on their next
-prompt, and a dormant name holds it until a session of that name next starts.
-Send it as your first and only step. Do not check who is live first, and do not
-hunt for somewhere else to leave it. Only a never-used name is refused.
+agent by name, running or not, here or on another machine sharing this origin:
+a live agent sees it on their next prompt (after a fetch, if remote), and a
+dormant name holds it until that session next starts. Send it as your only step;
+do not check who is live first or hunt elsewhere. Only an unused name is refused.
 
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.45.2",
+  "version": "0.46.1",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -252,7 +252,7 @@
     "access": "public",
     "provenance": true
   },
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.4",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/rewrite-dts-extensions.mjs",
     "build:openclaw-plugin": "mkdir -p openclaw-plugin/dist && bun build openclaw-plugin/src/index.ts openclaw-plugin/src/record-worker.ts --target=node --format=esm --external openclaw --outdir openclaw-plugin/dist --entry-naming '[name].js' && cp openclaw-plugin/package.json openclaw-plugin/openclaw.plugin.json openclaw-plugin/dist/",

package/src/commander.ts

@@ -130,6 +130,19 @@ export interface HarneryProgramContext {
    * harn standalone skips the callback entirely.
    */
   extraCookies?: import("./lib/cookies/index.ts").ExtraCookies;
+  /**
+   * When it returns true for a run, `fetch` follows redirects itself so the
+   * cookie header, `extraHeaders`, and Set-Cookie persistence apply to every
+   * hop instead of only the first request.
+   */
+  clientRedirects?: () => boolean;
+  /**
+   * Called once per `browse` run. Returns the guard that inspects that
+   * session's live cookies before each request, after each response, and at
+   * close (throwing stops the session and fails the run), or undefined for no
+   * guard.
+   */
+  cookieGuard?: () => import("./lib/browser/client.ts").CookieGuard | undefined;
   /**
    * Host-injected vision-model call for `browse --check-critique`. harnery
    * ships no model client or API key; a consumer wires this to its own

package/src/commands/admission.ts

@@ -15,7 +15,7 @@ import { closeSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { type Command, Option } from "commander";
 import type { EmitContext } from "../commander.ts";
-import { resolveBinName } from "../core/config.ts";
+import { readAdmissionConfig, resolveBinName } from "../core/config.ts";
 import {
   type AdmissionEntry,
   type AdmissionStatus,
@@ -24,7 +24,16 @@ import {
   admissionBaseDir,
   admissionStatus,
   listAdmissionResources,
+  waitForMemoryPressure,
 } from "../lib/admission.ts";
+import {
+  type AdmissionHistoryGroup,
+  type AdmissionHistoryRecord,
+  type AdmissionReleaseResult,
+  readAdmissionHistory,
+  resolveAdmissionHistoryDir,
+  summarizeAdmissionHistory,
+} from "../lib/admission-history.ts";
 import {
   classifyJob,
   createJobDir,
@@ -53,6 +62,7 @@ interface AdmissionRunOpts {
   capacity?: string;
   timeout?: string;
   label?: string;
+  projectRoot?: string;
   detach?: boolean;
   json?: boolean;
 }
@@ -67,6 +77,15 @@ interface AdmissionWaitOpts {
   json?: boolean;
 }
 
+interface AdmissionHistoryOpts {
+  resource?: string;
+  since?: string;
+  label?: string;
+  list?: boolean;
+  limit?: string;
+  json?: boolean;
+}
+
 interface AdmissionJobsOpts {
   json?: boolean;
   limit?: string;
@@ -86,6 +105,95 @@ export function jobsBaseDir(): string {
   return coordEnv("JOBS_DIR") ?? `${admissionBaseDir()}-jobs`;
 }
 
+/**
+ * Resources this process tree already holds, set on every child that
+ * `admission run` starts. A nested run on one of them runs directly.
+ */
+const HELD_ENV = "HARNERY_ADMISSION_HELD";
+
+function heldResources(): string[] {
+  return (coordEnv("ADMISSION_HELD") ?? "")
+    .split(",")
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
+/** Run a command with inherited stdio and report how it ended. Never throws. */
+async function runChild(
+  emit: EmitContext,
+  commandArgs: string[],
+  env: NodeJS.ProcessEnv,
+): Promise<AdmissionReleaseResult> {
+  const [executable, ...childArgs] = commandArgs;
+  try {
+    const outcome = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(
+      (resolvePromise, rejectPromise) => {
+        const child = spawn(executable as string, childArgs, {
+          stdio: "inherit",
+          shell: false,
+          env,
+        });
+        child.on("error", rejectPromise);
+        child.on("exit", (code, signal) => resolvePromise({ code, signal }));
+      },
+    );
+    if (outcome.signal !== null) {
+      emit.error({
+        code: "admission_child_signal",
+        message: `${executable} was terminated by signal ${outcome.signal}`,
+      });
+    }
+    return { exitCode: outcome.code, signal: outcome.signal };
+  } catch (err: unknown) {
+    emit.error({
+      code: "admission_spawn_error",
+      message: `cannot run ${executable}: ${describeError(err)}`,
+    });
+    return { exitCode: 1 };
+  }
+}
+
+/** Parse "30m", "24h", or "7d" into milliseconds; undefined means invalid. */
+function parseLookback(raw: string): number | undefined {
+  const match = /^(\d+)([mhd])$/.exec(raw.trim());
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  const unitMs = match[2] === "m" ? 60_000 : match[2] === "h" ? 3_600_000 : 86_400_000;
+  return amount > 0 ? amount * unitMs : undefined;
+}
+
+function describeHistoryGroup(group: AdmissionHistoryGroup): string {
+  const outcomes = Object.entries(group.outcomes)
+    .filter(([outcome]) => outcome !== "released")
+    .map(([outcome, count]) => `${count} ${outcome}`);
+  const hold =
+    group.hold_ms !== null
+      ? `held p50 ${formatJobAge(group.hold_ms.p50)}, p90 ${formatJobAge(group.hold_ms.p90)}`
+      : "no completed holds";
+  return (
+    `  ${group.label || "(no label)"}: ${group.count} run(s), ${group.queued} queued; ` +
+    `waited p50 ${formatJobAge(group.wait_ms.p50)}, p90 ${formatJobAge(group.wait_ms.p90)}, ` +
+    `max ${formatJobAge(group.wait_ms.max)}, total ${formatJobAge(group.wait_ms.total)}; ${hold}` +
+    (outcomes.length > 0 ? `; ${outcomes.join(", ")}` : "")
+  );
+}
+
+function describeHistoryRecord(record: AdmissionHistoryRecord): string {
+  const bits = [
+    record.outcome,
+    `waited ${formatJobAge(record.wait_ms)}`,
+    ...(record.hold_ms !== undefined ? [`held ${formatJobAge(record.hold_ms)}`] : []),
+    ...(record.exit_code !== undefined && record.exit_code !== null
+      ? [`exit ${record.exit_code}`]
+      : []),
+    ...(record.signal ? [`signal ${record.signal}`] : []),
+  ];
+  const behind = record.waited_behind?.length
+    ? ` (behind: ${record.waited_behind.join(", ")})`
+    : "";
+  return `  ${record.ended_at} ${record.resource} ${record.label || "(no label)"}: ${bits.join(", ")}${behind}`;
+}
+
 /** Parse an integer flag with a bounded range; undefined means invalid. */
 function parseBoundedInt(
   raw: string | undefined,
@@ -231,6 +339,11 @@ export function registerAdmissionCommand(program: Command, emit: EmitContext): v
       "--label <text>",
       "Holder description shown in status listings (default: the command itself).",
     )
+    .option(
+      "--project-root <dir>",
+      "Read admission settings from this project's .harnery/config.jsonc instead of " +
+        "the nearest one (for callers inside a nested checkout).",
+    )
     .option(
       "--detach",
       "Launch the command as a durable job: a detached supervisor holds the slot, " +
@@ -248,7 +361,8 @@ export function registerAdmissionCommand(program: Command, emit: EmitContext): v
         "launch failure. The job's own outcome comes from admission wait.",
     )
     .action(async (commandArgs: string[], opts: AdmissionRunOpts) => {
-      const capacity = parseBoundedInt(opts.capacity, 1, 1, 32);
+      const resourceConfig = readAdmissionConfig(opts.projectRoot)?.resources[opts.resource];
+      const capacity = parseBoundedInt(opts.capacity, resourceConfig?.capacity ?? 1, 1, 32);
       if (capacity === undefined) {
         emit.error({
           code: "admission_usage",
@@ -257,7 +371,12 @@ export function registerAdmissionCommand(program: Command, emit: EmitContext): v
         process.exitCode = 1;
         return;
       }
-      const timeoutMinutes = parseBoundedInt(opts.timeout, 60, 1, 1440);
+      const timeoutMinutes = parseBoundedInt(
+        opts.timeout,
+        resourceConfig?.timeout_minutes ?? 60,
+        1,
+        1440,
+      );
       if (timeoutMinutes === undefined) {
         emit.error({
           code: "admission_usage",
@@ -271,6 +390,16 @@ export function registerAdmissionCommand(program: Command, emit: EmitContext): v
         opts.label ??
         (joined.length > LABEL_MAX_CHARS ? `${joined.slice(0, LABEL_MAX_CHARS - 3)}...` : joined);
 
+      // A nested run on a resource this process tree already holds would wait
+      // on its own parent forever, and HARNERY_ADMISSION_SKIP=1 opts one
+      // command out on purpose. Both run the command directly.
+      const held = heldResources();
+      if (coordEnv("ADMISSION_SKIP") === "1" || held.includes(opts.resource)) {
+        const result = await runChild(emit, commandArgs, process.env);
+        process.exitCode = result.exitCode ?? 1;
+        return;
+      }
+
       if (opts.detach) {
         launchDetachedJob(emit, {
           commandArgs,
@@ -279,10 +408,29 @@ export function registerAdmissionCommand(program: Command, emit: EmitContext): v
           label,
           timeoutMinutes,
           json: opts.json === true,
+          ...(resourceConfig?.defer_on_pressure
+            ? { deferOnPressure: resourceConfig.defer_on_pressure }
+            : {}),
         });
         return;
       }
 
+      let pressureWaitMs = 0;
+      const pressure = resourceConfig?.defer_on_pressure;
+      if (pressure) {
+        pressureWaitMs = await waitForMemoryPressure({
+          threshold: pressure.psi_full_avg10,
+          maxWaitMs: pressure.max_wait_seconds * 1000,
+          onWait: (event) =>
+            emit.log(
+              event.gaveUp
+                ? `memory pressure still ${event.pressure} after ${formatJobAge(event.waitedMs)}; starting anyway: ${label}`
+                : `memory pressure ${event.pressure} > ${pressure.psi_full_avg10}; waiting before: ${label}`,
+              "info",
+            ),
+        });
+      }
+
       const dir = admissionBaseDir();
       let lastWaitMessage = "";
       let handle: Awaited<ReturnType<typeof acquireAdmission>>;
@@ -292,6 +440,7 @@ export function registerAdmissionCommand(program: Command, emit: EmitContext): v
           {
             label,
             timeoutMs: timeoutMinutes * 60_000,
+            ...(pressureWaitMs > 0 ? { pressureWaitMs } : {}),
             onWait: (info) => {
               const holders = info.holders.map((holder) => holder.label).join(", ") || "none";
               const message =
@@ -317,36 +466,103 @@ export function registerAdmissionCommand(program: Command, emit: EmitContext): v
         throw err;
       }
 
-      const [executable, ...childArgs] = commandArgs;
+      const childEnv = {
+        ...process.env,
+        [HELD_ENV]: [...held, opts.resource].join(","),
+      };
+      let result: AdmissionReleaseResult = {};
       try {
-        const outcome = await new Promise<{
-          code: number | null;
-          signal: NodeJS.Signals | null;
-        }>((resolvePromise, rejectPromise) => {
-          const child = spawn(executable as string, childArgs, {
-            stdio: "inherit",
-            shell: false,
-          });
-          child.on("error", rejectPromise);
-          child.on("exit", (code, signal) => resolvePromise({ code, signal }));
+        result = await runChild(emit, commandArgs, childEnv);
+        process.exitCode = result.signal ? 1 : (result.exitCode ?? 1);
+      } finally {
+        handle.release(result);
+      }
+    });
+
+  // ----------------------------------------------------------------- history
+  admission
+    .command("history")
+    .description(
+      "Report finished slot use: how long work queued for each resource, what it " +
+        "waited behind, how long holders kept their slots, and which tickets timed " +
+        "out or were abandoned by a process that died. Grouped by resource and " +
+        "label, most total wait first; --list shows individual records.",
+    )
+    .option("--resource <name>", "Report one resource instead of all of them.")
+    .option("--since <window>", "Look back this far: 30m, 24h, 7d (default 24h).")
+    .option("--label <text>", "Keep records whose label contains this text.")
+    .option("--list", "List individual records, newest first, after the summary.")
+    .option("--limit <n>", "With --list, how many records to show (1-500; default 20).")
+    .option("--json", "Emit { history_dir, since, groups: [...], records: [...] } as JSON.")
+    .addHelpText(
+      "after",
+      "\nHistory is written to $XDG_STATE_HOME/harnery/admission-history (default " +
+        "~/.local/state/harnery/admission-history); HARNERY_ADMISSION_HISTORY_DIR " +
+        "moves it and HARNERY_ADMISSION_HISTORY=off stops recording." +
+        "\nExit codes: 0 always (reporting only) · 1 usage error.",
+    )
+    .action((opts: AdmissionHistoryOpts) => {
+      const lookbackMs = parseLookback(opts.since ?? "24h");
+      if (lookbackMs === undefined) {
+        emit.error({
+          code: "admission_usage",
+          message: "--since must look like 30m, 24h, or 7d",
         });
-        if (outcome.signal !== null) {
-          emit.error({
-            code: "admission_child_signal",
-            message: `${executable} was terminated by signal ${outcome.signal}`,
-          });
-          process.exitCode = 1;
-          return;
-        }
-        process.exitCode = outcome.code ?? 1;
-      } catch (err: unknown) {
+        process.exitCode = 1;
+        return;
+      }
+      const limit = parseBoundedInt(opts.limit, 20, 1, 500);
+      if (limit === undefined) {
         emit.error({
-          code: "admission_spawn_error",
-          message: `cannot run ${executable}: ${describeError(err)}`,
+          code: "admission_usage",
+          message: "--limit must be an integer between 1 and 500",
         });
         process.exitCode = 1;
-      } finally {
-        handle.release();
+        return;
+      }
+      const historyDir = resolveAdmissionHistoryDir(admissionBaseDir());
+      const sinceMs = Date.now() - lookbackMs;
+      const records = readAdmissionHistory(historyDir, {
+        ...(opts.resource !== undefined ? { resource: opts.resource } : {}),
+        ...(opts.label !== undefined ? { labelContains: opts.label } : {}),
+        sinceMs,
+      });
+      const groups = summarizeAdmissionHistory(records);
+      const newest = [...records].reverse().slice(0, limit);
+      if (opts.json) {
+        emit.data({
+          history_dir: historyDir,
+          since: new Date(sinceMs).toISOString(),
+          groups,
+          records: opts.list ? newest : [],
+        });
+        return;
+      }
+      if (historyDir === null) {
+        emit.log("admission history recording is off (HARNERY_ADMISSION_HISTORY=off)", "info");
+        return;
+      }
+      if (records.length === 0) {
+        emit.log(`no admission history since ${new Date(sinceMs).toISOString()}`, "info");
+        return;
+      }
+      let resource = "";
+      for (const group of groups.sort((a, b) => a.resource.localeCompare(b.resource))) {
+        if (group.resource !== resource) {
+          resource = group.resource;
+          const inResource = groups.filter((candidate) => candidate.resource === resource);
+          const total = inResource.reduce((sum, candidate) => sum + candidate.wait_ms.total, 0);
+          emit.log(
+            `${resource}: ${inResource.reduce((sum, candidate) => sum + candidate.count, 0)} ` +
+              `run(s), ${formatJobAge(total)} total queue wait`,
+            "info",
+          );
+        }
+        emit.log(describeHistoryGroup(group), "info");
+      }
+      if (opts.list) {
+        emit.log(`latest ${newest.length} record(s):`, "info");
+        for (const record of newest) emit.log(describeHistoryRecord(record), "info");
       }
     });
 
@@ -480,6 +696,7 @@ interface LaunchOptions {
   label: string;
   timeoutMinutes: number;
   json: boolean;
+  deferOnPressure?: { psi_full_avg10: number; max_wait_seconds: number };
 }
 
 function launchDetachedJob(emit: EmitContext, options: LaunchOptions): void {
@@ -507,6 +724,7 @@ function launchDetachedJob(emit: EmitContext, options: LaunchOptions): void {
       argv: options.commandArgs,
       cwd: process.cwd(),
       created_at: nowIso(),
+      ...(options.deferOnPressure ? { defer_on_pressure: options.deferOnPressure } : {}),
     };
     writeJobDocument(jobDir, document);
     logFd = openSync(join(jobDir, DURABLE_JOB_LOG_FILENAME), "a");
@@ -623,6 +841,25 @@ export async function superviseJob(emit: EmitContext, opts: AdmissionSuperviseOp
     });
   };
 
+  // Defer before queueing, holding no slot, exactly as a foreground run does.
+  let pressureWaitMs = 0;
+  const pressure = document.defer_on_pressure;
+  if (pressure) {
+    pressureWaitMs = await waitForMemoryPressure({
+      threshold: pressure.psi_full_avg10,
+      maxWaitMs: pressure.max_wait_seconds * 1000,
+      onWait: (event) => {
+        writeJobStatus(jobDir, { ...status, updated_at: nowIso() });
+        emit.log(
+          event.gaveUp
+            ? `memory pressure still ${event.pressure} after ${formatJobAge(event.waitedMs)}; queueing anyway`
+            : `memory pressure ${event.pressure} > ${pressure.psi_full_avg10}; waiting before queueing`,
+          "info",
+        );
+      },
+    });
+  }
+
   let handle: Awaited<ReturnType<typeof acquireAdmission>>;
   try {
     handle = await acquireAdmission(
@@ -634,6 +871,7 @@ export async function superviseJob(emit: EmitContext, opts: AdmissionSuperviseOp
       {
         label: document.label,
         timeoutMs: timeoutMinutes * 60_000,
+        ...(pressureWaitMs > 0 ? { pressureWaitMs } : {}),
         onWait: () => {
           writeJobStatus(jobDir, { ...status, updated_at: nowIso() });
         },
@@ -668,6 +906,7 @@ export async function superviseJob(emit: EmitContext, opts: AdmissionSuperviseOp
   heartbeat.unref?.();
 
   const [executable, ...childArgs] = document.argv;
+  const result: AdmissionReleaseResult = {};
   let logFd: number | undefined;
   try {
     logFd = openSync(join(jobDir, DURABLE_JOB_LOG_FILENAME), "a");
@@ -676,12 +915,15 @@ export async function superviseJob(emit: EmitContext, opts: AdmissionSuperviseOp
         const child = spawn(executable as string, childArgs, {
           stdio: ["ignore", logFd as number, logFd as number],
           shell: false,
+          env: { ...process.env, [HELD_ENV]: [...heldResources(), document.resource].join(",") },
           ...(document.cwd ? { cwd: document.cwd } : {}),
         });
         child.on("error", rejectPromise);
         child.on("exit", (code, signal) => resolvePromise({ code, signal }));
       },
     );
+    result.exitCode = outcome.code;
+    result.signal = outcome.signal;
     finish({ exitCode: outcome.code, signal: outcome.signal });
     process.exitCode = outcome.signal !== null ? 1 : (outcome.code ?? 1);
   } catch (err: unknown) {
@@ -690,10 +932,11 @@ export async function superviseJob(emit: EmitContext, opts: AdmissionSuperviseOp
       message: `cannot run ${executable}: ${describeError(err)}`,
     });
     finish({ exitCode: 1, signal: null });
+    result.exitCode = 1;
     process.exitCode = 1;
   } finally {
     clearInterval(heartbeat);
     if (logFd !== undefined) closeSync(logFd);
-    handle.release();
+    handle.release(result);
   }
 }