@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/native-metrics/node-load-ring.d.ts

@@ -1,214 +1,214 @@
 /**
- * In-memory retention for the per-node load snapshots — the shared analogue of
- * the log ring (`packages/system/src/logging/partitioned-log-buffer.ts`), and
- * built to the same shape for the same reason: a fixed-capacity circular
- * partition per key, plus **declared hard ceilings** on the total.
- *
- * ## What this is, and what it deliberately is not
- *
- * `native-metrics` emits `metrics.node-processes-snapshot` every 20 s on every
- * node whether or not anyone is watching (D250). Until now nobody kept it: the
- * Load charts accumulated 180 points inside the browser tab, so closing the
- * page threw the hour away and two operators looking at the same node saw two
- * different windows.
- *
- * This ring RETAINS what already arrives. It adds no timer, no sampler, no
- * probe and no new event — subscribing to a fan-out that exists is the whole
- * mechanism. It is **not** durable retention: nothing here reaches disk, and a
- * stored series remains its own decision with its own resolution, retention and
- * owner (D250 § Consequences).
- *
- * ## It does not know what a load snapshot looks like
- *
- * `TProcess` is a type parameter and the payload is stored **verbatim**. The
- * ring reads exactly two things off the envelope — which node, and when — and
- * never a field of a process row. A field added to the snapshot (a `deviceId`
- * next to the pid, say) flows through untouched, because there is nothing here
- * for it to flow through.
- *
- * ## Measured cost — see `docs/architecture/load-ledger.md`
- *
- * Measured, not estimated, against the real process payloads of the live
- * cluster (`metricsProvider.listNodeProcesses` on all three nodes: 42 + 20 + 14
- * rows) replayed 180 deep and weighed as V8 retained heap after a forced GC:
- *
- *   **464 B per process row**, so the live cluster's full hour —
- *   3 nodes x 180 samples x 76 rows = 13 680 rows — is **6.06 MiB**.
- *
- * Linear in rows (checked at 360 samples: 463.9 B/row). Every ceiling below is
- * expressed in ROWS for that reason: rows are what the memory is proportional
- * to, and samples are not.
- */
+* In-memory retention for the per-node load snapshots — the shared analogue of
+* the log ring (`packages/system/src/logging/partitioned-log-buffer.ts`), and
+* built to the same shape for the same reason: a fixed-capacity circular
+* partition per key, plus **declared hard ceilings** on the total.
+*
+* ## What this is, and what it deliberately is not
+*
+* `native-metrics` emits `metrics.node-processes-snapshot` every 20 s on every
+* node whether or not anyone is watching (D250). Until now nobody kept it: the
+* Load charts accumulated 180 points inside the browser tab, so closing the
+* page threw the hour away and two operators looking at the same node saw two
+* different windows.
+*
+* This ring RETAINS what already arrives. It adds no timer, no sampler, no
+* probe and no new event — subscribing to a fan-out that exists is the whole
+* mechanism. It is **not** durable retention: nothing here reaches disk, and a
+* stored series remains its own decision with its own resolution, retention and
+* owner (D250 § Consequences).
+*
+* ## It does not know what a load snapshot looks like
+*
+* `TProcess` is a type parameter and the payload is stored **verbatim**. The
+* ring reads exactly two things off the envelope — which node, and when — and
+* never a field of a process row. A field added to the snapshot (a `deviceId`
+* next to the pid, say) flows through untouched, because there is nothing here
+* for it to flow through.
+*
+* ## Measured cost — see `docs/architecture/load-ledger.md`
+*
+* Measured, not estimated, against the real process payloads of the live
+* cluster (`metricsProvider.listNodeProcesses` on all three nodes: 42 + 20 + 14
+* rows) replayed 180 deep and weighed as V8 retained heap after a forced GC:
+*
+*   **464 B per process row**, so the live cluster's full hour —
+*   3 nodes x 180 samples x 76 rows = 13 680 rows — is **6.06 MiB**.
+*
+* Linear in rows (checked at 360 samples: 463.9 B/row). Every ceiling below is
+* expressed in ROWS for that reason: rows are what the memory is proportional
+* to, and samples are not.
+*/
 /** One retained snapshot: when it arrived, and the payload exactly as it came. */
 export interface LoadSample<TProcess> {
-    readonly atMs: number;
-    readonly processes: readonly TProcess[];
+	readonly atMs: number;
+	readonly processes: readonly TProcess[];
 }
 /** What a reader gets back for one node. */
 export interface NodeLoadSeries<TProcess> {
-    readonly nodeId: string;
-    /** Oldest-first, and filtered by the caller's `sinceMs` when given. */
-    readonly samples: readonly LoadSample<TProcess>[];
-    /** Samples retained for this node right now — independent of `sinceMs`. */
-    readonly retainedSamples: number;
-    /** Oldest retained sample's timestamp, or `null` when nothing is retained. */
-    readonly oldestAtMs: number | null;
-    /** The per-node ceiling in force, so a caller can say what it is looking at. */
-    readonly capacity: number;
+	readonly nodeId: string;
+	/** Oldest-first, and filtered by the caller's `sinceMs` when given. */
+	readonly samples: readonly LoadSample<TProcess>[];
+	/** Samples retained for this node right now — independent of `sinceMs`. */
+	readonly retainedSamples: number;
+	/** Oldest retained sample's timestamp, or `null` when nothing is retained. */
+	readonly oldestAtMs: number | null;
+	/** The per-node ceiling in force, so a caller can say what it is looking at. */
+	readonly capacity: number;
 }
 /**
- * Per-node ceiling, in SAMPLES.
- *
- * 180 at the 20 s process-snapshot cadence is **one hour** — the window the
- * operator asked to keep, and the same 180 the browser buffer used before this
- * existed (`LOAD_SERIES_MAX_POINTS`). The cap is on points, not on age, so a
- * node whose emits are deduped away covers a longer wall-clock window at the
- * same cost.
- */
+* Per-node ceiling, in SAMPLES.
+*
+* 180 at the 20 s process-snapshot cadence is **one hour** — the window the
+* operator asked to keep, and the same 180 the browser buffer used before this
+* existed (`LOAD_SERIES_MAX_POINTS`). The cap is on points, not on age, so a
+* node whose emits are deduped away covers a longer wall-clock window at the
+* same cost.
+*/
 export declare const DEFAULT_SAMPLES_PER_NODE = 180;
 /**
- * Fleet ceiling, in PROCESS ROWS across every node.
- *
- * This is the bound the per-node ceiling cannot provide. 180 samples is a fixed
- * number of samples, not a fixed amount of memory: a node whose process count
- * explodes — a leaked tsx tree, an inference pool respawning, the ghost storms
- * the Processes tab exists to surface — multiplies its own partition without
- * ever touching the per-node cap. That is precisely the defect the RTP pre-roll
- * rings have in `docs/architecture/load-ledger.md` (#5): a maximum per instance
- * and no budget for the fleet, which reached 898 MB across 47 rings.
- *
- * 32 000 rows x the measured 464 B = **14.2 MiB**, which is deliberately the
- * same envelope hub-main already accepted for the log ring
- * (`DEFAULT_MAX_TOTAL_LOG_ENTRIES` 50 000 x ~306 B ~ 15 MB). It is 2.3x the
- * live cluster's full hour (13 680 rows), so no real deployment evicts on it —
- * it exists so a runaway node costs 14 MiB instead of everything.
- */
-export declare const DEFAULT_MAX_TOTAL_PROCESS_ROWS = 32000;
+* Fleet ceiling, in PROCESS ROWS across every node.
+*
+* This is the bound the per-node ceiling cannot provide. 180 samples is a fixed
+* number of samples, not a fixed amount of memory: a node whose process count
+* explodes — a leaked tsx tree, an inference pool respawning, the ghost storms
+* the Processes tab exists to surface — multiplies its own partition without
+* ever touching the per-node cap. That is precisely the defect the RTP pre-roll
+* rings have in `docs/architecture/load-ledger.md` (#5): a maximum per instance
+* and no budget for the fleet, which reached 898 MB across 47 rings.
+*
+* 32 000 rows x the measured 464 B = **14.2 MiB**, which is deliberately the
+* same envelope hub-main already accepted for the log ring
+* (`DEFAULT_MAX_TOTAL_LOG_ENTRIES` 50 000 x ~306 B ~ 15 MB). It is 2.3x the
+* live cluster's full hour (13 680 rows), so no real deployment evicts on it —
+* it exists so a runaway node costs 14 MiB instead of everything.
+*/
+export declare const DEFAULT_MAX_TOTAL_PROCESS_ROWS = 32e3;
 /**
- * Ceiling on the number of PARTITIONS.
- *
- * The backstop for an unbounded key space, exactly as `DEFAULT_MAX_LOG_BUCKETS`
- * is: a partition is created on first write, and a node id that appears once —
- * a renamed agent, a node that joined for an afternoon — must not hold a ring
- * for the life of the process. 16 is >5x the live fleet of 3.
- */
+* Ceiling on the number of PARTITIONS.
+*
+* The backstop for an unbounded key space, exactly as `DEFAULT_MAX_LOG_BUCKETS`
+* is: a partition is created on first write, and a node id that appears once —
+* a renamed agent, a node that joined for an afternoon — must not hold a ring
+* for the life of the process. 16 is >5x the live fleet of 3.
+*/
 export declare const DEFAULT_MAX_NODES = 16;
 /**
- * A partition whose newest sample is older than this is dropped whole.
- *
- * **Why age, and why this age.** The alternative — evict when the node leaves
- * the cluster registry — was rejected twice over: it couples this ring to a
- * registry it has no other reason to know, and a node that is merely offline is
- * never "removed", so the case that actually happens (an agent that stops
- * answering) would keep its partition forever. That is the failure mode being
- * bounded.
- *
- * The number is not chosen, it is derived: `DEFAULT_SAMPLES_PER_NODE` x the 20 s
- * snapshot cadence = **one hour** = the entire window this ring can represent.
- * A node silent for that long holds nothing that overlaps the hour an operator
- * is asking about; every point in it has aged out of the question. Below that
- * threshold the partition is still answering a live question and is kept, even
- * though the node is quiet — a node emits at least once a minute
- * (`METRICS_SNAPSHOT_HEARTBEAT_MS`), so an hour of silence is not a slow node,
- * it is a gone one.
- */
-export declare const DEFAULT_NODE_IDLE_EVICTION_MS = 3600000;
+* A partition whose newest sample is older than this is dropped whole.
+*
+* **Why age, and why this age.** The alternative — evict when the node leaves
+* the cluster registry — was rejected twice over: it couples this ring to a
+* registry it has no other reason to know, and a node that is merely offline is
+* never "removed", so the case that actually happens (an agent that stops
+* answering) would keep its partition forever. That is the failure mode being
+* bounded.
+*
+* The number is not chosen, it is derived: `DEFAULT_SAMPLES_PER_NODE` x the 20 s
+* snapshot cadence = **one hour** = the entire window this ring can represent.
+* A node silent for that long holds nothing that overlaps the hour an operator
+* is asking about; every point in it has aged out of the question. Below that
+* threshold the partition is still answering a live question and is kept, even
+* though the node is quiet — a node emits at least once a minute
+* (`METRICS_SNAPSHOT_HEARTBEAT_MS`), so an hour of silence is not a slow node,
+* it is a gone one.
+*/
+export declare const DEFAULT_NODE_IDLE_EVICTION_MS = 36e5;
 export interface NodeLoadRingOptions {
-    readonly samplesPerNode?: number;
-    readonly maxTotalProcessRows?: number;
-    readonly maxNodes?: number;
-    readonly idleEvictionMs?: number;
-    /** Injectable clock. Tests drive eviction without sleeping for an hour. */
-    readonly now?: () => number;
+	readonly samplesPerNode?: number;
+	readonly maxTotalProcessRows?: number;
+	readonly maxNodes?: number;
+	readonly idleEvictionMs?: number;
+	/** Injectable clock. Tests drive eviction without sleeping for an hour. */
+	readonly now?: () => number;
 }
 /**
- * The partitioned ring: one {@link LoadPartition} per node id.
- *
- * Three bounds, doing three different jobs — the same division as the log
- * buffer, for the same reason:
- *
- * - **`samplesPerNode`** is HARD and per partition. It is what the operator
- *   asked for (an hour) and it can never be exceeded.
- * - **`maxTotalProcessRows`** is the FLEET budget, and it is denominated in the
- *   thing memory is proportional to. When it bites, the oldest sample of the
- *   HEAVIEST partition is dropped — the node creating the pressure is the node
- *   that pays, and a quiet node keeps its full hour. The node just written to is
- *   NOT protected here: if it is the heaviest, it is the culprit.
- * - **`maxNodes`** is the backstop against an unbounded key space, and it drops
- *   whole partitions least-recently-written first, never the one being written.
- *
- * Plus {@link DEFAULT_NODE_IDLE_EVICTION_MS}, which is what stops a node that
- * simply stopped emitting from living in memory forever.
- */
+* The partitioned ring: one {@link LoadPartition} per node id.
+*
+* Three bounds, doing three different jobs — the same division as the log
+* buffer, for the same reason:
+*
+* - **`samplesPerNode`** is HARD and per partition. It is what the operator
+*   asked for (an hour) and it can never be exceeded.
+* - **`maxTotalProcessRows`** is the FLEET budget, and it is denominated in the
+*   thing memory is proportional to. When it bites, the oldest sample of the
+*   HEAVIEST partition is dropped — the node creating the pressure is the node
+*   that pays, and a quiet node keeps its full hour. The node just written to is
+*   NOT protected here: if it is the heaviest, it is the culprit.
+* - **`maxNodes`** is the backstop against an unbounded key space, and it drops
+*   whole partitions least-recently-written first, never the one being written.
+*
+* Plus {@link DEFAULT_NODE_IDLE_EVICTION_MS}, which is what stops a node that
+* simply stopped emitting from living in memory forever.
+*/
 export declare class NodeLoadRing<TProcess> {
-    private readonly partitions;
-    /**
-     * Node id → write ordinal of its last accepted sample. A monotonic counter,
-     * not a clock: partition eviction must follow the order writes actually
-     * happened, and node clocks disagree.
-     */
-    private readonly lastWriteSeq;
-    private writeSeq;
-    private totalRows;
-    private readonly samplesPerNode;
-    private readonly maxTotalProcessRows;
-    private readonly maxNodes;
-    private readonly idleEvictionMs;
-    private readonly now;
-    constructor(options?: NodeLoadRingOptions);
-    /**
-     * Retain one snapshot. `processes` is stored by reference — the payload is
-     * already an immutable arrival off the bus, and copying it would double the
-     * measured cost for nothing.
-     *
-     * Returns whether the sample was ACCEPTED — that is, whether it was new
-     * rather than a replay of a timestamp this node has already delivered.
-     *
-     * The return value is not diagnostics. It is the idempotence gate the
-     * DURABLE tier rides on (`load-series-store.ts`): only an accepted sample is
-     * appended to the table, which is what lets that table carry an `INTEGER`
-     * rowid key instead of a composite unique index over two million rows. The
-     * gate is one monotonic comparison in memory; the index it replaces was
-     * measured at ~40 bytes per row.
-     */
-    record(nodeId: string, atMs: number, processes: readonly TProcess[]): boolean;
-    /**
-     * Read one node's retained series, oldest-first.
-     *
-     * `sinceMs` is EXCLUSIVE: a caller passes the newest timestamp it already
-     * holds and gets back only what it is missing. That is the whole contract
-     * that lets the admin UI seed from here and then continue live without
-     * doubling a point it already drew.
-     *
-     * A node nobody has recorded answers with an empty series, not an error —
-     * unknown is the truth about a node that has not reported.
-     */
-    read(nodeId: string, sinceMs?: number): NodeLoadSeries<TProcess>;
-    /** Node ids with a live partition. Observability for the fleet bound. */
-    nodeIds(): readonly string[];
-    /** Process rows retained across every partition — the number that IS memory. */
-    rowCount(): number;
-    /** Samples retained across every partition. */
-    sampleCount(): number;
-    /**
-     * Drop partitions whose newest sample is older than the retention window.
-     *
-     * Lazy, on write and on read — never a timer. A timer would be a new
-     * periodic cost in a subsystem whose entire premise is that it adds none,
-     * and a ring that nobody writes to and nobody reads is not growing either.
-     */
-    private sweepIdle;
-    /**
-     * Bring the fleet back under the row budget by dropping the OLDEST sample of
-     * the HEAVIEST partition, repeatedly.
-     *
-     * Terminates: every iteration removes one sample from a non-empty partition,
-     * and the population of samples is finite and strictly decreasing.
-     */
-    private enforceRowBudget;
-    private heaviestPartition;
-    /** Drop `count` whole partitions, least-recently-written first. */
-    private evictPartitions;
-    /** Remove a partition and everything that indexes it. */
-    private dropPartition;
+	private readonly partitions;
+	/**
+	* Node id → write ordinal of its last accepted sample. A monotonic counter,
+	* not a clock: partition eviction must follow the order writes actually
+	* happened, and node clocks disagree.
+	*/
+	private readonly lastWriteSeq;
+	private writeSeq;
+	private totalRows;
+	private readonly samplesPerNode;
+	private readonly maxTotalProcessRows;
+	private readonly maxNodes;
+	private readonly idleEvictionMs;
+	private readonly now;
+	constructor(options?: NodeLoadRingOptions);
+	/**
+	* Retain one snapshot. `processes` is stored by reference — the payload is
+	* already an immutable arrival off the bus, and copying it would double the
+	* measured cost for nothing.
+	*
+	* Returns whether the sample was ACCEPTED — that is, whether it was new
+	* rather than a replay of a timestamp this node has already delivered.
+	*
+	* The return value is not diagnostics. It is the idempotence gate the
+	* DURABLE tier rides on (`load-series-store.ts`): only an accepted sample is
+	* appended to the table, which is what lets that table carry an `INTEGER`
+	* rowid key instead of a composite unique index over two million rows. The
+	* gate is one monotonic comparison in memory; the index it replaces was
+	* measured at ~40 bytes per row.
+	*/
+	record(nodeId: string, atMs: number, processes: readonly TProcess[]): boolean;
+	/**
+	* Read one node's retained series, oldest-first.
+	*
+	* `sinceMs` is EXCLUSIVE: a caller passes the newest timestamp it already
+	* holds and gets back only what it is missing. That is the whole contract
+	* that lets the admin UI seed from here and then continue live without
+	* doubling a point it already drew.
+	*
+	* A node nobody has recorded answers with an empty series, not an error —
+	* unknown is the truth about a node that has not reported.
+	*/
+	read(nodeId: string, sinceMs?: number): NodeLoadSeries<TProcess>;
+	/** Node ids with a live partition. Observability for the fleet bound. */
+	nodeIds(): readonly string[];
+	/** Process rows retained across every partition — the number that IS memory. */
+	rowCount(): number;
+	/** Samples retained across every partition. */
+	sampleCount(): number;
+	/**
+	* Drop partitions whose newest sample is older than the retention window.
+	*
+	* Lazy, on write and on read — never a timer. A timer would be a new
+	* periodic cost in a subsystem whose entire premise is that it adds none,
+	* and a ring that nobody writes to and nobody reads is not growing either.
+	*/
+	private sweepIdle;
+	/**
+	* Bring the fleet back under the row budget by dropping the OLDEST sample of
+	* the HEAVIEST partition, repeatedly.
+	*
+	* Terminates: every iteration removes one sample from a non-empty partition,
+	* and the population of samples is finite and strictly decreasing.
+	*/
+	private enforceRowBudget;
+	private heaviestPartition;
+	/** Drop `count` whole partitions, least-recently-written first. */
+	private evictPartitions;
+	/** Remove a partition and everything that indexes it. */
+	private dropPartition;
 }

package/dist/builtins/native-metrics/proc-process-table.d.ts

@@ -1,11 +1,11 @@
-import { ProcReader } from '../../process/proc-stat.js';
-import { PsProcessRow } from './process-classification.js';
+import { type ProcReader } from "../../process/proc-stat.js";
+import type { PsProcessRow } from "./process-classification.js";
 /** Every process in `/proc`, as the rows `ps -eo …` would have printed. */
 export declare function readProcProcessTable(reader?: ProcReader): Promise<readonly PsProcessRow[]>;
 /**
- * Parse `ps etime` → seconds. `MM:SS`, `HH:MM:SS`, `DD-HH:MM:SS`.
- * Only the `ps` path needs this; `/proc` gives the number directly.
- */
+* Parse `ps etime` → seconds. `MM:SS`, `HH:MM:SS`, `DD-HH:MM:SS`.
+* Only the `ps` path needs this; `/proc` gives the number directly.
+*/
 export declare function parseEtime(etime: string): number;
 /** Parse the output of `ps -eo pid=,ppid=,pgid=,pcpu=,rss=,etime=,command=`. */
 export declare function parsePsTable(stdout: string): readonly PsProcessRow[];
@@ -13,13 +13,13 @@ export declare function parsePsTable(stdout: string): readonly PsProcessRow[];
 export declare function spawnPsTable(): Promise<readonly PsProcessRow[]>;
 /** What decides the source. Injectable so the choice is pinned by a test, not by the CI host. */
 export interface ProcessTableDeps {
-    readonly platform: NodeJS.Platform;
-    readonly reader: ProcReader;
-    readonly spawnPs: () => Promise<readonly PsProcessRow[]>;
+	readonly platform: NodeJS.Platform;
+	readonly reader: ProcReader;
+	readonly spawnPs: () => Promise<readonly PsProcessRow[]>;
 }
 /**
- * The process table, from `/proc` where it exists and from `ps` elsewhere.
- * Throws only when the chosen source cannot answer at all; the caller logs it
- * as a skipped interval.
- */
+* The process table, from `/proc` where it exists and from `ps` elsewhere.
+* Throws only when the chosen source cannot answer at all; the caller logs it
+* as a skipped interval.
+*/
 export declare function readProcessTable(deps?: ProcessTableDeps): Promise<readonly PsProcessRow[]>;

package/dist/builtins/native-metrics/process-classification.d.ts

@@ -1,51 +1,110 @@
-import { NodeProcess } from '@camstack/types';
-import { ThreadCpuSplit } from './thread-cpu-sampler.js';
+/**
+* Classification of the camstack-shaped processes on one node.
+*
+* Pure: no `ps`, no broker, no clock. Everything the verdict depends on
+* arrives as an argument, so a `ps` row becoming a class is pinned by
+* `__tests__/process-classification.spec.ts` rather than by a running node.
+*
+* This is a MONITORING label and nothing else. Nothing acts on it: the
+* process-control surface (`metricsProvider.killProcess` and the kill buttons
+* in Cluster → Node → Processes) was deleted on 2026-08-27. A runner's
+* lifecycle belongs to `CrashSupervisor` and is driven through
+* `addons.restartAddon` / `$process.restart`; signalling a raw pid went around
+* the supervisor, which is the exact thing D6 exists to prevent. If a class
+* ever needs to gate an ACTION again, that is a new decision, not a
+* re-plumbing of this one.
+*
+* ── The classes ────────────────────────────────────────────────────────────
+*
+*   root    — this node's own pid.
+*   managed — a forked addon worker the kernel's `$process.list` names, so its
+*             CPU and RSS can be attributed to that addon.
+*   system  — every other camstack-shaped process on the machine: one the node
+*             did not spawn and cannot name. Reported, never attributed.
+*
+* ── What used to be here, and why it must not come back as it was ──────────
+*
+* There was a fourth class, `ghost`, produced by a `classifyByAncestry` walk:
+* a process whose ancestry reached `ppid=1` — or a parent `ps` could not see —
+* without crossing `SUPERVISOR_BOUNDARY_RE` was declared an orphan, and it was
+* the one class `killProcess` allowed.
+*
+* That boundary list was entirely a DEV-WORKSTATION list: `tsx watch …
+* launcher.ts`, the agent CLI, `concurrently`, `vite`, `npm exec`. Production
+* has none of those shapes, so the definition never had a chance to be right
+* there — it did not age out, it never knew production:
+*
+*   - in a container, pid 1 is `tini -- docker-entrypoint.sh … starter.js`. It
+*     matches the camstack command pattern, its ppid is 0, and pid 0 is not in
+*     the `ps` snapshot → ghost. Every containerised node called its own init
+*     an orphan, permanently. **The init of a container is not an orphan.**
+*   - on the desktop node, `/Applications/camstack.app` is launched by launchd
+*     (ppid 1) and its three Electron helpers hang off it → four ghosts, which
+*     were the operator's running app.
+*
+* Measured on the live cluster on 2026-08-27: 6 ghosts across three nodes, 6
+* false positives, 0 true ones. And because `ghost` was the killable class,
+* the UI's "Kill all N ghost(s)" aimed SIGKILL at pid 1 and its tree-kill
+* button aimed at the desktop app. Nothing downstream stopped either — which
+* is a large part of why the kill path is gone too.
+*
+* Detecting a REAL orphan is still a legitimate goal. Whoever picks it up:
+* do not restart from an ancestry walk gated on a hand-written list of
+* supervisor command lines. `ppid == 1` is the normal state of a container
+* init, of a launchd-started app, and of anything a service manager owns —
+* it is not evidence, and pid 1 of a container is not an orphan. Evidence
+* would be positive: a pid the cluster once spawned (it is in the runner
+* ledger) that is no longer in `$process.list` and whose runner is gone.
+* Anything less does not get to name a process disposable.
+*/
+import type { NodeProcess } from "@camstack/types";
+import type { ThreadCpuSplit } from "./thread-cpu-sampler.js";
 /** The classes a node process can carry. Mirrors `NodeProcessSchema`. */
-export type ProcessClassification = NodeProcess['classification'];
+export type ProcessClassification = NodeProcess["classification"];
 /** One parsed `ps -eo pid,ppid,pgid,pcpu,rss,etime,command` row. */
 export interface PsProcessRow {
-    readonly pid: number;
-    readonly ppid: number;
-    readonly pgid: number;
-    readonly cpuPercent: number;
-    readonly memoryRssBytes: number;
-    readonly uptimeSec: number;
-    readonly command: string;
+	readonly pid: number;
+	readonly ppid: number;
+	readonly pgid: number;
+	readonly cpuPercent: number;
+	readonly memoryRssBytes: number;
+	readonly uptimeSec: number;
+	readonly command: string;
 }
 /** A pid the kernel's `$process.list` attributes to an addon runner. */
 export interface ManagedProcessEntry {
-    readonly addonId: string;
-    readonly nodeId: string;
+	readonly addonId: string;
+	readonly nodeId: string;
 }
 export interface BuildNodeProcessesInput {
-    /** Every visible `ps` row on this node, camstack-shaped or not. */
-    readonly psRows: readonly PsProcessRow[];
-    /** This node's own pid. */
-    readonly selfPid: number;
-    /** Node id reported for the `root` row. */
-    readonly selfNodeId: string;
-    /** pid → addon attribution from `$process.list`. */
-    readonly managed: ReadonlyMap<number, ManagedProcessEntry>;
-    /** pid → thread CPU split, when the sampler had an answer this tick. */
-    readonly cpuSplits: ReadonlyMap<number, ThreadCpuSplit>;
+	/** Every visible `ps` row on this node, camstack-shaped or not. */
+	readonly psRows: readonly PsProcessRow[];
+	/** This node's own pid. */
+	readonly selfPid: number;
+	/** Node id reported for the `root` row. */
+	readonly selfNodeId: string;
+	/** pid → addon attribution from `$process.list`. */
+	readonly managed: ReadonlyMap<number, ManagedProcessEntry>;
+	/** pid → thread CPU split, when the sampler had an answer this tick. */
+	readonly cpuSplits: ReadonlyMap<number, ThreadCpuSplit>;
 }
 /**
- * Regex matching camstack-related command lines. We surface anything with
- * an obvious camstack fingerprint so operators can spot stray inference
- * pools, leaked tsx watchers, and zombie node workers in the Cluster →
- * Agent → Processes tab.
- *
- * Patterns mirror `scripts/hunt-zombies.sh` — keep them in sync when
- * adding a new long-lived subprocess.
- */
+* Regex matching camstack-related command lines. We surface anything with
+* an obvious camstack fingerprint so operators can spot stray inference
+* pools, leaked tsx watchers, and zombie node workers in the Cluster →
+* Agent → Processes tab.
+*
+* Patterns mirror `scripts/hunt-zombies.sh` — keep them in sync when
+* adding a new long-lived subprocess.
+*/
 export declare const CAMSTACK_CMD_RE: RegExp;
 /**
- * Classify one pid.
- *
- * Identity-driven, not ancestry-driven: a process is `root` because it IS
- * this node, `managed` because the kernel named it, and `system` otherwise.
- * There is no third source of truth to consult and no walk to get wrong.
- */
+* Classify one pid.
+*
+* Identity-driven, not ancestry-driven: a process is `root` because it IS
+* this node, `managed` because the kernel named it, and `system` otherwise.
+* There is no third source of truth to consult and no walk to get wrong.
+*/
 export declare function classifyProcess(pid: number, selfPid: number, managed: ReadonlyMap<number, ManagedProcessEntry>): ProcessClassification;
 /** Turn a `ps` snapshot into the node's process table. */
 export declare function buildNodeProcesses(input: BuildNodeProcessesInput): readonly NodeProcess[];