instar 1.3.761 → 1.3.763

package/dist/monitoring/ExternalHogRealAdapters.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ExternalHogRealAdapters — the IMPURE edge that binds the reviewed pure modules to the real OS
+ * (CMT-1901, docs/specs/external-hog-zombie-autokill-sentinel.md §1-§6). It builds the
+ * `ExternalHogAdapters` object the ExternalHogSentinel shell consumes.
+ *
+ * Every raw side-effect (spawn `ps`/`launchctl`/`lsof` off-loop, `process.kill`, the model call,
+ * raising an attention item, reading the clock + arm file) is a single INJECTED primitive, so the
+ * wiring here is unit-testable with fakes and NO real process is ever spawned or signalled in a
+ * test. The server supplies the real primitives (`defaultPrimitives`-style) at construction.
+ *
+ * This module holds NO kill decision — it only READS the OS to produce facts and EXECUTES the
+ * signals the reviewed funnel decides on. The watch-only guarantee, the floor veto, the arm gate
+ * and the classifier authority all live in the modules it wires together, unchanged.
+ */
+import { type ExternalHogAdapters } from './ExternalHogSentinel.js';
+import { type ArmMarker } from './ExternalHogArmMarker.js';
+/** The raw side-effect primitives — the ONLY things that touch the real OS / network. */
+export interface ExternalHogPrimitives {
+    /** Run a command off the event loop, resolve stdout. Reject/throw on non-zero exit is fine —
+     *  each caller decides the fail-safe direction. */
+    exec(cmd: string, args: readonly string[]): Promise<string>;
+    /** Send a signal to a pid; `0` is an aliveness probe. Returns false if the pid is gone. */
+    signal(pid: number, sig: 'SIGTERM' | 'SIGKILL' | 0): boolean;
+    /** Kill-time CPU RE-CONFIRM (§4.5): sample the pid's cumulative cputime twice over `windowMs`
+     *  (monotonic Δwall) and resolve the core-equivalents right now; null if the pid vanished /
+     *  is unreadable. This is the fresh "is it STILL pinning cores, or did it go idle?" probe that
+     *  gates every signal — a null or below-threshold reading must abort the kill (fail-safe). */
+    cpuCoresOver(pid: number, windowMs: number): Promise<number | null>;
+    /** Call the classifier model with a prompt (wrapped by the caller in the LlmQueue background lane). */
+    callModel(prompt: string): Promise<string>;
+    /** Raise ONE attention item for the coalesced notices. */
+    raiseAttention(item: {
+        title: string;
+        body: string;
+        priority?: 'low' | 'medium' | 'high';
+        source?: string;
+    }): Promise<unknown> | unknown;
+    /** A monotonic clock reading (ms). */
+    now(): number;
+    /** The sentinel's own effective uid. */
+    ownEuid(): number;
+    /** The server process pid (an instar-owned root of the ownership walk). */
+    serverPid(): number;
+    /** The pids of live tmux panes (instar-owned session roots). */
+    listTmuxPanePids(): Promise<readonly number[]>;
+    /** Read the durable armed state (marker + lastDisarmEpoch) — loadArmState(stateDir). */
+    loadArm(): {
+        marker: ArmMarker | null;
+        lastDisarmEpoch: number;
+    };
+    /** The LIVE kill-capability config (read fresh each call). */
+    config(): {
+        enabled: boolean;
+        dryRun: boolean;
+    };
+    /** Append one scrubbed audit row per tick (best-effort). */
+    auditRow?(row: unknown): void;
+}
+export interface ExternalHogAdapterOpts {
+    readonly cpuCoreThreshold: number;
+    readonly maxAncestorHops: number;
+    /** The kill-time CPU re-confirm micro-window (§4.5, ~2.5s) and its core threshold (~0.5) — the
+     *  fresh "still pinning cores vs went idle" gate applied at every reReadFacts before a signal. */
+    readonly killTimeCpuRecheckWindowMs: number;
+    readonly killTimeCpuCoreThreshold: number;
+    /** Paths that count as user-document / workspace roots for the fd-skip (kill-time write) check.
+     *  Empty → the conservative default (a writable regular file under $HOME but not Library/caches). */
+    readonly workspacePathHints?: readonly string[];
+    /** Home dir for the default workspace heuristic. */
+    readonly homeDir?: string;
+}
+/** Parse `lsof -F fatn` output into fd records. Pure. */
+export declare function parseLsofFdRecords(out: string): Array<{
+    access: string;
+    type: string;
+    name: string;
+}>;
+/** Does this pid hold an open WRITABLE regular file under a user-document path? Pure over lsof out. */
+export declare function hasWritableUserFile(lsofOut: string, opts: {
+    workspacePathHints?: readonly string[];
+    homeDir?: string;
+}): boolean;
+/** Parse `launchctl list` output → the set of pids that are labeled launchd jobs. Pure. */
+export declare function parseLaunchctlPids(out: string): Set<number>;
+/**
+ * Build the live `ExternalHogAdapters` from the raw primitives. A short-lived per-tick cache
+ * (the last parsed table + resolved ownership + launchctl set) lets the per-candidate `factsFor`
+ * calls reuse one ps/launchctl read instead of re-spawning per candidate.
+ */
+export declare function createExternalHogAdapters(prims: ExternalHogPrimitives, opts: ExternalHogAdapterOpts): ExternalHogAdapters;
+//# sourceMappingURL=ExternalHogRealAdapters.d.ts.map

package/dist/monitoring/ExternalHogRealAdapters.d.ts.map

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

package/dist/monitoring/ExternalHogRealAdapters.js

@@ -0,0 +1,247 @@
+/**
+ * ExternalHogRealAdapters — the IMPURE edge that binds the reviewed pure modules to the real OS
+ * (CMT-1901, docs/specs/external-hog-zombie-autokill-sentinel.md §1-§6). It builds the
+ * `ExternalHogAdapters` object the ExternalHogSentinel shell consumes.
+ *
+ * Every raw side-effect (spawn `ps`/`launchctl`/`lsof` off-loop, `process.kill`, the model call,
+ * raising an attention item, reading the clock + arm file) is a single INJECTED primitive, so the
+ * wiring here is unit-testable with fakes and NO real process is ever spawned or signalled in a
+ * test. The server supplies the real primitives (`defaultPrimitives`-style) at construction.
+ *
+ * This module holds NO kill decision — it only READS the OS to produce facts and EXECUTES the
+ * signals the reviewed funnel decides on. The watch-only guarantee, the floor veto, the arm gate
+ * and the classifier authority all live in the modules it wires together, unchanged.
+ */
+import { parseProcTable } from './ExternalHogProcTable.js';
+import { buildProcTree } from './ExternalHogSentinel.js';
+import { buildFacts, buildIdentity } from './ExternalHogFactBuilder.js';
+import { matchAllowlistClass, classRuleSources } from './ExternalHogFloor.js';
+import { classContentHash, isMarkerValid } from './ExternalHogArmMarker.js';
+import { buildClassifierPrompt } from './ExternalHogClassifierPrompt.js';
+const PS_TABLE_ARGS = ['-o', 'pid=,ppid=,uid=,lstart=,time=,comm='];
+/** Parse `lsof -F fatn` output into fd records. Pure. */
+export function parseLsofFdRecords(out) {
+    const recs = [];
+    let cur = null;
+    for (const line of out.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const tag = line[0];
+        const val = line.slice(1);
+        if (tag === 'f') { // a new fd record begins
+            if (cur)
+                recs.push(cur);
+            cur = { access: '', type: '', name: '' };
+        }
+        else if (cur) {
+            if (tag === 'a')
+                cur.access = val;
+            else if (tag === 't')
+                cur.type = val;
+            else if (tag === 'n')
+                cur.name = val;
+        }
+    }
+    if (cur)
+        recs.push(cur);
+    return recs;
+}
+/** Does this pid hold an open WRITABLE regular file under a user-document path? Pure over lsof out. */
+export function hasWritableUserFile(lsofOut, opts) {
+    const hints = opts.workspacePathHints ?? [];
+    const home = opts.homeDir ?? '';
+    for (const r of parseLsofFdRecords(lsofOut)) {
+        if (r.type !== 'REG')
+            continue;
+        if (!(r.access.includes('w') || r.access.includes('u')))
+            continue; // write or read+write
+        const name = r.name;
+        if (hints.length > 0) {
+            if (hints.some((h) => h && name.startsWith(h)))
+                return true;
+            continue;
+        }
+        // Default heuristic: a writable regular file under $HOME but NOT under a cache/library/system dir.
+        if (home && name.startsWith(home)) {
+            const rel = name.slice(home.length);
+            if (/^\/(Library|\.cache|\.Trash|\.npm|\.cache|Caches)\b/i.test(rel))
+                continue;
+            return true;
+        }
+    }
+    return false;
+}
+/** Parse `launchctl list` output → the set of pids that are labeled launchd jobs. Pure. */
+export function parseLaunchctlPids(out) {
+    const pids = new Set();
+    for (const line of out.split('\n')) {
+        // Columns: PID  Status  Label. A '-' PID means not-currently-running (skip).
+        const m = /^\s*(\d+)\s+\S+\s+\S/.exec(line);
+        if (m) {
+            const pid = Number(m[1]);
+            if (Number.isInteger(pid) && pid > 0)
+                pids.add(pid);
+        }
+    }
+    return pids;
+}
+/**
+ * Build the live `ExternalHogAdapters` from the raw primitives. A short-lived per-tick cache
+ * (the last parsed table + resolved ownership + launchctl set) lets the per-candidate `factsFor`
+ * calls reuse one ps/launchctl read instead of re-spawning per candidate.
+ */
+export function createExternalHogAdapters(prims, opts) {
+    let lastTable = [];
+    let lastOwned = new Map();
+    let launchctlCache = null;
+    async function readProcTable() {
+        try {
+            lastTable = parseProcTable(await prims.exec('ps', PS_TABLE_ARGS));
+        }
+        catch {
+            lastTable = []; // a failed ps read → empty table → the sampler heartbeat won't advance (→ on-stale)
+        }
+        return lastTable;
+    }
+    async function ownedRefs() {
+        const owned = new Map();
+        const rootPids = [prims.serverPid()];
+        try {
+            rootPids.push(...(await prims.listTmuxPanePids()));
+        }
+        catch { /* tmux unavailable → server pid only */ }
+        for (const pid of rootPids) {
+            const row = lastTable.find((r) => r.pid === pid);
+            if (row)
+                owned.set(pid, row.startTime);
+        }
+        lastOwned = owned;
+        return owned;
+    }
+    async function launchctlPids() {
+        const now = prims.now();
+        if (launchctlCache && now - launchctlCache.at < 30_000)
+            return launchctlCache.pids;
+        try {
+            const pids = parseLaunchctlPids(await prims.exec('launchctl', ['list']));
+            launchctlCache = { at: now, pids };
+            return pids;
+        }
+        catch {
+            // @silent-fallback-ok: reviewed decision (round 8) — launchctl failed → EMPTY set.
+            // hasLaunchctlLabel:false does NOT open a kill on its own (every OTHER floor invariant
+            // must still hold), and a genuinely labeled job that we fail to detect is a rare edge;
+            // the conservative alternative (mark everything labeled → never kill) would break the
+            // feature entirely. Fail toward the feature working, floor-bounded.
+            return new Set();
+        }
+    }
+    async function fetchArgv(pid) {
+        try {
+            const out = (await prims.exec('ps', ['-o', 'args=', '-p', String(pid)])).trim();
+            return out.length > 0 ? out : null;
+        }
+        catch {
+            // @silent-fallback-ok: fail-SAFE direction — can't read argv → the caller returns null
+            // facts → candidate skipped entirely (a missing fact always blocks, never permits).
+            return null;
+        }
+    }
+    async function factsFor(candidate, table) {
+        const row = table.find((r) => r.pid === candidate.pid && r.startTime === candidate.startTime);
+        if (!row)
+            return null; // vanished / identity changed since candidacy
+        const argv = await fetchArgv(candidate.pid);
+        if (argv === null)
+            return null;
+        const tree = buildProcTree(table);
+        const launchctlLabeledPids = await launchctlPids();
+        return buildFacts({
+            row, argv, tree, ownedRefs: lastOwned, maxAncestorHops: opts.maxAncestorHops,
+            ownEuid: prims.ownEuid(), launchctlLabeledPids,
+            sustainedThisWindow: candidate.coreEquivalents >= opts.cpuCoreThreshold,
+        });
+    }
+    function identityFor(_candidate, facts) {
+        return buildIdentity(facts);
+    }
+    async function classify(facts) {
+        const classId = matchAllowlistClass(facts.name, facts.argv);
+        if (!classId)
+            return null; // not an allowlist class → decider-unavailable → alert (never happens: only classified after identity)
+        return prims.callModel(buildClassifierPrompt(facts, classId));
+    }
+    function currentClassContentHash(classId) {
+        const sources = classRuleSources(classId);
+        // A class with no rule sources can't be armed; return a sentinel hash that matches NOTHING in
+        // any snapshot (so the arm-scope check fails closed → no kill).
+        return sources ? classContentHash(sources) : 'no-such-class';
+    }
+    const killFunnelDeps = {
+        reReadFacts: async (pid, startTime) => {
+            const table = await readProcTable();
+            const row = table.find((r) => r.pid === pid && r.startTime === startTime);
+            if (!row)
+                return null; // gone or pid reused (startTime mismatch) → identity changed
+            const argv = await fetchArgv(pid);
+            if (argv === null)
+                return null;
+            // §4.5 kill-time CPU re-confirm — a FRESH micro-sample RIGHT NOW: is it still pinning cores,
+            // or did it go idle since classify? A null (probe failed / pid gone) or below-threshold
+            // reading sets sustainedHighCpu:false → the floor re-check vetoes → the kill aborts (safe).
+            const cores = await prims.cpuCoresOver(pid, opts.killTimeCpuRecheckWindowMs);
+            const stillHog = cores !== null && Number.isFinite(cores) && cores >= opts.killTimeCpuCoreThreshold;
+            return buildFacts({
+                row, argv, tree: buildProcTree(table), ownedRefs: lastOwned, maxAncestorHops: opts.maxAncestorHops,
+                ownEuid: prims.ownEuid(), launchctlLabeledPids: await launchctlPids(),
+                sustainedThisWindow: stillHog,
+            });
+        },
+        reReadArmState: () => {
+            const arm = prims.loadArm();
+            return { config: prims.config(), marker: arm.marker, lastDisarmEpoch: arm.lastDisarmEpoch };
+        },
+        currentClassContentHash,
+        hasOpenWritableWorkspaceFile: async (pid) => {
+            try {
+                return hasWritableUserFile(await prims.exec('lsof', ['-p', String(pid), '-F', 'fatn']), opts);
+            }
+            catch {
+                return true; // lsof error → can't rule out an in-progress write → DEFER (bounded, safe)
+            }
+        },
+        sendSignal: (pid, signal) => { prims.signal(pid, signal); },
+        stillAlive: (pid) => prims.signal(pid, 0),
+        wait: (ms) => new Promise((res) => setTimeout(res, Math.max(0, ms))),
+    };
+    function deliverNotices(result) {
+        if (!result || result.emitted.length === 0)
+            return;
+        const hasKill = result.emitted.some((n) => n.cls === 'kill');
+        const body = result.emitted.map((n) => `• ${n.text}`).join('\n');
+        void Promise.resolve(prims.raiseAttention({
+            title: hasKill ? 'External-hog sentinel: auto-killed a zombie' : 'External-hog sentinel: sustained CPU hog',
+            body,
+            priority: hasKill ? 'high' : 'medium',
+            source: 'external-hog-sentinel',
+        })).catch(() => undefined); // delivery is best-effort; never throw into the tick
+    }
+    function armStatus() {
+        const cfg = prims.config();
+        const arm = prims.loadArm();
+        return { enabled: cfg.enabled === true, dryRun: cfg.dryRun !== false, markerValid: isMarkerValid(arm.marker, arm.lastDisarmEpoch) };
+    }
+    return {
+        readProcTable,
+        ownedRefs,
+        factsFor,
+        identityFor,
+        classify,
+        killFunnelDeps,
+        deliverNotices,
+        armStatus,
+        nowMs: () => prims.now(),
+        ...(prims.auditRow ? { auditTick: (row) => prims.auditRow(row) } : {}),
+    };
+}
+//# sourceMappingURL=ExternalHogRealAdapters.js.map

package/dist/monitoring/ExternalHogRealAdapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalHogRealAdapters.js","sourceRoot":"","sources":["../../src/monitoring/ExternalHogRealAdapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAqB,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA4B,MAAM,0BAA0B,CAAC;AAGnF,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAyB,MAAM,uBAAuB,CAAC;AACrG,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAkB,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAkDzE,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,qCAAqC,CAAU,CAAC;AAE7E,yDAAyD;AACzD,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,IAAI,GAA0D,EAAE,CAAC;IACvE,IAAI,GAAG,GAA0D,IAAI,CAAC;IACtE,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC,CAAC,yBAAyB;YAC1C,IAAI,GAAG;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAC3C,CAAC;aAAM,IAAI,GAAG,EAAE,CAAC;YACf,IAAI,GAAG,KAAK,GAAG;gBAAE,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC;iBAC7B,IAAI,GAAG,KAAK,GAAG;gBAAE,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;iBAChC,IAAI,GAAG,KAAK,GAAG;gBAAE,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;QACvC,CAAC;IACH,CAAC;IACD,IAAI,GAAG;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,IAAkE;IACrH,MAAM,KAAK,GAAG,IAAI,CAAC,kBAAkB,IAAI,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;YAAE,SAAS;QAC/B,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,SAAS,CAAC,sBAAsB;QACzF,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACpB,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC5D,SAAS;QACX,CAAC;QACD,mGAAmG;QACnG,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,sDAAsD,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC/E,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,6EAA6E;QAC7E,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACzB,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAA4B,EAAE,IAA4B;IAClG,IAAI,SAAS,GAA4B,EAAE,CAAC;IAC5C,IAAI,SAAS,GAAc,IAAI,GAAG,EAAE,CAAC;IACrC,IAAI,cAAc,GAA6C,IAAI,CAAC;IAEpE,KAAK,UAAU,aAAa;QAC1B,IAAI,CAAC;YACH,SAAS,GAAG,cAAc,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;QACpE,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,GAAG,EAAE,CAAC,CAAC,oFAAoF;QACtG,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,UAAU,SAAS;QACtB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;QACxC,MAAM,QAAQ,GAAa,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,wCAAwC,CAAC,CAAC;QAC9G,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;YACjD,IAAI,GAAG;gBAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;QACD,SAAS,GAAG,KAAK,CAAC;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,UAAU,aAAa;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QACxB,IAAI,cAAc,IAAI,GAAG,GAAG,cAAc,CAAC,EAAE,GAAG,MAAM;YAAE,OAAO,cAAc,CAAC,IAAI,CAAC;QACnF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,kBAAkB,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACzE,cAAc,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,mFAAmF;YACnF,uFAAuF;YACvF,uFAAuF;YACvF,sFAAsF;YACtF,oEAAoE;YACpE,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED,KAAK,UAAU,SAAS,CAAC,GAAW;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAChF,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,uFAAuF;YACvF,oFAAoF;YACpF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,UAAU,QAAQ,CAAC,SAAoB,EAAE,KAA8B;QAC1E,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,SAAS,CAAC,CAAC;QAC9F,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC,CAAC,8CAA8C;QACrE,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC/B,MAAM,IAAI,GAAa,aAAa,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,oBAAoB,GAAG,MAAM,aAAa,EAAE,CAAC;QACnD,OAAO,UAAU,CAAC;YAChB,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe;YAC5E,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,oBAAoB;YAC9C,mBAAmB,EAAE,SAAS,CAAC,eAAe,IAAI,IAAI,CAAC,gBAAgB;SACxE,CAAC,CAAC;IACL,CAAC;IAED,SAAS,WAAW,CAAC,UAAqB,EAAE,KAAuB;QACjE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,UAAU,QAAQ,CAAC,KAAuB;QAC7C,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5D,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC,CAAC,uGAAuG;QAClI,OAAO,KAAK,CAAC,SAAS,CAAC,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,SAAS,uBAAuB,CAAC,OAAe;QAC9C,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC1C,8FAA8F;QAC9F,gEAAgE;QAChE,OAAO,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;IAC/D,CAAC;IAED,MAAM,cAAc,GAAmB;QACrC,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE;YACpC,MAAM,KAAK,GAAG,MAAM,aAAa,EAAE,CAAC;YACpC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;YAC1E,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAC,CAAC,6DAA6D;YACpF,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,6FAA6F;YAC7F,wFAAwF;YACxF,4FAA4F;YAC5F,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,0BAA0B,CAAC,CAAC;YAC7E,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,wBAAwB,CAAC;YACpG,OAAO,UAAU,CAAC;gBAChB,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe;gBAClG,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,oBAAoB,EAAE,MAAM,aAAa,EAAE;gBACrE,mBAAmB,EAAE,QAAQ;aAC9B,CAAC,CAAC;QACL,CAAC;QACD,cAAc,EAAE,GAAG,EAAE;YACnB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC;QAC9F,CAAC;QACD,uBAAuB;QACvB,4BAA4B,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC1C,IAAI,CAAC;gBACH,OAAO,mBAAmB,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YAChG,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC,CAAC,2EAA2E;YAC1F,CAAC;QACH,CAAC;QACD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAC3D,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;QACzC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;KACrE,CAAC;IAEF,SAAS,cAAc,CAAC,MAAsB;QAC5C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACnD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC;YACxC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,6CAA6C,CAAC,CAAC,CAAC,0CAA0C;YAC3G,IAAI;YACJ,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;YACrC,MAAM,EAAE,uBAAuB;SAChC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,qDAAqD;IACnF,CAAC;IAED,SAAS,SAAS;QAChB,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,KAAK,EAAE,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;IACtI,CAAC;IAED,OAAO;QACL,aAAa;QACb,SAAS;QACT,QAAQ;QACR,WAAW;QACX,QAAQ;QACR,cAAc;QACd,cAAc;QACd,SAAS;QACT,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;QACxB,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,QAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC"}

package/dist/monitoring/ExternalHogSampler.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ExternalHogSampler — the PURE stage-1 candidacy state machine of the External-Hog sentinel
+ * (CMT-1901, docs/specs/external-hog-zombie-autokill-sentinel.md §1).
+ *
+ * Given two successive `ps` snapshots, compute the stage-1 CANDIDATES: external (own-uid,
+ * not-instar-owned) processes whose cross-tick `Δcputime / Δwall` crosses the core threshold.
+ * This is the cheap whole-table pass that selects the small set (typically 0–3) the expensive
+ * N-window confirmation + classifier then act on. PURE over its inputs (the actual `ps` spawn
+ * + the wall clock live in the thin I/O worker shell) so the candidacy logic is fully testable.
+ *
+ * Two round-reviewed properties carried here:
+ *  - candidacy uses the DELTA (Δcputime/Δwall), NOT `ps %cpu` — a process idle for 23h that
+ *    only NOW pins cores is caught (its lifetime average is diluted, but its cross-tick delta
+ *    is high). The map is rebuilt from the current table each tick (bounded; no accumulate).
+ *  - a LIVENESS HEARTBEAT (`lastSnapshotAt`) advances on any SUCCESSFUL parse (≥1 plausible
+ *    row), regardless of candidate count — so an idle no-hog machine is never read as
+ *    sampler-dead, and a failed/empty parse does NOT advance it (→ eventually sampler-dead).
+ */
+import { type CpuSample } from './ExternalHogCpuDelta.js';
+import { type ProcTree, type OwnedRefs } from './ExternalHogOwnership.js';
+import type { ProcTableRow } from './ExternalHogProcTable.js';
+export interface SamplerState {
+    /** Previous tick's identity-key → { cumulativeCpuSeconds, monotonicWallMs }. */
+    readonly prev: ReadonlyMap<string, CpuSample>;
+    /** The liveness heartbeat — advances on any successful (plausible) parse. */
+    readonly lastSnapshotAt: number | null;
+}
+export declare const EMPTY_SAMPLER_STATE: SamplerState;
+export interface Candidate {
+    readonly pid: number;
+    readonly startTime: string;
+    readonly comm: string;
+    readonly coreEquivalents: number;
+}
+export interface SamplerTick {
+    readonly nextState: SamplerState;
+    readonly candidates: readonly Candidate[];
+    /** True when this tick's parse was plausible (heartbeat advanced). */
+    readonly parsedOk: boolean;
+}
+export interface SamplerOpts {
+    readonly ownEuid: number;
+    readonly cpuCoreThreshold: number;
+    readonly sampleWindowMs: number;
+    readonly maxAncestorHops: number;
+    /** Minimum plausible row count for a "successful" parse (heartbeat gate). Default 1. */
+    readonly minPlausibleRows?: number;
+}
+/**
+ * Advance the sampler by one tick. `table` is the current parsed `ps` snapshot; `tree`/`owned`
+ * are built from it by the caller (the ownership sets). `monotonicWallMs` is a monotonic-clock
+ * reading. Returns the next state (with the rebuilt map + advanced heartbeat) and the stage-1
+ * candidates. Pure — mutates nothing.
+ */
+export declare function advanceSampler(state: SamplerState, table: readonly ProcTableRow[], tree: ProcTree, owned: OwnedRefs, monotonicWallMs: number, opts: SamplerOpts): SamplerTick;
+/**
+ * Is the sampler DEAD (heartbeat too old)? Never-run (null heartbeat) is NOT dead — it just
+ * hasn't started. A non-finite `now` fails toward not-declaring-dead (avoid a false restart on
+ * a bad clock read). `deadThresholdMs = max(2*scanInterval, N*window)` per §1.
+ */
+export declare function isSamplerDead(state: SamplerState, nowMs: number, deadThresholdMs: number): boolean;
+//# sourceMappingURL=ExternalHogSampler.d.ts.map

package/dist/monitoring/ExternalHogSampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalHogSampler.d.ts","sourceRoot":"","sources":["../../src/monitoring/ExternalHogSampler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAiB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAO9D,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9C,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAwD,CAAC;AAE3F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,wFAAwF;IACxF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,SAAS,EAChB,eAAe,EAAE,MAAM,EACvB,IAAI,EAAE,WAAW,GAChB,WAAW,CA8Cb;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAIlG"}

package/dist/monitoring/ExternalHogSampler.js.map

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

package/dist/monitoring/ExternalHogScanTick.d.ts

@@ -0,0 +1,89 @@
+/**
+ * ExternalHogScanTick — the orchestrator that composes the External-Hog sentinel's modules into
+ * ONE scan tick (CMT-1901, docs/specs/external-hog-zombie-autokill-sentinel.md §1-§6).
+ *
+ * This is the "make it alive" integration: discovery (sampler) → classify (worst-CPU-first under
+ * the cap) → floor → kill funnel → P19 ledger → P17 coalesced notices. All I/O is INJECTED
+ * (read ps, build ownership, classify, the kill-funnel deps, clock, deliver) so the whole tick
+ * is end-to-end testable without a real ps read, a real model call, or a real signal. The thin
+ * server-side wiring (the actual ps spawn, LlmQueue call, notice delivery, interval) is a
+ * separate slice; this is the pure control flow that ties the reviewed modules together.
+ *
+ * Watch-only rides through: the kill funnel returns `would-kill` (no signal) unless a live kill
+ * is authorized, so in the shipped dryRun state a scan tick produces would-kill records + the
+ * §4 observability notices, and kills NOTHING.
+ */
+import type { ProcTableRow } from './ExternalHogProcTable.js';
+import { type SamplerState, type SamplerOpts, type Candidate } from './ExternalHogSampler.js';
+import type { ProcTree, OwnedRefs } from './ExternalHogOwnership.js';
+import { type ClassifierVerdict } from './ExternalHogClassifier.js';
+import { type ExternalHogFacts } from './ExternalHogFloor.js';
+import { type KillOutcome, type KillFunnelDeps, type KillFunnelOpts } from './ExternalHogKillFunnel.js';
+import { type KillLedgerState, type BreakerOpts } from './ExternalHogKillLedger.js';
+import { type CoalesceResult } from './ExternalHogNoticeCoalescer.js';
+import { type SustainedState } from './ExternalHogSustained.js';
+export interface ScanState {
+    readonly sampler: SamplerState;
+    readonly ledger: KillLedgerState;
+    /** Stage-2 N-window sustained-CPU streaks (§1 anti-spike; feeds sustainedHighCpu authoritatively). */
+    readonly sustained: SustainedState;
+}
+export interface ScanDeps {
+    /** The current parsed ps table (the sampler's input). */
+    readProcTable(): readonly ProcTableRow[];
+    /** Build the ownership sets (tree + owned pids) from the current table + instar pids. */
+    buildOwnership(table: readonly ProcTableRow[]): {
+        tree: ProcTree;
+        owned: OwnedRefs;
+    };
+    /** Full deterministic facts for a candidate (the floor input); null if it vanished. May be async
+     *  (a per-candidate ps -o args= read + launchctl) — the orchestrator awaits it. */
+    factsFor(candidate: Candidate): ExternalHogFacts | null | Promise<ExternalHogFacts | null>;
+    /** The command-hash + ledger key + class for a candidate (identity for the ledger/funnel). */
+    identityFor(candidate: Candidate, facts: ExternalHogFacts): {
+        commandHash: string;
+        ledgerKey: string;
+        classId: string;
+    } | null;
+    /** Call the classifier (LlmQueue). Returns raw model output, or null if the decider is unavailable. */
+    classify(facts: ExternalHogFacts): Promise<unknown>;
+    /** The kill-funnel I/O (re-read facts/arm, fd-probe, signal, aliveness, wait). */
+    killFunnelDeps: KillFunnelDeps;
+    /** A monotonic clock reading (ms). */
+    nowMs(): number;
+    /** How many times a target signature has already been deferred (for maxKillDeferrals). */
+    deferralsFor(ledgerKey: string): number;
+}
+export interface ScanOpts {
+    readonly sampler: SamplerOpts;
+    /** N consecutive delta windows over threshold before sustainedHighCpu is true (§1 anti-spike). */
+    readonly sustainedSampleCount: number;
+    readonly maxClassificationsPerScan: number;
+    readonly breaker: Omit<BreakerOpts, 'nowMs'>;
+    readonly killFunnel: Omit<KillFunnelOpts, 'currentDeferrals'>;
+    readonly noticeBudgetPerWindow: number;
+    readonly killLedgerRetentionMs: number;
+}
+/** One per-candidate outcome row (for the audit/soak log AND cross-tick deferral tracking).
+ *  `ledgerKey`/`classId` carry the target IDENTITY so a consumer (the sentinel shell) can
+ *  persist how many times a signature has been deferred without re-deriving it. */
+export interface ScanOutcome {
+    readonly pid: number;
+    readonly ledgerKey: string;
+    readonly classId: string;
+    readonly verdict: ClassifierVerdict | 'decider-unavailable';
+    readonly outcome: KillOutcome | 'alert-only';
+}
+export interface ScanResult {
+    readonly nextState: ScanState;
+    /** Per-candidate outcomes (for the audit/soak log). */
+    readonly outcomes: ReadonlyArray<ScanOutcome>;
+    /** The coalesced notices to deliver. */
+    readonly notices: CoalesceResult;
+}
+/**
+ * Run one scan tick. Pure control flow over the injected I/O; mutates nothing. In the shipped
+ * dryRun state every `outcome` is `would-kill`/`alert-only` and no signal is sent.
+ */
+export declare function runScanTick(state: ScanState, deps: ScanDeps, opts: ScanOpts): Promise<ScanResult>;
+//# sourceMappingURL=ExternalHogScanTick.d.ts.map

package/dist/monitoring/ExternalHogScanTick.d.ts.map

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