harnery 0.35.0 → 0.36.0

package/dist/commands/semantic.js

@@ -1,5 +1,6 @@
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import { createSemanticAdapters, discoverSemanticReaders, inspectSemanticDocument, readSemanticManifest, readSemanticServiceStatus, requestSemanticServiceStop, runSemanticOnce, runSemanticServiceDaemon, semanticPaths, spawnSemanticService, } from "../core/semantic/index.js";
+import { createSemanticAdapters, discoverSemanticReaders, inspectSemanticDocument, prepareSemanticReviewStudy, readSemanticManifest, readSemanticServiceStatus, readSemanticSoakReport, requestSemanticServiceStop, runSemanticOnce, runSemanticServiceDaemon, semanticPaths, spawnSemanticService, storeSemanticReviewSubmission, } from "../core/semantic/index.js";
 export function registerSemanticCommand(program, emit, context) {
     const semantic = program
         .command("semantic")
@@ -40,7 +41,7 @@ export function registerSemanticCommand(program, emit, context) {
     });
     service
         .command("status")
-        .description("Show singleton liveness, pass metrics, and pending work")
+        .description("Show reader liveness, rolling calls, token usage, routes, and pending work")
         .option("--root <path>", "Explicit coordination root")
         .action((options) => {
         try {
@@ -101,6 +102,57 @@ export function registerSemanticCommand(program, emit, context) {
             emitFailure(emit, "semantic_inspect_failed", error);
         }
     });
+    semantic
+        .command("soak")
+        .description("Summarize recent reader outcomes, controlled cues, stability, and token usage")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--minutes <count>", "Lookback window in whole minutes", integer)
+        .action((options) => {
+        try {
+            emit.data(readSemanticSoakReport(resolve(options.root ?? coordRoot(context)), {
+                ...(options.minutes !== undefined ? { minutes: options.minutes } : {}),
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_soak_failed", error);
+        }
+    });
+    const review = semantic
+        .command("review")
+        .description("Prepare and record a local human review of accepted semantic readings");
+    review
+        .command("prepare")
+        .description("Capture current accepted readings and return the next bounded review set")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--limit <count>", "Maximum candidates in this review set", integer)
+        .action((options) => {
+        try {
+            emit.data(prepareSemanticReviewStudy(resolve(options.root ?? coordRoot(context)), {
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_review_prepare_failed", error);
+        }
+    });
+    review
+        .command("submit")
+        .description("Validate one frozen review set and store its controlled-label receipt")
+        .requiredOption("--file <path>", "JSON submission file")
+        .option("--root <path>", "Explicit coordination root")
+        .action((options) => {
+        try {
+            const file = resolve(options.file);
+            const size = statSync(file).size;
+            if (size <= 0 || size > 128 * 1024) {
+                throw new Error("semantic review submission has invalid size");
+            }
+            emit.data(storeSemanticReviewSubmission(resolve(options.root ?? coordRoot(context)), JSON.parse(readFileSync(file, "utf8"))));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_review_submit_failed", error);
+        }
+    });
     semantic
         .command("doctor")
         .description("Inspect semantic reader availability without making a model request")

package/dist/commands/storage.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export declare function registerStorageCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=storage.d.ts.map

package/dist/commands/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/commands/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAwD1E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA+IN"}

package/dist/commands/storage.js

@@ -0,0 +1,238 @@
+import { resolve } from "node:path";
+import { resolveCoordRoot as resolveCanonicalCoordRoot } from "../core/agents/coord-client.js";
+import { createStorageCatalog } from "../core/storage/catalog.js";
+import { storageHealth } from "../core/storage/health.js";
+import { filterStorageInventory, inventoryStorage } from "../core/storage/inventory.js";
+import { DEFAULT_MAINTENANCE_BUDGET, executeStorageMaintenance, HARNERY_MAINTENANCE_PRESSURE_SCHEMA, HarneryMaintenanceError, listMaintenanceTransactions, planStorageMaintenance, readMaintenanceTransaction, } from "../core/storage/maintenance.js";
+import { createStructuredLogMaintenanceProviders } from "../core/storage/maintenance-providers.js";
+const STORAGE_CLASSES = new Set([
+    "canonical-authority",
+    "recovery-state",
+    "operational-log",
+    "debug-log",
+    "durable-object-history",
+    "repairable-cache",
+    "managed-artifact",
+]);
+export function registerStorageCommand(program, emit, context) {
+    const storage = program
+        .command("storage")
+        .description("Inspect registered Harnery storage without reading file bodies");
+    storage
+        .command("inventory")
+        .description("Inventory .harnery and explicitly registered external storage roots")
+        .option("--family <id>", "Show one registered storage family")
+        .option("--class <class>", "Show one registered storage class")
+        .option("--json", "Emit the stable versioned inventory schema")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const catalog = catalogFor(context);
+            if (options.family && !catalog.get(options.family)) {
+                throw new StorageCommandError("unknown_storage_family", `unknown storage family: ${options.family}`);
+            }
+            const storageClass = parseStorageClass(options.class);
+            const report = filterStorageInventory(await inventoryStorage(catalog), {
+                ...(options.family ? { family_id: options.family } : {}),
+                ...(storageClass ? { storage_class: storageClass } : {}),
+            });
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(report);
+            }
+            else {
+                emit.rows(inventoryRows(report));
+            }
+        });
+    });
+    storage
+        .command("health")
+        .description("Report reason-coded health for every registered storage family")
+        .option("--json", "Emit the stable versioned health schema")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const report = storageHealth(await inventoryStorage(catalogFor(context)));
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(report);
+            }
+            else {
+                emit.text(`storage health: ${report.status}\n`);
+                emit.rows(report.families.map((family) => ({
+                    family_id: family.family_id,
+                    status: family.status,
+                    reasons: family.reason_codes.join(",") || "none",
+                    maintenance: family.maintenance.state,
+                    max_bytes: family.log_storage?.effective_policy?.max_bytes ?? "unavailable",
+                    max_age_days: family.log_storage?.effective_policy?.max_age_days ?? "unavailable",
+                    managed_bytes: family.log_storage?.usage.managed_bytes ?? "not-a-log",
+                    unmanaged_bytes: family.log_storage?.usage.unmanaged_bytes ?? "not-a-log",
+                    pressure: family.log_storage?.pressure.state ?? "not-a-log",
+                    enforcement: family.log_storage?.retention.enforcement ?? "not-a-log",
+                })));
+            }
+        });
+    });
+    storage
+        .command("maintain")
+        .description("Plan bounded maintenance, or execute one exact transaction")
+        .option("--family <id>", "Limit a new plan to one registered family")
+        .option("--budget <duration>", "Wall-time budget such as 500ms, 5s, or 1m")
+        .option("--dry-run", "Plan without mutating source storage", true)
+        .option("--transaction <id>", "Execute one previously planned exact transaction")
+        .option("--yes", "Confirm execution of the exact transaction")
+        .option("--authorize-structured-log-deletion", "Authorize deletion only for exact manifest-backed structured-log actions")
+        .option("--json", "Emit the versioned transaction schema")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const catalog = catalogFor(context);
+            const providers = [
+                ...createStructuredLogMaintenanceProviders(catalog),
+                ...(context?.storageMaintenanceProviders ?? []),
+            ];
+            const transaction = options.transaction
+                ? await executeStorageMaintenance(catalog, providers, options.transaction, {
+                    yes: options.yes === true,
+                    authorize_structured_log_deletion: options.authorizeStructuredLogDeletion === true,
+                })
+                : await planStorageMaintenance(catalog, providers, await pressureFor(catalog), {
+                    ...(options.family ? { family_id: options.family } : {}),
+                    budget: {
+                        ...DEFAULT_MAINTENANCE_BUDGET,
+                        max_duration_ms: parseDuration(options.budget),
+                    },
+                    persist: true,
+                });
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(transaction);
+            }
+            else {
+                emit.rows([
+                    {
+                        transaction_id: transaction.transaction_id,
+                        state: transaction.state,
+                        dry_run: transaction.dry_run,
+                        actions: transaction.actions.length,
+                        files: transaction.actions.reduce((sum, action) => sum + action.files, 0),
+                        bytes: transaction.actions.reduce((sum, action) => sum + action.bytes, 0),
+                        reasons: transaction.reason_codes.join(",") || "none",
+                    },
+                ]);
+            }
+        });
+    });
+    storage
+        .command("status")
+        .description("Inspect maintenance transactions without changing storage")
+        .option("--transaction <id>", "Show one exact transaction")
+        .option("--json", "Emit versioned transaction records")
+        .action(async (options) => {
+        await run(emit, async () => {
+            const catalog = catalogFor(context);
+            const transactions = options.transaction
+                ? [readMaintenanceTransaction(catalog.context.coord_root, options.transaction)]
+                : listMaintenanceTransactions(catalog.context.coord_root);
+            if (options.json) {
+                emit.config({ format: "json" });
+                emit.data(transactions);
+            }
+            else {
+                emit.rows(transactions.map((transaction) => ({
+                    transaction_id: transaction.transaction_id,
+                    state: transaction.state,
+                    created_at: transaction.created_at,
+                    actions: transaction.actions.length,
+                    reasons: transaction.reason_codes.join(",") || "none",
+                })));
+            }
+        });
+    });
+}
+function catalogFor(context) {
+    const coordRoot = resolve(context?.resolveCoordRoot?.() ??
+        context?.repoRoot ??
+        process.env.HARNERY_COORD_ROOT ??
+        resolveCanonicalCoordRoot() ??
+        process.cwd());
+    return createStorageCatalog({ coord_root: coordRoot, project_root: resolve(context?.repoRoot ?? coordRoot) }, context?.storage);
+}
+function parseStorageClass(value) {
+    if (value === undefined)
+        return undefined;
+    if (!STORAGE_CLASSES.has(value)) {
+        throw new StorageCommandError("unknown_storage_class", `unknown storage class: ${value}`);
+    }
+    return value;
+}
+async function pressureFor(catalog) {
+    const inventory = await inventoryStorage(catalog);
+    return {
+        schema: HARNERY_MAINTENANCE_PRESSURE_SCHEMA,
+        captured_at: inventory.captured_at,
+        families: inventory.families.map((family) => ({
+            family_id: family.family_id,
+            logical_bytes: family.totals.logical_bytes.state === "observed" ? family.totals.logical_bytes.value : 0,
+            regular_files: family.totals.regular_files.state === "observed" ? family.totals.regular_files.value : 0,
+            needs_maintenance: family.maintenance.state === "eligible",
+            observed_at: inventory.captured_at,
+        })),
+    };
+}
+function parseDuration(value) {
+    if (value === undefined)
+        return DEFAULT_MAINTENANCE_BUDGET.max_duration_ms;
+    const match = /^(\d+)(ms|s|m)$/.exec(value);
+    if (!match)
+        throw new StorageCommandError("invalid_maintenance_budget", `invalid duration: ${value}`);
+    const amount = Number(match[1]);
+    const multiplier = match[2] === "ms" ? 1 : match[2] === "s" ? 1_000 : 60_000;
+    const result = amount * multiplier;
+    if (!Number.isSafeInteger(result) || result <= 0 || result > 60 * 60 * 1_000) {
+        throw new StorageCommandError("invalid_maintenance_budget", `invalid duration: ${value}`);
+    }
+    return result;
+}
+function inventoryRows(report) {
+    return report.families.map((family) => ({
+        family_id: family.family_id,
+        class: family.storage_class,
+        state: family.state,
+        regular_files: measurementValue(family.totals.regular_files),
+        logical_bytes: measurementValue(family.totals.logical_bytes),
+        allocated_bytes: measurementValue(family.totals.allocated_bytes),
+        maintenance: family.maintenance.state,
+        max_bytes: family.log_storage?.effective_policy?.max_bytes ?? "unavailable",
+        max_age_days: family.log_storage?.effective_policy?.max_age_days ?? "unavailable",
+        managed_bytes: family.log_storage?.usage.managed_bytes ?? "not-a-log",
+        unmanaged_bytes: family.log_storage?.usage.unmanaged_bytes ?? "not-a-log",
+        pressure: family.log_storage?.pressure.state ?? "not-a-log",
+        enforcement: family.log_storage?.retention.enforcement ?? "not-a-log",
+        reasons: family.reason_codes.join(",") || "none",
+    }));
+}
+function measurementValue(measurement) {
+    return measurement.state === "observed"
+        ? measurement.value
+        : `unavailable:${measurement.reason_code}`;
+}
+class StorageCommandError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+async function run(emit, action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        emit.error({
+            code: error instanceof StorageCommandError || error instanceof HarneryMaintenanceError
+                ? error.code
+                : "storage_inspection_failed",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        emit.setExitCode(1);
+    }
+}

package/dist/commands/tunnel.d.ts

@@ -1,6 +1,10 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.js";
-import { type TunnelState } from "../lib/tunnel/state.js";
+import { type TunnelProvider, type TunnelState } from "../lib/tunnel/state.js";
+export declare function tunnelLogDestinations(name: string, provider: TunnelProvider, env?: NodeJS.ProcessEnv, root?: string): {
+    gate: string;
+    provider: string;
+};
 /**
  * Restart ONE instance's gate in place, deliberately leaving the provider
  * process running.

package/dist/commands/tunnel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/commands/tunnel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAa1E,OAAO,EAYL,KAAK,WAAW,EAGjB,MAAM,wBAAwB,CAAC;AA8rBhC;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAsE7F;AA+MD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,YAAY,CAAC,EAAE,qBAAqB,GACnC,IAAI,CA2EN"}
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/commands/tunnel.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAQ1E,OAAO,EAWL,KAAK,cAAc,EACnB,KAAK,WAAW,EAGjB,MAAM,wBAAwB,CAAC;AAoDhC,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,SAAgB,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAcpC;AAuoBD;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAsE7F;AA+MD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,YAAY,CAAC,EAAE,qBAAqB,GACnC,IAAI,CA2EN"}

package/dist/commands/tunnel.js

@@ -1,12 +1,8 @@
-// Inline cachePath; see lib/tunnel/state.ts for rationale.
-function cachePath(tool, filename) {
-    const dir = resolve(process.cwd(), ".cache", tool);
-    return resolve(dir, filename);
-}
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { resolveBinName } from "../core/config.js";
+import { processLogDestination, runRotatingProcessSync, spawnRotatingProcess, } from "../core/storage/process-log.js";
 import { clearState, DEFAULT_INSTANCE, ensureCloudflared, gateLogFile, isProcessAlive, listStates, providerLogFile, readConfig, readState, writeConfig, writeState, } from "../lib/tunnel/state.js";
 /**
  * `tunnel`: provider-backed tunnel in front of a local upstream.
@@ -24,6 +20,20 @@ const DEFAULT_TARGET = "127.0.0.1:8001";
 const DEFAULT_VHOST = "localhost";
 const DEFAULT_GATE_PORT = 9001;
 const MAX_GATE_PORT = DEFAULT_GATE_PORT + 99; // auto-allocation scan ceiling
+export function tunnelLogDestinations(name, provider, env = process.env, root = process.cwd()) {
+    const destination = (filename) => processLogDestination({
+        coord_root: root,
+        project_root: root,
+        family_id: "tunnel-process-log",
+        filename,
+        legacy_path: resolve(root, ".cache", "tunnel", filename),
+        env,
+    });
+    return {
+        gate: destination(gateLogFile(name)),
+        provider: destination(providerLogFile(name, provider)),
+    };
+}
 /**
  * Validate + normalize an instance name. Names become filename fragments
  * (state-<name>.json) and pgrep patterns, so they're restricted to a safe
@@ -270,7 +280,6 @@ function tailscaleCommand(mode) {
     return mode === "funnel" ? "funnel" : "serve";
 }
 function runTailscaleShare(mode, targetUrl, path, httpsPort, logPath) {
-    const fd = openSync(logPath, "a");
     const args = [
         tailscaleCommand(mode),
         "--bg",
@@ -279,31 +288,36 @@ function runTailscaleShare(mode, targetUrl, path, httpsPort, logPath) {
         `--set-path=${path}`,
         targetUrl,
     ];
-    const r = spawnSync("tailscale", args, {
-        stdio: ["ignore", fd, fd],
+    const status = runRotatingProcessSync({
+        path: logPath,
+        command: "tailscale",
+        arguments: args,
     });
-    if (r.status !== 0) {
+    if (status !== 0) {
         emit.error({
             code: "tunnel_tailscale_failed",
             message: `tailscale ${tailscaleCommand(mode)} failed. Check log: ${logPath}`,
         });
-        process.exit(r.status ?? 1);
+        process.exit(status ?? 1);
     }
 }
 function stopTailscaleShare(state) {
     if (state.provider !== "tailscale" || !state.tailscale_mode)
         return true;
     const cmd = tailscaleCommand(state.tailscale_mode);
-    const logPath = cachePath("tunnel", providerLogFile(state.name, "tailscale"));
-    const fd = openSync(logPath, "a");
+    const logPath = tunnelLogDestinations(state.name, "tailscale").provider;
     const args = [
         cmd,
         `--https=${state.tailscale_https_port ?? 443}`,
         `--set-path=${state.tailscale_path ?? "/"}`,
         "off",
     ];
-    const r = spawnSync("tailscale", args, { stdio: ["ignore", fd, fd] });
-    if (r.status !== 0) {
+    const status = runRotatingProcessSync({
+        path: logPath,
+        command: "tailscale",
+        arguments: args,
+    });
+    if (status !== 0) {
         // The gate is torn down and its port is freed for reuse regardless, so a
         // surviving serve/funnel mapping could later re-expose whatever next binds
         // that port. Surface it loudly so the operator can clear it by hand.
@@ -339,12 +353,12 @@ function tunnelIsAlive(state) {
  * re-reads — that snapshot is precisely why `reload` has to exist.
  */
 function spawnGate(o) {
-    const gateFd = openSync(o.gateLogPath, "a");
     // `--name`/`--port` on argv mirror the env vars; they're what makes the gate
     // process distinguishable per-instance in `pgrep -f` (see sweepStrays).
-    const gateProc = spawn("bun", ["run", gateScriptPath(), "--name", o.name, "--port", String(o.gatePort)], {
-        detached: true,
-        stdio: ["ignore", gateFd, gateFd],
+    const gateProc = spawnRotatingProcess({
+        path: o.gateLogPath,
+        command: "bun",
+        arguments: ["run", gateScriptPath(), "--name", o.name, "--port", String(o.gatePort)],
         env: {
             ...process.env,
             HARNERY_TUNNEL_ALLOW: o.allowedIps.join(","),
@@ -414,10 +428,9 @@ async function up(opts) {
         });
         process.exit(1);
     }
-    const gateLogPath = cachePath("tunnel", gateLogFile(name));
-    const providerLogPath = cachePath("tunnel", providerLogFile(name, provider));
-    writeFileSync(gateLogPath, "");
-    writeFileSync(providerLogPath, "");
+    const logPaths = tunnelLogDestinations(name, provider);
+    const gateLogPath = logPaths.gate;
+    const providerLogPath = logPaths.provider;
     const gateProc = spawnGate({
         name,
         gatePort,
@@ -439,15 +452,15 @@ async function up(opts) {
     let registered = true;
     let cloudflaredPid;
     if (provider === "cloudflare") {
-        const cfdFd = openSync(providerLogPath, "a");
         // Force HTTP/2 transport. The default QUIC transport wedges at precheck on
         // constrained hosts (e.g. WSL, where UDP receive buffers can't grow and ICMP
         // is restricted): the URL prints but the edge never registers. HTTP/2 is
         // marginally higher-latency but registers reliably, which is what a dev
         // tunnel needs.
-        const cfdProc = spawn(cloudflaredBin, ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`], {
-            detached: true,
-            stdio: ["ignore", cfdFd, cfdFd],
+        const cfdProc = spawnRotatingProcess({
+            path: providerLogPath,
+            command: cloudflaredBin,
+            arguments: ["tunnel", "--protocol", "http2", "--url", `http://localhost:${gatePort}`],
         });
         cfdProc.unref();
         cloudflaredPid = cfdProc.pid;
@@ -649,7 +662,7 @@ export async function reloadOne(state) {
         vhost: state.vhost,
         provider: state.provider,
         allowedIps: cfg.allowed_ips,
-        gateLogPath: cachePath("tunnel", gateLogFile(name)),
+        gateLogPath: tunnelLogDestinations(name, state.provider).gate,
     });
     await sleep(800);
     const pid = gateProc.pid;
@@ -794,8 +807,8 @@ function logs(opts) {
     const name = resolveName(opts.name);
     const state = readState(name);
     const provider = state?.provider ?? "cloudflare";
-    const which = opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
-    const path = cachePath("tunnel", which);
+    const destinations = tunnelLogDestinations(name, provider);
+    const path = opts.provider ? destinations.provider : destinations.gate;
     if (!existsSync(path)) {
         emit.error({ code: "tunnel_no_log", message: `No log file at ${path}` });
         process.exit(1);

package/dist/commands/web.d.ts

@@ -19,6 +19,9 @@ export declare function resolveMaxOldSpaceMb(flag?: string): number;
  * wins without clobbering flags the caller set (source maps, inspector, …).
  */
 export declare function nodeOptionsWithHeapCap(mb: number): string | undefined;
+/** Preload the request diagnostics hook without replacing Next's HTTP server. */
+export declare function nodeOptionsWithWebDiagnostics(webDir: string, mb: number): string;
+export declare function webPerformanceLogDestination(coordRoot: string, env?: Readonly<Record<string, string | undefined>>): string;
 /**
  * Probe the exact localhost socket Next will claim. This is deliberately a
  * check-and-report step, not an alternate-port allocator: Harnery keeps one

package/dist/commands/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAkCnD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKrE;AAyCD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAevE;AAsBD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA6K5E"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/commands/web.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAyCnD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKrE;AAED,iFAAiF;AACjF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAKhF;AAED,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,MAAM,CAQR;AAyCD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAevE;AAsBD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAuN5E"}

package/dist/commands/web.js

@@ -2,9 +2,11 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createServer } from "node:net";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.js";
 import { ensureSemanticServiceRunning } from "../core/semantic/service.js";
+import { processLogDestination } from "../core/storage/process-log.js";
+import { parsePerformanceWindow, readWebPerformanceReport, WEB_PERFORMANCE_LOG, } from "../lib/web-performance.js";
 import { lazyFetchWebRoot, webRunner } from "./web-fetch.js";
 /**
  * `harn web`: Next.js dashboard for harnery's coord state.
@@ -13,6 +15,7 @@ import { lazyFetchWebRoot, webRunner } from "./web-fetch.js";
  *   up [--prod]:   start the server (dev mode default; --prod runs next start)
  *   build:         next build (production bundle)
  *   start:         next start (must `harn web build` first)
+ *   performance:   summarize request latency and event-loop delays
  *
  * Launches the Next.js app under `harnery/web/` against the user's current
  * working directory. The web app reads `.harnery/` via `HARNERY_COORD_ROOT`;
@@ -66,6 +69,23 @@ export function nodeOptionsWithHeapCap(mb) {
         return inherited;
     return `${inherited} --max-old-space-size=${mb}`.trim();
 }
+/** Preload the request diagnostics hook without replacing Next's HTTP server. */
+export function nodeOptionsWithWebDiagnostics(webDir, mb) {
+    const inherited = nodeOptionsWithHeapCap(mb) ?? "";
+    if (inherited.includes("server-performance.mjs"))
+        return inherited;
+    const preload = pathToFileURL(path.join(webDir, "server-performance.mjs")).href;
+    return `${inherited} --import=${preload}`.trim();
+}
+export function webPerformanceLogDestination(coordRoot, env = process.env) {
+    return processLogDestination({
+        coord_root: coordRoot,
+        family_id: "web-performance-log",
+        filename: "active.jsonl",
+        legacy_path: path.join(coordRoot, ".harnery", "logs", WEB_PERFORMANCE_LOG),
+        env,
+    });
+}
 async function startSemanticServiceWithWeb(coordRoot, emit) {
     const result = await ensureSemanticServiceRunning(coordRoot);
     if (result.state === "started")
@@ -185,9 +205,12 @@ export function registerWebCommand(program, emit) {
             return;
         await startSemanticServiceWithWeb(coordRoot, emit);
         const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
+        const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
+        const performanceLogPath = webPerformanceLogDestination(coordRoot);
         emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
         emit.log(`files origin · http://harnery-files.localhost:${port}`, "info");
         emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
+        emit.log(`performance log · ${performanceLogPath}`, "info");
         if (heapMb > 0)
             emit.log(`heap ceiling · ${heapMb} MB`, "info");
         const child = spawn(webRunner(), ["run", mode], {
@@ -196,9 +219,9 @@ export function registerWebCommand(program, emit) {
                 ...process.env,
                 HARNERY_COORD_ROOT: coordRoot,
                 HARNERY_WEB_PORT: String(port),
-                ...(nodeOptionsWithHeapCap(heapMb)
-                    ? { NODE_OPTIONS: nodeOptionsWithHeapCap(heapMb) }
-                    : {}),
+                HARNERY_WEB_MODE: mode,
+                HARNERY_WEB_PERFORMANCE_LOG_PATH: performanceLogPath,
+                NODE_OPTIONS: nodeOptions,
             },
             stdio: "inherit",
         });
@@ -271,8 +294,11 @@ export function registerWebCommand(program, emit) {
             return;
         await startSemanticServiceWithWeb(coordRoot, emit);
         const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
+        const nodeOptions = nodeOptionsWithWebDiagnostics(root, heapMb);
+        const performanceLogPath = webPerformanceLogDestination(coordRoot);
         emit.log(`harn web · http://localhost:${port} (start)`, "info");
         emit.log(`reading .harnery/ from: ${coordRoot}`, "info");
+        emit.log(`performance log · ${performanceLogPath}`, "info");
         if (heapMb > 0)
             emit.log(`heap ceiling · ${heapMb} MB`, "info");
         const child = spawn(webRunner(), ["run", "start"], {
@@ -281,9 +307,9 @@ export function registerWebCommand(program, emit) {
                 ...process.env,
                 HARNERY_COORD_ROOT: coordRoot,
                 HARNERY_WEB_PORT: String(port),
-                ...(nodeOptionsWithHeapCap(heapMb)
-                    ? { NODE_OPTIONS: nodeOptionsWithHeapCap(heapMb) }
-                    : {}),
+                HARNERY_WEB_MODE: "start",
+                HARNERY_WEB_PERFORMANCE_LOG_PATH: performanceLogPath,
+                NODE_OPTIONS: nodeOptions,
             },
             stdio: "inherit",
         });
@@ -297,4 +323,38 @@ export function registerWebCommand(program, emit) {
             process.exitCode = code ?? 0;
         });
     });
+    web
+        .command("performance")
+        .description("Summarize dashboard request, event-loop, memory, and GC diagnostics")
+        .option("--coord-root <dir>", "Override the coordination root", process.cwd())
+        .option("--since <window>", "Include the last Nm, Nh, or Nd", "1h")
+        .option("--limit <n>", "Keep the N slowest requests and delays", "20")
+        .option("--json", "Emit structured JSON")
+        .action((opts) => {
+        const windowMs = parsePerformanceWindow(opts.since);
+        if (windowMs === null) {
+            emit.error({
+                code: "invalid_web_performance_window",
+                message: `invalid --since value '${opts.since}'`,
+                hint: "Use Nm, Nh, or Nd, for example 30m, 1h, or 7d.",
+            });
+            return;
+        }
+        const limit = Number(opts.limit);
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+            emit.error({
+                code: "invalid_web_performance_limit",
+                message: `invalid --limit value '${opts.limit}'`,
+                hint: "Use an integer from 1 through 500.",
+            });
+            return;
+        }
+        if (opts.json)
+            emit.config({ format: "json" });
+        emit.data(readWebPerformanceReport({
+            root: opts.coordRoot,
+            since: opts.since,
+            limit,
+        }));
+    });
 }