@tpsdev-ai/flair-mcp 0.57.0 → 0.58.0

package/dist/continuity.d.ts

@@ -55,6 +55,25 @@
  *     file untouched (scenario S7: compaction ≠ restart; no rotation, no new
  *     sessionId).
  *
+ * PRE-COMPACTION RECORD (flair#2069): just before a compaction, each run of
+ * the `flair-precompact` hook that has something to record attempts at most
+ * one PUT of a row into the session's journal, once its local checks pass, in
+ * this row shape with meta.hook "PreCompact" (a row is added or updated only
+ * when Flair applies that PUT); a later run for the same harness session and
+ * trigger within its dedup window, which starts when the marker first names
+ * the id (before the first PUT is attempted), reuses the row's id, so its
+ * PUT, if applied, creates that row if it is absent and updates it if
+ * present (./precompact.ts PRECOMPACT_DEDUP_WINDOW_MS). It quotes user turns, so unlike the journal
+ * lines it is redacted, and it is the one continuity row whose CONTENT
+ * flair-session-start shows (first, after a compaction or a restart, when the
+ * local marker names it and the GET returns an eligible live row). Its rules
+ * live in ./precompact.ts; nothing above
+ * changes for journal rows. That
+ * hook arms a process-level deadline, which can fire only between
+ * asynchronous steps, so it reads the state file through
+ * bumpSeqBounded (asynchronous, size-capped with fstat before any byte is
+ * read) instead of the synchronous bumpSeq the capture hook uses.
+ *
  * FAIL-OPEN THROUGHOUT: continuity is a recovery aid, not a correctness gate.
  * Flair unreachable, a #1261 guard 400, a malformed payload, a missing state
  * file — every failure degrades to "journal nothing / hint nothing" and never
@@ -121,6 +140,34 @@ export declare function readPointer(sessionDir: string, agentId: string): Sessio
 /** Read + parse a state file. null on ANY problem — capture then journals
  *  nothing (continuity wasn't seeded for this harness session). */
 export declare function readState(sessionDir: string, agentId: string, harnessSessionId: string): SessionState | null;
+/**
+ * Upper bound on a session file read through readSmallFile: the state file and
+ * the pre-compaction marker (./precompact.ts). Each is a few hundred bytes when
+ * Flair wrote it, so anything larger is refused unread.
+ */
+export declare const SESSION_FILE_MAX_BYTES: number;
+/** A bounded read's outcome. Only a missing file is "absent"; every other
+ *  failure is "refused" with a short reason, never an empty read. */
+export type SmallFileRead = {
+    kind: "absent";
+} | {
+    kind: "ok";
+    text: string;
+} | {
+    kind: "refused";
+    detail: string;
+};
+/**
+ * Read a small regular file without ever holding the event loop:
+ *   - the open is non-blocking, so a FIFO at the path cannot stall it;
+ *   - the opened descriptor is checked with fstat BEFORE any byte is read, and
+ *     anything that is not a regular file of at most `maxBytes` is refused;
+ *   - at most `maxBytes + 1` bytes are ever read, so a file that grew after
+ *     the check is refused too;
+ *   - every step is asynchronous, so a process-level deadline can fire
+ *     between them.
+ */
+export declare function readSmallFile(path: string, maxBytes?: number): Promise<SmallFileRead>;
 /**
  * Mint a fresh sessionId + processUUID, seed the per-harness-session state
  * file (seq 0) and rotate the pointer file to the new session. Called by the
@@ -143,6 +190,28 @@ export declare function seedSession(sessionDir: string, agentId: string, harness
  * its seq — gaps are fine, non-monotonicity is not.
  */
 export declare function bumpSeq(sessionDir: string, agentId: string, harnessSessionId: string, now?: Date): SessionState | null;
+/** bumpSeqBounded's outcome. "absent" (never seeded) is kept apart from
+ *  "unreadable" (a state file that exists but was refused or did not parse),
+ *  so a caller that reports it never words the second as the first. */
+export type SeqBump = {
+    kind: "bumped";
+    state: SessionState;
+} | {
+    kind: "absent";
+} | {
+    kind: "unreadable";
+    detail: string;
+} | {
+    kind: "unwritable";
+};
+/**
+ * bumpSeq for a caller with a process-level deadline (the PreCompact hook):
+ * the same increment and the same temp-file + rename, with every step
+ * asynchronous and the read bounded by readSmallFile (size-capped with fstat
+ * before any byte is read; a FIFO or other non-regular file refused). Never
+ * throws.
+ */
+export declare function bumpSeqBounded(sessionDir: string, agentId: string, harnessSessionId: string, now?: Date): Promise<SeqBump>;
 /** Subset of the Claude Code hook payload the capture bin reads. It extracts
  *  ONLY these fields — the raw hook JSON (tool_input.command, tool_response,
  *  transcript_path, …) is NEVER stored or forwarded. */

package/dist/continuity.js

@@ -55,12 +55,32 @@
  *     file untouched (scenario S7: compaction ≠ restart; no rotation, no new
  *     sessionId).
  *
+ * PRE-COMPACTION RECORD (flair#2069): just before a compaction, each run of
+ * the `flair-precompact` hook that has something to record attempts at most
+ * one PUT of a row into the session's journal, once its local checks pass, in
+ * this row shape with meta.hook "PreCompact" (a row is added or updated only
+ * when Flair applies that PUT); a later run for the same harness session and
+ * trigger within its dedup window, which starts when the marker first names
+ * the id (before the first PUT is attempted), reuses the row's id, so its
+ * PUT, if applied, creates that row if it is absent and updates it if
+ * present (./precompact.ts PRECOMPACT_DEDUP_WINDOW_MS). It quotes user turns, so unlike the journal
+ * lines it is redacted, and it is the one continuity row whose CONTENT
+ * flair-session-start shows (first, after a compaction or a restart, when the
+ * local marker names it and the GET returns an eligible live row). Its rules
+ * live in ./precompact.ts; nothing above
+ * changes for journal rows. That
+ * hook arms a process-level deadline, which can fire only between
+ * asynchronous steps, so it reads the state file through
+ * bumpSeqBounded (asynchronous, size-capped with fstat before any byte is
+ * read) instead of the synchronous bumpSeq the capture hook uses.
+ *
  * FAIL-OPEN THROUGHOUT: continuity is a recovery aid, not a correctness gate.
  * Flair unreachable, a #1261 guard 400, a malformed payload, a missing state
  * file — every failure degrades to "journal nothing / hint nothing" and never
  * blocks the agent's turn or boot.
  */
-import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, constants as fsConstants, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmod, open, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -161,31 +181,100 @@ export function readPointer(sessionDir, agentId) {
         return null;
     }
 }
-/** Read + parse a state file. null on ANY problem — capture then journals
- *  nothing (continuity wasn't seeded for this harness session). */
-export function readState(sessionDir, agentId, harnessSessionId) {
+/** Parse a state file's text: the state, or why it is not one. */
+function parseState(raw, agentId, harnessSessionId) {
+    let parsed;
     try {
-        const raw = readFileSync(statePath(sessionDir, agentId, harnessSessionId), "utf-8");
-        const parsed = JSON.parse(raw);
-        if (parsed &&
-            typeof parsed.sessionId === "string" && parsed.sessionId !== "" &&
-            typeof parsed.processUUID === "string" && parsed.processUUID !== "" &&
-            typeof parsed.seq === "number" && Number.isFinite(parsed.seq)) {
-            return {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, detail: "malformed JSON" };
+    }
+    if (parsed &&
+        typeof parsed.sessionId === "string" && parsed.sessionId !== "" &&
+        typeof parsed.processUUID === "string" && parsed.processUUID !== "" &&
+        typeof parsed.seq === "number" && Number.isFinite(parsed.seq)) {
+        return {
+            ok: true,
+            state: {
                 sessionId: parsed.sessionId,
                 processUUID: parsed.processUUID,
                 seq: parsed.seq,
                 agentId: typeof parsed.agentId === "string" ? parsed.agentId : agentId,
                 harnessSessionId: typeof parsed.harnessSessionId === "string" ? parsed.harnessSessionId : harnessSessionId,
                 updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
-            };
-        }
-        return null;
+            },
+        };
+    }
+    return { ok: false, detail: "unexpected shape" };
+}
+/** Read + parse a state file. null on ANY problem — capture then journals
+ *  nothing (continuity wasn't seeded for this harness session). */
+export function readState(sessionDir, agentId, harnessSessionId) {
+    try {
+        const parsed = parseState(readFileSync(statePath(sessionDir, agentId, harnessSessionId), "utf-8"), agentId, harnessSessionId);
+        return parsed.ok ? parsed.state : null;
     }
     catch {
         return null;
     }
 }
+// ── bounded asynchronous reads (the PreCompact hook's deadline) ─────────────
+/**
+ * Upper bound on a session file read through readSmallFile: the state file and
+ * the pre-compaction marker (./precompact.ts). Each is a few hundred bytes when
+ * Flair wrote it, so anything larger is refused unread.
+ */
+export const SESSION_FILE_MAX_BYTES = 16 * 1024;
+/**
+ * Read a small regular file without ever holding the event loop:
+ *   - the open is non-blocking, so a FIFO at the path cannot stall it;
+ *   - the opened descriptor is checked with fstat BEFORE any byte is read, and
+ *     anything that is not a regular file of at most `maxBytes` is refused;
+ *   - at most `maxBytes + 1` bytes are ever read, so a file that grew after
+ *     the check is refused too;
+ *   - every step is asynchronous, so a process-level deadline can fire
+ *     between them.
+ */
+export async function readSmallFile(path, maxBytes = SESSION_FILE_MAX_BYTES) {
+    let handle;
+    try {
+        handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK ?? 0));
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return { kind: "absent" };
+        return { kind: "refused", detail: typeof code === "string" ? code : "unreadable" };
+    }
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile())
+            return { kind: "refused", detail: "not a regular file" };
+        if (opened.size > maxBytes)
+            return { kind: "refused", detail: `larger than ${maxBytes} bytes` };
+        // Read to EOF, not to the size fstat reported, into a buffer one byte
+        // larger than the cap: a file that grew past the cap is refused, never cut.
+        const buf = Buffer.alloc(maxBytes + 1);
+        let got = 0;
+        while (got < buf.length) {
+            const { bytesRead } = await handle.read(buf, got, buf.length - got, got);
+            if (bytesRead === 0)
+                break;
+            got += bytesRead;
+        }
+        if (got > maxBytes)
+            return { kind: "refused", detail: `larger than ${maxBytes} bytes` };
+        return { kind: "ok", text: buf.subarray(0, got).toString("utf8") };
+    }
+    catch (err) {
+        const code = err?.code;
+        return { kind: "refused", detail: typeof code === "string" ? code : "unreadable" };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
 /**
  * Mint a fresh sessionId + processUUID, seed the per-harness-session state
  * file (seq 0) and rotate the pointer file to the new session. Called by the
@@ -237,6 +326,35 @@ export function bumpSeq(sessionDir, agentId, harnessSessionId, now = new Date())
         return null;
     }
 }
+/**
+ * bumpSeq for a caller with a process-level deadline (the PreCompact hook):
+ * the same increment and the same temp-file + rename, with every step
+ * asynchronous and the read bounded by readSmallFile (size-capped with fstat
+ * before any byte is read; a FIFO or other non-regular file refused). Never
+ * throws.
+ */
+export async function bumpSeqBounded(sessionDir, agentId, harnessSessionId, now = new Date()) {
+    const finalPath = statePath(sessionDir, agentId, harnessSessionId);
+    const read = await readSmallFile(finalPath);
+    if (read.kind === "absent")
+        return { kind: "absent" };
+    if (read.kind === "refused")
+        return { kind: "unreadable", detail: read.detail };
+    const parsed = parseState(read.text, agentId, harnessSessionId);
+    if (!parsed.ok)
+        return { kind: "unreadable", detail: parsed.detail };
+    const next = { ...parsed.state, seq: parsed.state.seq + 1, updatedAt: now.toISOString() };
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await writeFile(tmpPath, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+        await chmod(tmpPath, 0o600);
+        await rename(tmpPath, finalPath);
+        return { kind: "bumped", state: next };
+    }
+    catch {
+        return { kind: "unwritable" };
+    }
+}
 /** HARD truncate at CAPTURE_BOUND_CHARS with a visible ellipsis, so a reader
  *  knows the excerpt is incomplete and never acts on a cut sentence as if it
  *  were whole. See CAPTURE_BOUND_CHARS — the bound is load-bearing. */

package/dist/env-guard.d.ts

@@ -56,7 +56,8 @@ export declare const ENV_RESURRECTED_BY_FLAIR_CLIENT: readonly ["FLAIR_URL"];
 export declare function stripInterpolationLiteralsFromEnv(env?: NodeJS.ProcessEnv, names?: readonly string[]): void;
 /**
  * Hook probe mode (flair#1007) — shared by every hook binary this package
- * ships (session-start-hook.ts, continuity-capture-hook.ts). `flair doctor`
+ * ships (session-start-hook.ts, continuity-capture-hook.ts,
+ * prompt-recall-hook.ts). `flair doctor`
  * sets FLAIR_HOOK_PROBE to ask "does this command still resolve and execute?"
  * and a probed binary answers by exiting immediately, before stdin, clients,
  * network or any side effect — being reached at all IS the answer.

package/dist/env-guard.js

@@ -70,7 +70,8 @@ export function stripInterpolationLiteralsFromEnv(env = process.env, names = ENV
 }
 /**
  * Hook probe mode (flair#1007) — shared by every hook binary this package
- * ships (session-start-hook.ts, continuity-capture-hook.ts). `flair doctor`
+ * ships (session-start-hook.ts, continuity-capture-hook.ts,
+ * prompt-recall-hook.ts). `flair doctor`
  * sets FLAIR_HOOK_PROBE to ask "does this command still resolve and execute?"
  * and a probed binary answers by exiting immediately, before stdin, clients,
  * network or any side effect — being reached at all IS the answer.

package/dist/precompact-hook.d.ts

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Flair PreCompact hook for Claude Code (flair#2069): when the transcript
+ * tail holds something to record and the local checks pass, attempt one PUT
+ * of a bounded continuity record before context is lost (to a new row, or,
+ * within the dedup window, to the same row), so the next session start can
+ * show it first. The record's
+ * content, bounds, redaction, storage and dedup are defined in
+ * ./precompact.ts; this file is the binary around them.
+ *
+ * PER RUN
+ * -------
+ *   1. Reads Claude Code's PreCompact payload on stdin: `hook_event_name`
+ *      ("PreCompact"), `session_id`, `transcript_path` and `trigger`
+ *      ("manual" for /compact, "auto" for automatic compaction).
+ *   2. Finds this harness session's continuity state (seeded by
+ *      flair-session-start) and consumes a journal seq, as
+ *      flair-continuity-capture does, through the bounded asynchronous
+ *      bumpSeqBounded.
+ *   3. Reads the transcript TAIL (bounded in bytes and lines) and builds the
+ *      record: standing instructions, open tasks, in-flight work and the last
+ *      assistant message, redacted and cut to the record bound. Nothing to
+ *      record: nothing written.
+ *   4. Resolves the record id through the local marker (a later run for the
+ *      same harness session and trigger within the dedup window reuses it),
+ *      writes the marker, then writes the row with one signed
+ *      `PUT /Memory/<id>` as the agent's own Ed25519 identity.
+ *
+ * EXIT 0 ON EVERY PATH IT HANDLES
+ * -------------------------------
+ * Claude Code blocks compaction when a PreCompact hook exits 2 or prints a
+ * `decision: "block"` object. Once this binary has started, it does neither
+ * on any path it handles: it exits 0 and prints either nothing or ONE
+ * `{"systemMessage": …}` object (a warning Claude Code shows the user). A
+ * failure before that (the launcher, the runtime's start-up, a static import
+ * that fails to load) is outside the binary; the documented command's
+ * `|| true` covers it. The time budget (FLAIR_PRECOMPACT_TIMEOUT_MS,
+ * default 5 s) is a process-level deadline armed in main(), after the module
+ * has loaded and the entry-point check (isDirectRun) has run, and before
+ * stdin is read. When it passes, the timer starts finishing whatever
+ * asynchronous work is still pending (stdin held open, a slow read, a write
+ * in flight): the hook prints the one timeout note when FLAIR_AGENT_ID is
+ * set, and nothing when it is not (main() decides this when it arms the
+ * deadline), then exits 0 once stdout drains, waiting at most a further
+ * STDOUT_DRAIN_GRACE_MS (1 s).
+ * Synchronous work can delay the timer itself; Claude Code's hook timeout is
+ * the outer bound. stdin is read up
+ * to STDIN_MAX_BYTES; a larger payload is ignored. The hook's own local files
+ * (the transcript, the continuity state file and the marker) are read
+ * asynchronously with a size cap checked (fstat) before any byte is read: the
+ * transcript by its tail caps, the state file and the marker by
+ * SESSION_FILE_MAX_BYTES. A state file or marker larger than that, or anything
+ * at those three paths that is not a regular file, is refused with a note.
+ * Its local writes are asynchronous too, so none of the hook's own file work
+ * can hold the process past the deadline.
+ * The deadline bounds asynchronous work only: a timer cannot preempt
+ * synchronous code, and one local read is synchronous and not this hook's
+ * own: flair-client reads the agent's key file synchronously while the client
+ * is built, outside the size caps above. The outer bound on the whole process
+ * is Claude Code's own hook `timeout` in the settings entry. What runs before
+ * main() arms the deadline (the launcher, the runtime's start-up, module
+ * loading, the entry-point check) is outside the budget too.
+ *
+ * NOTES (the only output)
+ * -----------------------
+ * Silent: a probe, a malformed or non-PreCompact payload, no FLAIR_AGENT_ID,
+ * a tail with nothing to record, and success. One note, naming the reason: no
+ * continuity state for the session, a state file that could not be read (too
+ * large, not a regular file, malformed) or updated, an unreadable transcript,
+ * a marker that could not be read or written, and a write that was not
+ * confirmed (named by its kind, from classifyPreCompactFailure's three
+ * inputs: a numeric HTTP status, 401 or 403 as auth and any other as
+ * http-<status>; the hook's own timer or an error named exactly TimeoutError,
+ * as timeout; anything else as unreachable. Never by an error's message text
+ * or URL. Worded as "may be missing", never as "not saved", because the
+ * server may have applied it). A note that names a state file or the marker
+ * shows its path through notePath, which changes it only where each rule
+ * applies (see notePath).
+ *
+ * IDENTITY
+ * --------
+ * The agent's own key, resolved like the other hooks (FLAIR_AGENT_ID +
+ * FLAIR_KEY_PATH or the standard key locations). The client is built with an
+ * empty admin pair, which turns off flair-client's FLAIR_ADMIN_USER /
+ * FLAIR_ADMIN_PASSWORD Basic fallback: the record is written as the agent or
+ * not at all.
+ *
+ * CONFIG (env)
+ *   FLAIR_AGENT_ID  (required; absent → silent no-op)
+ *   FLAIR_URL       (default via flair-client)
+ *   FLAIR_KEY_PATH  (default ~/.flair/keys/<agent>.key via flair-client)
+ *   FLAIR_PRECOMPACT_TIMEOUT_MS (default 5000; 250..15000)
+ *   FLAIR_SESSION_DIR (default ~/.flair/session; tests)
+ *   FLAIR_HOOK_PROBE (probe mode: exit 0 before stdin, files or network)
+ */
+import { type ContinuityClient } from "./continuity.js";
+type Env = Record<string, string | undefined>;
+export declare const ENV_PRECOMPACT_TIMEOUT_MS = "FLAIR_PRECOMPACT_TIMEOUT_MS";
+export declare const DEFAULT_PRECOMPACT_TIMEOUT_MS = 5000;
+export declare const PRECOMPACT_TIMEOUT_FLOOR_MS = 250;
+export declare const PRECOMPACT_TIMEOUT_CEILING_MS = 15000;
+/** Upper bound on the hook's stdin (the PreCompact payload is a few hundred bytes). */
+export declare const STDIN_MAX_BYTES: number;
+/** The process-level budget (armed in main(), before stdin is read; when it passes, finishing starts and the process exits once stdout drains, at most STDOUT_DRAIN_GRACE_MS later):
+ *  FLAIR_PRECOMPACT_TIMEOUT_MS when in range, else the default. */
+export declare function resolvePreCompactBudgetMs(env?: Env): number;
+/** The hook's OWN budget timer. Recognized by identity, never by message. */
+export declare class PreCompactTimeoutError extends Error {
+    constructor();
+}
+export type PreCompactFailureKind = "auth" | "timeout" | "unreachable" | `http-${number}`;
+/** Same rules as the session-start classifier (flair#1943): a numeric HTTP
+ *  status first (401/403 → auth), then the hook's own timer or an error named
+ *  exactly TimeoutError, else unreachable. Message text is never read. */
+export declare function classifyPreCompactFailure(err: unknown): PreCompactFailureKind;
+/** The hook's only non-empty output: ONE JSON object with a `systemMessage`
+ *  (shown to the user). Never a `decision` field: that could block compaction. */
+export declare function preCompactNote(text: string): string;
+/** The note for a write that was not confirmed. It never says the record
+ *  was not saved: after a timeout the server may still complete the write,
+ *  and after any other error the server may already have applied it (the
+ *  client can fail while reading or parsing the answer). What is known is
+ *  that the save was not confirmed, so the record may be missing. */
+export declare function writeFailedNote(kind: PreCompactFailureKind): string;
+/** The longest local path a note shows, in characters. */
+export declare const NOTE_PATH_MAX_CHARS = 200;
+/**
+ * A local path as a note shows it. Each change applies only where it fits:
+ *   - a path inside the home directory (`env.HOME`, else the OS's) starts
+ *     with "~" instead; a home directory of "/" collapses nothing;
+ *   - each control or line-break character is shown as "?";
+ *   - strings that match the credential patterns are redacted
+ *     (redactSecrets);
+ *   - a result longer than NOTE_PATH_MAX_CHARS is cut to that, ending in "…".
+ * A path outside the home directory that none of these touch is shown as it
+ * is. The session directory and the agent id in the path are configuration;
+ * a secret in them that matches no pattern is shown as written.
+ */
+export declare function notePath(path: string, env?: Env): string;
+export type PreCompactReason = "malformed-input" | "not-precompact" | "no-agent-id" | "bad-session-id" | "no-state" | "state-unreadable" | "state-unwritable" | "no-transcript" | "nothing-to-record" | "marker-unreadable" | "marker-unwritable" | "write-failed" | "written";
+export interface PreCompactOutcome {
+    /** The exact string the binary prints ("" prints nothing). */
+    output: string;
+    /** Why. Diagnostic only: the exit code is 0 regardless. */
+    reason: PreCompactReason;
+    /** The record id, once one was resolved. */
+    recordId?: string;
+    /** True when this run reused the marker's record id. */
+    reused?: boolean;
+}
+export interface PreCompactDeps {
+    makeClient?: (agentId: string, timeoutMs: number, env: Env) => ContinuityClient | Promise<ContinuityClient>;
+    env?: Env;
+    sessionDir?: string;
+    now?: () => Date;
+    /** When the budget started (epoch ms). The entry point passes its own start. */
+    startedAt?: number;
+    /** The process-level budget in ms (default: resolvePreCompactBudgetMs(env)). */
+    budgetMs?: number;
+}
+/**
+ * Core flow with injectable dependencies. Never throws for a failed read or
+ * write; returns the exact output plus a diagnostic reason.
+ */
+export declare function runPreCompact(rawInput: string, deps?: PreCompactDeps): Promise<PreCompactOutcome>;
+/**
+ * Whether this module is the process entry point. Where the runtime provides
+ * `import.meta.main` (Bun; Node 22.18+), its answer decides, true or false.
+ * Otherwise compare FILESYSTEM paths resolved through symlinks: the module URL
+ * is percent-encoded and an npm bin shim is a symlink, so comparing the URL
+ * string with `argv[1]` misses both.
+ */
+export declare function isDirectRun(moduleUrl: string, argv1: string | undefined, metaMain: boolean | undefined, realpath?: (p: string) => string): boolean;
+export {};