@nathapp/nax-agent 0.1.0

package/dist/internal/path-file-lock.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generic path-keyed file lock.
+ *
+ * Keyed on an arbitrary file path (e.g. `metrics.json`) instead of the queue
+ * file. Used to serialize read-modify-write sequences across processes so a
+ * concurrent `saveRunMetrics` cannot race with another and drop one run's
+ * append (BUG-6).
+ *
+ * Implementation is the shared single-file exclusive-create lock in
+ * `file-lock.ts` (see its module doc for the #1731 correctness argument and
+ * the BUG-10 / BUG-25 staleness rules). The lock file lives next to the
+ * target as `<target>.lock`.
+ *
+ * Failure mode: the default 5s timeout aborts with a descriptive error —
+ * it never enters over a possible holder (fail closed).
+ */
+export interface PathFileLockOptions {
+    /** Milliseconds between acquisition retries. Default 10. */
+    retryMs?: number;
+    /** Maximum time to wait for the lock before throwing. Default 5000. */
+    timeoutMs?: number;
+}
+export declare function withPathFileLock<T>(targetPath: string, operation: () => Promise<T>, options?: PathFileLockOptions): Promise<T>;

package/dist/internal/path-file-lock.js

@@ -0,0 +1,25 @@
+/**
+ * Generic path-keyed file lock.
+ *
+ * Keyed on an arbitrary file path (e.g. `metrics.json`) instead of the queue
+ * file. Used to serialize read-modify-write sequences across processes so a
+ * concurrent `saveRunMetrics` cannot race with another and drop one run's
+ * append (BUG-6).
+ *
+ * Implementation is the shared single-file exclusive-create lock in
+ * `file-lock.ts` (see its module doc for the #1731 correctness argument and
+ * the BUG-10 / BUG-25 staleness rules). The lock file lives next to the
+ * target as `<target>.lock`.
+ *
+ * Failure mode: the default 5s timeout aborts with a descriptive error —
+ * it never enters over a possible holder (fail closed).
+ */
+import { withFileLock } from "./file-lock.js";
+export async function withPathFileLock(targetPath, operation, options = {}) {
+    return withFileLock(`${targetPath}.lock`, operation, {
+        retryMs: options.retryMs,
+        timeoutMs: options.timeoutMs,
+        lockName: "path",
+        errorPrefix: "[path-lock]",
+    });
+}

package/dist/internal/process-alive.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Process Liveness Probe — SSOT
+ *
+ * Answers "is this PID still running?" for lock holders, queue holders, and
+ * spawned children. This is the only place in the codebase that interprets a
+ * `process.kill(pid, 0)` probe.
+ */
+/**
+ * Check whether a process with the given PID is still alive.
+ *
+ * `process.kill(pid, 0)` sends no signal — it only performs the permission and
+ * existence checks the kernel would run for a real signal, then throws on
+ * failure. Interpreting that throw is the whole subtlety:
+ *
+ * | Outcome        | Meaning                                    | Alive? |
+ * |:---------------|:-------------------------------------------|:-------|
+ * | no throw       | Probe succeeded                            | yes    |
+ * | `ESRCH`        | No such process                            | no     |
+ * | `EPERM`        | Process EXISTS, caller may not signal it   | yes    |
+ * | any other/none | Probe inconclusive                         | yes    |
+ *
+ * Only `ESRCH` proves absence. A bare `catch { return false }` — the shape this
+ * helper replaces — misreads `EPERM` as "dead", so a live run owned by another
+ * user or another privilege level looks stale. That is a correctness bug for
+ * every caller that then reclaims the resource: `nax unlock` deletes a running
+ * process's lock, and lock acquisition lets a second run start on top of the
+ * first. Inconclusive errors therefore fail **safe** (report alive) rather than
+ * fail convenient.
+ *
+ * @param pid - Process ID to probe. Non-positive and non-finite values are
+ *   never valid process IDs and report dead without probing — passing a
+ *   negative PID to `process.kill` would address a process *group*.
+ * @returns true if the process exists (or its existence cannot be ruled out)
+ *
+ * @example
+ * ```ts
+ * if (isProcessAlive(lockPid)) {
+ *   throw new NaxError(`nax is already running (PID ${lockPid})`, "LOCK_ACQUISITION_FAILED", { stage: "file-lock" });
+ * }
+ * ```
+ */
+export declare function isProcessAlive(pid: number): boolean;

package/dist/internal/process-alive.js

@@ -0,0 +1,56 @@
+/**
+ * Process Liveness Probe — SSOT
+ *
+ * Answers "is this PID still running?" for lock holders, queue holders, and
+ * spawned children. This is the only place in the codebase that interprets a
+ * `process.kill(pid, 0)` probe.
+ */
+/**
+ * Check whether a process with the given PID is still alive.
+ *
+ * `process.kill(pid, 0)` sends no signal — it only performs the permission and
+ * existence checks the kernel would run for a real signal, then throws on
+ * failure. Interpreting that throw is the whole subtlety:
+ *
+ * | Outcome        | Meaning                                    | Alive? |
+ * |:---------------|:-------------------------------------------|:-------|
+ * | no throw       | Probe succeeded                            | yes    |
+ * | `ESRCH`        | No such process                            | no     |
+ * | `EPERM`        | Process EXISTS, caller may not signal it   | yes    |
+ * | any other/none | Probe inconclusive                         | yes    |
+ *
+ * Only `ESRCH` proves absence. A bare `catch { return false }` — the shape this
+ * helper replaces — misreads `EPERM` as "dead", so a live run owned by another
+ * user or another privilege level looks stale. That is a correctness bug for
+ * every caller that then reclaims the resource: `nax unlock` deletes a running
+ * process's lock, and lock acquisition lets a second run start on top of the
+ * first. Inconclusive errors therefore fail **safe** (report alive) rather than
+ * fail convenient.
+ *
+ * @param pid - Process ID to probe. Non-positive and non-finite values are
+ *   never valid process IDs and report dead without probing — passing a
+ *   negative PID to `process.kill` would address a process *group*.
+ * @returns true if the process exists (or its existence cannot be ruled out)
+ *
+ * @example
+ * ```ts
+ * if (isProcessAlive(lockPid)) {
+ *   throw new NaxError(`nax is already running (PID ${lockPid})`, "LOCK_ACQUISITION_FAILED", { stage: "file-lock" });
+ * }
+ * ```
+ */
+export function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Only ESRCH proves absence. EPERM, any other errno, and a throw carrying
+        // no errno at all all mean the same thing — the process was not proven
+        // gone — so they report alive. Reclaiming callers (lock steal, unlock
+        // delete) must never act on an inconclusive probe.
+        return error.code !== "ESRCH";
+    }
+}

package/dist/internal/process-kill.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Process Group Kill Utility
+ *
+ * Shared helper for killing process groups, preventing orphaned child processes.
+ * Uses process.kill(-pid, signal) to kill the entire process group.
+ */
+/**
+ * Kill a process group by PID, falling back to single process if group kill fails.
+ *
+ * Process groups are spawned with the negative PID. This function:
+ * 1. Attempts to kill the entire process group (negative PID)
+ * 2. Falls back to killing the single process if group kill fails
+ *
+ * @param pid - Process ID (positive, not negative)
+ * @param signal - Signal to send (SIGTERM, SIGKILL, etc.)
+ * @returns true if kill was sent successfully, false if process already exited
+ *
+ * @example
+ * ```ts
+ * if (killProcessGroup(proc.pid, "SIGTERM")) {
+ *   console.log("Process group killed");
+ * } else {
+ *   console.log("Process already exited");
+ * }
+ * ```
+ */
+export declare function killProcessGroup(pid: number, signal: NodeJS.Signals | number): boolean;

package/dist/internal/process-kill.js

@@ -0,0 +1,54 @@
+/**
+ * Process Group Kill Utility
+ *
+ * Shared helper for killing process groups, preventing orphaned child processes.
+ * Uses process.kill(-pid, signal) to kill the entire process group.
+ */
+/**
+ * Kill a process group by PID, falling back to single process if group kill fails.
+ *
+ * Process groups are spawned with the negative PID. This function:
+ * 1. Attempts to kill the entire process group (negative PID)
+ * 2. Falls back to killing the single process if group kill fails
+ *
+ * @param pid - Process ID (positive, not negative)
+ * @param signal - Signal to send (SIGTERM, SIGKILL, etc.)
+ * @returns true if kill was sent successfully, false if process already exited
+ *
+ * @example
+ * ```ts
+ * if (killProcessGroup(proc.pid, "SIGTERM")) {
+ *   console.log("Process group killed");
+ * } else {
+ *   console.log("Process already exited");
+ * }
+ * ```
+ */
+export function killProcessGroup(pid, signal) {
+    // A pid that is not a real child reaches other processes: 0 is our own group,
+    // 1 (as -1) is every process we may signal, and a negative pid is init or a
+    // foreign group. A spawn that failed has no pid, so refuse rather than signal.
+    if (!Number.isInteger(pid) || pid <= 1)
+        return false;
+    // Try process group kill first (negative PID)
+    try {
+        process.kill(-pid, signal);
+        return true;
+    }
+    catch (error) {
+        const err = error;
+        // ESRCH = no such process — process group doesn't exist, try single process
+        if (err.code === "ESRCH") {
+            try {
+                process.kill(pid, signal);
+                return true;
+            }
+            catch {
+                // Process already exited
+                return false;
+            }
+        }
+        // Other errors (EPERM, etc.) — signal was likely sent, return true
+        return true;
+    }
+}

package/dist/internal/realpath.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Symlink-tolerant path normalisation for comparing paths from different sources.
+ *
+ * `getGitRoot` returns git's realpath — `git rev-parse --show-toplevel` run from
+ * `/tmp/repo` answers `/private/tmp/repo` — while paths threaded through config,
+ * pipeline context, or a story record keep whatever spelling the caller supplied.
+ * On macOS `/tmp` is a symlink to `/private/tmp` and worktrees are created under
+ * temp directories, so the two spellings meet constantly. Comparing them
+ * unresolved makes equal paths look different, and every containment check
+ * (`startsWith(root)`) silently fails closed.
+ *
+ * Pure apart from the `realpathSync` probe, and never throws.
+ */
+/**
+ * Absolute, symlink-resolved form of `p`.
+ *
+ * A path that does not exist cannot be resolved directly, so this walks up to
+ * the nearest ancestor that DOES exist, resolves that, and re-attaches the
+ * remaining segments. Resolving only the immediate parent is not enough: a
+ * changed file that has since been deleted, or one under a directory that was
+ * never created, leaves several missing segments — and a half-resolved answer
+ * compares unequal to a fully-resolved root, turning every containment check
+ * into a silent false negative.
+ *
+ * Falls back to the lexical absolute form when no ancestor resolves.
+ */
+export declare function realOrRaw(p: string): string;
+/** Is `filePath` inside `root`'s subtree, symlinks resolved on both sides? */
+export declare function isInside(root: string, filePath: string): boolean;

package/dist/internal/realpath.js

@@ -0,0 +1,52 @@
+/**
+ * Symlink-tolerant path normalisation for comparing paths from different sources.
+ *
+ * `getGitRoot` returns git's realpath — `git rev-parse --show-toplevel` run from
+ * `/tmp/repo` answers `/private/tmp/repo` — while paths threaded through config,
+ * pipeline context, or a story record keep whatever spelling the caller supplied.
+ * On macOS `/tmp` is a symlink to `/private/tmp` and worktrees are created under
+ * temp directories, so the two spellings meet constantly. Comparing them
+ * unresolved makes equal paths look different, and every containment check
+ * (`startsWith(root)`) silently fails closed.
+ *
+ * Pure apart from the `realpathSync` probe, and never throws.
+ */
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+/**
+ * Absolute, symlink-resolved form of `p`.
+ *
+ * A path that does not exist cannot be resolved directly, so this walks up to
+ * the nearest ancestor that DOES exist, resolves that, and re-attaches the
+ * remaining segments. Resolving only the immediate parent is not enough: a
+ * changed file that has since been deleted, or one under a directory that was
+ * never created, leaves several missing segments — and a half-resolved answer
+ * compares unequal to a fully-resolved root, turning every containment check
+ * into a silent false negative.
+ *
+ * Falls back to the lexical absolute form when no ancestor resolves.
+ */
+export function realOrRaw(p) {
+    const abs = resolve(p);
+    const trailing = [];
+    let current = abs;
+    for (;;) {
+        try {
+            return trailing.length === 0 ? realpathSync(current) : join(realpathSync(current), ...trailing);
+        }
+        catch {
+            const parent = dirname(current);
+            // `dirname` is a fixed point at the filesystem root — nothing resolved.
+            if (parent === current)
+                return abs;
+            trailing.unshift(basename(current));
+            current = parent;
+        }
+    }
+}
+/** Is `filePath` inside `root`'s subtree, symlinks resolved on both sides? */
+export function isInside(root, filePath) {
+    const base = realOrRaw(root);
+    const target = realOrRaw(filePath);
+    return target === base || target.startsWith(`${base}${sep}`);
+}

package/dist/internal/redact.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Secret-redaction helper for the JSONL logger write path.
+ *
+ * Two layers of protection:
+ *  1. Key-based: any field whose name matches SECRET_KEY_PATTERN gets its value
+ *     replaced with "[REDACTED]" regardless of content.
+ *  2. Pattern-based: free-text strings (in values that did NOT trigger layer 1)
+ *     are scanned for token-shaped substrings (API keys, PATs, etc.).
+ */
+/**
+ * Patterns are reset via `re.lastIndex = 0` before every call because they carry
+ * the `/g` flag (required for `String.replace`). Resetting prevents the stale
+ * `lastIndex` bug that skips matches on subsequent calls.
+ */
+/** One secret-value pattern and the kind label a masked span shows. */
+export interface SecretValuePattern {
+    readonly kind: string;
+    readonly re: RegExp;
+}
+export declare const SECRET_VALUE_PATTERNS: readonly SecretValuePattern[];
+/**
+ * Recursively walk `input` and return a new value with secrets removed.
+ * - Primitive non-strings are returned as-is.
+ * - Object keys matching SECRET_KEY_PATTERN → value replaced with "[REDACTED]".
+ * - String values (not key-redacted) → token-pattern scan.
+ * - Arrays and nested objects are walked recursively.
+ */
+export declare function redactSecrets<T>(input: T): T;
+/**
+ * Redact a whole log entry — both the free-text `message` and the structured
+ * `data` payload.
+ *
+ * `message` matters as much as `data`: callers routinely interpolate shell
+ * commands, agent stderr, and error text into it, any of which can carry a
+ * credential. Redacting only `data` left those in cleartext.
+ */
+export declare function redactEntry<T extends {
+    message: string;
+    data?: Record<string, unknown>;
+}>(entry: T): T;

package/dist/internal/redact.js

@@ -0,0 +1,161 @@
+/**
+ * Secret-redaction helper for the JSONL logger write path.
+ *
+ * Two layers of protection:
+ *  1. Key-based: any field whose name matches SECRET_KEY_PATTERN gets its value
+ *     replaced with "[REDACTED]" regardless of content.
+ *  2. Pattern-based: free-text strings (in values that did NOT trigger layer 1)
+ *     are scanned for token-shaped substrings (API keys, PATs, etc.).
+ */
+// TOKEN(?!s\b) prevents matching plural metric keys like "tokens", "inputTokens",
+// "totalTokens" (which are counts, not credentials) while still matching "token",
+// "GITHUB_TOKEN", "accessToken", etc.
+// SEC-1 (Round 2 review): URL/URI/DSN/_URL/CONNECTIONSTRING were missing —
+// DATABASE_URL=postgres://admin:s3cret@db/prod passed through both redaction
+// layers (the KEY=value regex required SECRET|TOKEN|... before `=`, which
+// DATABASE_URL doesn't satisfy; the key pattern didn't match either).
+// SEC-3: AUTHORIZATION/COOKIE/CREDENTIAL/PASSWD were missing. Deliberately
+// narrowed — this is an unanchored substring test, so AUTH(?:ORIZATION)?
+// would also match author/authorName, and SESSION would match
+// sessionName/sessionId/sessionScratchDir, the run log's primary correlation
+// key (see prompt-auditor.ts:300-302). COOKIE already covers SET-COOKIE and
+// setCookie; sessionToken stays covered by the TOKEN branch.
+const SECRET_KEY_PATTERN = /(SECRET|TOKEN(?!s\b)|API_?KEY|PASSWORD|PRIVATE_?KEY|ACCESS_?KEY|WEBHOOK|AUTHORIZATION|COOKIE|CREDENTIAL|PASSWD|(?:\w+)?_URL|\w+_URI|\w+_DSN|CONNECTION\s*STRING)/i;
+export const SECRET_VALUE_PATTERNS = [
+    { kind: "openai", re: /sk-[A-Za-z0-9_-]{16,}/g },
+    { kind: "github", re: /ghp_[A-Za-z0-9]{16,}/g },
+    { kind: "github", re: /gh[opsu]_[A-Za-z0-9]{16,}/g },
+    // LOG-1: GitHub fine-grained PATs — gh[opsu]_ above never matches "github_pat_"
+    // ("gh" + "i" is not one of [opsu]).
+    { kind: "github-pat", re: /github_pat_[A-Za-z0-9_]{20,}/g },
+    { kind: "npm", re: /npm_[A-Za-z0-9]{8,}/g },
+    { kind: "aws", re: /AKIA[0-9A-Z]{16}/g },
+    { kind: "slack", re: /xox[baprs]-[A-Za-z0-9-]{10,}/g },
+    // LOG-1: Telegram bot tokens ("<bot-id>:<35-char secret>").
+    { kind: "telegram", re: /\b\d{6,}:[A-Za-z0-9_-]{30,}\b/g },
+    // KEY=value assignments inside strings (e.g. "NPM_TOKEN=somevalue")
+    { kind: "assignment", re: /(?:SECRET|TOKEN|API_?KEY|PASSWORD|PRIVATE_?KEY|ACCESS_?KEY|WEBHOOK)=[^\s"',]+/gi },
+    // MED-01: PEM-encoded key/cert blocks (private keys, certificates, incl.
+    // PGP's " ... BLOCK" suffix). The gap between BEGIN/END is bounded to
+    // 64KB — generous enough for any realistic single key or bundled
+    // certificate chain, while still capping the rescan cost of an
+    // unterminated "BEGIN" marker in a pathologically large payload on this
+    // synchronous logger write path (a small bound like a few KB risks
+    // missing legitimate multi-cert chain bundles entirely).
+    {
+        kind: "pem",
+        re: /-----BEGIN [A-Z ]*(?:PRIVATE KEY|CERTIFICATE)(?: BLOCK)?-----[\s\S]{0,65536}?-----END [A-Z ]*(?:PRIVATE KEY|CERTIFICATE)(?: BLOCK)?-----/g,
+    },
+    // MED-01: JWTs (header.payload.signature, base64url segments).
+    { kind: "jwt", re: /eyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/g },
+    // MED-01: Authorization header values (Bearer/Basic schemes). Requires a
+    // credential-shaped value (>=8 chars, at least one digit/symbol) so
+    // ordinary prose like "Basic authentication failed" or "Bearer token
+    // scheme" isn't swallowed — real bearer tokens and base64 basic creds
+    // almost always contain a non-alphabetic character; English words
+    // essentially never do. Length floor kept at 8 (not raised to 16) so
+    // short-but-real base64 credentials (e.g. "user:pass" -> ~16 raw chars,
+    // shorter inputs shorter still) aren't under-redacted.
+    { kind: "bearer", re: /\bBearer\s+(?=[A-Za-z0-9\-._~+/]*[0-9+/_-])[A-Za-z0-9\-._~+/]{8,}={0,2}/gi },
+    // LOG-1: Basic creds are base64(user:pass) and are frequently pure-alphabetic
+    // (no digit/symbol), which the digit-requiring lookahead above misses. Require
+    // mixed case instead — real base64 output almost always mixes upper/lower,
+    // while English prose like "Basic authentication" does not. No `i` flag here
+    // (unlike Bearer): case-insensitivity would make [A-Z]/[a-z] equivalent,
+    // defeating the mixed-case check — so the "basic" keyword is spelled out
+    // char-by-char to stay case-insensitive for the scheme name only (the
+    // scheme is case-insensitive per RFC 7617; "basic"/"BASIC" are as valid as
+    // "Basic") while the payload lookaheads remain case-sensitive.
+    {
+        kind: "basic",
+        re: /\b[Bb][Aa][Ss][Ii][Cc]\s+(?=[A-Za-z0-9+/]*[A-Z])(?=[A-Za-z0-9+/]*[a-z])[A-Za-z0-9+/]{8,}={0,2}/g,
+    },
+    // MED-01: header-style key:value / key=value pairs for api-key headers
+    // that SECRET_KEY_PATTERN's object-key check can't reach because the
+    // key/value are both embedded in one free-text string (e.g. raw HTTP logs).
+    { kind: "api-key-header", re: /(?:x-api-key|api[_-]?key)\s*[:=]\s*[^\s"',]+/gi },
+    // SEC-3: Cookie / Set-Cookie headers interpolated into a free-text string
+    // (agent stderr is the common path) — SECRET_KEY_PATTERN only sees object
+    // keys, not header text. Consumes the rest of the line; cookie values are
+    // opaque and line-delimited in header dumps, so a narrower character class
+    // would only risk under-redacting the tail of a multi-cookie header.
+    { kind: "cookie", re: /\b(?:Set-)?Cookie\s*:\s*[^\r\n]+/gi },
+    // SEC-1 (Round 2 review): URL-embedded credentials (scheme://user:pass@host).
+    // Matches a scheme name (lowercase letters, digits, +, ., -), then ://, then
+    // optional user:password (no /, whitespace, or @), then @. The colon + @
+    // is the load-bearing signal that a credential is present; credential-less
+    // URLs like "https://example.com/foo" are intentionally left alone because
+    // they have no colon between :// and @.
+    // Examples:
+    //   postgres://admin:s3cret@db.internal:5432/prod  →  "postgres://admin:s3cret@"
+    //   redis://:hunter2@cache.internal:6379/0          →  "redis://:hunter2@"     (empty user)
+    //   mongodb://root:mongoPwd@mongo.internal:27017    →  "mongodb://root:mongoPwd@"
+    { kind: "url-credentials", re: /\b[a-z][a-z0-9+.-]*:\/\/(?:[^/\s@]*:[^/\s@]+)@/gi },
+];
+const REDACTED = "[REDACTED]";
+function redactString(value) {
+    let out = value;
+    for (const { re } of SECRET_VALUE_PATTERNS) {
+        re.lastIndex = 0;
+        out = out.replace(re, REDACTED);
+    }
+    return out;
+}
+/**
+ * Recursively walk `input` and return a new value with secrets removed.
+ * - Primitive non-strings are returned as-is.
+ * - Object keys matching SECRET_KEY_PATTERN → value replaced with "[REDACTED]".
+ * - String values (not key-redacted) → token-pattern scan.
+ * - Arrays and nested objects are walked recursively.
+ */
+export function redactSecrets(input) {
+    return redactValue(input);
+}
+/**
+ * Redact a whole log entry — both the free-text `message` and the structured
+ * `data` payload.
+ *
+ * `message` matters as much as `data`: callers routinely interpolate shell
+ * commands, agent stderr, and error text into it, any of which can carry a
+ * credential. Redacting only `data` left those in cleartext.
+ */
+export function redactEntry(entry) {
+    return {
+        ...entry,
+        message: redactString(entry.message),
+        ...(entry.data ? { data: redactValue(entry.data) } : {}),
+    };
+}
+/** Depth guard is a backstop against pathological (non-circular but very deep) input; the WeakSet is what actually stops cycles. */
+const MAX_REDACT_DEPTH = 100;
+const CIRCULAR_REF_MARKER = "[Circular]";
+/**
+ * MED-02: unguarded recursion here threw a RangeError (stack overflow) out
+ * of every logger call whenever a data payload contained a circular
+ * reference — a single bad log call could crash whatever code path was
+ * trying to log. `seen` tracks objects/arrays currently on the recursion
+ * stack (removed on the way back out, so the same object appearing twice at
+ * different, non-nested positions is still redacted normally) and
+ * `MAX_REDACT_DEPTH` bounds pathologically deep-but-acyclic input.
+ */
+function redactValue(input, seen = new WeakSet(), depth = 0) {
+    if (typeof input === "string")
+        return redactString(input);
+    if (input === null || typeof input !== "object")
+        return input;
+    if (depth >= MAX_REDACT_DEPTH || seen.has(input))
+        return CIRCULAR_REF_MARKER;
+    seen.add(input);
+    try {
+        if (Array.isArray(input))
+            return input.map((item) => redactValue(item, seen, depth + 1));
+        const out = {};
+        for (const [key, value] of Object.entries(input)) {
+            out[key] = SECRET_KEY_PATTERN.test(key) ? REDACTED : redactValue(value, seen, depth + 1);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(input);
+    }
+}

package/dist/internal/shell-quote.d.ts

@@ -0,0 +1,2 @@
+/** POSIX single-quote a shell argument so it survives `/bin/sh -c`. */
+export declare function shellQuoteArg(arg: string): string;

package/dist/internal/shell-quote.js

@@ -0,0 +1,4 @@
+/** POSIX single-quote a shell argument so it survives `/bin/sh -c`. */
+export function shellQuoteArg(arg) {
+    return `'${arg.replaceAll("'", `'\\''`)}'`;
+}

package/dist/internal/sort.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Comparators for `Array.prototype.sort`.
+ *
+ * A bare `.sort()` coerces every element to a string and orders by UTF-16 code
+ * unit. That is correct for a `string[]` and silently wrong for a `number[]`
+ * (`[2, 10]` sorts to `[10, 2]`), so `suspicious/useArraySortCompare` bans the
+ * bare form outright. These are the comparators it should resolve to.
+ */
+/**
+ * Code-point ordering for strings.
+ *
+ * Byte-identical to what a bare `.sort()` already does on a `string[]`, so
+ * adopting it never changes an existing ordering. Preferred over
+ * `localeCompare` wherever the order is part of a contract: locale-aware
+ * collation is not stable across locales or ICU versions (CTX-5 — see
+ * `src/context/engine/digest.ts`).
+ */
+export declare const byCodePoint: (a: string, b: string) => number;
+/** Ascending numeric ordering — the comparison a bare `.sort()` does *not* do. */
+export declare const byNumber: (a: number, b: number) => number;

package/dist/internal/sort.js

@@ -0,0 +1,20 @@
+/**
+ * Comparators for `Array.prototype.sort`.
+ *
+ * A bare `.sort()` coerces every element to a string and orders by UTF-16 code
+ * unit. That is correct for a `string[]` and silently wrong for a `number[]`
+ * (`[2, 10]` sorts to `[10, 2]`), so `suspicious/useArraySortCompare` bans the
+ * bare form outright. These are the comparators it should resolve to.
+ */
+/**
+ * Code-point ordering for strings.
+ *
+ * Byte-identical to what a bare `.sort()` already does on a `string[]`, so
+ * adopting it never changes an existing ordering. Preferred over
+ * `localeCompare` wherever the order is part of a contract: locale-aware
+ * collation is not stable across locales or ICU versions (CTX-5 — see
+ * `src/context/engine/digest.ts`).
+ */
+export const byCodePoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** Ascending numeric ordering — the comparison a bare `.sort()` does *not* do. */
+export const byNumber = (a, b) => a - b;

package/dist/internal/strip-control-chars.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SEC-09: strip ANSI/escape sequences and other C0 control characters from
+ * agent-controlled or PRD-authored display strings before they reach a
+ * terminal renderer.
+ *
+ * Ink's <Text> does not sanitize its children, and the headless console
+ * formatter writes raw strings straight to stdout. A crafted prd.json field
+ * (story title, failure reason) or agent output containing ESC (\x1b)
+ * sequences can move the cursor, clear the screen, or (via OSC 52) write to
+ * the clipboard in a terminal showing the user's session — defense-in-depth
+ * against a prompt-injected repo or a malicious PRD, not a primary trust
+ * boundary (the LLM already writes code that runs).
+ */
+/**
+ * Removes ESC-initiated sequences (CSI, OSC, and other ANSI escape forms)
+ * and other C0 control characters, while leaving normal whitespace
+ * (tab, newline, carriage return) untouched.
+ */
+export declare function stripControlChars(input: string): string;

package/dist/internal/strip-control-chars.js

@@ -0,0 +1,38 @@
+/**
+ * SEC-09: strip ANSI/escape sequences and other C0 control characters from
+ * agent-controlled or PRD-authored display strings before they reach a
+ * terminal renderer.
+ *
+ * Ink's <Text> does not sanitize its children, and the headless console
+ * formatter writes raw strings straight to stdout. A crafted prd.json field
+ * (story title, failure reason) or agent output containing ESC (\x1b)
+ * sequences can move the cursor, clear the screen, or (via OSC 52) write to
+ * the clipboard in a terminal showing the user's session — defense-in-depth
+ * against a prompt-injected repo or a malicious PRD, not a primary trust
+ * boundary (the LLM already writes code that runs).
+ */
+// C0 control range 0x00-0x1F and DEL (0x7F), excluding tab (\x09), newline
+// (\x0A), and carriage return (\x0D) — display strings are frequently
+// multi-line and stripping those would corrupt legitimate formatting for no
+// security benefit.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: this IS the control-character stripper
+const CONTROL_CHARS_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+/**
+ * Removes ESC-initiated sequences (CSI, OSC, and other ANSI escape forms)
+ * and other C0 control characters, while leaving normal whitespace
+ * (tab, newline, carriage return) untouched.
+ */
+export function stripControlChars(input) {
+    if (!input)
+        return input;
+    // ESC-initiated sequences: OSC "\x1b]...BEL-or-ST", CSI "\x1b[...<final-byte>",
+    // and any other "\x1b" + single byte (short escapes like \x1bc, \x1b=).
+    const withoutEscapes = input
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: matching a real ESC/BEL/ST sequence to strip
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "") // OSC ... BEL | OSC ... ST
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: matching a real ESC (CSI) sequence to strip
+        .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "") // CSI ... final byte
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: matching a real ESC sequence to strip
+        .replace(/\x1b[ -~]/g, ""); // other short two-byte escapes (ESC + one printable byte, e.g. ESC c, ESC =, ESC 7)
+    return withoutEscapes.replace(CONTROL_CHARS_RE, "");
+}

package/dist/internal/thenable.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Is `value` a promise-like — something `await` would suspend on?
+ *
+ * Two callers need the SAME answer rather than two near-copies: the loop-event
+ * dispatcher decides with it whether an `await` is warranted at all (a
+ * synchronous answer must not pay a needless microtask yield), and the plugin
+ * stager uses it to detect an `async register()` contract violation. A single
+ * predicate keeps those from diverging on an exotic function-thenable.
+ */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;

package/dist/internal/thenable.js

@@ -0,0 +1,15 @@
+/**
+ * Is `value` a promise-like — something `await` would suspend on?
+ *
+ * Two callers need the SAME answer rather than two near-copies: the loop-event
+ * dispatcher decides with it whether an `await` is warranted at all (a
+ * synchronous answer must not pay a needless microtask yield), and the plugin
+ * stager uses it to detect an `async register()` contract violation. A single
+ * predicate keeps those from diverging on an exotic function-thenable.
+ */
+export function isThenable(value) {
+    if (value === null)
+        return false;
+    const type = typeof value;
+    return (type === "object" || type === "function") && typeof value.then === "function";
+}