agent-nuvira 3.5.1 → 3.5.2

package/dist/tools/run-registry.d.ts

@@ -0,0 +1,282 @@
+/**
+ * The durable half of the monitored-run registry.
+ *
+ * WHY THIS EXISTS. Monitoring a long command in memory (see `run-terminal.ts`)
+ * fixed the killing, but it made the record as fragile as the process holding it:
+ * a CLI exit, a dashboard restart, a crash — all normal — and a command that is
+ * still running becomes unpollable. Nothing is left to follow it with, its real
+ * exit code is never collected, and the turn that started it can only re-run the
+ * work (wrong) or guess at the outcome. Two facts have to outlive the process:
+ *
+ *   what is running  — id, command, cwd, pid, start time, and how it ended;
+ *   what it said     — its output, from the FIRST byte as well as the last.
+ *
+ * The second one is why there is a spool file and not just a record. The
+ * in-memory buffer is a bounded TAIL (a 40MB build log must not be held), so the
+ * beginning of a long run was simply gone — the model could read the end of a
+ * failure and not the line that explained it. The spool keeps a bounded HEAD and
+ * a bounded TAIL (rewritten whole, so the file never grows past the cap), which
+ * is the part a diagnosis actually uses.
+ *
+ * Everything here is best-effort and must never break a turn: a missing, unreadable
+ * or corrupt registry is an empty registry, never a throw.
+ */
+/** How much of the BEGINNING of a run's output is kept. */
+export declare const SPOOL_HEAD_BYTES = 32768;
+/** How much of the END of a run's output is kept. */
+export declare const SPOOL_TAIL_BYTES = 32768;
+/**
+ * How much of a run's output is kept IN FULL before the window collapses to
+ * head+tail.
+ *
+ * WHY THIS EXISTS. A bounded window throws away the MIDDLE of a long run, and
+ * that is exactly where a failure explains itself — so the honest trade is to
+ * keep everything while everything is small. Most runs never reach this cap, so
+ * the common case stops losing anything at all; past it the file collapses to
+ * head+tail (with the dropped count stated), which keeps the guarantee that a
+ * chatty command cannot fill the disk. `NUVIRA_RUN_LOG_FULL_BYTES=0` restores
+ * "always a bounded window".
+ */
+export declare const SPOOL_FULL_BYTES = 2000000;
+/** How often an in-flight spool is written out (a crash loses at most this much). */
+export declare const SPOOL_FLUSH_MS = 2000;
+export interface PersistedRun {
+    id: string;
+    command: string;
+    cwd: string;
+    /** The process-tree root: the shell we spawned, or the command it exec'd. */
+    pid: number;
+    startedAt: number;
+    status: 'running' | 'done';
+    exitCode: number | null;
+    endedAt?: number;
+    /** Why it stopped, when it was stopped rather than finishing on its own. */
+    exitReason?: string;
+    reaped?: boolean;
+    stopRequested?: boolean;
+    /**
+     * The OS's own start token for the process this run was started as — the
+     * second identity witness (see `processIdentityVerdict`). Recorded once, while
+     * the process is certainly still ours; a run recovered without it can be
+     * followed but not stopped, which is the old, safe behaviour.
+     */
+    osStartedAt?: string;
+}
+/** `<config dir>/run-terminal` — isolated by `$NUVIRA_CONFIG_DIR`, like the rest. */
+export declare function runsDir(): string;
+export declare function spoolPath(id: string): string;
+/** Read the registry. A missing/corrupt file is an empty registry. */
+export declare function loadRuns(): PersistedRun[];
+/**
+ * Add or update one run. Finished entries are kept (so a restart can still report
+ * the real exit code) and the oldest are dropped past the cap.
+ */
+export declare function saveRun(entry: PersistedRun): void;
+/** The spooled output of one run, or null when there is none. */
+export declare function readSpool(id: string): string | null;
+export declare function spoolBytes(id: string): number;
+export declare function discardSpool(id: string): void;
+/**
+ * Delete spool files no record refers to.
+ *
+ * The registry is capped, but a file is not a record: without this, every run
+ * that was ever monitored would leave its log behind forever, and "bounded state"
+ * would be true of the JSON and false of the disk. Run on hydrate, when the live
+ * set is exactly known.
+ */
+export declare function sweepSpools(liveIds: readonly string[]): void;
+/**
+ * A bounded head+tail window over some text.
+ *
+ * The head is kept because a run's first lines name what it is doing and how it
+ * was invoked; the tail is kept because that is where the failure is. The middle
+ * is what gets dropped — bounded, explicit, and never silently a lie about size.
+ */
+export declare function outputWindow(text: string, maxChars: number, headChars?: number, tailChars?: number): {
+    text: string;
+    omittedChars: number;
+};
+/**
+ * Write the spool for one run: HEAD (until it is full) + a rolling TAIL.
+ *
+ * The file is REWRITTEN whole rather than appended to, which is what keeps it
+ * bounded: a chatty command can write gigabytes in an hour and the spool still
+ * stays at ~64KB. Flushing is throttled (`SPOOL_FLUSH_MS`) so the write cost is
+ * independent of the output rate; `close()` does the final write.
+ *
+ * NOTHING IS WRITTEN UNTIL {@link startPersisting}. Until a run is handed to
+ * monitoring it is not durable (there is no registry entry to read it back), so a
+ * file on disk would be litter the user never asked for — and litter they do get:
+ * MEASURED, the first output chunk of an ordinary `npm test` created
+ * `<config>/run-terminal/out/<id>.log` in the developer's REAL profile on every
+ * test that spawned a command and finished inside its budget, for a spool that
+ * was then discarded. Buffering in memory until hand-off loses nothing (the head
+ * is bounded, and the window written at hand-off is the same one) and keeps the
+ * suite out of the profile it runs in.
+ */
+export declare class SpoolWriter {
+    private readonly id;
+    private readonly headBytes;
+    private readonly tailBytes;
+    /**
+     * Where the window is written. Defaults to the monitored-run spool dir; the
+     * dashboard's tasks keep theirs beside their own records. Parameterised
+     * rather than duplicated because the discipline — bounded, rewritten whole,
+     * throttled, discarded when nobody will read it — is the part worth sharing.
+     */
+    private readonly dir;
+    private head;
+    private tail;
+    /** Everything ever written, so the window can say how much it dropped. */
+    private total;
+    private dirty;
+    private lastFlush;
+    private closed;
+    private discarded;
+    /** False until the run is durable — see {@link startPersisting}. */
+    private persisting;
+    /**
+     * `append` — the file is growing with the run, byte for byte, because it is
+     * still under the full-log cap. `window` — the cap was passed, so the file is
+     * the bounded head+tail window from here on.
+     */
+    private mode;
+    /** Text written since the last flush, in append mode. */
+    private pending;
+    private readonly fullBytes;
+    constructor(id: string, headBytes?: number, tailBytes?: number, 
+    /**
+     * Where the window is written. Defaults to the monitored-run spool dir; the
+     * dashboard's tasks keep theirs beside their own records. Parameterised
+     * rather than duplicated because the discipline — bounded, rewritten whole,
+     * throttled, discarded when nobody will read it — is the part worth sharing.
+     */
+    dir?: string, fullBytes?: number);
+    /** The file this window lives in. */
+    path(): string;
+    /**
+     * Begin writing to disk: the run has outlived its wait budget and is now
+     * durable (`persistRun`), so its output has to be readable by another process.
+     */
+    startPersisting(): void;
+    write(text: string): void;
+    private flushIfDue;
+    /**
+     * Cross the cap: write the bounded window ONCE, and stop growing the file.
+     *
+     * The bytes already appended are what a run's middle looked like while it still
+     * fit; rewriting the file is what keeps a gigabyte of output from becoming a
+     * gigabyte of disk.
+     */
+    private collapse;
+    /**
+     * Write what has accumulated. Safe to call at any time.
+     *
+     * The file is the HEAD plus the LAST `tailBytes` of the tail — taken from the
+     * END, because the tail is where a failure explains itself. When everything
+     * fits in the head, only the head is written: otherwise a short run's output
+     * would be stored twice and read back doubled.
+     */
+    flush(): void;
+    /**
+     * Make sure the bytes still held in memory reach the file.
+     *
+     * `close()` cannot use `flush()` for this: in append mode a pause in output
+     * older than the throttle leaves `pending` unwritten, and those are exactly the
+     * last lines of a run — the ones that explain why it failed.
+     */
+    private drainPending;
+    /** Final write. The file stays (a finished run's output is still worth reading). */
+    close(): void;
+    /** Drop the spool: the run finished inside its wait budget, so nobody will poll it. */
+    discard(): void;
+}
+/**
+ * Is `pid` still the process we started, or has the pid been recycled?
+ *
+ * A run recovered from the registry is identified by a NUMBER that outlived the
+ * process table it came from. Between the crash and the re-attach, that pid can
+ * belong to something else entirely — and this tool's whole safety story is that
+ * it only ever signals commands IT started. So before any recovered run is
+ * signalled, it is identified all over again.
+ *
+ * The process line — `ps` on POSIX, the same `Get-CimInstance Win32_Process`
+ * query the liveness sampler already runs on Windows — shows the shell we spawned
+ * (`/bin/sh -c <command>`) or, when the shell exec'd a simple command, that
+ * command's own line; both contain the command text, which is why the check is a
+ * containment test rather than equality.
+ */
+export declare function commandMatchesProcess(pid: number, command: string): boolean | null;
+/** What was recorded about the process a run was started as. */
+export interface RecordedProcess {
+    command: string;
+    /**
+     * The OS's own start token for that process (`lookupProcess().startedAtText`).
+     * Absent for a record written before this existed, or when the read failed —
+     * in which case the command line is the only witness, exactly as before.
+     */
+    osStartedAt?: string | null;
+}
+/** What the live process table says about a pid right now. */
+export interface LiveProcess {
+    found: boolean;
+    command: string | null;
+    startedAtText: string | null;
+}
+/**
+ * WHICH KIND of answer an identity check gave — the distinction a caller needs to
+ * avoid reading a statement about identity as a statement about liveness.
+ *
+ *  `verified`        ours, with evidence
+ *  `gone`            the pid is not in the table: a fact, so a task may be
+ *                    settled from it
+ *  `not-ours`        the pid exists but is a DIFFERENT process. The task is not
+ *                    ours any more either — but see the callers: this is a claim
+ *                    about identity, and it must not be turned into "it finished"
+ *                    without care, because a command line can change over a
+ *                    process's life (a shell that `exec`s keeps its pid).
+ *  `unknown`         nothing readable: never adopt, never signal, never conclude
+ *  `unreadable-table` this platform cannot list processes at all
+ */
+export type IdentityKind = 'verified' | 'gone' | 'not-ours' | 'unknown' | 'unreadable-table';
+/**
+ * Identity, decided by TWO independent witnesses — pure, so every branch can be
+ * asserted instead of hoped for.
+ *
+ *   pid + command line        what the run was started as
+ *   pid + OS start token      when the OS says that process began
+ *
+ * The rule that makes this safe rather than merely clever:
+ *
+ *   a witness may VETO, and only the start token may ACCEPT ALONE.
+ *
+ *  - A different command line is not our process, so `false` wins over any
+ *    agreement elsewhere — a recycled pid running something else is refused.
+ *  - When the command lines agree, a start token that DISAGREES refuses too: the
+ *    same command started as a different process (another `npm test` in another
+ *    directory, a stranger's `node`) is precisely the case that used to be
+ *    adopted. This is the new refusal, and it can only ever refuse.
+ *  - When the command line cannot be read at all (some platforms hide it, and a
+ *    kernel process has none), a MATCHING start token is accepted: that is a
+ *    value the kernel does not hand out twice, and it is the difference between
+ *    a recovered run that can be stopped and one that can only be stopped by
+ *    hand. Anything short of a match stays `null` — unknown, never ours.
+ */
+export declare function processIdentityVerdict(recorded: RecordedProcess, live: LiveProcess | null): boolean | null;
+/**
+ * The verdict AND the evidence behind it.
+ *
+ * A refusal the operator cannot act on is barely better than a crash: the whole
+ * consequence of `false` here is that a real command keeps running and can only
+ * be stopped by hand, so the message has to say WHICH witness failed — a
+ * different command line and a mismatched start time are different problems, and
+ * "could not tell" is a third.
+ */
+export declare function processIdentityCheck(recorded: RecordedProcess, live: LiveProcess | null): {
+    verdict: boolean | null;
+    why: string;
+    kind: IdentityKind;
+};
+/** `processIdentityVerdict` against the live table: one read, both witnesses. */
+export declare function processIdentityMatches(pid: number, recorded: RecordedProcess): boolean | null;
+//# sourceMappingURL=run-registry.d.ts.map

package/dist/tools/run-registry.d.ts.map

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