@evomap/evolver-core 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/trace/learningTrace.js

@@ -0,0 +1,298 @@
+// Agent runtime trace instrumentation (Learning Ops slice 1).
+// Aligns with evomap-hub Learning Ops data plane contract (schemaVersion `trace_event.v0` /
+// `learning_packet.v0`): the runtime emits ordered TraceEvents over the agent-run lifecycle and
+// assembles a LearningPacket DRAFT locally. Hub delivery goes through the LearningPacketSink port —
+// core never hardcodes a hub endpoint (file/console/memory sinks let a run trace without hub access).
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const TRACE_EVENT_SCHEMA = 'trace_event.v0';
+export const LEARNING_PACKET_SCHEMA = 'learning_packet.v0';
+/** Lifecycle vocabulary for slice 1. Kept flat + closed so hub-side eventType stays queryable. */
+export const TRACE_EVENT_TYPES = [
+    'run.started',
+    'run.completed',
+    'model.called',
+    'tool.called',
+    'tool.failed',
+    'retry.attempted',
+    'reflection.recorded',
+    'intervention.received',
+];
+export class InMemoryTraceSink {
+    events = [];
+    emit(event) { this.events.push(event); }
+}
+/** JSONL append sink for local inspection / offline replay. */
+export class FileTraceSink {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    emit(event) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        appendFileSync(this.path, `${JSON.stringify(event)}\n`, 'utf8');
+    }
+}
+export class ConsoleTraceSink {
+    log;
+    constructor(log = (line) => console.error(line)) {
+        this.log = log;
+    }
+    emit(event) { this.log(`[trace] ${event.sequence} ${event.eventType} ${JSON.stringify(event.payload)}`); }
+}
+/**
+ * Per-run trace recorder: the single hook surface the runtime calls at lifecycle points.
+ * Sequence numbers are assigned here (monotonic per run), so downstream ordering never depends on
+ * sink latency or clock resolution.
+ */
+export class AgentRunTraceRecorder {
+    opts;
+    sequence = 0;
+    recorded = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get events() { return this.recorded; }
+    get sessionId() { return this.opts.sessionId; }
+    /**
+     * Late-bind a session id discovered after run start (e.g. unique proxy llm_turn session).
+     * Backfills already-recorded events so the whole trajectory carries the join key.
+     * Fail closed on empty/whitespace values and conflicting rebinds.
+     */
+    bindSessionId(sessionId) {
+        const next = sessionId.trim();
+        if (next.length === 0) {
+            throw new Error('sessionId must be a non-empty string');
+        }
+        const current = this.opts.sessionId;
+        if (current !== undefined) {
+            if (current === next)
+                return;
+            throw new Error(`sessionId already bound to ${current}; refusing to rebind to ${next}`);
+        }
+        this.opts.sessionId = next;
+        for (const event of this.recorded) {
+            event.sessionId = next;
+        }
+    }
+    runStarted(input = {}) {
+        return this.record('run.started', {
+            ...(input.taskSummary !== undefined ? { taskSummary: input.taskSummary } : {}),
+            ...(input.signals !== undefined ? { signals: [...input.signals] } : {}),
+            ...(input.geneId !== undefined ? { geneId: input.geneId } : {}),
+        }, input.metadata);
+    }
+    modelCalled(input = {}) {
+        return this.record('model.called', {
+            ...(input.provider !== undefined ? { provider: input.provider } : {}),
+            ...(input.model !== undefined ? { model: input.model } : {}),
+            ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+            ...(input.latencyMs !== undefined ? { latencyMs: input.latencyMs } : {}),
+            ...(input.usage !== undefined ? { usage: input.usage } : {}),
+            ...(input.stopReason !== undefined ? { stopReason: input.stopReason } : {}),
+        });
+    }
+    toolCalled(input) {
+        return this.record('tool.called', {
+            toolName: input.toolName,
+            ...(input.callId !== undefined ? { callId: input.callId } : {}),
+            ...(input.durationMs !== undefined ? { durationMs: input.durationMs } : {}),
+        }, input.metadata);
+    }
+    toolFailed(input) {
+        return this.record('tool.failed', {
+            toolName: input.toolName,
+            ...(input.callId !== undefined ? { callId: input.callId } : {}),
+            error: input.error,
+        });
+    }
+    retryAttempted(input) {
+        return this.record('retry.attempted', {
+            attempt: input.attempt,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+            ...(input.target !== undefined ? { target: input.target } : {}),
+        });
+    }
+    reflectionRecorded(input) {
+        return this.record('reflection.recorded', {
+            outcome: input.outcome,
+            ...(input.action !== undefined ? { action: input.action } : {}),
+            ...(input.summary !== undefined ? { summary: input.summary } : {}),
+        });
+    }
+    interventionReceived(input) {
+        return this.record('intervention.received', {
+            kind: input.kind,
+            ...(input.actorId !== undefined ? { actorId: input.actorId } : {}),
+            ...(input.detail !== undefined ? { detail: input.detail } : {}),
+        });
+    }
+    runCompleted(input) {
+        return this.record('run.completed', {
+            status: input.status,
+            ...(input.score !== undefined ? { score: input.score } : {}),
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+            ...(input.producedValue !== undefined ? { producedValue: input.producedValue } : {}),
+            ...(input.failureKind !== undefined ? { failureKind: input.failureKind } : {}),
+        });
+    }
+    /** Fold one normalized llm_turn (trace/trajectory.ts) into model.called + tool.called/tool.failed events. */
+    recordLlmTurn(turn) {
+        const out = [this.modelCalled({
+                ...(turn.provider !== null ? { provider: turn.provider } : {}),
+                ...(turn.chosen_model !== null ? { model: turn.chosen_model } : {}),
+                ...(turn.request_id !== null ? { requestId: turn.request_id } : {}),
+                ...(turn.latency_ms !== null ? { latencyMs: turn.latency_ms } : {}),
+                ...(turn.usage !== undefined ? { usage: { ...turn.usage } } : {}),
+                ...(typeof turn.stop_reason === 'string' ? { stopReason: turn.stop_reason } : {}),
+            })];
+        if (Array.isArray(turn.tool_calls)) {
+            for (const call of turn.tool_calls) {
+                const rec = call;
+                const toolName = typeof rec.name === 'string' && rec.name.length > 0 ? rec.name : 'unknown_tool';
+                const callId = typeof rec.id === 'string' ? rec.id : undefined;
+                out.push(typeof rec.error === 'string' && rec.error.length > 0
+                    ? this.toolFailed({ toolName, ...(callId !== undefined ? { callId } : {}), error: rec.error })
+                    : this.toolCalled({ toolName, ...(callId !== undefined ? { callId } : {}) }));
+            }
+        }
+        return out;
+    }
+    record(eventType, payload, metadata) {
+        this.sequence += 1;
+        const at = (this.opts.now ?? Date.now)();
+        const event = {
+            schemaVersion: TRACE_EVENT_SCHEMA,
+            eventId: (this.opts.eventIdFactory ?? ((seq) => `${this.opts.runId}-${String(seq).padStart(4, '0')}`))(this.sequence),
+            eventType,
+            traceId: this.opts.runId,
+            ...(this.opts.sessionId !== undefined ? { sessionId: this.opts.sessionId } : {}),
+            ...(this.opts.taskId !== undefined ? { taskId: this.opts.taskId } : {}),
+            sequence: this.sequence,
+            occurredAt: new Date(at).toISOString(),
+            payload,
+            metadata: metadata ?? {},
+        };
+        this.recorded.push(event);
+        this.opts.sink?.emit(event);
+        return event;
+    }
+}
+/* ── Root-event bridge: existing cycle lifecycle → trace events, via the sanctioned ObserverBus ── */
+const BRIDGED_EVENT_TYPES = [
+    'cycle.started', 'cycle.solidified', 'cycle.failed',
+    'reflection.recorded',
+    'actor.human.nudge', 'actor.human.intervene', 'actor.human.teach',
+    'actor.human.review.approve', 'actor.human.review.reject',
+];
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * Bypass-side bridge (never blocks the write path): maps the engine's existing root events onto the
+ * run's TraceEvent stream, so CycleEngine needs no code change for run start/completion, reflection,
+ * or human intervention coverage.
+ */
+export function learningTraceObserver(deps) {
+    const meta = {
+        name: 'learning_trace',
+        eventTypes: BRIDGED_EVENT_TYPES,
+        idempotent: true,
+        timeoutMs: deps.timeoutMs ?? 2_000,
+    };
+    return {
+        meta,
+        handle(event) {
+            const payload = asRecord(event.payload) ?? {};
+            if (event.type === 'cycle.started') {
+                deps.recorder.runStarted({ metadata: { cycleId: payload['cycleId'] ?? null } });
+                return;
+            }
+            if (event.type === 'cycle.solidified' || event.type === 'cycle.failed') {
+                const outcome = asRecord(payload['outcome']);
+                const status = event.type === 'cycle.solidified' ? 'success' : 'failed';
+                const score = typeof outcome?.['score'] === 'number' ? outcome['score'] : undefined;
+                const reason = typeof payload['error'] === 'string'
+                    ? payload['error']
+                    : typeof payload['reason'] === 'string' ? payload['reason'] : undefined;
+                deps.recorder.runCompleted({
+                    status,
+                    ...(score !== undefined ? { score } : {}),
+                    ...(reason !== undefined ? { reason } : {}),
+                    ...(typeof payload['producedValue'] === 'boolean' ? { producedValue: payload['producedValue'] } : {}),
+                    ...(typeof payload['failureKind'] === 'string' ? { failureKind: payload['failureKind'] } : {}),
+                });
+                return;
+            }
+            if (event.type === 'reflection.recorded') {
+                deps.recorder.reflectionRecorded({
+                    outcome: typeof payload['outcome'] === 'string' ? payload['outcome'] : 'unknown',
+                    ...(typeof payload['action'] === 'string' ? { action: payload['action'] } : {}),
+                    ...(typeof payload['summary'] === 'string' ? { summary: payload['summary'] } : {}),
+                });
+                return;
+            }
+            // actor.human.*: host/human intervention audit trail.
+            deps.recorder.interventionReceived({
+                kind: event.type.replace(/^actor\.human\./, ''),
+                ...(event.actor.id !== undefined ? { actorId: event.actor.id } : {}),
+                ...(typeof payload['detail'] === 'string' ? { detail: payload['detail'] } : {}),
+            });
+        },
+    };
+}
+export function buildLearningPacketDraft(recorder, input) {
+    const events = [...recorder.events].sort((a, b) => a.sequence - b.sequence);
+    const first = events[0];
+    const completed = [...events].reverse().find((e) => e.eventType === 'run.completed');
+    const completedStatus = completed?.payload['status'];
+    const failureKind = completed?.payload['failureKind'];
+    const started = events.find((e) => e.eventType === 'run.started');
+    const startedSummary = started?.payload['taskSummary'];
+    return {
+        schemaVersion: LEARNING_PACKET_SCHEMA,
+        status: 'draft',
+        source: { repo: input.sourceRepo, run: first?.traceId ?? 'unknown-run', type: 'agent_run', id: first?.traceId ?? 'unknown-run' },
+        task: {
+            taskId: first?.taskId ?? null,
+            summary: input.taskSummary ?? (typeof startedSummary === 'string' ? startedSummary : null),
+            signals: [...(input.signals ?? [])],
+        },
+        context: {
+            sessionId: first?.sessionId ?? null,
+            traceId: first?.traceId ?? 'unknown-run',
+            environment: input.environment ?? {},
+        },
+        trajectory: events,
+        artifacts: { placeholder: true, items: [] },
+        evaluation: {
+            placeholder: input.verification === undefined,
+            outcomeStatus: completedStatus === 'success' ? 'success' : completedStatus === 'failed' ? 'failed' : 'unknown',
+            verifier: input.verification?.verifier ?? null,
+            ...(input.verification !== undefined ? { verifierPassed: input.verification.passed } : {}),
+            ...(input.verification?.score !== undefined ? { verifierScore: input.verification.score } : {}),
+            failureCategory: typeof failureKind === 'string' ? failureKind : null,
+        },
+        governance: { placeholder: true, redactionStatus: 'metadata_only', consentStatus: 'unknown', trainingEligible: false, retentionPolicy: 'standard' },
+    };
+}
+export class InMemoryLearningPacketSink {
+    drafts = [];
+    async submit(draft) {
+        this.drafts.push(draft);
+        return { accepted: true };
+    }
+}
+/** Writes one JSON file per run — the offline/no-hub path (and a manual-inspection artifact). */
+export class FileLearningPacketSink {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async submit(draft) {
+        mkdirSync(this.dir, { recursive: true });
+        const path = `${this.dir}/${draft.source.run}.learning-packet.json`;
+        writeFileSync(path, `${JSON.stringify(draft, null, 2)}\n`, 'utf8');
+        return { accepted: true, reason: path };
+    }
+}

package/dist/trace/proxyTurns.d.ts

@@ -0,0 +1,31 @@
+import { type TraceReadOptions } from './trajectoryExport.js';
+import { type TraceTurnDraft } from './trajectory.js';
+/** One agent run's wall-clock window (epoch ms, same host clock as the proxy's ts). */
+export interface RunTurnWindow {
+    startMs: number;
+    endMs: number;
+}
+export interface SelectRunLlmTurnsOptions {
+    /**
+     * Exact-match correlation key: when the caller knows the spawned agent's session id, only that session's
+     * turns are returned (the window heuristic is skipped — the id is authoritative).
+     */
+    sessionId?: string;
+}
+export interface CollectRunLlmTurnsOptions extends SelectRunLlmTurnsOptions {
+    /** Decryption material forwarded to readTraceRowsFromJsonl. allowPartial is always forced on. */
+    readOptions?: TraceReadOptions;
+}
+/**
+ * Pure selector (unit-testable without fs): pick the turns that belong to the run per the correlation
+ * contract above, sorted by ts ascending (stable — equal timestamps keep day-file append order, and the
+ * recorder's fold order becomes the sequence order).
+ */
+export declare function selectRunLlmTurns(turns: readonly TraceTurnDraft[], window: RunTurnWindow, opts?: SelectRunLlmTurnsOptions): TraceTurnDraft[];
+/**
+ * Read the proxy trace day-files in `dir` and return this run's llm_turns (see the correlation contract
+ * above), ready to fold via recordLlmTurn. Reuses readTraceRowsFromJsonl (decryption + row parsing) and
+ * traceRecordToTurnDraft (normalization). Never throws: any failure — no proxy, missing dir, unreadable
+ * file, undecryptable rows — degrades to [].
+ */
+export declare function collectRunLlmTurns(dir: string, window: RunTurnWindow, opts?: CollectRunLlmTurnsOptions): TraceTurnDraft[];

package/dist/trace/proxyTurns.js

@@ -0,0 +1,137 @@
+// Proxy llm_turn → run fold (Learning Ops slice 5): collect the per-request llm_turn records the LLM proxy
+// captured DURING one agent run's wall-clock window, normalized as TraceTurnDrafts ready for
+// AgentRunTraceRecorder.recordLlmTurn. This is what upgrades a run's trajectory from the bridge's single
+// coarse model.called (the headless runner is a black box) to real per-request fidelity
+// (provider/model/usage/latency/stop_reason + tool-call detail).
+//
+// Correlation contract (why time window + session-first-turn, not session_id alone): the headless runner does
+// not report its session id back to the bridge (`claude -p --output-format text` is opaque), and llm_turn rows
+// carry no cwd — so the run has no exact key to look up. What the run DOES own is its wall-clock window on the
+// same host the proxy writes from (one shared clock, no skew). A turn belongs to the run iff:
+//   1. its ts falls inside [startMs, endMs], AND
+//   2. its session's FIRST observed turn also falls inside the window — a session spawned by this run cannot
+//      have traffic predating the run, while a concurrent interactive session (started earlier) is excluded by
+//      its pre-window history. Sessionless turns (session_id null) fall back to the window test alone.
+// Callers that DO know the spawned agent's session id (e.g. a future runner passing --session-id) can pass
+// `sessionId` for exact-match correlation instead of the heuristic.
+//
+// Residual risk, accepted + documented: an interactive session whose very first request starts inside the run
+// window is indistinguishable from the run's own agent. On an unattended daemon host this is rare, and the
+// fold is observability-only — it can bias a trace, never a verdict.
+//
+// Everything degrades silently to [] (missing dir, unreadable file, undecryptable envelope, bad ts): the
+// learning trace must never fail or slow a task.
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readTraceRowsFromJsonl } from './trajectoryExport.js';
+import { traceRecordToTurnDraft } from './trajectory.js';
+/** Any proxy day-file (`llm-trace-*.jsonl`). */
+const TRACE_FILE_RE = /^llm-trace-.*\.jsonl$/i;
+/** The canonical day-stamped name the proxy's JsonlTraceSink writes (`llm-trace-YYYYMMDD.jsonl`, UTC). */
+const DAY_STAMPED_FILE_RE = /^llm-trace-(\d{8})\.jsonl$/i;
+function utcDayStamp(ms) {
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}`;
+}
+/**
+ * Keep day-stamped files that could contain the window's turns. Heuristic correlation must inspect all earlier
+ * day files to prove that an in-window session did not start before the run; exact session-id correlation only
+ * needs files that overlap the run window.
+ * Non-day-stamped `llm-trace-*.jsonl` names (custom sinks/tests) are kept conservatively — the ts window
+ * filter below is the authority; the filename filter only trims read volume.
+ */
+function fileCoversWindow(name, window, includeSessionHistory) {
+    const match = DAY_STAMPED_FILE_RE.exec(name);
+    if (!match)
+        return true;
+    const stamp = match[1];
+    return (includeSessionHistory || stamp >= utcDayStamp(window.startMs)) && stamp <= utcDayStamp(window.endMs);
+}
+function turnTsMs(turn) {
+    if (turn.ts === null)
+        return null;
+    const ms = Date.parse(turn.ts);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Pure selector (unit-testable without fs): pick the turns that belong to the run per the correlation
+ * contract above, sorted by ts ascending (stable — equal timestamps keep day-file append order, and the
+ * recorder's fold order becomes the sequence order).
+ */
+export function selectRunLlmTurns(turns, window, opts = {}) {
+    const stamped = turns
+        .map((turn) => ({ turn, tsMs: turnTsMs(turn) }))
+        .filter((entry) => entry.tsMs !== null);
+    let selected;
+    if (opts.sessionId !== undefined) {
+        selected = stamped.filter(({ turn }) => turn.session_id === opts.sessionId);
+    }
+    else {
+        // First observed turn per session across ALL provided turns (including pre-window rows from the same
+        // day files) — this is what tells an in-run spawned session apart from an older concurrent one.
+        const firstTsBySession = new Map();
+        for (const { turn, tsMs } of stamped) {
+            if (turn.session_id === null)
+                continue;
+            const prev = firstTsBySession.get(turn.session_id);
+            if (prev === undefined || tsMs < prev)
+                firstTsBySession.set(turn.session_id, tsMs);
+        }
+        selected = stamped.filter(({ turn, tsMs }) => {
+            if (tsMs < window.startMs || tsMs > window.endMs)
+                return false;
+            if (turn.session_id === null)
+                return true;
+            const firstTs = firstTsBySession.get(turn.session_id);
+            return firstTs !== undefined && firstTs >= window.startMs;
+        });
+    }
+    return selected
+        .map((entry, index) => ({ ...entry, index }))
+        .sort((a, b) => a.tsMs - b.tsMs || a.index - b.index)
+        .map(({ turn }) => turn);
+}
+/**
+ * Read the proxy trace day-files in `dir` and return this run's llm_turns (see the correlation contract
+ * above), ready to fold via recordLlmTurn. Reuses readTraceRowsFromJsonl (decryption + row parsing) and
+ * traceRecordToTurnDraft (normalization). Never throws: any failure — no proxy, missing dir, unreadable
+ * file, undecryptable rows — degrades to [].
+ */
+export function collectRunLlmTurns(dir, window, opts = {}) {
+    try {
+        if (!(window.endMs >= window.startMs))
+            return [];
+        const names = readdirSync(dir)
+            .filter((name) => TRACE_FILE_RE.test(name) && fileCoversWindow(name, window, opts.sessionId === undefined))
+            .sort();
+        const turns = [];
+        for (const name of names) {
+            const dayMatch = DAY_STAMPED_FILE_RE.exec(name);
+            const isHistoricalDay = opts.sessionId === undefined
+                && dayMatch !== null
+                && dayMatch[1] < utcDayStamp(window.startMs);
+            let text;
+            try {
+                text = readFileSync(join(dir, name), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            // allowPartial forced on: an undecryptable envelope is a coverage gap, never a fold failure.
+            const { rows } = readTraceRowsFromJsonl(text, { ...(opts.readOptions ?? {}), allowPartial: true });
+            for (const row of rows) {
+                const turn = traceRecordToTurnDraft(row);
+                if (turn !== null) {
+                    // Older day files establish that a session predates this run; they can never contribute candidate
+                    // turns even if a malformed row carries an in-window timestamp.
+                    turns.push(isHistoricalDay ? { ...turn, ts: new Date(window.startMs - 1).toISOString() } : turn);
+                }
+            }
+        }
+        return selectRunLlmTurns(turns, window, opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {});
+    }
+    catch {
+        return [];
+    }
+}

package/dist/trace/trajectory.d.ts

@@ -78,5 +78,13 @@ export interface TraceTrajectoryDraft {
     coverage: TraceCoverageItem[];
 }
 export declare function traceRecordToTurnDraft(record: NativeTraceRecord): TraceTurnDraft | null;
+/**
+ * Exact-join helper for Learning Ops: return the unique non-empty session id across turns.
+ * Fail closed — 0 or >1 distinct ids yield null. Matches the correlation key contract used by
+ * Darwin (`cc::<session_id>` ↔ packet `traceEvents[].sessionId`).
+ */
+export declare function uniqueSessionId(turns: readonly {
+    session_id?: string | null;
+}[]): string | null;
 export declare function buildTraceTrajectoryDraft(records: readonly NativeTraceRecord[]): TraceTrajectoryDraft;
 export declare function coverageForTurns(turns: readonly TraceTurnDraft[]): TraceCoverageItem[];

package/dist/trace/trajectory.js

@@ -95,12 +95,24 @@ export function traceRecordToTurnDraft(record) {
         ...(validation !== undefined ? { validation } : {}),
     };
 }
+/**
+ * Exact-join helper for Learning Ops: return the unique non-empty session id across turns.
+ * Fail closed — 0 or >1 distinct ids yield null. Matches the correlation key contract used by
+ * Darwin (`cc::<session_id>` ↔ packet `traceEvents[].sessionId`).
+ */
+export function uniqueSessionId(turns) {
+    const sessionIds = [
+        ...new Set(turns
+            .map((turn) => turn.session_id)
+            .filter((value) => typeof value === 'string' && value.length > 0)),
+    ];
+    return sessionIds.length === 1 ? sessionIds[0] : null;
+}
 export function buildTraceTrajectoryDraft(records) {
     const turns = records.map(traceRecordToTurnDraft).filter((turn) => turn !== null);
-    const sessionIds = [...new Set(turns.map((turn) => turn.session_id).filter((value) => typeof value === 'string' && value.length > 0))];
     return {
         schema: 'evolver_trace_trajectory_draft.v1',
-        session_id: sessionIds.length === 1 ? sessionIds[0] : null,
+        session_id: uniqueSessionId(turns),
         turns,
         coverage: coverageForTurns(turns),
     };

package/dist/util/fetchPort.d.ts

@@ -0,0 +1 @@
+export declare function isFetchForbiddenPort(port: number): boolean;

package/dist/util/fetchPort.js

@@ -0,0 +1,11 @@
+// https://fetch.spec.whatwg.org/#port-blocking
+const FETCH_FORBIDDEN_PORTS = new Set([
+    1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95,
+    101, 102, 103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179,
+    389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601,
+    636, 989, 990, 993, 995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000,
+    6566, 6665, 6666, 6667, 6668, 6669, 6679, 6697, 10080,
+]);
+export function isFetchForbiddenPort(port) {
+    return Number.isInteger(port) && FETCH_FORBIDDEN_PORTS.has(port);
+}

package/dist/util/fileLock.d.ts

@@ -1,24 +1,130 @@
 export declare function syncSleep(ms: number): void;
+export type FileLockProcessStartIdentity = {
+    readonly source: 'linux-proc';
+    readonly bootId: string;
+    readonly startTicks: string;
+} | {
+    readonly source: 'windows-powershell';
+    readonly startTimeTicks: string;
+} | {
+    readonly source: 'darwin-ps';
+    readonly startTime: string;
+};
+export interface FileLockOwnerRecord {
+    readonly pid: number;
+    readonly token: string;
+    readonly processStartIdentity: FileLockProcessStartIdentity;
+}
+export type TransferLockOwnershipReason = 'transferred' | 'not_owned' | 'ownership_changed' | 'mutation_busy' | 'guardian_exists' | 'guardian_missing' | 'target_process_dead' | 'target_process_pid_reused' | 'target_process_unverifiable' | 'path_changed';
+export type TransferLockOwnershipResult = {
+    transferred: true;
+    reason: 'transferred';
+    guardian: FileLockOwnerRecord;
+} | {
+    transferred: false;
+    reason: Exclude<TransferLockOwnershipReason, 'transferred'>;
+};
+export type AttachLockGuardianResult = {
+    attached: true;
+    reason: 'attached';
+    guardian: FileLockOwnerRecord;
+} | {
+    attached: false;
+    reason: Exclude<TransferLockOwnershipReason, 'transferred'>;
+};
+export type RetainLockGuardianResult = {
+    retained: true;
+    reason: 'retained';
+} | {
+    retained: false;
+    reason: 'not_owned' | 'ownership_changed' | 'mutation_busy' | 'guardian_missing' | 'path_changed';
+};
+export type ClearLockGuardianResult = {
+    cleared: true;
+    reason: 'cleared' | 'missing';
+} | {
+    cleared: false;
+    reason: 'not_owned' | 'ownership_changed' | 'mutation_busy' | 'path_changed';
+};
+export type FileLockOwnerProcessStatus = 'current' | 'dead' | 'pid_reused' | 'unverifiable';
 export declare class LockTimeoutError extends Error {
     readonly code = "LOCK_TIMEOUT";
-    constructor(lockPath: string);
+    constructor(_lockPath?: string);
+}
+export type UnsafeLockPathReason = 'symlink' | 'not_regular_file' | 'owner_too_large' | 'path_changed' | 'permission_denied' | 'process_identity_unavailable' | 'invalid_owner';
+export declare class UnsafeLockPathError extends Error {
+    readonly reason: UnsafeLockPathReason;
+    readonly code = "UNSAFE_LOCK_PATH";
+    constructor(reason: UnsafeLockPathReason);
 }
+export declare const MAX_LOCK_OWNER_BYTES = 4096;
+/** Fresh native process-start observation. Unlike lock acquisition, this does not use caches. */
+export declare function readFileLockProcessStartIdentity(pid: number): FileLockProcessStartIdentity | null;
+export declare function sameFileLockProcessStartIdentity(left: FileLockProcessStartIdentity, right: FileLockProcessStartIdentity): boolean;
+export declare function parseFileLockProcessStartIdentity(value: unknown): FileLockProcessStartIdentity | undefined;
+/**
+ * Conservative owner classification for crash recovery. PID reuse and unavailable identity
+ * remain distinct from a proven-dead PID so callers cannot reclaim ambiguous ownership.
+ */
+export declare function inspectFileLockOwnerProcess(owner: Pick<FileLockOwnerRecord, 'pid' | 'processStartIdentity'>): FileLockOwnerProcessStatus;
+export declare function _setFileLockTestHooksForTest(hooks?: {
+    processStartIdentity?: (pid: number) => FileLockProcessStartIdentity | null;
+    pidAlive?: (pid: number) => boolean;
+    beforeOwnerPublish?: (temporaryPath: string, lockPath: string) => void;
+    beforeGuardianPublish?: (temporaryPath: string, guardianPath: string) => void;
+    afterGuardianPublish?: (guardianPath: string, lockPath: string) => void;
+    beforeGuardianReclaim?: (guardianPath: string, lockPath: string) => void;
+    beforeMutationGuardRelease?: (mutationGuardPath: string, lockPath: string) => void;
+}): void;
+/**
+ * Pre-arm an acquired lock with the exact child PID generation while retaining local ownership.
+ * A controller can therefore keep mutating its journal, while a hard controller crash cannot make
+ * the primary owner reclaimable until the child exits.
+ */
+export declare function attachLockGuardianToProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, targetPid: number): AttachLockGuardianResult;
+/**
+ * Drop local ownership only after an already-published guardian has been revalidated exactly.
+ * No file mutation is needed: the durable guardian receipt is the crash-safe owner binding.
+ */
+export declare function retainLockGuardianForProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, expectedGuardian: FileLockOwnerRecord): RetainLockGuardianResult;
+/**
+ * Remove an exact attached guardian after the child has definitely exited, retaining the primary
+ * owner so rollback or another launch can continue under the same lifecycle lease.
+ */
+export declare function clearLockGuardianForProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, expectedGuardian: FileLockOwnerRecord): ClearLockGuardianResult;
+/**
+ * Atomically bind an acquired lock to a still-running child and relinquish local ownership.
+ */
+export declare function transferLockOwnershipToProcess(lockPath: string, expectedOwner: FileLockOwnerRecord, targetPid: number): TransferLockOwnershipResult;
 export interface AcquireLockOptions {
     maxTries?: number;
     waitMs?: number;
 }
 /**
- * Cross-process O_EXCL file lock with crashed-owner recovery.
+ * Cross-process file lock with crashed-owner recovery.
  *
  * The lock file records the owner pid and token. If a waiter finds the lock held by a pid that is no longer
  * alive (the owner crashed without releaseLock), it reclaims the stale lock instead of spinning
  * until timeout — otherwise one crashed process would deadlock every future writer until the file
- * is removed by hand. Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside
- * under a mutation guard before deletion so waiters cannot delete each other's newly-created locks.
- * A live owner's lock (including this process's own) is never stolen.
+ * is removed by hand. Empty or truncated locks are reclaimed only after the same inode and contents
+ * remain malformed for a grace period, so a live creator can finish publishing its owner payload.
+ * Acquisition publishes a fully synced temporary owner with an atomic no-replace hardlink, and stale
+ * reclaim moves the old lock aside under a mutation guard, then verifies the inode snapshot before
+ * deletion. A live owner's lock (including this
+ * process's own) is never stolen.
  *
  * NOTE: still synchronous (blocks the event loop while waiting) by design — it guards short
  * synchronous critical sections (append-only writes).
  */
-export declare function acquireLock(lockPath: string, opts?: AcquireLockOptions): void;
-export declare function releaseLock(lockPath: string): void;
+export declare function acquireLock(lockPath: string, opts?: AcquireLockOptions): FileLockOwnerRecord;
+export type ReleaseLockReason = 'released' | 'missing' | 'ownership_changed' | 'not_owned' | 'released_with_cleanup_error' | UnsafeLockPathReason | 'release_failed';
+export interface ReleaseLockResult {
+    released: boolean;
+    reason: ReleaseLockReason;
+}
+export declare function releaseLock(lockPath: string): ReleaseLockResult;
+export declare class LockReleaseError extends Error {
+    readonly reason: ReleaseLockReason;
+    readonly code = "LOCK_RELEASE_FAILED";
+    constructor(reason: ReleaseLockReason);
+}