harnery 0.35.0 → 0.37.0

package/dist/core/inbox/lifecycle.js

@@ -0,0 +1,41 @@
+import { project } from "./service.js";
+export const HARNERY_INBOX_COMPACTION_PLAN_SCHEMA = "harnery.inbox-compaction-plan/v1";
+export function planInboxCompaction(input) {
+    const projection = project(input.records);
+    const surfacedAt = new Map();
+    for (const record of input.records) {
+        if (record.kind === "surfaced")
+            surfacedAt.set(record.message_id, Date.parse(record.surfaced_at));
+    }
+    const compactableIds = new Set([...surfacedAt]
+        .filter(([, timestamp]) => input.now.getTime() - timestamp >= input.limits.surfaced_grace_ms)
+        .map(([id]) => id));
+    const compactableRecords = input.records.filter((record) => compactableIds.has(record.message_id)).length;
+    if (input.lifecycle === "terminal") {
+        if (projection.pending.length > 0) {
+            return plan(input, "none", "pending_protected", 0, input.records.length, projection.pending.length);
+        }
+        const terminalAt = input.terminal_at ? Date.parse(input.terminal_at) : Number.NaN;
+        if (!Number.isFinite(terminalAt) ||
+            input.now.getTime() - terminalAt < input.limits.terminal_grace_ms) {
+            return plan(input, "none", "terminal_grace", 0, input.records.length, 0);
+        }
+        return plan(input, "prune-terminal", "eligible", input.records.length, 0, 0);
+    }
+    if (compactableRecords === 0) {
+        return plan(input, "none", surfacedAt.size > 0 ? "surfaced_grace" : "active_recipient", 0, input.records.length, projection.pending.length);
+    }
+    return plan(input, "compact-surfaced", "eligible", compactableRecords, input.records.length - compactableRecords, projection.pending.length);
+}
+function plan(input, action, reason_code, remove_record_count, retained_record_count, protected_pending_count) {
+    return {
+        schema: HARNERY_INBOX_COMPACTION_PLAN_SCHEMA,
+        recipient_instance_id: input.recipient_instance_id,
+        action,
+        reason_code,
+        remove_record_count,
+        retained_record_count,
+        protected_pending_count,
+        dry_run: true,
+    };
+}

package/dist/core/inbox/service.d.ts

@@ -0,0 +1,36 @@
+import { type HarneryInboxLimits, type HarneryInboxMessageRecordV1, type HarneryInboxRecordV1, type HarneryInboxStatusV1, type HarneryInboxSurfaceBudget, type HarneryInboxSurfaceResult } from "./contract.js";
+export interface HarneryInboxServiceOptions {
+    coord_root: string;
+    limits: HarneryInboxLimits;
+    now?: () => Date;
+    id?: () => string;
+}
+export interface HarneryInboxSendInput {
+    sender_instance_id: string;
+    sender_display_name: string;
+    recipient_instance_id: string;
+    recipient_display_name: string;
+    body: string;
+}
+export interface HarneryInboxSendReceipt {
+    state: "queued";
+    message_id: string;
+    body_bytes: number;
+    synced: true;
+}
+export declare class HarneryInboxService {
+    #private;
+    constructor(options: HarneryInboxServiceOptions);
+    send(input: HarneryInboxSendInput): HarneryInboxSendReceipt;
+    records(recipientInstanceId: string): HarneryInboxRecordV1[];
+    pending(recipientInstanceId: string): HarneryInboxMessageRecordV1[];
+    status(recipientInstanceId: string): HarneryInboxStatusV1;
+    surface(recipientInstanceId: string, emit: (messages: readonly HarneryInboxMessageRecordV1[]) => Promise<void> | void, budget?: HarneryInboxSurfaceBudget): Promise<HarneryInboxSurfaceResult>;
+}
+export declare function inboxPath(coordRoot: string, recipientInstanceId: string): string;
+export declare function project(records: readonly HarneryInboxRecordV1[]): {
+    pending: HarneryInboxMessageRecordV1[];
+    surfaced: ReadonlySet<string>;
+    lastSurfaceAt?: string;
+};
+//# sourceMappingURL=service.d.ts.map

package/dist/core/inbox/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/service.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,CAAC;CACd;AAED,qBAAa,mBAAmB;;gBAGlB,OAAO,EAAE,0BAA0B;IAK/C,IAAI,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB;IA2C3D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB,EAAE;IAO5D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,2BAA2B,EAAE;IAInE,MAAM,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB;IA0BnD,OAAO,CACX,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAChF,MAAM,GAAE,yBAIP,GACA,OAAO,CAAC,yBAAyB,CAAC;CAoCtC;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,GAAG;IACjE,OAAO,EAAE,2BAA2B,EAAE,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAsBA"}

package/dist/core/inbox/service.js

@@ -0,0 +1,210 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCrashSafeJsonlFile, updateCrashSafeJsonlFile } from "../storage/durable-history.js";
+import { HARNERY_INBOX_RECORD_SCHEMA, HARNERY_INBOX_STATUS_SCHEMA, HarneryInboxCapacityError, } from "./contract.js";
+export class HarneryInboxService {
+    #options;
+    constructor(options) {
+        validateLimits(options.limits);
+        this.#options = options;
+    }
+    send(input) {
+        const recipient = opaqueId(input.recipient_instance_id, "recipient instance");
+        const bodyBytes = Buffer.byteLength(input.body);
+        const limits = this.#options.limits;
+        if (bodyBytes === 0 || bodyBytes > limits.max_message_body_bytes) {
+            throw new HarneryInboxCapacityError("message_body_limit", bodyBytes, limits.max_message_body_bytes);
+        }
+        const record = {
+            schema: HARNERY_INBOX_RECORD_SCHEMA,
+            kind: "message",
+            message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
+            sender_instance_id: opaqueId(input.sender_instance_id, "sender instance"),
+            sender_display_name: boundedDisplay(input.sender_display_name),
+            recipient_instance_id: recipient,
+            recipient_display_name: boundedDisplay(input.recipient_display_name),
+            created_at: now(this.#options).toISOString(),
+            body: input.body,
+            body_bytes: bodyBytes,
+        };
+        const path = inboxPath(this.#options.coord_root, recipient);
+        return updateCrashSafeJsonlFile(path, readOptions(limits), (records) => {
+            const projection = project(records);
+            capacityCheck(projection, record, path, limits);
+            return {
+                append: [record],
+                result: {
+                    state: "queued",
+                    message_id: record.message_id,
+                    body_bytes: bodyBytes,
+                    synced: true,
+                },
+            };
+        });
+    }
+    records(recipientInstanceId) {
+        return readCrashSafeJsonlFile(inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")), readOptions(this.#options.limits));
+    }
+    pending(recipientInstanceId) {
+        return project(this.records(recipientInstanceId)).pending;
+    }
+    status(recipientInstanceId) {
+        const recipient = opaqueId(recipientInstanceId, "recipient instance");
+        const path = inboxPath(this.#options.coord_root, recipient);
+        const projection = project(this.records(recipient));
+        const pendingBytes = projection.pending.reduce((sum, record) => sum + record.body_bytes, 0);
+        const ratio = Math.max(projection.pending.length / this.#options.limits.max_pending_count, pendingBytes / this.#options.limits.max_pending_bytes);
+        return {
+            schema: HARNERY_INBOX_STATUS_SCHEMA,
+            recipient_instance_id: recipient,
+            pending_count: projection.pending.length,
+            pending_bytes: pendingBytes,
+            total_history_bytes: existsSync(path) ? statSync(path).size : 0,
+            ...(projection.pending[0] ? { oldest_pending_at: projection.pending[0].created_at } : {}),
+            pressure: ratio >= 1
+                ? "exhausted"
+                : ratio >= this.#options.limits.warning_pressure_ratio
+                    ? "warning"
+                    : "normal",
+            ...(projection.lastSurfaceAt ? { last_surface_at: projection.lastSurfaceAt } : {}),
+        };
+    }
+    async surface(recipientInstanceId, emit, budget = {
+        max_count: this.#options.limits.max_surface_count,
+        max_bytes: this.#options.limits.max_surface_bytes,
+        max_tokens: this.#options.limits.max_surface_tokens,
+    }) {
+        validateSurfaceBudget(budget);
+        const recipient = opaqueId(recipientInstanceId, "recipient instance");
+        const selected = selectOldestFitting(this.pending(recipient), budget);
+        await emit(selected);
+        if (selected.length > 0) {
+            const surfacedAt = now(this.#options).toISOString();
+            updateCrashSafeJsonlFile(inboxPath(this.#options.coord_root, recipient), readOptions(this.#options.limits), (records) => {
+                const stillPending = new Set(project(records).pending.map(({ message_id }) => message_id));
+                return {
+                    append: selected
+                        .filter(({ message_id }) => stillPending.has(message_id))
+                        .map(({ message_id }) => ({
+                        schema: HARNERY_INBOX_RECORD_SCHEMA,
+                        kind: "surfaced",
+                        message_id,
+                        surfaced_at: surfacedAt,
+                    })),
+                    result: undefined,
+                };
+            });
+        }
+        const remaining = this.pending(recipient);
+        return {
+            emitted: selected,
+            remaining_pending_count: remaining.length,
+            remaining_pending_bytes: remaining.reduce((sum, record) => sum + record.body_bytes, 0),
+            repeated_after_crash_possible: true,
+        };
+    }
+}
+export function inboxPath(coordRoot, recipientInstanceId) {
+    const id = opaqueId(recipientInstanceId, "recipient instance");
+    return join(resolve(coordRoot), ".harnery", "inbox", `${id}.jsonl`);
+}
+export function project(records) {
+    const messages = new Map();
+    const surfaced = new Set();
+    let lastSurfaceAt;
+    for (const record of records) {
+        validateRecord(record);
+        if (record.kind === "message") {
+            if (messages.has(record.message_id))
+                throw new Error(`duplicate inbox message ${record.message_id}`);
+            messages.set(record.message_id, record);
+        }
+        else {
+            if (!messages.has(record.message_id))
+                throw new Error(`surfaced marker precedes ${record.message_id}`);
+            surfaced.add(record.message_id);
+            if (!lastSurfaceAt || record.surfaced_at > lastSurfaceAt)
+                lastSurfaceAt = record.surfaced_at;
+        }
+    }
+    return {
+        pending: [...messages.values()].filter(({ message_id }) => !surfaced.has(message_id)),
+        surfaced,
+        ...(lastSurfaceAt ? { lastSurfaceAt } : {}),
+    };
+}
+function selectOldestFitting(pending, budget) {
+    const selected = [];
+    let bytes = 0;
+    let tokens = 0;
+    for (const record of pending) {
+        const recordTokens = Math.ceil(record.body_bytes / 4);
+        if (selected.length >= budget.max_count ||
+            bytes + record.body_bytes > budget.max_bytes ||
+            tokens + recordTokens > budget.max_tokens) {
+            break;
+        }
+        selected.push(record);
+        bytes += record.body_bytes;
+        tokens += recordTokens;
+    }
+    return selected;
+}
+function capacityCheck(projection, record, path, limits) {
+    const pendingBytes = projection.pending.reduce((sum, item) => sum + item.body_bytes, 0);
+    if (projection.pending.length + 1 > limits.max_pending_count) {
+        throw new HarneryInboxCapacityError("pending_count_limit", projection.pending.length, limits.max_pending_count);
+    }
+    if (pendingBytes + record.body_bytes > limits.max_pending_bytes) {
+        throw new HarneryInboxCapacityError("pending_bytes_limit", pendingBytes, limits.max_pending_bytes);
+    }
+    const nextHistoryBytes = (existsSync(path) ? statSync(path).size : 0) + Buffer.byteLength(`${JSON.stringify(record)}\n`);
+    if (nextHistoryBytes > limits.max_history_bytes) {
+        throw new HarneryInboxCapacityError("history_bytes_limit", nextHistoryBytes, limits.max_history_bytes);
+    }
+}
+function readOptions(limits) {
+    return {
+        max_record_bytes: Math.max(limits.max_message_body_bytes * 2, 4_096),
+        max_records: limits.max_history_records,
+    };
+}
+function now(options) {
+    return options.now?.() ?? new Date();
+}
+function opaqueId(value, field) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value))
+        throw new Error(`invalid ${field} id`);
+    return value;
+}
+function boundedDisplay(value) {
+    const result = value.trim();
+    if (result.length === 0 || Buffer.byteLength(result) > 256)
+        throw new Error("invalid display name");
+    return result;
+}
+function validateRecord(record) {
+    if (record.schema !== HARNERY_INBOX_RECORD_SCHEMA)
+        throw new Error("unknown inbox record schema");
+    if (record.kind === "message" && Buffer.byteLength(record.body) !== record.body_bytes) {
+        throw new Error(`inbox message ${record.message_id} has invalid body_bytes`);
+    }
+}
+function validateLimits(limits) {
+    for (const [field, value] of Object.entries(limits)) {
+        if (field === "warning_pressure_ratio")
+            continue;
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`invalid inbox limit ${field}`);
+    }
+    if (limits.warning_pressure_ratio <= 0 || limits.warning_pressure_ratio >= 1) {
+        throw new Error("warning_pressure_ratio must be between zero and one");
+    }
+}
+function validateSurfaceBudget(budget) {
+    for (const value of Object.values(budget)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error("invalid inbox surface budget");
+    }
+}

package/dist/core/inbox/watcher.d.ts

@@ -0,0 +1,7 @@
+import type { HarneryInboxMessageRecordV1 } from "./contract.js";
+import type { HarneryInboxService } from "./service.js";
+export declare function watchInbox(service: HarneryInboxService, recipientInstanceId: string, options: {
+    signal: AbortSignal;
+    poll_ms?: number;
+}): AsyncGenerator<HarneryInboxMessageRecordV1>;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/core/inbox/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,wBAAuB,UAAU,CAC/B,OAAO,EAAE,mBAAmB,EAC5B,mBAAmB,EAAE,MAAM,EAC3B,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,cAAc,CAAC,2BAA2B,CAAC,CAc7C"}

package/dist/core/inbox/watcher.js

@@ -0,0 +1,26 @@
+export async function* watchInbox(service, recipientInstanceId, options) {
+    const seen = new Set();
+    while (!options.signal.aborted) {
+        try {
+            for (const message of service.pending(recipientInstanceId)) {
+                if (seen.has(message.message_id))
+                    continue;
+                seen.add(message.message_id);
+                yield message;
+            }
+        }
+        catch {
+            // A transient missing or incomplete source is retried; no cursor is advanced.
+        }
+        await delay(options.poll_ms ?? 250, options.signal);
+    }
+}
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}

package/dist/core/presence/codec-digest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec-digest.d.ts","sourceRoot":"","sources":["../../../src/core/presence/codec-digest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,GACN,MAAM,GACN,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,qBAAqB,CAAC;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAYD,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAI7F;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAoHlC"}
+{"version":3,"file":"codec-digest.d.ts","sourceRoot":"","sources":["../../../src/core/presence/codec-digest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,GACN,MAAM,GACN,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,qBAAqB,CAAC;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAYD,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAI7F;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CA0HlC"}

package/dist/core/presence/codec-digest.js

@@ -85,10 +85,21 @@ export function projectPresenceCodecDigests(events) {
                 break;
             case "context.observed": {
                 const measurement = event.payload.measurement;
-                if (measurement.state === "observed" && measurement.value.limit_tokens > 0) {
+                if (measurement.state === "observed") {
+                    const usedPercent = "used_percent" in measurement.value
+                        ? measurement.value.used_percent
+                        : measurement.value.limit_tokens > 0
+                            ? (measurement.value.used_tokens / measurement.value.limit_tokens) * 100
+                            : undefined;
+                    if (usedPercent === undefined)
+                        break;
                     slot.context = {
-                        used_percent: Math.min(100, Math.max(0, Math.round((measurement.value.used_tokens / measurement.value.limit_tokens) * 100))),
-                        confidence: measurement.confidence === "exact" ? "exact" : "reported",
+                        used_percent: Math.min(100, Math.max(0, Math.round(usedPercent))),
+                        confidence: measurement.attestation === "inferred"
+                            ? "estimated"
+                            : measurement.confidence === "exact"
+                                ? "exact"
+                                : "reported",
                         event_id: event.event_id,
                         observed_at: event.time.observed_at,
                     };

package/dist/core/presence/relay-client.d.ts

@@ -29,6 +29,7 @@
 export declare function ensureRelayDaemon(coordRoot: string): void;
 /** Foreground daemon loop (spawned detached by ensureRelayDaemon). */
 export declare function runRelayDaemon(coordRoot: string): Promise<number>;
+export declare function appendPresenceRelayDiagnostic(coordRoot: string, event: string, fields?: Record<string, unknown>): "shared" | "legacy";
 /** Daemon status for `presence peers`/doctor surfaces. */
 export declare function relayDaemonStatus(coordRoot: string): {
     running: boolean;

package/dist/core/presence/relay-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay-client.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyFH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAwBzD;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoKvE;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAMA"}
+{"version":3,"file":"relay-client.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA6FH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CA0BzD;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuLvE;AAED,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,QAAQ,GAAG,QAAQ,CAiBrB;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAMA"}

package/dist/core/presence/relay-client.js

@@ -22,11 +22,14 @@
  * daemon refuses to start and presence stays on git-refs.
  */
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, watch, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, watch, writeFileSync, } from "node:fs";
 import { join } from "node:path";
+import { coordEnv } from "../../lib/env.js";
 import { resolveMachineLabel } from "../../lib/machine.js";
 import { presenceRelayUrl } from "../config.js";
 import { eventV3ActiveWatchPath } from "../events/v3/reader.js";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.js";
+import { RotatingTextSink } from "../storage/process-log.js";
 import { buildPresenceBlob } from "./blob.js";
 import { originUrl, rootCommitSha, sanitizeRefComponent } from "./git.js";
 import { computeSenderId, decryptPayload, deriveRoomCredentials, encryptPayload, parseRelayFrame, } from "./relay-protocol.js";
@@ -99,13 +102,16 @@ export function ensureRelayDaemon(coordRoot) {
         if (!existsSync(harnBin))
             return;
         mkdirSync(presenceDir(coordRoot), { recursive: true });
-        const log = openSync(logFilePath(coordRoot), "a");
+        const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
+        const log = sharedLogs ? undefined : openSync(logFilePath(coordRoot), "a");
         const child = spawn(harnBin, ["presence", "relay-daemon"], {
             cwd: coordRoot,
             detached: true,
-            stdio: ["ignore", log, log],
+            stdio: log === undefined ? ["ignore", "ignore", "ignore"] : ["ignore", log, log],
             env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
         });
+        if (log !== undefined)
+            closeSync(log);
         child.unref();
     }
     catch {
@@ -116,17 +122,32 @@ export function ensureRelayDaemon(coordRoot) {
 export async function runRelayDaemon(coordRoot) {
     const url = presenceRelayUrl(coordRoot);
     if (!url) {
-        console.error("relay-daemon: no relay configured (presence.relay)");
+        const message = "relay-daemon: no relay configured (presence.relay)";
+        console.error(message);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.configuration_error", { message });
+        }
+        await closeProcessLoggers();
         return 2;
     }
     if (typeof WebSocket === "undefined") {
-        console.error("relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)");
+        const message = "relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)";
+        console.error(message);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.runtime_error", { message });
+        }
+        await closeProcessLoggers();
         return 2;
     }
     const sha = rootCommitSha(coordRoot);
     const origin = originUrl(coordRoot);
     if (!sha || !origin) {
-        console.error("relay-daemon: repo has no commits or no origin remote");
+        const message = "relay-daemon: repo has no commits or no origin remote";
+        console.error(message);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.repository_error", { message });
+        }
+        await closeProcessLoggers();
         return 2;
     }
     // Take (or take over) the pid file. A superseded daemon notices and exits.
@@ -152,6 +173,9 @@ export async function runRelayDaemon(coordRoot) {
     let shuttingDown = false;
     const log = (msg) => {
         console.log(`[${new Date().toISOString()}] ${msg}`);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.lifecycle", { message: msg });
+        }
     };
     const publishNow = async (force = false) => {
         if (!ws || ws.readyState !== WebSocket.OPEN)
@@ -265,7 +289,8 @@ export async function runRelayDaemon(coordRoot) {
             catch {
                 /* ignore */
             }
-            process.exit(0);
+            void closeProcessLoggers().finally(() => process.exit(0));
+            return;
         }
         // Idle machine (no live sessions for a while) → exit; hooks restart us.
         if (idleSince && Date.now() - idleSince > IDLE_EXIT_MS) {
@@ -279,12 +304,31 @@ export async function runRelayDaemon(coordRoot) {
             catch {
                 /* ignore */
             }
-            process.exit(0);
+            void closeProcessLoggers().finally(() => process.exit(0));
         }
     }, KEEPALIVE_MS);
     // Never resolves in normal operation; exits happen above.
     return await new Promise(() => { });
 }
+export function appendPresenceRelayDiagnostic(coordRoot, event, fields = {}) {
+    if (coordEnv("SHARED_LOGS") !== "0") {
+        try {
+            const logger = processLogger(coordRoot, "presence-relay");
+            if (event.includes("error"))
+                logger.error(event, legacyLogFields(fields));
+            else
+                logger.info(event, legacyLogFields(fields));
+            return "shared";
+        }
+        catch {
+            // Bootstrap failures retain a bounded text file for process diagnostics.
+        }
+    }
+    const sink = new RotatingTextSink({ path: logFilePath(coordRoot), max_bytes: 512 * 1_024 });
+    sink.append(`${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), event, ...fields })}\n`);
+    sink.close();
+    return "legacy";
+}
 /** Daemon status for `presence peers`/doctor surfaces. */
 export function relayDaemonStatus(coordRoot) {
     const rec = readPidRecord(coordRoot);

package/dist/core/resources/contract.d.ts

@@ -0,0 +1,90 @@
+export declare const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export declare const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;
+export type ResourceSupportState = "supported" | "partial" | "unsupported" | "error";
+export interface ResourceProcessSample {
+    pid: number;
+    ppid: number;
+    start_id: string;
+    state: string;
+    name: string;
+    command: string;
+    cpu_percent: number | null;
+    rss_bytes: number;
+    age_seconds: number;
+    owner_kind: "agent" | "service" | "unattributed";
+    owner_id: string | null;
+    owner_root_pid: number | null;
+}
+export interface ResourceProcessGroup {
+    kind: ResourceProcessSample["owner_kind"];
+    id: string;
+    process_count: number;
+    cpu_percent: number | null;
+    rss_bytes: number;
+    root_pids: number[];
+}
+export interface ResourceMachineSample {
+    cpu_percent: number | null;
+    cpu_logical_count: number;
+    load_average: [number, number, number] | null;
+    memory_total_bytes: number | null;
+    memory_available_bytes: number | null;
+    memory_used_bytes: number | null;
+    memory_percent: number | null;
+    swap_total_bytes: number | null;
+    swap_used_bytes: number | null;
+    process_count: number;
+}
+export interface ResourceSnapshot {
+    schema_version: typeof RESOURCE_SNAPSHOT_SCHEMA_VERSION;
+    sampled_at: string;
+    interval_ms: number | null;
+    sample_duration_ms: number;
+    collector_cpu_ms: number;
+    platform: NodeJS.Platform;
+    namespace: "host" | "wsl" | "unknown";
+    support: {
+        state: ResourceSupportState;
+        sampler: "procfs" | "unsupported";
+        reason?: string;
+    };
+    machine: ResourceMachineSample;
+    groups: ResourceProcessGroup[];
+    processes: ResourceProcessSample[];
+    visible_process_count: number;
+    omitted_process_count: number;
+    unattributed_process_count: number;
+}
+export interface ResourceServiceStatusRecord {
+    schema_version: typeof RESOURCE_SERVICE_STATUS_SCHEMA_VERSION;
+    pid: number;
+    start_token?: string;
+    host: string;
+    nonce: string;
+    state: "starting" | "running" | "stopping" | "stopped" | "error";
+    started_at: string;
+    heartbeat_at: string;
+    stopped_at?: string;
+    interval_ms: number;
+    sample_count: number;
+    last_sample_at?: string;
+    last_error_code?: string;
+}
+export interface ResourceServiceStatus {
+    running: boolean;
+    stale: boolean;
+    record?: ResourceServiceStatusRecord;
+    status_path: string;
+    snapshot_path: string;
+}
+export interface ResourceSamplerState {
+    sampled_at_ms: number;
+    cpu_total_ticks: number;
+    cpu_idle_ticks: number;
+    process_ticks: Map<string, number>;
+}
+export interface ResourceSampleResult {
+    snapshot: ResourceSnapshot;
+    state?: ResourceSamplerState;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/resources/contract.d.ts.map

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

package/dist/core/resources/contract.js

@@ -0,0 +1,2 @@
+export const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;

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

@@ -0,0 +1,6 @@
+export * from "./contract.js";
+export * from "./sampler.js";
+export * from "./service.js";
+export * from "./service-status.js";
+export * from "./storage.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/resources/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/core/resources/index.js

@@ -0,0 +1,5 @@
+export * from "./contract.js";
+export * from "./sampler.js";
+export * from "./service.js";
+export * from "./service-status.js";
+export * from "./storage.js";

package/dist/core/resources/sampler.d.ts

@@ -0,0 +1,27 @@
+import { type ResourceSampleResult, type ResourceSamplerState } from "./contract.js";
+interface ResourceSamplerOptions {
+    procRoot?: string;
+    nowMs?: number;
+    clockTicks?: number;
+    pageSize?: number;
+    services?: readonly {
+        pid: number;
+        id: string;
+    }[];
+    unattributedCpuFloor?: number;
+    unattributedRssFloor?: number;
+    maxProcesses?: number;
+}
+export declare function sampleResources(coordRoot: string, previous?: ResourceSamplerState, options?: ResourceSamplerOptions): ResourceSampleResult;
+export declare function parseLinuxProcessStat(line: string): {
+    pid: number;
+    name: string;
+    state: string;
+    ppid: number;
+    ticks: number;
+    startTicks: number;
+    rssPages: number;
+} | null;
+export declare function redactCommand(args: readonly string[]): string;
+export {};
+//# sourceMappingURL=sampler.d.ts.map

package/dist/core/resources/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../../src/core/resources/sampler.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AA0BvB,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAKD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,oBAAoB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CAgItB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CA0BP;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAuB7D"}