@descryy/runtime-controller 0.3.8 → 0.4.0

package/dist/attach-discovery.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Attach-mode discovery (H-attach-log-discovery): answers "what pid, if any,
+ * is listening on this port" and "where does that pid's own output go"
+ * from process/kernel state alone -- never by inferring what a framework
+ * logs, only by reading what the OS already knows. This is what lets
+ * `observe`'s attach mode work without the caller supplying a pid or a log
+ * file (`descry-core`'s own observe tool composes these two, once its pin on
+ * this package moves past the version that added them).
+ *
+ * Two independent lookups:
+ * - `findPortOwner` (port -> pid): reuses the same `/proc/net/tcp{,6}` +
+ *   per-pid fd-table matching `process-identity.ts`'s `verifyListeningSocketOwner`
+ *   already does for a DIFFERENT question (does a KNOWN pid own a port) --
+ *   this asks the converse (which pid, if any, owns it), so a second, small,
+ *   pure copy of the inode-matching core lives here rather than importing
+ *   that module's private helpers across a real seam boundary (this file's
+ *   own `reader` injection point, `process-identity.ts` has none).
+ * - `resolveLogSourceForPid` (pid -> log source descriptor): `readlink`s the
+ *   pid's own fd 1 and fd 2. A regular file is the file-attach path this
+ *   repo already tails with fencing (`attachManagedProcess`/
+ *   `attachToRunningProcess`) -- returned as a path for the caller to feed
+ *   into that machinery, not re-implemented here. A pipe or socket (a shell
+ *   redirect, a container runtime, a terminal) can't be read by another
+ *   process directly, so this falls back to the pid's own cgroup membership:
+ *   a Docker container's cgroup path names it, a systemd unit's cgroup path
+ *   names it. Building the actual stream source for those two
+ *   (`docker logs -f` / `journalctl -f`) is `@descryy/runtime-orchestrator`'s
+ *   job (`attach-log-sources.ts`) -- this package doesn't depend on the
+ *   `ProcessOutputSource` contract at all, and doesn't need to.
+ *
+ * **Injectable `ProcReader`, not real `/proc`, in tests.** Real Docker/systemd
+ * cgroup membership can't be fabricated hermetically against the real
+ * filesystem, and even the plain-file/plain-port cases are easier to prove
+ * correct against a fake than a real, racy `/proc`. Both functions default to
+ * `REAL_PROC_READER` and take an injected one for tests.
+ */
+/** The subset of filesystem reads this module needs from `/proc` -- injectable so tests never touch the real one. */
+export interface ProcReader {
+    readFile(path: string): string;
+    readdir(path: string): string[];
+    readlink(path: string): string;
+    /** `"dev:ino"` when `path` (symlinks followed) is a regular file, else `null` -- never a throw. */
+    regularFileIdentity(path: string): string | null;
+}
+export declare const REAL_PROC_READER: ProcReader;
+export type PortOwnerLookup = {
+    readonly outcome: "found";
+    readonly pid: number;
+} | {
+    readonly outcome: "nothing-listening";
+} | {
+    readonly outcome: "several-owners";
+    readonly pids: readonly number[];
+} | {
+    readonly outcome: "owned-by-docker-proxy";
+    readonly pid: number;
+} | {
+    readonly outcome: "proc-unreadable";
+    readonly reason: string;
+};
+/**
+ * Who, if anyone, is listening on `port` right now -- a real kernel-state
+ * lookup (`/proc/net/tcp{,6}` plus each candidate pid's own fd table), not a
+ * guess. `owned-by-docker-proxy` is named separately from `found` rather than
+ * silently returned as one: a published Docker port is commonly fronted by a
+ * host-side `docker-proxy` process, not the container's own pid, and treating
+ * that pid as the target would attach to the wrong process entirely.
+ */
+export declare function findPortOwner(port: number, reader?: ProcReader, platform?: NodeJS.Platform): PortOwnerLookup;
+export type LogSourceDescriptor = {
+    readonly kind: "file";
+    readonly path: string;
+} | {
+    readonly kind: "docker";
+    readonly container: string;
+} | {
+    readonly kind: "systemd";
+    readonly unit: string;
+} | {
+    readonly kind: "none";
+    readonly reason: string;
+};
+/**
+ * Where `pid`'s own log output can be read from, without the caller naming a
+ * pid or a log file. `file` reuses this repo's existing fenced file-tail path
+ * (`attachManagedProcess`/`attachToRunningProcess`) -- returned as a path for
+ * the caller to feed into that machinery, not re-implemented here.
+ * `docker`/`systemd` name a stream-only source `@descryy/runtime-orchestrator`
+ * builds directly -- neither has pre-existing content to fence, since both
+ * start reading from "now" (see `DiscoveredAttachLogSource`'s own doc,
+ * `@descryy/runtime-contracts`).
+ */
+export declare function resolveLogSourceForPid(pid: number, reader?: ProcReader, platform?: NodeJS.Platform): LogSourceDescriptor;
+//# sourceMappingURL=attach-discovery.d.ts.map

package/dist/attach-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-discovery.d.ts","sourceRoot":"","sources":["../src/attach-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,qHAAqH;AACrH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,mGAAmG;IACnG,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAClD;AAED,eAAO,MAAM,gBAAgB,EAAE,UAY9B,CAAC;AA6DF,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,UAA6B,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,eAAe,CA0BhJ;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAiDvD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,UAA6B,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,mBAAmB,CA4B5J"}

package/dist/attach-discovery.js

@@ -0,0 +1,238 @@
+/**
+ * Attach-mode discovery (H-attach-log-discovery): answers "what pid, if any,
+ * is listening on this port" and "where does that pid's own output go"
+ * from process/kernel state alone -- never by inferring what a framework
+ * logs, only by reading what the OS already knows. This is what lets
+ * `observe`'s attach mode work without the caller supplying a pid or a log
+ * file (`descry-core`'s own observe tool composes these two, once its pin on
+ * this package moves past the version that added them).
+ *
+ * Two independent lookups:
+ * - `findPortOwner` (port -> pid): reuses the same `/proc/net/tcp{,6}` +
+ *   per-pid fd-table matching `process-identity.ts`'s `verifyListeningSocketOwner`
+ *   already does for a DIFFERENT question (does a KNOWN pid own a port) --
+ *   this asks the converse (which pid, if any, owns it), so a second, small,
+ *   pure copy of the inode-matching core lives here rather than importing
+ *   that module's private helpers across a real seam boundary (this file's
+ *   own `reader` injection point, `process-identity.ts` has none).
+ * - `resolveLogSourceForPid` (pid -> log source descriptor): `readlink`s the
+ *   pid's own fd 1 and fd 2. A regular file is the file-attach path this
+ *   repo already tails with fencing (`attachManagedProcess`/
+ *   `attachToRunningProcess`) -- returned as a path for the caller to feed
+ *   into that machinery, not re-implemented here. A pipe or socket (a shell
+ *   redirect, a container runtime, a terminal) can't be read by another
+ *   process directly, so this falls back to the pid's own cgroup membership:
+ *   a Docker container's cgroup path names it, a systemd unit's cgroup path
+ *   names it. Building the actual stream source for those two
+ *   (`docker logs -f` / `journalctl -f`) is `@descryy/runtime-orchestrator`'s
+ *   job (`attach-log-sources.ts`) -- this package doesn't depend on the
+ *   `ProcessOutputSource` contract at all, and doesn't need to.
+ *
+ * **Injectable `ProcReader`, not real `/proc`, in tests.** Real Docker/systemd
+ * cgroup membership can't be fabricated hermetically against the real
+ * filesystem, and even the plain-file/plain-port cases are easier to prove
+ * correct against a fake than a real, racy `/proc`. Both functions default to
+ * `REAL_PROC_READER` and take an injected one for tests.
+ */
+import { readFileSync, readdirSync, readlinkSync, statSync } from "node:fs";
+export const REAL_PROC_READER = {
+    readFile: (path) => readFileSync(path, "utf8"),
+    readdir: (path) => readdirSync(path),
+    readlink: (path) => readlinkSync(path),
+    regularFileIdentity: (path) => {
+        try {
+            const stat = statSync(path);
+            return stat.isFile() ? `${String(stat.dev)}:${String(stat.ino)}` : null;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+function hexPort(port) {
+    return port.toString(16).toUpperCase().padStart(4, "0");
+}
+/** Every inode `/proc/net/tcp{,6}` records as LISTENing on `port`. A small, deliberate second copy of `process-identity.ts`'s private `listenInodesForPort` -- see this file's own header for why it isn't imported. */
+function listenInodesForPort(reader, port) {
+    const inodes = new Set();
+    const targetPort = hexPort(port);
+    const TCP_LISTEN_STATE = "0A";
+    for (const path of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+        let content;
+        try {
+            content = reader.readFile(path);
+        }
+        catch {
+            continue;
+        }
+        for (const line of content.split("\n").slice(1)) {
+            const fields = line.trim().split(/\s+/);
+            const localAddress = fields[1];
+            const state = fields[3];
+            const inode = fields[9];
+            if (localAddress === undefined || state === undefined || inode === undefined)
+                continue;
+            if (state !== TCP_LISTEN_STATE)
+                continue;
+            if (localAddress.split(":")[1] === targetPort)
+                inodes.add(inode);
+        }
+    }
+    return inodes;
+}
+/** Whether `pid`'s fd table holds one of `inodes`. `false`, never a throw, for a pid whose fd table cannot be read (exited mid-scan, or a permission boundary) -- the same benign-race tolerance this repo's other `/proc` scanners apply. */
+function ownsOneOf(reader, pid, inodes) {
+    let fds;
+    try {
+        fds = reader.readdir(`/proc/${pid}/fd`);
+    }
+    catch {
+        return false;
+    }
+    const SOCKET_FD_PATTERN = /^socket:\[(\d+)\]$/;
+    for (const fd of fds) {
+        let link;
+        try {
+            link = reader.readlink(`/proc/${pid}/fd/${fd}`);
+        }
+        catch {
+            continue;
+        }
+        const match = SOCKET_FD_PATTERN.exec(link);
+        if (match !== null && inodes.has(match[1]))
+            return true;
+    }
+    return false;
+}
+function commOf(reader, pid) {
+    try {
+        return reader.readFile(`/proc/${pid}/comm`).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Who, if anyone, is listening on `port` right now -- a real kernel-state
+ * lookup (`/proc/net/tcp{,6}` plus each candidate pid's own fd table), not a
+ * guess. `owned-by-docker-proxy` is named separately from `found` rather than
+ * silently returned as one: a published Docker port is commonly fronted by a
+ * host-side `docker-proxy` process, not the container's own pid, and treating
+ * that pid as the target would attach to the wrong process entirely.
+ */
+export function findPortOwner(port, reader = REAL_PROC_READER, platform = process.platform) {
+    if (platform !== "linux") {
+        return { outcome: "proc-unreadable", reason: `port ownership lookup requires /proc, which is Linux-only; not available on "${platform}"` };
+    }
+    const inodes = listenInodesForPort(reader, port);
+    if (inodes.size === 0)
+        return { outcome: "nothing-listening" };
+    let pidEntries;
+    try {
+        pidEntries = reader.readdir("/proc").filter((entry) => /^\d+$/.test(entry));
+    }
+    catch (error) {
+        return {
+            outcome: "proc-unreadable",
+            reason: `could not list /proc to find the process listening on port ${String(port)}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const owners = pidEntries.filter((pid) => ownsOneOf(reader, pid, inodes)).map(Number);
+    if (owners.length === 0)
+        return { outcome: "nothing-listening" };
+    if (owners.length > 1)
+        return { outcome: "several-owners", pids: owners };
+    const pid = owners[0];
+    if (commOf(reader, String(pid)) === "docker-proxy") {
+        return { outcome: "owned-by-docker-proxy", pid };
+    }
+    return { outcome: "found", pid };
+}
+/**
+ * The path of the regular file `pid` holds open on `fd`, or `null`. An absolute link target
+ * is not enough: a terminal (`/dev/pts/3`) and `/dev/null` are absolute too, and tailing a
+ * terminal device would read keystrokes, not logs. So the open file itself (`/proc/<pid>/fd/N`,
+ * which stat follows to the real inode) must be a regular file, and the path must still name
+ * that same inode -- after a log rotation the process keeps writing the old file while the path
+ * names a new one, and tailing the path would read a file nobody is writing to.
+ */
+function fileTargetOf(reader, pid, fd) {
+    const fdPath = `/proc/${String(pid)}/fd/${String(fd)}`;
+    let link;
+    try {
+        link = reader.readlink(fdPath);
+    }
+    catch {
+        return null;
+    }
+    if (!link.startsWith("/"))
+        return null;
+    const held = reader.regularFileIdentity(fdPath);
+    if (held === null)
+        return null;
+    return reader.regularFileIdentity(link) === held ? link : null;
+}
+/** `/proc/<pid>/cgroup`'s docker container id, from either the legacy `.../docker/<id>` path or the cgroup-v2 `.../docker-<id>.scope` form. `null` when neither pattern is present. */
+function dockerContainerFromCgroup(cgroup) {
+    const legacy = /\/docker\/([0-9a-f]{12,64})/.exec(cgroup);
+    if (legacy?.[1] !== undefined)
+        return legacy[1];
+    const scoped = /docker-([0-9a-f]{12,64})\.scope/.exec(cgroup);
+    return scoped?.[1] ?? null;
+}
+/**
+ * The system unit `pid` runs as, e.g. `myapp.service` from `0::/system.slice/myapp.service`.
+ * Only when that unit is the process's own cgroup leaf under `system.slice`: an app started
+ * from a desktop terminal sits under `user@1000.service/...`, the per-user manager, whose
+ * journal is every desktop app's output, and a user service's journal is not what
+ * `journalctl -u` reads. Either would attribute someone else's logs to the target, so
+ * both are `null` here and disclosed as unreadable rather than guessed.
+ */
+function systemdUnitFromCgroup(cgroup) {
+    for (const line of cgroup.split("\n")) {
+        const path = line.slice(line.indexOf(":", line.indexOf(":") + 1) + 1);
+        const match = /^\/system\.slice\/(?:[\w.@-]+\.slice\/)*([\w.@-]+\.service)$/.exec(path);
+        if (match?.[1] !== undefined)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Where `pid`'s own log output can be read from, without the caller naming a
+ * pid or a log file. `file` reuses this repo's existing fenced file-tail path
+ * (`attachManagedProcess`/`attachToRunningProcess`) -- returned as a path for
+ * the caller to feed into that machinery, not re-implemented here.
+ * `docker`/`systemd` name a stream-only source `@descryy/runtime-orchestrator`
+ * builds directly -- neither has pre-existing content to fence, since both
+ * start reading from "now" (see `DiscoveredAttachLogSource`'s own doc,
+ * `@descryy/runtime-contracts`).
+ */
+export function resolveLogSourceForPid(pid, reader = REAL_PROC_READER, platform = process.platform) {
+    if (platform !== "linux") {
+        return { kind: "none", reason: `log-source discovery reads /proc, which is Linux-only; not available on "${platform}"` };
+    }
+    const filePath = fileTargetOf(reader, pid, 1) ?? fileTargetOf(reader, pid, 2);
+    if (filePath !== null)
+        return { kind: "file", path: filePath };
+    let cgroup;
+    try {
+        cgroup = reader.readFile(`/proc/${String(pid)}/cgroup`);
+    }
+    catch (error) {
+        return {
+            kind: "none",
+            reason: `pid ${String(pid)}'s stdout/stderr is neither a regular file nor a terminal/pipe this process can name a container or service for, and its cgroup membership could not be read: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const container = dockerContainerFromCgroup(cgroup);
+    if (container !== null)
+        return { kind: "docker", container };
+    const unit = systemdUnitFromCgroup(cgroup);
+    if (unit !== null)
+        return { kind: "systemd", unit };
+    return {
+        kind: "none",
+        reason: `pid ${String(pid)}'s stdout/stderr is a pipe or terminal, not a regular file -- another process cannot read it, and its cgroup names neither a Docker container nor a systemd unit to follow instead.`,
+    };
+}
+//# sourceMappingURL=attach-discovery.js.map

package/dist/attach-discovery.js.map

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

package/dist/attach-fencing.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Attach fencing (RT-N3): the boundary between "content this run watched happen"
+ * and "content that already existed when this run started watching it."
+ *
+ * Both `orchestrator/src/attach-to-running-process.ts` and this package's own
+ * `attachManagedProcess` read a target's ENTIRE log file on every poll —
+ * necessary, since a plain file offers no delta API — which means the very
+ * first read hands back everything the target had already written before
+ * attach, indistinguishable from something that happens during this run
+ * unless something records the boundary.
+ *
+ * Real incident (`documents/plans/descry-uat-phase-4.md`, finding N3): a
+ * killed, orphaned FIRST process took its full timeout to exit and kept
+ * writing to the SAME log path a SECOND, successful process also used;
+ * attaching to the second process's pid read the first process's crash as if
+ * it were the second's own. Two independent fences close two independent
+ * parts of that gap:
+ *
+ * - `computeAttachFence` records, at the moment of attach, how much of the
+ *   log file already existed (`attachOffsetBytes`, `preExistingLineCount`)
+ *   and the target's own process start time (best-effort, Linux only) — the
+ *   information a caller needs to mark already-written content instead of
+ *   treating it as freshly observed.
+ * - `detectOtherLogWriters` answers a different question: is some OTHER
+ *   process, right now, also holding this same log file open for writing?
+ *   On Linux only, by scanning `/proc/*\/fd`. A genuinely shared log (e.g. a
+ *   `docker compose` stack's combined stream) is a legitimate answer here,
+ *   not refused — this function reports who else has the file open, and it
+ *   is the caller's job to decide what that means for a given target.
+ *
+ * Neither function makes attach perfectly correct — a log file carries no
+ * per-line writer-pid metadata, so "verify every line against the declared
+ * pid" is not implementable over a plain text file. What these two give a
+ * caller together: the boundary of what this run actually watched happen,
+ * and a best-effort, honestly-labelled answer to "is anything else writing
+ * here right now."
+ */
+export type ProcessStartTimeResult = {
+    readonly ok: true;
+    readonly startTimeMs: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * `pid`'s own start time, as wall-clock epoch milliseconds — Linux only.
+ * `/proc/<pid>/stat` field 22 (`starttime`) is clock ticks since boot, not
+ * since epoch; converted via `/proc/uptime`'s boot-relative uptime, itself
+ * converted to an epoch instant from `Date.now()` at read time (so this is
+ * only as precise as the gap between the two reads, sub-millisecond in
+ * practice).
+ *
+ * The `comm` field (`/proc/pid/stat` field 2) can itself contain spaces and
+ * parentheses — parsed by finding the LAST `)` on the line, matching every
+ * real `/proc/pid/stat` parser: the kernel guarantees the true comm field
+ * ends at the last `)`, whatever it contains.
+ */
+export declare function getProcessStartTimeMs(pid: number, platform?: NodeJS.Platform): ProcessStartTimeResult;
+export type OtherLogWriterCheck = {
+    readonly checked: true;
+    readonly otherWriterPids: readonly number[];
+} | {
+    readonly checked: false;
+    readonly reason: string;
+};
+/**
+ * Every OTHER process (not `targetPid`) currently holding an open file
+ * descriptor to `logFilePath`, by scanning `/proc/*\/fd` and comparing each
+ * descriptor's real target against `logFilePath`'s own real path. Linux only.
+ *
+ * A non-empty result is not by itself a problem — a deliberately shared log
+ * (several processes in one `docker compose` stack writing one combined
+ * stream) is legitimate multi-writer use. This function only answers "who
+ * else has it open right now"; a caller decides what that means for a given
+ * target.
+ *
+ * `checked: false` (never a thrown exception) only for what stops the scan
+ * from running AT ALL: non-Linux, `/proc` itself unreadable, or the log path
+ * can't be resolved to a real path. A single pid's `/proc/<pid>/fd` being
+ * unreadable (exited mid-scan, or a permission boundary) is NOT that —
+ * skipped for that one pid only, the same benign-race tolerance
+ * `inferRespawnCommandFromProc` already applies to `/proc` reads elsewhere
+ * in this codebase.
+ */
+export declare function detectOtherLogWriters(logFilePath: string, targetPid: number, platform?: NodeJS.Platform): OtherLogWriterCheck;
+export interface AttachFence {
+    /** The log file's size in bytes at the moment of attach — rotation detection compares this (or a later high-water mark) against the file's current size. */
+    readonly attachOffsetBytes: number;
+    /**
+     * How many complete lines already existed in the log file at the moment of
+     * attach. A source that yields lines in file order marks the first
+     * this-many `preExisting: true`. See `countCompleteLines` for the one
+     * disclosed edge case (a line torn exactly at the attach instant).
+     */
+    readonly preExistingLineCount: number;
+    /** Best-effort, Linux-only; `ok: false` on any other platform or read failure — never blocks the attach itself. */
+    readonly processStartTime: ProcessStartTimeResult;
+    /** See `detectOtherLogWriters` — computed once, at the moment of attach, against the pid this fence was built for. */
+    readonly otherWriters: OtherLogWriterCheck;
+    readonly attachedAt: string;
+}
+/**
+ * Snapshots the fence at the moment of attach. Never throws: a log file that
+ * doesn't exist yet at attach time (a target that hasn't written anything) is
+ * an honest zero-backlog fence, not an error — the file-tail machinery
+ * downstream already tolerates a not-yet-existing path the same way.
+ */
+export declare function computeAttachFence(pid: number, logFilePath: string, platform?: NodeJS.Platform): AttachFence;
+//# sourceMappingURL=attach-fencing.d.ts.map

package/dist/attach-fencing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-fencing.d.ts","sourceRoot":"","sources":["../src/attach-fencing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAsBH,MAAM,MAAM,sBAAsB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAwB3I;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,sBAAsB,CAiCvH;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,mBAAmB,CA+C/I;AAED,MAAM,WAAW,WAAW;IAC1B,4JAA4J;IAC5J,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,mHAAmH;IACnH,QAAQ,CAAC,gBAAgB,EAAE,sBAAsB,CAAC;IAClD,sHAAsH;IACtH,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,WAAW,CAgB9H"}