@sema-agent/core 7.6.0 → 7.6.1

package/dist/core/types.js

@@ -1,76 +1,2 @@
-import { observeThenableRejection } from "./safe-notify.js";
-let malformedDelegationSeatAnnounced = false;
-export function __resetMalformedDelegationSeatAnnouncement() {
-    malformedDelegationSeatAnnounced = false;
-}
-export function deliverDelegationLifecycle(seat, event, notifier, site) {
-    if (typeof seat === "function") {
-        const frame = Object.freeze(Object.assign(Object.create(null), event));
-        notifier.notify(() => observeThenableRejection(seat(frame), notifier, site), site);
-        return;
-    }
-    if (seat !== undefined && !malformedDelegationSeatAnnounced) {
-        malformedDelegationSeatAnnounced = true;
-        try {
-            console.warn(`The delegation-lifecycle sink (RunnerDeps.onDelegationLifecycle) holds ${seat === null ? "null" : typeof seat} — not a ` +
-                `function. Delegation spawn/terminal frames are NOT delivered until the wiring is fixed (omit the key, or wire a function).`);
-        }
-        catch {
-        }
-    }
-}
-let malformedNoticeSeatAnnounced = false;
-export function __resetMalformedNoticeSeatAnnouncement() {
-    malformedNoticeSeatAnnounced = false;
-}
-export function deliverEngineNotice(onNotice, notice) {
-    if (notice.sessionId === undefined && typeof notice.detail?.["sessionId"] === "string") {
-        notice = { ...notice, sessionId: notice.detail["sessionId"] };
-    }
-    if (typeof onNotice === "function") {
-        try {
-            const r = onNotice(notice);
-            if (typeof r?.then === "function") {
-                r.then(undefined, () => {
-                });
-            }
-        }
-        catch {
-        }
-        return;
-    }
-    if (onNotice !== undefined) {
-        if (!malformedNoticeSeatAnnounced) {
-            malformedNoticeSeatAnnounced = true;
-            try {
-                console.warn(`The structured notice sink (RunnerDeps.onNotice) holds ${onNotice === null ? "null" : typeof onNotice} — not a ` +
-                    `function. Notices fall back to console.warn until the wiring is fixed (omit the key, or wire a function).`);
-            }
-            catch {
-            }
-        }
-    }
-    console.warn(notice.message);
-}
-export function undrainedUserInputNotices(counts, taskId, sessionId, runId) {
-    const tid = taskId !== undefined ? { taskId } : {};
-    const sid = sessionId !== undefined ? { sessionId } : {};
-    const rid = runId !== undefined ? { runId } : {};
-    const tail = `accepted as "queued" were never consumed — the run ended first. They are NOT redelivered; re-send against a live run if still wanted.`;
-    const out = [];
-    if (counts.steer > 0) {
-        out.push({
-            code: "task.user_steer_undrained",
-            message: `${counts.steer} user steer(s) ${tail}`,
-            detail: { steer: counts.steer, ...tid, ...sid, ...rid },
-        });
-    }
-    if (counts.followUp > 0) {
-        out.push({
-            code: "task.user_followup_undrained",
-            message: `${counts.followUp} user follow-up(s) ${tail}`,
-            detail: { followUp: counts.followUp, ...tid, ...sid, ...rid },
-        });
-    }
-    return out;
-}
+export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
+export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, undrainedUserInputNotices } from "./engine-notice.js";

package/dist/core/warm-resume.d.ts

@@ -1,4 +1,4 @@
-import type { Runner } from "./runner/runtask.js";
+import type { RunnerSelfSeat } from "./runner/contracts.js";
 import type { TaskResult, TaskSpec } from "./types.js";
 /**
  * design/114 P0 — a convenience for the RECOMMENDED safe warm-resume of a (failed / timed-out) run: FORK the
@@ -17,6 +17,6 @@ import type { TaskResult, TaskSpec } from "./types.js";
  * the directive for picking up the work; pass the model (and any other spec fields) via `opts` — a continuation
  * still needs a model like any task.
  */
-export declare function warmResume(runner: Runner, sessionId: string, objective: string, opts?: Omit<Partial<TaskSpec>, "objective" | "sessionId"> & {
+export declare function warmResume(runner: RunnerSelfSeat, sessionId: string, objective: string, opts?: Omit<Partial<TaskSpec>, "objective" | "sessionId"> & {
     owner?: string | null;
 }): Promise<TaskResult | null>;

package/dist/index.d.ts

@@ -8,6 +8,7 @@
 export { Runner, runTask } from "./core/runner/runtask.js";
 export { resolveTaskLimits } from "./core/runner/prepare-task.js";
 export type { RunInternals, ResolvedWorkspace } from "./core/runner/prepare-task.js";
+export type { RunnerSelfSeat } from "./core/runner/contracts.js";
 export type { BudgetAxis } from "./core/runner/assemble-result.js";
 export { terminalProjection } from "./core/runner/terminal-projection.js";
 export { SESSION_LOG_DIGEST_SCHEME, sessionEntryDigest, sessionLogDigest, sessionLogDigestsComparable, } from "./engine/session/log-digest.js";
@@ -113,7 +114,7 @@ export type { FileHistoryStore, FileHistoryResult, FileHistoryTrackResult, FileH
 export type { InMemoryFileHistoryStoreOptions } from "./core/file-history-store.js";
 export { DEFAULT_FILE_HISTORY_BOUNDARY_KEEP, resolveFileHistoryRetention, fileHistoryBoundariesToKeep } from "./core/file-history-retention.js";
 export type { FileHistoryRetentionPolicy } from "./core/file-history-retention.js";
-export { FileStorageBackend, FileSessionRepo, FileCheckpointStore, FileMemoryStore, FileToolResultStore, FileSessionPolicyStore, FileStrategyStore, FileFileHistoryStore, FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult, resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock, atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog, FileStoreLockError, type FileStoreLockErrorCode, type FileStorageBackendOptions, type FileStorageCorruptReadInfo, type FileStrategyStoreOptions, type FileFileHistoryStoreOptions, type FileSessionRepoOptions, type FileCheckpointStoreOptions, } from "./stores/file/index.js";
+export { FileStorageBackend, FileSessionRepo, FileCheckpointStore, FileMemoryStore, FileToolResultStore, FileSessionPolicyStore, FileStrategyStore, FileFileHistoryStore, FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult, resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock, atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog, FileStoreLockError, type FileStoreLockErrorCode, processFingerprint, isProcessLive, type ProcessFingerprint, type FileStorageBackendOptions, type FileStorageCorruptReadInfo, type FileStrategyStoreOptions, type FileFileHistoryStoreOptions, type FileSessionRepoOptions, type FileCheckpointStoreOptions, } from "./stores/file/index.js";
 export { CacheBreakDetector, type CacheBreakFinding, type ToolFingerprintInput } from "./core/cache-break-detector.js";
 export { maybeCompact, type MaybeCompactOptions, type CompactionWindowSafetyInfo } from "./core/auto-compaction.js";
 export { brainToRuntime } from "./core/runtime.js";

package/dist/index.js

@@ -90,7 +90,7 @@ export { worldStillMatchesMint } from "./core/file-history-store.js";
 export { trackKeyOf as fileHistoryTrackKeyOf, resolveTrackKey as fileHistoryResolveTrackKey } from "./core/file-history-store.js";
 export { describeTrackKey as fileHistoryDescribeTrackKey, trackKeyFamilyOf as fileHistoryKeyFamilyOf, fileHistoryExportDigest, validateFileHistoryExport } from "./core/file-history-store.js";
 export { DEFAULT_FILE_HISTORY_BOUNDARY_KEEP, resolveFileHistoryRetention, fileHistoryBoundariesToKeep } from "./core/file-history-retention.js";
-export { FileStorageBackend, FileSessionRepo, FileCheckpointStore, FileMemoryStore, FileToolResultStore, FileSessionPolicyStore, FileStrategyStore, FileFileHistoryStore, FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult, resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock, atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog, FileStoreLockError, } from "./stores/file/index.js";
+export { FileStorageBackend, FileSessionRepo, FileCheckpointStore, FileMemoryStore, FileToolResultStore, FileSessionPolicyStore, FileStrategyStore, FileFileHistoryStore, FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult, resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock, atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog, FileStoreLockError, processFingerprint, isProcessLive, } from "./stores/file/index.js";
 export { CacheBreakDetector } from "./core/cache-break-detector.js";
 export { maybeCompact } from "./core/auto-compaction.js";
 export { brainToRuntime } from "./core/runtime.js";

package/dist/orchestration/goal.d.ts

@@ -11,7 +11,7 @@
  * **无任何 commit/accept 副作用**(纯 loop,同 runRepairLoop SAFE-tier 永不 `fixed`)。要 accept,caller 自走
  * design/77 Gate-1 out-of-process oracle 隔离边界,不在 goal helper 开后门。
  */
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { CheckpointToken } from "../core/checkpoint-store.js";
 import type { TaskResult, TaskSpec } from "../core/types.js";
 /** Read-only snapshot a `doneCheck` sees after one iteration. */
@@ -103,4 +103,4 @@ export declare const DECLARE_DONE_TOOL_NAME = "DeclareDone";
  * doneCheck feeds its reason back (fenced) and continues. Bounded by maxIterations / budget / wall-clock /
  * cancel; a durable pause (suspended/needs_review) is a hard boundary that surfaces the checkpointToken.
  */
-export declare function runGoal(runner: Runner, spec: GoalSpec): Promise<GoalResult>;
+export declare function runGoal(runner: RunnerSelfSeat, spec: GoalSpec): Promise<GoalResult>;

package/dist/orchestration/run-spec.d.ts

@@ -25,7 +25,7 @@
  * 生命周期(调用方保证起点是干净树 —— preflight 红才有意义)、模型/Runner 装配、chaos 包装。frozen 写入
  * 面:policy 只挡 Write/Edit 族 = belt;bash 写入由快照恢复兜(suspenders);危险 bash deny 仍是使用方纪律。
  */
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { TaskResult, TaskSpec } from "../core/types.js";
 import type { TaskOutcome } from "../core/task-outcome.js";
 import { type OracleBaseline, type OracleGateResult, type OracleVerdict, type SpecContract } from "../core/spec-contract.js";
@@ -59,4 +59,4 @@ export interface RunSpecResult {
  * `spec.frozen_path_invalid`, `spec.frozen_missing`, `spec.spec_unreadable`, `spec.not_red`,
  * `spec.oracle_error`.
  */
-export declare function runSpec(runner: Pick<Runner, "runTask"> & Partial<Pick<Runner, "emitTaskOutcome" | "gateBaseline">>, contract: SpecContract, opts: RunSpecOptions): Promise<RunSpecResult>;
+export declare function runSpec(runner: Pick<RunnerSelfSeat, "runTask"> & Partial<Pick<RunnerSelfSeat, "emitTaskOutcome" | "gateBaseline">>, contract: SpecContract, opts: RunSpecOptions): Promise<RunSpecResult>;

package/dist/orchestration/run-workflow-tool.d.ts

@@ -11,7 +11,7 @@
  */
 import type { AgentTool } from "../internal/harness-types.js";
 import type { Model } from "../internal/llm.js";
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { WorkflowGovernanceBaseline } from "../core/types.js";
 import type { WorkflowRunStore } from "../core/workflow-run-store.js";
 import type { WorkflowJournalStore } from "../core/workflow-journal-store.js";
@@ -128,7 +128,7 @@ export declare function workflowWhenToUseText(m: {
 export declare function renderNamedWorkflowListing(entries: ReadonlyArray<NamedWorkflowListing>): string | undefined;
 export interface RunWorkflowToolDeps {
     /** The Runner that executes child tasks (the workflow's `ctx.agent` → `runner.runTask`). */
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /** The HARD sandbox (asserted `safeForUntrustedScripts:true`). */
     scriptRunner: WorkflowScriptRunner;
     /** Deployment-trusted governance every spawned agent inherits (design/98 §2.5). */
@@ -322,7 +322,7 @@ export interface RunWorkflowToolDeps {
      *  trusted internals — workflow children inherit the host's evaluated gate exactly like a
      *  `createSubagentTool` delegation. (A dep for the same reason as `forwardEvent`: the direct mount's
      *  execute ctx is minimal; `ctx.inheritedGateForChildren` still wins when a wrapping path provides it.) */
-    inheritedGateForChildren?: () => import("../core/runner/prepare-task.js").InheritedGate;
+    inheritedGateForChildren?: () => import("../core/runner/contracts.js").InheritedGate;
     /** RB-201 FO-3 — the HOST session's auto-mode classifier, threaded via `RunWorkflowOptions.autoModeReview`
      *  so every child this workflow spawns is reviewed before it starts, exactly like a `createSubagentTool`
      *  delegation's child. (A dep for the same reason as `forwardEvent`/`inheritedGateForChildren`: the direct

package/dist/orchestration/workflow.d.ts

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { AgentDefinition, TaskEvent, TaskResult, TaskSpec } from "../core/types.js";
 import type { WorkflowRunStore } from "../core/workflow-run-store.js";
 import type { WorkflowJournalStore, ResumeClaimArgs } from "../core/workflow-journal-store.js";
@@ -452,7 +452,7 @@ export interface RunWorkflowOptions {
      *  (`RunInternals.inheritedGate`) on both spawn legs (`agent()` and `agentStream()`). Set by the
      *  `run_workflow` tool wiring; a directly-started workflow may pass its own. Absent ⇒ children run
      *  under only their own gates (pre-seam behavior). TRUSTED: never a script/model argument. */
-    inheritedGate?: import("../core/runner/prepare-task.js").InheritedGate;
+    inheritedGate?: import("../core/runner/contracts.js").InheritedGate;
     /** RB-201 FO-3 (workflow lane) — the session's auto-mode classifier, consulted BEFORE each script-spawned
      *  child starts (objective + toolset + output schema, finalized). The delegation-tool lane reviews its
      *  children at one shared point; a workflow's children reach `runner.runTask` through this module instead,
@@ -553,11 +553,11 @@ export declare const workflowResumeClaimFallback: {
  * `done` rejects. `cancel(reason)` aborts the whole run. A nesting/validation violation throws SYNCHRONOUSLY
  * from this call (before any handle exists). Thin composition over `runner.runTask` — no Runner changes.
  */
-export declare function startWorkflow<T>(runner: Runner, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): WorkflowHandle<T>;
+export declare function startWorkflow<T>(runner: RunnerSelfSeat, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): WorkflowHandle<T>;
 /**
  * Run a workflow to completion (design/97 S1a) — the thin await over {@link startWorkflow}: returns the
  * script's value + the assembled {@link WorkflowRun}. A synchronous nesting/validation throw from
  * `startWorkflow` becomes a rejected promise here (this function is `async`), preserving the original
  * `runWorkflow` contract (`await runWorkflow(...)` rejects rather than throwing synchronously).
  */
-export declare function runWorkflow<T>(runner: Runner, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): Promise<RunWorkflowResult<T>>;
+export declare function runWorkflow<T>(runner: RunnerSelfSeat, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): Promise<RunWorkflowResult<T>>;

package/dist/scenarios/scenario-registry.d.ts

@@ -11,7 +11,7 @@
  * yet implemented). The model pairing (who's cheap / who's strong / heterogeneous decorrelation) is
  * deploy-side knowledge — core fills guard-number defaults + prompts + orchestrator choice, never the model.
  */
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { ModelRef, ModelRole, TaskSpec } from "../core/types.js";
 import { type TeamResult } from "../agents/team.js";
 import { type VerificationResult } from "../agents/verify.js";
@@ -59,7 +59,7 @@ export interface ScenarioProfile {
 export declare const SCENARIO_REGISTRY: Record<ScenarioId, ScenarioProfile>;
 export interface RunScenarioOptions {
     scenario: ScenarioId;
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /** What the scenario operates on — the team `topic` (design/code review) or the solo task objective. */
     objective: string;
     /**
@@ -83,7 +83,7 @@ export interface RunScenarioOptions {
 /** Per-scenario result union — each entry returns its orchestrator's native result shape. */
 export type RunScenarioResult = {
     scenario: "solo";
-    result: Awaited<ReturnType<Runner["runTask"]>>;
+    result: Awaited<ReturnType<RunnerSelfSeat["runTask"]>>;
 } | {
     scenario: "design-review";
     result: TeamResult;

package/dist/scenarios/teacher-quickstart.d.ts

@@ -10,7 +10,7 @@
  * defaults only. The guard defaults are NOT re-stated here: we let teacher.ts own them (single source of
  * truth, no drift).
  */
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { ModelRef, TaskSpec } from "../core/types.js";
 import { type TeacherRunResult } from "../agents/teacher.js";
 export interface TeacherModePair {
@@ -25,7 +25,7 @@ export interface TeacherModePair {
  * student task spec's `model`. All guards use teacher.ts's built-in defaults (not re-stated here, so core
  * owns the single source of truth). The caller supplies only the two models + the task spec.
  */
-export declare function teacherMode(runner: Runner, spec: TaskSpec, pair: TeacherModePair): Promise<TeacherRunResult>;
+export declare function teacherMode(runner: RunnerSelfSeat, spec: TaskSpec, pair: TeacherModePair): Promise<TeacherRunResult>;
 /**
  * Teacher-mode preset profile (G2: a profile = which two models to fill). The two model cells are role-name
  * placeholders the deploy side maps to concrete models (core never guesses); guard defaults are NOT pinned

package/dist/server/http.d.ts

@@ -1,6 +1,6 @@
 import http from "node:http";
 import type { IncomingMessage } from "node:http";
-import type { Runner } from "../core/runner/runtask.js";
+import type { RunnerSelfSeat } from "../core/runner/contracts.js";
 import type { ImageInput, TaskSpec } from "../core/types.js";
 /** Inbound request body. Tool *code* can never come over the wire — the server injects tools via resolveSpec. */
 export interface TaskRequestBody {
@@ -10,7 +10,7 @@ export interface TaskRequestBody {
     [key: string]: unknown;
 }
 export interface TaskServerOptions {
-    runner: Runner;
+    runner: RunnerSelfSeat;
     /**
      * Map an inbound request body to a full TaskSpec. This is where the SERVER decides the model,
      * tools, MCP servers, system prompt, and limits for the request. The body only supplies content

package/dist/stores/file/fs-atomic.d.ts

@@ -184,10 +184,11 @@ export declare class FileStoreLockError extends Error {
     ownerPid?: number | undefined);
 }
 /**
- * The coarse boot guard (§2.4): an `O_EXCL` PID file (`root/LOCK` for the whole data dir; one per store
+ * The coarse boot guard (§2.4): an `O_EXCL` owner file (`root/LOCK` for the whole data dir; one per store
  * ledger directory via {@link acquireStoreDirLock}) that forbids two processes sharing it. A second
- * instance fails fast ("another instance owns this data dir"). A STALE lock (the writing PID is dead) is
- * pruned and re-acquired — `proper-lockfile`/CC `concurrentSessions` parity.
+ * instance fails fast ("another instance owns this data dir"). A STALE lock (the process that WROTE it is
+ * gone — see {@link isProcessLive}, which is not the same question as "is that pid free") is pruned and
+ * re-acquired — `proper-lockfile`/CC `concurrentSessions` parity.
  *
  * This is the family's ONE lock MECHANISM (the per-operation CAS stays in-process: one event loop + a
  * per-token async mutex, so there is NO per-operation flock). A holder of one of these fences guarantees
@@ -201,7 +202,7 @@ export declare class BootLock {
     /** The verdict of the ONE release this holding gets, replayed to any later caller (see {@link release}). */
     private spentVerdict;
     constructor(lockPath: string);
-    /** Acquire the lock or throw. Reclaims a lock whose recorded PID is not running (see below). */
+    /** Acquire the lock or throw. Reclaims a lock whose recorded OWNER is gone (see below). */
     acquire(): void;
     /**
      * @param depth how many stale reclaim gates deep we already are (see the gate below). Bounded so a
@@ -240,8 +241,8 @@ export declare class BootLock {
      *
      * ONE-SHOT, and that is load-bearing. This object stops being a holder the moment it is ASKED to release
      * — before the filesystem is touched — and a second call REPEATS the first verdict instead of acting on
-     * it again. A lock file is a bare pid, so two BootLocks over one path in this process are byte-identical
-     * on disk: after a FAILED release the path can legitimately be re-published (a later acquisition here
+     * it again. A lock file names its publishing PROCESS, so two BootLocks over one path in this process are
+     * byte-identical on disk: after a FAILED release the path can legitimately be re-published (a later acquisition here
      * finishing our cleanup), and a stale object that "removed its own lock" a second time would be deleting
      * the SUCCESSOR's fence while both sides believed they held the directory — the double-writer this whole
      * mechanism exists to refuse, minted from bookkeeping instead of from a race. So a second release answers
@@ -320,11 +321,86 @@ export declare function acquireStoreDirLock(dir: string, opts: {
  * stops two processes consolidating the SAME scope at once (the in-process model the file backend assumes —
  * see {@link BootLock} — does not cover a second OS process with its own timer).
  *
- * `acquire(scope)` writes `lockDir/<sanitizedScope>.consolidate.lock` carrying THIS pid (atomic
- * {@link writeThenLink}, so the lock appears with its pid already in it — no empty-window prune race). It
- * returns a `release` callback on success, or `undefined` when a LIVE owner already holds it (the caller
- * treats `undefined` as "busy → skip this pass", a no-op). A STALE lock (recorded pid is dead) is pruned and
- * re-acquired once. The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core
- * only DEFINES the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
+ * `acquire(scope)` takes a {@link BootLock} over `lockDir/<sanitizedScope>.consolidate.lock`. It returns a
+ * `release` callback on success, or `undefined` for EVERY refusal that lock knows how to make — a live
+ * owner (including this process: a second pass here is still a conflict), a takeover in flight, an
+ * unreadable file — because the caller's whole vocabulary is "busy → skip this pass", a no-op that costs
+ * one deferred consolidation. A stale lock is reclaimed by the same protocol as any other, which is the
+ * point of not hand-rolling one: this factory used to prune with a bare `unlink` and re-publish, and two
+ * passes that had both read the same dead owner would then both prune and both publish — one deleting the
+ * other's fresh lock, leaving two processes consolidating the SAME scope, which is exactly what the lock
+ * exists to prevent. The reclaim gate serialises that, the depth cap bounds it, and the identity re-read
+ * makes sure a reclaim prunes the owner it came for. One lock MECHANISM in this family, not two.
+ *
+ * The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core only DEFINES
+ * the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
  */
 export declare function createFileConsolidationLock(lockDir: string): (scope: string) => (() => void) | undefined;
+/**
+ * A process identity that survives PID REUSE: a pid, WHEN that pid's process started, and the host the
+ * observation was made on.
+ *
+ * A pid alone is not an identity. The OS hands the same number out again once its holder exits, so a lock
+ * (or lease, or any other durable "who owns this" record) carrying only a pid says no more than "somebody
+ * with that number" — and after a crash, an unrelated process that inherits the number makes the dead
+ * owner's record read as a LIVE owner for as long as that process lives. Adding the START TIME makes the
+ * record falsifiable: the pid narrows the candidate to one process, the start time decides whether it is
+ * still the SAME one.
+ *
+ * The start time is carried TWICE, against two different clocks, and that is the whole robustness of the
+ * thing. Both numbers come from ONE reading of the process's elapsed time, but one is subtracted from the
+ * WALL clock and the other from the host's UPTIME — and a platform that leaves one of them unmoved when
+ * the wall clock is corrected moves the other. (Where `ps` measures elapsed time against the boot clock, a
+ * corrected wall clock shifts the derived wall-clock start and leaves the uptime-relative one alone; where
+ * it measures against a stored absolute start, it is the other way round.) A comparison that insists on
+ * BOTH before calling a record stale therefore cannot be talked into a reclaim by a clock correction —
+ * which matters because that reclaim would be of a LIVE writer's lock. See {@link isProcessLive}.
+ *
+ * Both are `null` when this host cannot produce a start time (no `ps`, a cut-down `ps` that rejects the
+ * query, a probe too slow for its own reading to be worth anything). That is a plain "unknown" — never a
+ * zero and never a guess — and every consumer treats an unobtainable fingerprint as UNFALSIFIABLE, keeping
+ * the pid-only verdict: the degrade lands on yesterday's behaviour rather than on a wrong reclaim, and
+ * says so out loud once.
+ */
+export interface ProcessFingerprint {
+    /** The process id the rest of the record is about. */
+    readonly pid: number;
+    /** Start of that pid's process against the WALL clock, to the second; `null` when unobtainable here. */
+    readonly startedAtMs: number | null;
+    /** The same start against this host's UPTIME (ms after boot), to the second; `null` likewise. */
+    readonly startedSinceBootMs: number | null;
+    /** The host both were read on — a fingerprint from ANOTHER host is comparable to nothing here. */
+    readonly host: string;
+}
+/**
+ * The fingerprint of a process: this one when called with no pid, any other pid when named.
+ *
+ * ONE derivation for both halves of the mechanism — the record a holder WRITES and the probe a later reader
+ * verifies it with — on purpose. Deriving our own start time from `process.uptime()` instead would be
+ * cheaper, but it measures from Node's own initialisation rather than from the kernel's `exec`, so a busy
+ * machine can put the two derivations seconds apart. A reader comparing across them would then read a
+ * healthy holder as stale and RECLAIM A LIVE LOCK — a strictly worse failure than the pid reuse this fixes.
+ * One derivation makes the tolerance a rounding allowance instead of a guess about bootstrap latency.
+ *
+ * The self case is memoized: our start time cannot change, the probe is a subprocess, and a lock publish is
+ * the only place that needs it — so a process pays for it at most once, whatever it opens.
+ */
+export declare function processFingerprint(pid?: number): ProcessFingerprint;
+/**
+ * Is the process a record names still the one that wrote it? ONE predicate, two terms: the pid is running,
+ * AND the fingerprint has not been falsified.
+ *
+ * "Not falsified" is the load-bearing wording, and it is what every degrade lands on. A record with no
+ * `startedAtMs` (the pre-fingerprint spelling, or a host that cannot produce one), a record written on
+ * ANOTHER host (its start time was measured against a different boot — comparing it here would be
+ * arithmetic on unrelated numbers), and a probe that cannot answer all reach the same verdict: LIVE. The
+ * asymmetry is deliberate and is the whole safety argument — a false "dead" reclaims a directory out from
+ * under a working process (two writers, and the ledger loses whichever rows the loser never loaded), while
+ * a false "live" costs a refusal an operator can act on.
+ */
+export declare function isProcessLive(record: {
+    readonly pid: number;
+    readonly startedAtMs?: number | null;
+    readonly startedSinceBootMs?: number | null;
+    readonly host?: string | null;
+}): boolean;