humanish 0.104.3 → 0.106.0

package/dist/run-status.js

@@ -1,218 +0,0 @@
-// Run identity + liveness on disk (#455/#475): one small record per run that says WHICH LAB the
-// run belongs to and WHETHER IT IS STILL ALIVE, written by every backend.
-//
-// Why it exists. Two questions could not be answered from the filesystem before this:
-//   1. "which lab produced this run?" — the bundle carried no lab field; attribution rode a string
-//      convention (`persona.source = "lab:<id>"`) that is not universal.
-//   2. "is this run still going?" — the mid-run bundle flush is gated on an interactive-observer
-//      callback, so a run launched by an agent (`lab run --json`) or detached wrote nothing at all
-//      until it completed. Anything watching the directory could not tell running from abandoned.
-//
-// EVIDENCE VS INDEX (the honesty rule that makes this safe). `run.json` remains the
-// evidence-of-record; this file is a DERIVED INDEX + LIVENESS RECORD. `verify` never gates on it,
-// nothing here is a claim about what a participant did, and when the two disagree `run.json` wins
-// and this file is rebuildable from it. It exists so a reader can list and classify runs without
-// parsing every bundle (a 25-run tree measured 152ms warm that way), and so a live run is
-// recognizable while it is live.
-//
-// PUBLIC-SAFETY. Only public-safe fields: the run id, the lab id/path/origin (author-chosen names,
-// the same strings `humanish lab list` already prints), the mode, a local pid, and timestamps.
-// Deliberately NOT the hostname or any user/path identity — this file sits inside a run directory
-// that an operator may share, so it must carry nothing a share-safety gate would have to strip.
-import { AsyncLocalStorage } from "node:async_hooks";
-import { hrtime } from "node:process";
-import { writeContainedOutputFile } from "./selected-output-paths.js";
-export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
-/** The file, relative to the run directory. */
-export const RUN_STATUS_FILE = "status.json";
-/** How often a live run touches `updatedAt`. */
-export const RUN_STATUS_TOUCH_MS = 5_000;
-/**
- * A `running` record whose `updatedAt` is older than this is INTERRUPTED, not alive: the process
- * died without finalizing (a dropped SSH, a killed terminal, a crash). Three touch intervals of
- * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
- */
-export const RUN_STATUS_STALE_MS = RUN_STATUS_TOUCH_MS * 3;
-/** A no-op handle, so a caller that cannot write status still has a uniform interface. */
-export function inertRunStatus() {
-    return { started: Promise.resolve(), touch: async () => { }, finish: async () => { }, stop: async () => { } };
-}
-/**
- * The set of handles opened inside the currently-running run, so the run's own return finalizes
- * them. Scoped rather than global: labs can run concurrently in one process, and each must clean up
- * only what it opened.
- */
-const runStatusScope = new AsyncLocalStorage();
-/**
- * Bind a run's status records to the lifetime of the run itself.
- *
- * WHY THIS IS NOT A `finally` AT EACH BACKEND. A run function does not have one exit — the lab
- * backends have 18 early `return`s between opening the record and finalizing it, every one of them
- * a fail-closed path (bad subject, packing failure, missing key). Relying on each of those to
- * remember the record is the same per-call-site discipline that already failed once on this
- * contract, and the failure is silent: the run is over, the cadence keeps ticking, and the record
- * keeps saying `running` — a listing surface then shows a dead run as alive for as long as the
- * process lives. CI caught it as a deleted run directory racing a still-live writer.
- *
- * So the scope owns the lifetime. Control returning from the run function IS the run ending,
- * whatever path it took, and any record still open at that moment is finalized with NO outcome:
- * the run ended and we have no verdict to report. That is honest and it is different from both
- * neighbours — a backend that finalized properly carries its real outcome, and a process that
- * CRASHED never reaches here at all, leaving a `running` record to go stale and read as
- * `interrupted`, which is exactly what happened.
- */
-export async function withRunStatusScope(fn) {
-    const scope = new Set();
-    try {
-        return await runStatusScope.run(scope, fn);
-    }
-    finally {
-        // `finish` swallows its own write errors and is idempotent, so this can neither throw over the
-        // run's own error nor overwrite an outcome a backend already recorded.
-        await Promise.all([...scope].map((handle) => handle.finish()));
-    }
-}
-/**
- * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
- * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d — this file can never be the reason a process stays alive.
- */
-export function beginRunStatus(runPaths, options) {
-    const now = options.now ?? (() => Date.now());
-    const iso = () => new Date(now()).toISOString();
-    const startedAt = iso();
-    const base = {
-        schema: RUN_STATUS_SCHEMA,
-        runId: options.runId,
-        state: "running",
-        mode: options.mode,
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
-        pid: options.pid ?? process.pid,
-        startedAt,
-        updatedAt: startedAt
-    };
-    let finished = false;
-    let writing = Promise.resolve();
-    const write = (record) => {
-        // Serialized: two overlapping atomic writes of the same path would be a coin flip over which
-        // record survives, and a `running` record landing after a `finished` one would resurrect it.
-        writing = writing
-            .then(() => writeContainedOutputFile(runPaths, RUN_STATUS_FILE, `${JSON.stringify(record, null, 2)}\n`, "utf8"))
-            .catch(() => {
-            // Deliberately swallowed: the index is a convenience, the bundle is the evidence.
-        });
-        return writing;
-    };
-    const started = write(base);
-    const touchMs = options.touchMs ?? RUN_STATUS_TOUCH_MS;
-    let timer;
-    if (touchMs > 0) {
-        timer = setInterval(() => {
-            if (finished)
-                return;
-            void write({ ...base, updatedAt: iso() });
-        }, touchMs);
-        timer.unref?.();
-    }
-    const stop = () => {
-        if (timer !== undefined) {
-            clearInterval(timer);
-            timer = undefined;
-        }
-        // `writing` is the tail of the serialized write chain, so awaiting it awaits everything queued.
-        return writing.catch(() => undefined);
-    };
-    const scope = runStatusScope.getStore();
-    const handle = {
-        started,
-        async touch() {
-            if (finished)
-                return;
-            await write({ ...base, updatedAt: iso() });
-        },
-        async finish(outcome) {
-            if (finished)
-                return;
-            finished = true;
-            void stop();
-            scope?.delete(handle);
-            const completedAt = iso();
-            await write({
-                ...base,
-                state: "finished",
-                updatedAt: completedAt,
-                completedAt,
-                ...(outcome === undefined ? {} : { outcome })
-            });
-        },
-        stop() {
-            scope?.delete(handle);
-            return stop();
-        }
-    };
-    // The enclosing run now owns this record's lifetime; see `withRunStatusScope`. A caller outside a
-    // scope (a direct library import) simply gets the old behavior.
-    scope?.add(handle);
-    return handle;
-}
-/**
- * Classify a status record. Pure, so the TUI, the CLI and tests share one definition of "alive".
- * `nowMs` is passed in rather than read, so a classification is reproducible.
- */
-export function classifyRunStatus(record, nowMs, staleMs = RUN_STATUS_STALE_MS) {
-    if (record.state === "finished")
-        return "finished";
-    const updated = Date.parse(record.updatedAt);
-    if (!Number.isFinite(updated))
-        return "interrupted";
-    return nowMs - updated <= staleMs ? "running" : "interrupted";
-}
-/** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
-export function isRunStatusRecord(value) {
-    if (value === null || typeof value !== "object")
-        return false;
-    const record = value;
-    if (record.schema !== RUN_STATUS_SCHEMA)
-        return false;
-    if (typeof record.runId !== "string" || record.runId === "")
-        return false;
-    if (record.state !== "running" && record.state !== "finished")
-        return false;
-    if (record.mode !== "dry-run" && record.mode !== "live")
-        return false;
-    if (typeof record.pid !== "number")
-        return false;
-    if (typeof record.startedAt !== "string" || typeof record.updatedAt !== "string")
-        return false;
-    if (record.lab !== undefined) {
-        if (record.lab === null || typeof record.lab !== "object")
-            return false;
-        if (typeof record.lab.id !== "string")
-            return false;
-    }
-    return true;
-}
-/**
- * The legacy bridge: infer a lab id for a bundle written BEFORE this contract, where the only
- * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
- * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
- * remainder is not an id. Ids may contain colons (`oss:meta`), so only the FIRST segment is
- * stripped. Returns undefined when the bundle carries no such marker.
- */
-export function inferLegacyLabId(bundle) {
-    for (const source of [bundle.persona?.source, bundle.scenario?.source]) {
-        if (typeof source !== "string")
-            continue;
-        if (!source.startsWith("lab:"))
-            continue;
-        const id = source.slice("lab:".length).trim();
-        if (id !== "")
-            return id;
-    }
-    return undefined;
-}
-/** A monotonic elapsed-ms helper for callers that need a duration without trusting wall clocks. */
-export function elapsedMsSince(startNs) {
-    return Number((hrtime.bigint() - startNs) / 1000000n);
-}
-//# sourceMappingURL=run-status.js.map

package/dist/run-status.js.map

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