harnery 0.34.1 → 0.36.0

package/dist/commands/read.js

@@ -7,11 +7,11 @@ let emit;
 /**
  * `harn read`: extract clean readable markdown from HTML.
  */
-export function registerReadCommand(program, emitParam) {
+export function registerReadCommand(program, emitParam, binName = resolveBinName()) {
     emit = emitParam;
     program
         .command("read [html-file]")
-        .description(`Extract clean readable markdown from HTML. Reads from file or stdin (use '-'). Pair with \`${resolveBinName()} fetch\` or \`${resolveBinName()} browse\` for scrape-to-markdown.`)
+        .description(`Extract clean readable markdown from HTML. Reads from file or stdin (use '-'). Pair with \`${binName} fetch\` or \`${binName} browse\` for scrape-to-markdown.`)
         .option("-o, --output <file>", "Write markdown to file instead of stdout")
         .option("--url <url>", "Base URL: used to resolve relative links")
         .option("--selector <css>", "Use this CSS selector instead of Readability (fallback when extraction misses content)")

package/dist/commands/semantic.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/commands/semantic.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiB1E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8LN"}

package/dist/commands/semantic.js

@@ -0,0 +1,199 @@
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+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")
+        .description("Build and inspect evidence-cited semantic readings of active V3 generations");
+    semantic
+        .command("once")
+        .description("Run one bounded semantic pass using each generation's source harness")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--calls-per-hour <count>", "Configured call ceiling below the hard limit", integer)
+        .action(async (options) => {
+        try {
+            emit.data(await runSemanticOnce({
+                coordRoot: resolve(options.root ?? coordRoot(context)),
+                callsPerHour: options.callsPerHour,
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_once_failed", error);
+        }
+    });
+    const service = semantic
+        .command("service")
+        .description("Run semantic reading as a singleton service");
+    service
+        .command("start")
+        .description("Start or resume the detached per-root semantic reader service")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--calls-per-hour <count>", "Configured call ceiling below the hard limit", integer)
+        .action(async (options) => {
+        try {
+            emit.data(await spawnSemanticService(resolve(options.root ?? coordRoot(context)), {
+                callsPerHour: options.callsPerHour,
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_service_start_failed", error);
+        }
+    });
+    service
+        .command("status")
+        .description("Show reader liveness, rolling calls, token usage, routes, and pending work")
+        .option("--root <path>", "Explicit coordination root")
+        .action((options) => {
+        try {
+            emit.data(readSemanticServiceStatus(resolve(options.root ?? coordRoot(context))));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_service_status_failed", error);
+        }
+    });
+    service
+        .command("stop")
+        .description("Request a graceful stop after the current model call")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            let status = requestSemanticServiceStop(root);
+            const deadline = Date.now() + 5_000;
+            while (status.running && Date.now() < deadline) {
+                await new Promise((done) => setTimeout(done, 50));
+                status = readSemanticServiceStatus(root);
+            }
+            emit.data(status);
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_service_stop_failed", error);
+        }
+    });
+    service
+        .command("daemon", { hidden: true })
+        .description("Internal detached semantic service entrypoint")
+        .option("--root <path>", "Explicit coordination root")
+        .option("--calls-per-hour <count>", "Configured call ceiling below the hard limit", integer)
+        .action(async (options) => {
+        try {
+            emit.data(await runSemanticServiceDaemon({
+                coordRoot: resolve(options.root ?? coordRoot(context)),
+                callsPerHour: options.callsPerHour,
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_service_daemon_failed", error);
+        }
+    });
+    semantic
+        .command("inspect")
+        .description("Inspect one generation or instance semantic document")
+        .argument("<instance-or-generation>")
+        .option("--root <path>", "Explicit coordination root")
+        .action((instanceOrGeneration, options) => {
+        try {
+            const document = inspectSemanticDocument(resolve(options.root ?? coordRoot(context)), instanceOrGeneration);
+            if (!document)
+                throw new Error(`no semantic document for ${instanceOrGeneration}`);
+            emit.data(document);
+        }
+        catch (error) {
+            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")
+        .option("--root <path>", "Explicit coordination root")
+        .action((options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            emit.data({
+                schema_version: 1,
+                root,
+                storage: semanticPaths(root).root,
+                readers: discoverSemanticReaders(createSemanticAdapters()),
+                manifest: readManifestSafe(root),
+            });
+        }
+        catch (error) {
+            emitFailure(emit, "semantic_doctor_failed", error);
+        }
+    });
+}
+function coordRoot(context) {
+    return resolve(context?.resolveCoordRoot?.() ??
+        context?.repoRoot ??
+        process.env.HARNERY_COORD_ROOT ??
+        process.cwd());
+}
+function integer(value) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1)
+        throw new Error("count must be a positive integer");
+    return parsed;
+}
+function readManifestSafe(root) {
+    try {
+        return readSemanticManifest(root);
+    }
+    catch {
+        return undefined;
+    }
+}
+function emitFailure(emit, code, error) {
+    emit.error({ code, message: error instanceof Error ? error.message : String(error) });
+    throw error;
+}

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