harnery 0.40.0 → 0.42.0

package/dist/core/semantic/service.js

@@ -7,6 +7,7 @@ import { coordEnv } from "../../lib/env.js";
 import { readEventV3ControlState, readLedgerV3Since, } from "../events/v3/index.js";
 import { eventV3ActiveWatchPath } from "../events/v3/reader.js";
 import { closeProcessLoggers, encodeBoundedLogObjectArray, legacyLogFields, processLogger, } from "../storage/logger.js";
+import { stateDirMode, stateFileMode } from "../storage/modes.js";
 import { runSemanticOnce } from "./once.js";
 import { semanticPendingPassDue } from "./scheduler.js";
 import { readSemanticServiceStatus, SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION, } from "./service-status.js";
@@ -47,11 +48,11 @@ export async function spawnSemanticService(coordRootRaw, options = {}) {
         throw new Error(`semantic service is already running under pid ${current.record?.pid}`);
     }
     const paths = semanticPaths(coordRoot);
-    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
     const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
-    const logFd = sharedLogs ? undefined : openSync(paths.log, "a", 0o600);
+    const logFd = sharedLogs ? undefined : openSync(paths.log, "a", stateFileMode());
     if (logFd !== undefined)
-        chmodSync(paths.log, 0o600);
+        chmodSync(paths.log, stateFileMode());
     const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
     if (!existsSync(harnBin)) {
         if (logFd !== undefined)
@@ -132,7 +133,7 @@ export async function ensureSemanticServiceRunning(coordRootRaw, overrides = {})
 export function requestSemanticServiceStop(coordRootRaw) {
     const coordRoot = resolve(coordRootRaw);
     const status = readSemanticServiceStatus(coordRoot);
-    mkdirSync(semanticPaths(coordRoot).root, { recursive: true, mode: 0o700 });
+    mkdirSync(semanticPaths(coordRoot).root, { recursive: true, mode: stateDirMode() });
     writePrivateJsonAtomic(semanticPaths(coordRoot).stop, {
         requested_at: new Date().toISOString(),
         requested_by_pid: process.pid,
@@ -339,7 +340,7 @@ export async function runSemanticServiceDaemon(input) {
 }
 export function acquireSemanticServiceLease(coordRootRaw) {
     const path = semanticPaths(coordRootRaw).lease;
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
     const owner = {
         pid: process.pid,
         host: hostname(),
@@ -348,7 +349,7 @@ export function acquireSemanticServiceLease(coordRootRaw) {
     };
     const acquire = () => {
         try {
-            const fd = openSync(path, "wx", 0o600);
+            const fd = openSync(path, "wx", stateFileMode());
             try {
                 writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
             }
@@ -544,9 +545,9 @@ function prepareSemanticServiceDiagnostic(entry) {
 }
 function appendSemanticServiceLegacyLog(coordRoot, entry) {
     const path = semanticPaths(coordRoot).log;
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    appendFileSync(path, `${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), ...entry })}\n`, { encoding: "utf8", mode: 0o600 });
-    chmodSync(path, 0o600);
+    mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+    appendFileSync(path, `${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), ...entry })}\n`, { encoding: "utf8", mode: stateFileMode() });
+    chmodSync(path, stateFileMode());
     if (statSync(path).size <= MAX_LOG_BYTES)
         return;
     const buffer = readFileSync(path);
@@ -554,7 +555,7 @@ function appendSemanticServiceLegacyLog(coordRoot, entry) {
     const newline = tail.indexOf(10);
     const body = newline >= 0 ? tail.subarray(newline + 1) : tail;
     const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-    writeFileSync(temporary, body, { flag: "wx", mode: 0o600 });
+    writeFileSync(temporary, body, { flag: "wx", mode: stateFileMode() });
     renameSync(temporary, path);
 }
 function writePrivateJsonAtomic(path, value) {
@@ -562,12 +563,12 @@ function writePrivateJsonAtomic(path, value) {
     if (Buffer.byteLength(body) > MAX_FILE_BYTES) {
         throw new Error(`semantic service file exceeds ${MAX_FILE_BYTES} bytes`);
     }
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    chmodSync(dirname(path), 0o700);
+    mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+    chmodSync(dirname(path), stateDirMode());
     const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-    writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: stateFileMode() });
     renameSync(temporary, path);
-    chmodSync(path, 0o600);
+    chmodSync(path, stateFileMode());
 }
 function validTimestamp(value) {
     return typeof value === "string" && Number.isFinite(Date.parse(value));

package/dist/core/semantic/storage.d.ts.map

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

package/dist/core/semantic/storage.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { canonicalJsonV3, sha256V3 } from "../events/v3/canonical.js";
+import { stateDirMode, stateFileMode } from "../storage/modes.js";
 import { validateSemanticReadModel } from "./validate.js";
 export const SEMANTIC_MANIFEST_SCHEMA_VERSION = 2;
 const MAX_JSON_BYTES = 512 * 1024;
@@ -171,10 +172,10 @@ function writePrivateJsonAtomic(path, value) {
     if (Buffer.byteLength(body) > MAX_JSON_BYTES) {
         throw new Error(`semantic file exceeds ${MAX_JSON_BYTES} bytes`);
     }
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    chmodSync(dirname(path), 0o700);
+    mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+    chmodSync(dirname(path), stateDirMode());
     const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-    writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: stateFileMode() });
     renameSync(temporary, path);
-    chmodSync(path, 0o600);
+    chmodSync(path, stateFileMode());
 }

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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"}