@theford/runly 0.0.0-stage → 0.20.0

package/dist/core/procscan.js

@@ -0,0 +1,342 @@
+/**
+ * Process identity and orphan discovery.
+ *
+ * Runly spawns each service detached (its own process group) and kills the
+ * group on teardown — but a daemon that dies ungracefully leaves those groups
+ * running with nothing tracking them. Recorded pids alone are not enough to
+ * clean up afterwards: by the time a new daemon reads them they may have been
+ * recycled by the OS onto an unrelated process, and signalling those is worse
+ * than leaking.
+ *
+ * So every supervised service carries a tag in its environment (see
+ * `serviceTag`), and every recorded pid carries the kernel's start-time for
+ * that pid. Together they answer the two questions cleanup needs:
+ *
+ *   - "is pid N still the process I recorded?"        -> `sameProcess`
+ *   - "which runly processes has everyone lost?"    -> `scanTagged`
+ *
+ * Identity works on every platform: /proc where it exists, `ps -o lstart=`
+ * otherwise, so a recycled pid is never mistaken for the process we recorded.
+ * Orphan SCANNING needs to read other processes' environments and so is
+ * Linux-only; elsewhere `pool gc` reports unsupported rather than guessing.
+ * That asymmetry is deliberate — skipping a sweep is safe, signalling a
+ * stranger's process is not.
+ */
+import { readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+export const ENV_TAG = 'BACKLOT_ENV_ID';
+export const SERVICE_TAG = 'BACKLOT_SERVICE';
+/** Scopes a tag to one state root so parallel installs never reap each other. */
+export const ROOT_TAG = 'BACKLOT_STATE_ROOT';
+/** The environment every supervised service is spawned with. */
+/** The service name `runly exec`'s command is tagged with; never reaped (see scanTagged). */
+export const EXEC_SERVICE = 'exec';
+export function serviceTag(envId, service, stateRoot) {
+    return { [ENV_TAG]: envId, [SERVICE_TAG]: service, [ROOT_TAG]: stateRoot };
+}
+export const procScanSupported = () => process.platform === 'linux';
+/**
+ * Field 22 of /proc/<pid>/stat: the process start time in clock ticks since
+ * boot. Unique per pid *life*, so (pid, startTime) survives pid reuse.
+ *
+ * comm (field 2) is an arbitrary string wrapped in parens and may itself
+ * contain spaces or parens, so parse after the LAST ')' rather than splitting
+ * the whole line.
+ */
+export function startTime(pid) {
+    if (!procScanSupported())
+        return darwinStartTime(pid);
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const ticks = Number(rest[19]); // field 22 == index 19 after pid and comm
+        return Number.isFinite(ticks) ? ticks : undefined;
+    }
+    catch {
+        return undefined; // gone, or not ours to read
+    }
+}
+/**
+ * A portable identity for platforms without /proc.
+ *
+ * Without this, non-Linux recovery fell back to a bare liveness check, which is
+ * exactly the pid-reuse hazard the start time exists to close — and macOS is
+ * the platform runly's primary users are on. `ps -o lstart=` reports a
+ * process's start wall-clock to the second, which is enough to distinguish a
+ * recycled pid from the process we recorded.
+ *
+ * Returns undefined if ps is unavailable or the pid is gone; callers treat an
+ * un-verifiable pid as un-signallable, so failing to read is safe.
+ */
+function darwinStartTime(pid) {
+    try {
+        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        }).trim();
+        if (!out)
+            return undefined;
+        const ms = Date.parse(out);
+        return Number.isFinite(ms) ? ms : undefined;
+    }
+    catch {
+        return undefined; // gone, not ours to read, or no ps
+    }
+}
+/**
+ * Field 5 of /proc/<pid>/stat: the process group id.
+ *
+ * `sh -c <cmd>` does NOT reliably exec: dash forks for anything non-trivial,
+ * so the pid runly records is often only the wrapper, and the real server is
+ * a sibling in the same group. Killing "the leader" and then checking the
+ * leader's liveness therefore reports success while the server keeps running —
+ * group membership is the only honest liveness question.
+ */
+export function processGroup(pid) {
+    if (!procScanSupported())
+        return undefined;
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const pgrp = Number(rest[2]); // field 5 == index 2 after pid and comm
+        return Number.isFinite(pgrp) ? pgrp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is ANY process still in this group?
+ *
+ * Without /proc, `kill(-pgid, 0)` is still a genuine GROUP query — ESRCH means
+ * the group is empty. Checking the leader instead would report "gone" the
+ * moment an `sh -c` wrapper exited, while the real server kept running, which
+ * is the whole failure this function exists to detect.
+ */
+export function groupAlive(pgid) {
+    // `kill(-pgid, 0)` is a SINGLE syscall and an authoritative group query:
+    // ESRCH means no process remains in the group. An earlier version walked all
+    // of /proc here, which is O(processes) file reads per call — and
+    // killGroupVerified polls this every 50ms, so on a busy host a single reap
+    // issued hundreds of thousands of reads and stalled the daemon.
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: the group exists but belongs to another user — still alive.
+        return err.code === 'EPERM';
+    }
+}
+/** Is this pid alive at all? Says nothing about whose it is. */
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means alive but owned by another user — still alive.
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Is pid N still the same process that was recorded with `recordedStart`?
+ *
+ * With no recorded start time (a journal written by an older runly, or a
+ * non-Linux host) this can only fall back to liveness, which is exactly the
+ * pid-reuse hazard this exists to close — so callers should treat an
+ * un-verifiable pid as un-signallable where a mistake would be costly.
+ */
+export function sameProcess(pid, recordedStart) {
+    if (!isAlive(pid))
+        return false;
+    if (recordedStart === undefined)
+        return true;
+    const current = startTime(pid);
+    if (current === undefined)
+        return false;
+    return current === recordedStart;
+}
+/** Read a process's environment as a map, or undefined if unreadable. */
+function readEnviron(pid) {
+    try {
+        const raw = readFileSync(`/proc/${pid}/environ`, 'utf8');
+        const out = {};
+        for (const entry of raw.split('\0')) {
+            if (!entry)
+                continue;
+            const eq = entry.indexOf('=');
+            if (eq > 0)
+                out[entry.slice(0, eq)] = entry.slice(eq + 1);
+        }
+        return out;
+    }
+    catch {
+        return undefined; // exited mid-scan, or another user's process
+    }
+}
+/**
+ * Every live process tagged as belonging to this state root.
+ *
+ * Note this finds *descendants* too — an `ng serve` inherits the tag from the
+ * `sh -c` wrapper runly spawned, which is the whole point: after the wrapper
+ * dies the child is still identifiable.
+ */
+export function scanTagged(stateRoot) {
+    if (!procScanSupported())
+        return [];
+    const found = [];
+    let entries;
+    try {
+        entries = readdirSync('/proc');
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        const pid = Number(entry);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        const env = readEnviron(pid);
+        if (!env)
+            continue;
+        if (env[ROOT_TAG] !== stateRoot)
+            continue;
+        const envId = env[ENV_TAG];
+        if (!envId)
+            continue;
+        // `runly exec`'s command (decision 0040) carries the tag so it can be told
+        // apart, but it is the CALLER's process, run by the CLI: no daemon path
+        // (gc, recycle, shutdown) may reap it as an environment's orphan.
+        if (env[SERVICE_TAG] === EXEC_SERVICE)
+            continue;
+        const st = startTime(pid);
+        if (st === undefined)
+            continue; // exited between the two reads
+        found.push({ pid, envId, service: env[SERVICE_TAG] ?? '?', startTime: st });
+    }
+    return found;
+}
+/** Carried by `runly db with`'s command and its descendants: the copy it runs against (decision 0039). */
+export const DB_COPY_TAG = 'BACKLOT_DB_COPY';
+/** The environment `runly db with` runs its command with, so the daemon can find it again. */
+export function dbCopyTag(copy, stateRoot) {
+    return { [DB_COPY_TAG]: copy, [ROOT_TAG]: stateRoot };
+}
+/**
+ * Every live process of this state root running against database copy
+ * `copy` — `runly db with`'s command and whatever it started (the tag is
+ * inherited). Linux only, like `scanTagged`; elsewhere the recorded pid is
+ * all there is.
+ */
+export function scanDbCopy(copy, stateRoot) {
+    if (!procScanSupported())
+        return [];
+    const found = [];
+    let entries;
+    try {
+        entries = readdirSync('/proc');
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        const pid = Number(entry);
+        if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
+            continue;
+        const env = readEnviron(pid);
+        if (!env || env[ROOT_TAG] !== stateRoot || env[DB_COPY_TAG] !== copy)
+            continue;
+        const st = startTime(pid);
+        if (st !== undefined)
+            found.push({ pid, startTime: st });
+    }
+    return found;
+}
+/**
+ * Field 7 of /proc/<pid>/stat: the controlling terminal, 0 for none.
+ *
+ * Runly spawns every service with `stdio: ['ignore', 'pipe', 'pipe']` and
+ * detached, so it and all its descendants have NO controlling terminal. A human's
+ * interactive shell always has one. That difference is the only cheap evidence
+ * available for "is a person sitting in front of this process".
+ */
+function hasControllingTty(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const ttyNr = Number(rest[4]); // field 7 == index 4 after pid and comm
+        return Number.isFinite(ttyNr) && ttyNr !== 0;
+    }
+    catch {
+        return false; // unreadable — the caller's other guards decide
+    }
+}
+/**
+ * Every live process whose working directory sits inside `prefix` AND which has
+ * no controlling terminal.
+ *
+ * The tag scan above misses a descendant that scrubbed its environment (a
+ * process launched through `env -i`, a re-exec that rebuilds environ, some
+ * language runtimes' worker pools). Those still have to live SOMEWHERE. Under
+ * the old projection that somewhere was the environment's own tree; since
+ * decision 0032 services run in the caller's worktree, where cwd proves
+ * nothing, so the engine only ever points this at an environment's PRIVATE
+ * directory (see Engine.reapEnvTree).
+ *
+ * Linux keeps the cwd link readable after the directory is unlinked, appending
+ * " (deleted)" to the target — which is precisely the shape of the leak this
+ * exists to catch: hundreds of service children still running out of an
+ * environment tree that was removed a day earlier. The suffix is stripped so a
+ * deleted tree still matches its prefix.
+ *
+ * The tty exclusion is not a nicety. cwd is NOT proof of ownership — a developer
+ * who runs `cd <env-tree>` to look around matches this scan exactly, and callers
+ * signal a matched process's whole GROUP, so without the exclusion a teardown
+ * would kill that person's shell and every job in it. That is the one outcome
+ * this module exists to prevent (see the header): skipping a sweep is safe,
+ * signalling a stranger's process is not. A runly service can never be
+ * excluded by it, because it never has a terminal to begin with.
+ *
+ * Even so, deliberately NOT used on the quiesce path, and never on a worktree:
+ * only teardown, which is about to delete the environment's private directory
+ * anyway, may reap by cwd — and only inside that directory.
+ */
+export function scanByCwd(prefix) {
+    if (!procScanSupported())
+        return [];
+    const self = process.pid;
+    const found = [];
+    let entries;
+    try {
+        entries = readdirSync('/proc');
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        const pid = Number(entry);
+        if (!Number.isInteger(pid) || pid <= 0 || pid === self)
+            continue;
+        let cwd;
+        try {
+            cwd = readlinkSync(`/proc/${pid}/cwd`);
+        }
+        catch {
+            continue; // exited, or another user's process — not ours to touch
+        }
+        const path = cwd.endsWith(' (deleted)') ? cwd.slice(0, -' (deleted)'.length) : cwd;
+        // Prefix match on a path BOUNDARY, so `…/env-1` never matches `…/env-10`.
+        if (path !== prefix && !path.startsWith(prefix.endsWith('/') ? prefix : prefix + '/'))
+            continue;
+        if (hasControllingTty(pid))
+            continue; // a person is using this one
+        const st = startTime(pid);
+        if (st === undefined)
+            continue; // exited between the two reads
+        found.push({ pid, startTime: st, cwd });
+    }
+    return found;
+}
+//# sourceMappingURL=procscan.js.map

package/dist/core/procscan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"procscan.js","sourceRoot":"","sources":["../../src/core/procscan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,CAAC,MAAM,OAAO,GAAG,gBAAgB,CAAC;AACxC,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,iFAAiF;AACjF,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;AAS7C,gEAAgE;AAChE,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,OAAe,EAAE,SAAiB;IAC1E,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;AAC7E,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAY,EAAE,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AAE7E;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,0CAA0C;QAC1E,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,4BAA4B;IAChD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE;YACnE,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO,EAAE,IAAI;SACd,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,mCAAmC;IACvD,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,wCAAwC;QACtE,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,yEAAyE;IACzE,6EAA6E;IAC7E,iEAAiE;IACjE,2EAA2E;IAC3E,gEAAgE;IAChE,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,qEAAqE;QACrE,OAAQ,GAA6B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACH,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,6DAA6D;QAC7D,OAAQ,GAA6B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,aAAsB;IAC7D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,aAAa,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,OAAO,KAAK,aAAa,CAAC;AACnC,CAAC;AAED,yEAAyE;AACzE,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,GAAG,UAAU,EAAE,MAAM,CAAC,CAAC;QACzD,MAAM,GAAG,GAA2B,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,EAAE,GAAG,CAAC;gBAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,6CAA6C;IACjE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,SAAiB;IAC1C,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;YAAE,SAAS;QACjD,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,SAAS;YAAE,SAAS;QAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,2EAA2E;QAC3E,wEAAwE;QACxE,kEAAkE;QAClE,IAAI,GAAG,CAAC,WAAW,CAAC,KAAK,YAAY;YAAE,SAAS;QAChD,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS,CAAC,+BAA+B;QAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,WAAW,CAAC,IAAI,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0GAA0G;AAC1G,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE7C,8FAA8F;AAC9F,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,SAAiB;IACvD,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,SAAiB;IACxD,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,KAAK,GAA8C,EAAE,CAAC;IAC5D,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,OAAO,CAAC,GAAG;YAAE,SAAS;QACxE,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,CAAC,KAAK,IAAI;YAAE,SAAS;QAC/E,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,GAAW;IACpC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,wCAAwC;QACvE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,gDAAgD;IAChE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC;IACzB,MAAM,KAAK,GAA2D,EAAE,CAAC;IACzE,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,IAAI;YAAE,SAAS;QACjE,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,YAAY,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,wDAAwD;QACpE,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACnF,0EAA0E;QAC1E,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC;YAAE,SAAS;QAChG,IAAI,iBAAiB,CAAC,GAAG,CAAC;YAAE,SAAS,CAAC,6BAA6B;QACnE,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS,CAAC,+BAA+B;QAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/retention.d.ts

@@ -0,0 +1,97 @@
+import type { Journal } from './journal.js';
+import type { Policy } from './policy.js';
+/**
+ * Service logs past the cap are rotated once (decision 0038): `<name>.log`
+ * becomes `<name>.log.1`, replacing the previous rotation. The writer rotates
+ * as it writes; this is the backstop for a file it never reached (a writer
+ * from an older daemon, or a log that grew between restarts). Only `*.log`
+ * files are touched.
+ */
+export declare function truncateLogs(p: Policy, root?: string): number;
+/**
+ * Which stacks a template may still serve: anything a journal row names, or
+ * whose worktree is still on disk (decision 0037). A stack whose worktree is
+ * gone and that no row names keeps no "current" template — nobody can bind
+ * it again.
+ */
+export interface TemplateRefs {
+    /** `<stack>/<file>` of every template an environment or copy was restored from. */
+    referenced: ReadonlySet<string>;
+    /** False when the stack can never be bound again. */
+    stackAlive: (stackId: string) => boolean;
+    /**
+     * Where a template's recorded drop command runs: it comes from the
+     * manifest and is written to run in the repo (`node scripts/db.cjs drop …`).
+     * The stack's own worktree while it exists, else a live worktree of the same
+     * project (same manifest name; from the journal or a sibling's `.root`),
+     * else the templates root.
+     */
+    dropCwd?: (stackId: string) => string;
+}
+export type TemplateVerdict = {
+    f: string;
+    keep: true;
+    why: 'current' | 'referenced' | 'grace';
+} | {
+    f: string;
+    keep: false;
+    why: 'superseded' | 'dead' | 'private' | 'duplicate';
+};
+/**
+ * What retention (and `pool doctor`, without the grace) does with each
+ * template in one templates dir (decisions 0037, 0044):
+ *
+ * - per datastore and preset, the newest `keep` are current — in a stack dir
+ *   that can be bound again, or in a `<name>@shared` dir while any worktree of
+ *   that name can;
+ * - a template a row or a live worktree's record references stays;
+ * - a private (`--pristine`) template is never "current": it stays only while
+ *   referenced;
+ * - a per-worktree template whose file name the shared dir also holds is a
+ *   duplicate of it (the migration adopted it), never "current" either;
+ * - anything else goes once older than `grace`.
+ */
+export declare function templateVerdicts(dir: string, files: Array<{
+    f: string;
+    mtime: number;
+}>, refs: TemplateRefs, keepNewest: number, graceMs: number, sharedFiles?: ReadonlySet<string>): TemplateVerdict[];
+/** The template files of one dir with their mtimes (dot-files — `.root` — excluded). */
+export declare function templateFiles(dir: string): Array<{
+    f: string;
+    mtime: number;
+}>;
+/** The file names in the shared dir of `dir`'s project (empty for a shared dir itself). */
+export declare function sharedFilesFor(dir: string, root?: string): Set<string>;
+/**
+ * Templates are collected by reference (decisions 0037, 0044): see
+ * `templateVerdicts`. A marker for a server-side template is dropped WITH its
+ * database (its persisted drop command), unless another marker still names it.
+ */
+export declare function pruneTemplates(p: Pick<Policy, 'templatesKeep'> & Partial<Pick<Policy, 'templateGraceMs'>>, root?: string, refs?: TemplateRefs): Promise<number>;
+/**
+ * Per-worktree state (decision 0032 — the trigger-file hash cache and the upkeep
+ * ledger) for a worktree that no longer exists. It must outlive every
+ * environment, because `runly warm` writes it for a worktree with none; so it
+ * goes only when its recorded root is gone AND no environment still names the
+ * stack. A missing or unreadable record is left alone: it proves nothing.
+ */
+export declare function pruneWorktreeState(journal: Journal, root?: string): number;
+/**
+ * What the journal says about templates (decision 0037): the ones rows
+ * reference, and which stacks are alive. A stack no row names is alive while
+ * the worktree it was recorded for exists — recorded by its worktree state
+ * (`worktrees/<stack>/*.json`) or by the `.root` its first bake wrote next to
+ * its templates. A stack with no record at all is NOT alive (0.19): its
+ * worktree records were pruned because the worktree was gone, and treating it
+ * as alive kept the templates of every pruned worktree forever.
+ *
+ * Shared templates (decision 0044): `<name>@shared` is alive while any stack
+ * of that name is; a live worktree's `templates.json` (the template each of
+ * its datastores was last restored from) counts as a reference.
+ */
+export declare function templateRefs(journal: Journal, root?: string, templates?: string): TemplateRefs;
+export declare function retentionSweep(journal: Journal, p: Policy): Promise<{
+    logs: number;
+    templates: number;
+    worktrees: number;
+}>;