harnery 0.41.0 → 0.42.0

package/dist/core/hooks/adapter/wiring.js

@@ -13,19 +13,68 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveBinName } from "../../config.js";
+import { codexWindowsBridgeConfig, resolveBinName } from "../../config.js";
 import { ADAPTER_SPECS, } from "./events.js";
 import { checkOpenCodePlugin, isOwnedOpenCodePlugin } from "./opencode-plugin.js";
 /** Bound Cursor Stop `followup_message` retries so a missed ritual cannot loop 5 times. */
 export const CURSOR_STOP_FOLLOWUP_LOOP_LIMIT = 2;
 /** Build a hook entry in the adapter's shape. */
 export function makeEntry(shape, command, extras) {
-    if (shape !== "cursor")
-        return { hooks: [{ type: "command", command }] };
+    if (shape !== "cursor") {
+        return {
+            hooks: [
+                orderHandlerKeys({
+                    type: "command",
+                    command,
+                    commandWindows: extras?.commandWindows,
+                    timeout: extras?.timeout,
+                }),
+            ],
+        };
+    }
     return extras?.loop_limit !== undefined
         ? { command, loop_limit: extras.loop_limit }
         : { command };
 }
+/**
+ * Rebuild a handler with Harnery's fields first in a fixed order, dropping
+ * undefined ones and keeping any other fields after them.
+ */
+export function orderHandlerKeys(handler) {
+    const { type, command, commandWindows, timeout, ...rest } = handler;
+    return {
+        type,
+        command,
+        ...(commandWindows !== undefined ? { commandWindows } : {}),
+        ...(timeout !== undefined ? { timeout } : {}),
+        ...rest,
+    };
+}
+/**
+ * The Windows command for an opted-in project (ADR 0197). It hands the hook to
+ * the bridge entry point when that is on PATH and the working directory is a
+ * WSL UNC path, and otherwise runs the usual command. `ProviderPath` drops the
+ * provider prefix that `Path` carries. The trailing `exit $LASTEXITCODE` is
+ * required: without it PowerShell reports any non-zero exit from inside the
+ * `if` block as 1, which would turn a hook's blocking exit 2 into a failure.
+ */
+export function hookCommandWindows(spec, agentHookPath, subcommand, adapter, entryPoint) {
+    const direct = hookCommand(spec, agentHookPath, subcommand, adapter);
+    return (`if ((Get-Command ${entryPoint} -ErrorAction Ignore) -and $PWD.ProviderPath -like '\\\\wsl*') ` +
+        `{ ${entryPoint} ${subcommand} --adapter ${adapter} } else { ${direct} }; exit $LASTEXITCODE`);
+}
+/** The `commandWindows` init writes for one event, or undefined for none. */
+export function expectedCommandWindows(spec, agentHookPath, subcommand, adapter, options) {
+    if (!spec.windowsBridgeHooks || !options?.windowsBridgeEntryPoint)
+        return undefined;
+    return hookCommandWindows(spec, agentHookPath, subcommand, adapter, options.windowsBridgeEntryPoint);
+}
+/** The `timeout` init writes on one event's Harnery hook, or undefined for none. */
+export function hookTimeoutFor(spec, subcommand) {
+    if (!spec.hookTimeouts)
+        return undefined;
+    return spec.hookTimeouts.bySubcommand?.[subcommand] ?? spec.hookTimeouts.default;
+}
 /** Pin Cursor Stop followups to Harnery's loop cap. Returns true when the entry changed. */
 export function applyCursorStopLoopLimit(group, subcommand) {
     if (subcommand !== "stop")
@@ -107,7 +156,15 @@ export function diffWiring(settings, spec, expected) {
             duplicates.push(event);
         if (expected && commands.length > 0) {
             const canonical = hookCommand(spec, expected.agentHookPath, event.subcommand, expected.adapter);
-            if (commands.some((command) => command !== canonical))
+            const timeout = hookTimeoutFor(spec, event.subcommand);
+            const commandWindows = expectedCommandWindows(spec, expected.agentHookPath, event.subcommand, expected.adapter, expected);
+            const handlerDrift = groups.some((group) => "hooks" in group &&
+                Array.isArray(group.hooks) &&
+                group.hooks.some((hook) => typeof hook.command === "string" &&
+                    commandWiresSubcommand(hook.command, event.subcommand) &&
+                    ((timeout !== undefined && hook.timeout !== timeout) ||
+                        (spec.windowsBridgeHooks === true && hook.commandWindows !== commandWindows))));
+            if (handlerDrift || commands.some((command) => command !== canonical))
                 stale.push(event);
         }
         const wrongKey = Object.entries(hooks).some(([key, otherGroups]) => key !== event.settingsKey &&
@@ -222,6 +279,7 @@ export function loadAdapterWiring(projectRoot) {
             ? {
                 agentHookPath: agentHookPathForProject(projectRoot, packageRoot),
                 adapter: id,
+                windowsBridgeEntryPoint: codexWindowsBridgeConfig(projectRoot).entryPoint,
             }
             : undefined);
         if (diff.present.length === 0)

package/dist/core/hooks/cli.js

@@ -42,7 +42,9 @@ import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/
 import { stableScopeId } from "../workflow/scope-id.js";
 import { adapterBehavior } from "./adapter/behaviors/index.js";
 import { detectAdapter, shouldSkipHookAdapter } from "./adapter/detect.js";
+import { ADAPTER_SPECS } from "./adapter/events.js";
 import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./adapter/parse.js";
+import { hookTimeoutFor } from "./adapter/wiring.js";
 import { scheduleBackupSnapshot } from "./backup-schedule.js";
 import { captureImages, detectPresence, imageJanitor, journalArchive, journalJanitor, journalRecoveryCue, playSound, recordImageArtifactsV3, resetSoundCounters, runSessionSyncExtension, soundForEvent, } from "./effects/index.js";
 import { toolInputHash, toolTargetHash } from "./events/input-hash.js";
@@ -52,9 +54,11 @@ import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/
 import { extractIntentComment, resolveIntent } from "./resolve/intent.js";
 import { resolveOwner } from "./resolve/owner.js";
 import { inspectSessionNameDisplayImmediately, scanAssistantStatusBoxPresent, scanStatusBoxPresent, scanTranscriptRuntime, } from "./resolve/transcript.js";
+import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.js";
 import { sessionNamePresence } from "./session-name-presence.js";
 import { shellWaiterReason } from "./shell-waiter.js";
 let hookHealthState;
+let hookRunMarkerPath = null;
 function parseArgv(argv) {
     const out = { eventName: null, extra: [] };
     for (let i = 0; i < argv.length; i++) {
@@ -236,7 +240,11 @@ function buildEventData(eventType, ctx) {
             const forkedFrom = undefined;
             // Assign (or recover) name + kind in-process. Idempotent: resume
             // returns the original name; new owner consumes a counter slot.
-            const assigned = assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
+            // Workflow children stay unnamed, as on the tool path: a pool name
+            // would make them the addressee of mail held for that name.
+            const assigned = coordEnv("WORKFLOW_CHILD") === "1"
+                ? undefined
+                : assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
             // Write the adapter pid-map row so `harn agents whoami` ppid-walks find
             // this owner. Prefer the payload pid (the actual claude binary), then the
             // anchor walk (the `node` ancestor for Cursor, which has no payload pid),
@@ -299,7 +307,8 @@ function buildEventData(eventType, ctx) {
             // SessionStart. Mint durable display identity here so a later
             // SessionStart remains idempotent and Codec is not stuck on the
             // 8-character native id.
-            if (!readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name) {
+            if (coordEnv("WORKFLOW_CHILD") !== "1" &&
+                !readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name) {
                 assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session");
             }
             const prompt = p?.prompt ?? "";
@@ -475,6 +484,23 @@ async function main() {
     const { eventName, extra } = parseArgv(process.argv.slice(2));
     const adapter = detectAdapter(process.argv.slice(2));
     const behavior = adapter ? adapterBehavior(adapter) : null;
+    // Adapters that kill a hook at its timeout get a start marker, so a killed
+    // run leaves evidence for doctor (ADR 0197). Written before stdin is read.
+    const markerSpec = adapter ? ADAPTER_SPECS[adapter] : undefined;
+    const markerTimeout = markerSpec && eventName && markerSpec.events.some((e) => e.subcommand === eventName)
+        ? hookTimeoutFor(markerSpec, eventName)
+        : undefined;
+    if (markerTimeout !== undefined && adapter && eventName && coordEnv("AGENT_COORD_OFF") !== "1") {
+        const markerRoot = resolveCoordRoot(process.cwd());
+        if (markerRoot) {
+            hookRunMarkerPath = writeHookRunMarker(markerRoot, {
+                event: eventName,
+                adapter,
+                pid: process.pid,
+                timeout_sec: markerTimeout,
+            });
+        }
+    }
     const raw = await readStdin();
     hookHealthState = beginHookHealth({
         started_at_ms: hookStartedAt,
@@ -941,9 +967,12 @@ async function handleSessionStarted(run) {
     const { autoCleanArtifacts } = await import("../artifacts/index.js");
     const { autoCleanEventV3Archives } = await import("../events/v3/archive-retention.js");
     const { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import("../storage/maintenance-providers.js");
-    // Effect: throttled daily sweep of expired artifact workspaces (guarded,
-    // managed-expired only; see autoCleanArtifacts). Best-effort like every
-    // janitor here: a failure logs and never blocks session start.
+    // Effect: throttled hourly artifact sweep (see autoCleanArtifacts). It
+    // deletes expired workspaces, plus unheld workspaces over the per-bundle
+    // ceiling or repository budget once they have been idle past
+    // artifacts.idle_grace_hours. Each deletion is rechecked first and recorded
+    // in .harnery/artifact-deletions.jsonl. Best-effort like every janitor
+    // here: a failure logs and never blocks session start.
     try {
         autoCleanArtifacts(coordRoot);
     }
@@ -1291,7 +1320,8 @@ async function handlePostToolUse(run) {
     // status is the wrong place to ask.
     try {
         const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
-        const name = sessionNameDisplayPending(row);
+        // A workflow child has no user-visible title to set.
+        const name = coordEnv("WORKFLOW_CHILD") === "1" ? undefined : sessionNameDisplayPending(row);
         if (name && toolResponseMintedSessionName(payload?.tool_response, name)) {
             // Record the title before asking for it. The suggestion can still
             // change afterwards (an assigned-name rewrite, a lifecycle re-mint, a
@@ -1469,6 +1499,8 @@ function reportSessionNameObservationUnavailable(coordRoot, instanceId, adapter,
     process.stderr.write(`Harnery: session-name observation unavailable (${reason}); allowing this ${eventName} without display enforcement. The name remains pending.\n`);
 }
 async function enforcePendingSessionNameDisplay(coordRoot, instanceId, adapter, payload, coordination) {
+    if (coordEnv("WORKFLOW_CHILD") === "1")
+        return true;
     const name = sessionNameDisplayPending(coordination);
     if (!name)
         return true;
@@ -1830,6 +1862,11 @@ function cleanupSessionEnd(coordRoot, instanceId) {
     }
 }
 async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionId, adapter, workspaceCwd, recoveryBriefing = "", hostPromptContext = "") {
+    // Workflow children get no prompt-time coordination context, matching
+    // SessionStart. The turn ritual is not enforced for them, the naming nudge
+    // would register them as named peers, and rendering drains peer mail.
+    if (coordEnv("WORKFLOW_CHILD") === "1")
+        return false;
     const behavior = adapterBehavior(adapter);
     const { renderPromptContext } = await import("../agents/render/prompt-context.js");
     let additionalContext = renderPromptContext({
@@ -1943,6 +1980,7 @@ function completeRecoveryInjection(coordRoot, instanceId, sessionId, recovery) {
 }
 main()
     .then(async (code) => {
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
         finished_at_ms: performance.now(),
         finished_rss_bytes: process.memoryUsage().rss,
@@ -1957,6 +1995,7 @@ main()
         pid: process.pid,
         phase: "top-level",
     });
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
         finished_at_ms: performance.now(),
         finished_rss_bytes: process.memoryUsage().rss,

package/dist/core/hooks/run-markers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Start markers for hook runs on adapters that kill a hook at its `timeout`
+ * (ADR 0197). A Codex hook that times out has its process tree killed and the
+ * tool proceeds without that hook's checks, and the killed process never
+ * reaches the completion receipt in `health.ts`. A small marker written at
+ * start and removed at completion leaves evidence of that case for doctor.
+ *
+ * Observer-only: every write, read, and removal swallows its own errors so a
+ * marker can never change hook behavior.
+ */
+export interface HookRunMarker {
+    event: string;
+    adapter: string;
+    pid: number;
+    started_at: string;
+    timeout_sec: number;
+}
+export declare function hookRunMarkerDir(coordRoot: string): string;
+/** Write this run's marker; returns its path, or null when it could not be written. */
+export declare function writeHookRunMarker(coordRoot: string, marker: Omit<HookRunMarker, "started_at">, now?: Date): string | null;
+export declare function clearHookRunMarker(path: string | null): void;
+export interface UnfinishedHookRuns {
+    count: number;
+    /** Count per event name, most frequent first. */
+    events: Array<{
+        event: string;
+        count: number;
+    }>;
+    latest: string | null;
+}
+/**
+ * Markers whose run outlived its timeout plus a grace period and whose
+ * process is gone, within the window. A live process past its timeout is
+ * still running and is not counted.
+ */
+export declare function findUnfinishedHookRuns(coordRoot: string, nowMs?: number, windowMs?: number, isAlive?: (pid: number) => boolean): UnfinishedHookRuns;
+//# sourceMappingURL=run-markers.d.ts.map

package/dist/core/hooks/run-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-markers.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/run-markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,EACzC,GAAG,OAAa,GACf,MAAM,GAAG,IAAI,CAYf;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAO5D;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,KAAK,SAAa,EAClB,QAAQ,SAAsB,EAC9B,OAAO,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAsB,GAC/C,kBAAkB,CA+BpB"}

package/dist/core/hooks/run-markers.js

@@ -0,0 +1,109 @@
+/**
+ * Start markers for hook runs on adapters that kill a hook at its `timeout`
+ * (ADR 0197). A Codex hook that times out has its process tree killed and the
+ * tool proceeds without that hook's checks, and the killed process never
+ * reaches the completion receipt in `health.ts`. A small marker written at
+ * start and removed at completion leaves evidence of that case for doctor.
+ *
+ * Observer-only: every write, read, and removal swallows its own errors so a
+ * marker can never change hook behavior.
+ */
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** Markers older than this are pruned when a new one is written. */
+const MARKER_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** A run is unfinished once its marker outlives the timeout by this much. */
+const UNFINISHED_GRACE_MS = 30_000;
+export function hookRunMarkerDir(coordRoot) {
+    return join(coordRoot, ".harnery", "active", "hook-runs");
+}
+/** Write this run's marker; returns its path, or null when it could not be written. */
+export function writeHookRunMarker(coordRoot, marker, now = new Date()) {
+    try {
+        const dir = hookRunMarkerDir(coordRoot);
+        mkdirSync(dir, { recursive: true });
+        pruneHookRunMarkers(dir, now.getTime());
+        const path = join(dir, `${marker.pid}-${safeName(marker.event)}.json`);
+        const body = { ...marker, started_at: now.toISOString() };
+        writeFileSync(path, `${JSON.stringify(body)}\n`);
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearHookRunMarker(path) {
+    if (!path)
+        return;
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Observer-only.
+    }
+}
+/**
+ * Markers whose run outlived its timeout plus a grace period and whose
+ * process is gone, within the window. A live process past its timeout is
+ * still running and is not counted.
+ */
+export function findUnfinishedHookRuns(coordRoot, nowMs = Date.now(), windowMs = 24 * 60 * 60 * 1000, isAlive = processAlive) {
+    const counts = new Map();
+    let latest = null;
+    let count = 0;
+    let names = [];
+    try {
+        names = readdirSync(hookRunMarkerDir(coordRoot)).filter((n) => n.endsWith(".json"));
+    }
+    catch {
+        return { count: 0, events: [], latest: null };
+    }
+    for (const name of names) {
+        let marker;
+        try {
+            marker = JSON.parse(readFileSync(join(hookRunMarkerDir(coordRoot), name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const started = Date.parse(marker.started_at);
+        if (!Number.isFinite(started) || nowMs - started > windowMs)
+            continue;
+        if (nowMs - started < marker.timeout_sec * 1000 + UNFINISHED_GRACE_MS)
+            continue;
+        if (isAlive(marker.pid))
+            continue;
+        count++;
+        counts.set(marker.event, (counts.get(marker.event) ?? 0) + 1);
+        if (!latest || marker.started_at > latest)
+            latest = marker.started_at;
+    }
+    const events = [...counts.entries()]
+        .map(([event, n]) => ({ event, count: n }))
+        .sort((a, b) => b.count - a.count || a.event.localeCompare(b.event));
+    return { count, events, latest };
+}
+function pruneHookRunMarkers(dir, nowMs) {
+    for (const name of readdirSync(dir)) {
+        const path = join(dir, name);
+        try {
+            if (nowMs - statSync(path).mtimeMs > MARKER_RETENTION_MS)
+                rmSync(path, { force: true });
+        }
+        catch {
+            // Observer-only.
+        }
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function safeName(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 64) || "unknown";
+}

package/dist/core/servers/index.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Local server registry.
+ *
+ * Every command that starts a long-lived local server (a preview UI, a tuning
+ * panel, a tunnel gate, a dashboard) writes one record under
+ * `.harnery/servers/<id>.json` and removes it when the server stops. One
+ * reader can then list every running server, stop any of them, and clean up
+ * session servers whose starting agent is gone.
+ *
+ * Two kinds:
+ *   - `service`: one long-running copy (a dashboard, a tunnel). Listed and
+ *     stoppable by hand; never stopped automatically.
+ *   - `session`: one copy per piece of work (a preview for one scene). Eligible
+ *     for `gc` once its starting agent has ended or been unobserved for a long
+ *     time AND nobody has used the server for the idle window.
+ *
+ * Fail-closed rules: a record whose pid was recycled is treated as dead, never
+ * signalled; an unreadable coordination view makes every owner `unknown`,
+ * which `gc` never stops; a record without an owner is never stopped
+ * automatically.
+ */
+import { type ScanSupport } from "./net.js";
+export { ancestry, establishedConnectionCounts, listListeningPorts, listListeningSockets, lsofConnectionCounts, lsofListeningSockets, parseElapsed, parseLsofListen, parseProcNetTcp, processStartedAt, psProcessInfo, readProcessInfo, scanSupport, } from "./net.js";
+export { tunnelServerId, tunnelServerInput } from "./tunnels.js";
+export declare const SERVER_RECORD_SCHEMA_VERSION = 1;
+export declare const SERVER_DEFAULT_IDLE_HOURS = 2;
+export declare const SERVER_DEFAULT_OWNER_STALE_HOURS = 24;
+export type ServerKind = "service" | "session";
+export interface ServerRecord {
+    schema_version: typeof SERVER_RECORD_SCHEMA_VERSION;
+    id: string;
+    kind: ServerKind;
+    /** Free-form family name: `preview`, `tunnel`, `dashboard`, ... */
+    type: string;
+    label: string;
+    url?: string;
+    port?: number;
+    /** The process that owns the server's lifetime (signalled on stop). */
+    pid: number;
+    start_token?: string;
+    /** Further processes that belong to this server (helpers, children). */
+    pids?: number[];
+    host: string;
+    /** What the server serves, usually a directory. */
+    scope?: string;
+    cwd?: string;
+    log?: string;
+    /** Graceful stop command; signals are the fallback. */
+    stop_argv?: string[];
+    owner?: {
+        instance_id: string;
+        name?: string;
+    };
+    started_at: string;
+    registered_at: string;
+    last_active_at?: string;
+}
+export interface RegisterServerInput {
+    id?: string;
+    kind: ServerKind;
+    type: string;
+    label?: string;
+    url?: string;
+    port?: number;
+    pid?: number;
+    pids?: number[];
+    scope?: string;
+    cwd?: string;
+    log?: string;
+    stop_argv?: string[];
+    started_at?: string;
+    /** `null` records no owner; omitted resolves the calling agent session. */
+    owner?: {
+        instance_id: string;
+        name?: string;
+    } | null;
+}
+export interface ServerOptions {
+    coordRoot?: string | null;
+}
+export type ServerState = "running" | "dead" | "other-host";
+export type OwnerState = "live" | "abandoned" | "ended" | "unknown" | "none";
+export interface ServerView {
+    record: ServerRecord;
+    state: ServerState;
+    owner_state: OwnerState;
+    connections: number | null;
+    last_active_at: string;
+    idle_ms: number;
+}
+export interface UnregisteredListener {
+    pid: number;
+    port: number;
+    address: string;
+    command: string;
+    cwd: string | null;
+}
+export interface ServersReport {
+    schema_version: 1;
+    coord_root: string;
+    scan: ScanSupport;
+    servers: ServerView[];
+    unregistered: UnregisteredListener[];
+    pruned: string[];
+}
+export declare function serversDir(coordRoot: string): string;
+/** A stable id for one server family serving one scope. */
+export declare function serverId(type: string, scope?: string): string;
+export declare function isValidServerId(id: string): boolean;
+/**
+ * Record a running server. Returns null when no coordination root resolves
+ * (a tool running outside any Harnery project), so callers never fail
+ * because registration was impossible.
+ */
+export declare function registerServer(input: RegisterServerInput, options?: ServerOptions): ServerRecord | null;
+/** Best-effort registration that never throws (for server start paths). */
+export declare function tryRegisterServer(input: RegisterServerInput, options?: ServerOptions): ServerRecord | null;
+/**
+ * Remove a server's record. With `pid`, only a record still naming that pid
+ * is removed, so a replacement that re-registered the same id survives.
+ */
+export declare function unregisterServer(id: string, options?: ServerOptions & {
+    pid?: number;
+}): boolean;
+export declare function readServer(id: string, options?: ServerOptions): ServerRecord | null;
+/** Mark a server as used now. */
+export declare function touchServer(id: string, options?: ServerOptions & {
+    now?: Date;
+}): void;
+/**
+ * A request hook for servers that want precise idle tracking: call the
+ * returned function on every request; it writes at most once a minute.
+ */
+export declare function createServerToucher(id: string, options?: ServerOptions): () => void;
+export declare function readServerRecords(options?: ServerOptions): ServerRecord[];
+export declare function pidAlive(pid: number): boolean;
+export declare function serverState(record: ServerRecord): ServerState;
+export interface ListServersOptions extends ServerOptions {
+    /** Look for listening processes inside the project that never registered. */
+    scan?: boolean;
+    /** Record observed connections as activity (default true). */
+    sample?: boolean;
+    /** Delete records of servers that are no longer running (default true). */
+    prune?: boolean;
+    ownerStaleHours?: number;
+    now?: Date;
+}
+/** Read every record, observe it, and optionally find unregistered listeners. */
+export declare function listServers(options?: ListServersOptions): ServersReport;
+/** Register running tunnels that have no current record. Returns adopted ids. */
+export declare function adoptRunningTunnels(coordRoot: string): string[];
+/**
+ * Listening processes that run inside the project (working directory or
+ * command line within the coordination root) but are not covered by any
+ * registered server: not a recorded pid, not a descendant of one, and not on
+ * a recorded port.
+ */
+export declare function findUnregisteredListeners(coordRoot: string, servers: Array<Pick<ServerView, "record" | "state">>): UnregisteredListener[];
+export interface GcPolicy {
+    idleHours?: number;
+    ownerStaleHours?: number;
+}
+export interface GcDecision {
+    id: string;
+    action: "stop" | "keep";
+    reason: string;
+}
+/**
+ * Decide which session servers to stop. Pure: the caller supplies the views.
+ * A server is stopped only when all hold: kind `session`, running on this
+ * host, its owner ended or went unobserved past the stale window, and it has
+ * been idle for the idle window.
+ */
+export declare function planServerGc(views: ServerView[], policy?: GcPolicy): GcDecision[];
+export interface StopResult {
+    id: string;
+    stopped: boolean;
+    method: "not-running" | "stop-command" | "signal" | "refused";
+    detail?: string;
+}
+/**
+ * Stop one server: its graceful stop command first when recorded, then
+ * SIGTERM to its process group, then SIGKILL after the grace period. A pid
+ * whose start token no longer matches is never signalled.
+ */
+export declare function stopServer(record: ServerRecord, options?: ServerOptions & {
+    graceMs?: number;
+}): Promise<StopResult>;
+/**
+ * The first free port in the configured range for `type`
+ * (`.harnery/config.jsonc` `servers.port_ranges`). Skips ports any process is
+ * listening on and ports a registered server claims. Returns null when the
+ * type has no configured range; throws when the range is exhausted.
+ */
+export declare function allocateServerPort(type: string, options?: ServerOptions): number | null;
+export interface AdoptOptions extends ServerOptions {
+    type?: string;
+    kind?: ServerKind;
+    label?: string;
+    scope?: string;
+    /** `self` (default) records the adopting agent as owner; `none` records no owner. */
+    owner?: "self" | "none";
+}
+/**
+ * Register a running server that never registered itself. Only a pid the scan
+ * reports as an unregistered listener inside the project can be adopted.
+ */
+export declare function adoptServer(pid: number, options?: AdoptOptions): ServerRecord;
+/** Ensure the registry directory exists (for hosts that write records directly). */
+export declare function ensureServersDir(coordRoot: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/servers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/servers/index.ts"],"names":[],"mappings":"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"}