parallel-codex-tui 0.1.0 → 0.1.4

package/dist/core/process-mutation-turn.js

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { ensureDir, readJson, removeIfExists, writeJson } from "./file-store.js";
+import { processIsAlive, readProcessStartToken } from "./process-identity.js";
+const ProcessMutationIntentSchema = z.object({
+    version: z.literal(1),
+    intent_id: z.string().min(1),
+    pid: z.number().int().positive(),
+    created_at: z.string().datetime(),
+    choosing: z.boolean(),
+    ticket: z.number().int().nonnegative(),
+    process_start_token: z.string().min(1).optional()
+});
+let currentProcessStartToken = null;
+export async function acquireProcessMutationTurn(directory, options) {
+    validateIntentPrefix(options.intentPrefix);
+    await ensureDir(directory);
+    const identity = await currentMutationIdentity();
+    const intentId = randomUUID();
+    const path = join(directory, `${options.intentPrefix}${intentId}.json`);
+    let intent = ProcessMutationIntentSchema.parse({
+        version: 1,
+        intent_id: intentId,
+        pid: identity.pid,
+        created_at: new Date().toISOString(),
+        choosing: true,
+        ticket: 0,
+        ...(identity.process_start_token ? { process_start_token: identity.process_start_token } : {})
+    });
+    await writeJson(path, intent);
+    try {
+        const existing = await readActiveIntents(directory, options.intentPrefix);
+        intent = {
+            ...intent,
+            choosing: false,
+            ticket: Math.max(0, ...existing.map((candidate) => candidate.ticket)) + 1
+        };
+        await writeJson(path, intent);
+        const deadline = Date.now() + (options.timeoutMs ?? 5000);
+        while (true) {
+            const candidates = await readActiveIntents(directory, options.intentPrefix);
+            const blocked = candidates.some((candidate) => (candidate.intent_id !== intent.intent_id
+                && (candidate.choosing || intentPrecedes(candidate, intent))));
+            if (!blocked) {
+                let released = false;
+                return {
+                    release: async () => {
+                        if (released) {
+                            return;
+                        }
+                        released = true;
+                        await removeIfExists(path);
+                    }
+                };
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(options.timeoutMessage);
+            }
+            await delay(options.pollMs ?? 5);
+        }
+    }
+    catch (error) {
+        await removeIfExists(path);
+        throw error;
+    }
+}
+async function currentMutationIdentity() {
+    currentProcessStartToken ??= readProcessStartToken(process.pid);
+    const processStartToken = await currentProcessStartToken;
+    return {
+        pid: process.pid,
+        ...(processStartToken ? { process_start_token: processStartToken } : {})
+    };
+}
+async function readActiveIntents(directory, prefix) {
+    const names = await readdir(directory);
+    const tokenReads = new Map();
+    const active = [];
+    for (const name of names) {
+        if (!name.startsWith(prefix) || !name.endsWith(".json")) {
+            continue;
+        }
+        const path = join(directory, name);
+        const intent = await readValidIntent(path);
+        if (!intent || !processIsAlive(intent.pid)) {
+            await removeIfExists(path);
+            continue;
+        }
+        if (intent.process_start_token) {
+            let tokenRead = tokenReads.get(intent.pid);
+            if (!tokenRead) {
+                tokenRead = readProcessStartToken(intent.pid);
+                tokenReads.set(intent.pid, tokenRead);
+            }
+            const currentToken = await tokenRead;
+            if (!currentToken || currentToken !== intent.process_start_token) {
+                await removeIfExists(path);
+                continue;
+            }
+        }
+        active.push(intent);
+    }
+    return active;
+}
+async function readValidIntent(path) {
+    try {
+        return await readJson(path, ProcessMutationIntentSchema);
+    }
+    catch {
+        return null;
+    }
+}
+function intentPrecedes(candidate, current) {
+    if (candidate.ticket !== current.ticket) {
+        return candidate.ticket < current.ticket;
+    }
+    return candidate.intent_id < current.intent_id;
+}
+function validateIntentPrefix(prefix) {
+    if (!prefix.startsWith(".") || prefix.includes("/") || prefix.includes("\\")) {
+        throw new Error(`Invalid process mutation intent prefix: ${prefix}`);
+    }
+}
+async function delay(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/core/process-ownership.js

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { ensureDir, pathExists, readJson, removeIfExists, writeJson } from "./file-store.js";
+import { processIsAlive, readProcessStartToken } from "./process-identity.js";
+import { acquireProcessMutationTurn } from "./process-mutation-turn.js";
+export { processIsAlive, readProcessStartToken } from "./process-identity.js";
+const TaskRunOwnerSchema = z.object({
+    version: z.literal(1),
+    owner_id: z.string().min(1),
+    pid: z.number().int().positive(),
+    acquired_at: z.string().datetime(),
+    process_start_token: z.string().min(1).optional()
+});
+const CLAIM_INTENT_PREFIX = ".run-owner-claim-";
+const CLAIM_INTENT_TIMEOUT_MS = 5000;
+const CLAIM_INTENT_POLL_MS = 5;
+const WorkerProcessRecordSchema = z.object({
+    version: z.literal(1),
+    worker_id: z.string().min(1),
+    pid: z.number().int().positive(),
+    process_group_id: z.number().int().positive().optional(),
+    process_start_token: z.string().min(1).optional(),
+    owner_pid: z.number().int().positive(),
+    command: z.string().min(1),
+    started_at: z.string().datetime()
+});
+export class TaskRunLeaseConflictError extends Error {
+    owner;
+    constructor(owner) {
+        super(`Task is already running in another parallel-codex-tui process (pid ${owner?.pid ?? "unknown"}).`);
+        this.owner = owner;
+        this.name = "TaskRunLeaseConflictError";
+    }
+}
+export function taskRunOwnerPath(taskDir) {
+    return join(taskDir, "run-owner.json");
+}
+export function workerProcessRecordPath(workerDir) {
+    return join(workerDir, "process.json");
+}
+export async function claimTaskRunLease(taskDir, options = {}) {
+    const pid = options.pid ?? process.pid;
+    const owner = TaskRunOwnerSchema.parse({
+        version: 1,
+        owner_id: options.ownerId ?? randomUUID(),
+        pid,
+        acquired_at: (options.now ?? (() => new Date()))().toISOString(),
+        ...await optionalProcessStartToken(pid)
+    });
+    const path = taskRunOwnerPath(taskDir);
+    await ensureDir(taskDir);
+    const mutationTurn = await acquireTaskRunMutationTurn(taskDir);
+    try {
+        if (await writeJsonExclusive(path, owner)) {
+            return {
+                owner,
+                release: () => releaseTaskRunLease(taskDir, path, owner.owner_id)
+            };
+        }
+        const inspection = await inspectTaskRunLease(taskDir);
+        if (inspection.state === "active") {
+            throw new TaskRunLeaseConflictError(inspection.owner);
+        }
+        await removeOwnedLease(path, inspection.owner?.owner_id);
+        if (await writeJsonExclusive(path, owner)) {
+            return {
+                owner,
+                release: () => releaseTaskRunLease(taskDir, path, owner.owner_id)
+            };
+        }
+        const current = await inspectTaskRunLease(taskDir);
+        throw new TaskRunLeaseConflictError(current.owner);
+    }
+    finally {
+        await mutationTurn.release();
+    }
+}
+export async function inspectTaskRunLease(taskDir) {
+    const path = taskRunOwnerPath(taskDir);
+    if (!(await pathExists(path))) {
+        return { state: "missing", owner: null };
+    }
+    const owner = await readValidJson(path, TaskRunOwnerSchema);
+    if (!owner) {
+        return { state: "stale", owner: null };
+    }
+    if (!processIsAlive(owner.pid)) {
+        return { state: "stale", owner };
+    }
+    if (owner.process_start_token) {
+        const currentToken = await readProcessStartToken(owner.pid);
+        if (!currentToken || currentToken !== owner.process_start_token) {
+            return { state: "stale", owner };
+        }
+    }
+    return { state: "active", owner };
+}
+export async function clearStaleTaskRunLease(taskDir, owner) {
+    const mutationTurn = await acquireTaskRunMutationTurn(taskDir);
+    try {
+        const inspection = await inspectTaskRunLease(taskDir);
+        if (inspection.state !== "stale") {
+            return;
+        }
+        await removeOwnedLease(taskRunOwnerPath(taskDir), owner?.owner_id ?? inspection.owner?.owner_id);
+    }
+    finally {
+        await mutationTurn.release();
+    }
+}
+export async function writeWorkerProcessRecord(workerDir, input) {
+    const record = WorkerProcessRecordSchema.parse({
+        version: 1,
+        worker_id: input.workerId,
+        pid: input.pid,
+        ...(input.processGroupId ? { process_group_id: input.processGroupId } : {}),
+        owner_pid: process.pid,
+        command: input.command,
+        started_at: (input.now ?? (() => new Date()))().toISOString(),
+        ...await optionalProcessStartToken(input.pid)
+    });
+    await writeJson(workerProcessRecordPath(workerDir), record);
+    return record;
+}
+export async function clearWorkerProcessRecord(workerDir) {
+    await removeIfExists(workerProcessRecordPath(workerDir));
+}
+export async function terminateOwnedWorkerProcess(workerDir) {
+    const path = workerProcessRecordPath(workerDir);
+    if (!(await pathExists(path))) {
+        return "missing";
+    }
+    const record = await readValidJson(path, WorkerProcessRecordSchema);
+    if (!record) {
+        return "unverifiable";
+    }
+    const leaderIsAlive = processIsAlive(record.pid);
+    if (!ownedProcessIsAlive(record)) {
+        await removeIfExists(path);
+        return "not-running";
+    }
+    if (!record.process_start_token) {
+        return "unverifiable";
+    }
+    if (leaderIsAlive) {
+        const currentToken = await readProcessStartToken(record.pid);
+        if (!currentToken) {
+            return "unverifiable";
+        }
+        if (currentToken !== record.process_start_token) {
+            return "identity-mismatch";
+        }
+    }
+    signalOwnedProcess(record, "SIGTERM");
+    if (!(await waitForOwnedProcessExit(record, 1500))) {
+        if (!targetsProcessGroup(record)) {
+            const tokenBeforeKill = await readProcessStartToken(record.pid);
+            if (tokenBeforeKill !== record.process_start_token) {
+                return "identity-mismatch";
+            }
+        }
+        signalOwnedProcess(record, "SIGKILL");
+        await waitForOwnedProcessExit(record, 500);
+    }
+    if (!ownedProcessIsAlive(record)) {
+        await removeIfExists(path);
+        return "terminated";
+    }
+    return "still-running";
+}
+async function optionalProcessStartToken(pid) {
+    const processStartToken = await readProcessStartToken(pid);
+    return processStartToken ? { process_start_token: processStartToken } : {};
+}
+async function writeJsonExclusive(path, value) {
+    try {
+        await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function acquireTaskRunMutationTurn(taskDir) {
+    return acquireProcessMutationTurn(taskDir, {
+        intentPrefix: CLAIM_INTENT_PREFIX,
+        timeoutMs: CLAIM_INTENT_TIMEOUT_MS,
+        pollMs: CLAIM_INTENT_POLL_MS,
+        timeoutMessage: "Timed out waiting to update task run ownership."
+    });
+}
+async function releaseTaskRunLease(taskDir, path, ownerId) {
+    if (!(await pathExists(taskDir))) {
+        return;
+    }
+    const mutationTurn = await acquireTaskRunMutationTurn(taskDir);
+    try {
+        await removeOwnedLease(path, ownerId);
+    }
+    finally {
+        await mutationTurn.release();
+    }
+}
+async function removeOwnedLease(path, ownerId) {
+    if (ownerId) {
+        const current = await readValidJson(path, TaskRunOwnerSchema);
+        if (!current || current.owner_id !== ownerId) {
+            return;
+        }
+    }
+    await removeIfExists(path);
+}
+async function readValidJson(path, schema) {
+    try {
+        return await readJson(path, schema);
+    }
+    catch {
+        return null;
+    }
+}
+function signalProcess(pid, signal) {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH") {
+            throw error;
+        }
+    }
+}
+function signalOwnedProcess(record, signal) {
+    if (targetsProcessGroup(record)) {
+        try {
+            process.kill(-record.process_group_id, signal);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "ESRCH") {
+                throw error;
+            }
+        }
+    }
+    signalProcess(record.pid, signal);
+}
+function targetsProcessGroup(record) {
+    return Boolean(record.process_group_id && process.platform !== "win32");
+}
+function ownedProcessIsAlive(record) {
+    return targetsProcessGroup(record)
+        ? processGroupIsAlive(record.process_group_id)
+        : processIsAlive(record.pid);
+}
+function processGroupIsAlive(processGroupId) {
+    try {
+        process.kill(-processGroupId, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function waitForOwnedProcessExit(record, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!ownedProcessIsAlive(record)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 40));
+    }
+    return !ownedProcessIsAlive(record);
+}

package/dist/core/process-tree.js

@@ -0,0 +1,90 @@
+export class ProcessTreeCleanupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProcessTreeCleanupError";
+    }
+}
+export async function terminateProcessTree(child, options) {
+    const pid = child.pid;
+    if (!pid || !processTreeIsAlive(child, options.processGroup)) {
+        return;
+    }
+    const termGraceMs = options.termGraceMs ?? 250;
+    const killWaitMs = options.killWaitMs ?? 500;
+    const pollMs = options.pollMs ?? 20;
+    try {
+        if (processGroupLeaderWasReused(child, options.processGroup)) {
+            return;
+        }
+        signalProcessTree(pid, "SIGTERM", options.processGroup);
+        if (await waitForProcessTreeExit(child, options.processGroup, termGraceMs, pollMs)) {
+            return;
+        }
+        signalProcessTree(pid, "SIGKILL", options.processGroup);
+        if (await waitForProcessTreeExit(child, options.processGroup, killWaitMs, pollMs)) {
+            return;
+        }
+    }
+    catch (error) {
+        throw new ProcessTreeCleanupError(`Could not terminate ${options.label} ${pid}: ${errorMessage(error)}`);
+    }
+    throw new ProcessTreeCleanupError(`${options.label} group ${pid} remained alive after SIGKILL.`);
+}
+export function processTreeIsAlive(child, processGroup) {
+    const pid = child.pid;
+    if (!pid) {
+        return false;
+    }
+    if (child.exitCode !== null || child.signalCode !== null) {
+        if (processGroupLeaderWasReused(child, processGroup)) {
+            return false;
+        }
+        return processGroup && signalTargetIsAlive(-pid);
+    }
+    if (processGroup && signalTargetIsAlive(-pid)) {
+        return true;
+    }
+    return signalTargetIsAlive(pid);
+}
+function processGroupLeaderWasReused(child, processGroup) {
+    // POSIX keeps the numeric PID reserved while the original process group still exists.
+    return processGroup
+        && (child.exitCode !== null || child.signalCode !== null)
+        && typeof child.pid === "number"
+        && signalTargetIsAlive(child.pid);
+}
+async function waitForProcessTreeExit(child, processGroup, timeoutMs, pollMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processTreeIsAlive(child, processGroup)) {
+            return true;
+        }
+        await delay(pollMs);
+    }
+    return !processTreeIsAlive(child, processGroup);
+}
+function signalProcessTree(pid, signal, processGroup) {
+    try {
+        process.kill(processGroup ? -pid : pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH") {
+            throw error;
+        }
+    }
+}
+function signalTargetIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function delay(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/router-audit.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { RouteDecisionSchema, RouterFailureKindSchema } from "../domain/schemas.js";
+import { readRecentJsonLines } from "./file-store.js";
+import { sanitizeRouterText } from "./router-redaction.js";
+export { RouterFailureKindSchema };
+export const RouterAuditRecordSchema = RouteDecisionSchema.extend({
+    time: z.string().datetime(),
+    request: z.string(),
+    workspace: z.string().min(1),
+    scope: z.enum(["initial", "follow-up"]).default("initial"),
+    router_timeout_ms: z.number().int().positive().optional(),
+    router_first_output_timeout_ms: z.number().int().positive().optional(),
+    router_idle_timeout_ms: z.number().int().positive().optional(),
+    router_max_output_bytes: z.number().int().min(1024).max(16 * 1024 * 1024).optional(),
+    router_max_attempts: z.number().int().min(1).max(3).optional(),
+    router_retry_delay_ms: z.number().int().nonnegative().max(10000).optional(),
+    proxy_configured: z.boolean().optional(),
+    failure_kind: RouterFailureKindSchema.optional()
+});
+export function classifyRouterFailure(reason) {
+    const timedOut = /\b(?:timed out|timeout|ETIMEDOUT)\b/i.test(reason);
+    const proxyMentioned = /\bproxy\b|代理/i.test(reason);
+    const proxyFailure = (/\bproxy(?:\s+(?:connection|connect|handshake|authentication|request|server|transport|tunnel))?\s+(?:authentication|required|failed|failure|error|refused|unreachable|invalid|closed|reset)\b/i.test(reason)
+        || /\b(?:failed|unable|cannot|could not)\s+(?:to\s+)?(?:connect|reach|use|negotiate).{0,30}\bproxy\b/i.test(reason)
+        || /代理.{0,20}(?:认证|失败|错误|拒绝|无法|不可达)/i.test(reason));
+    if (proxyMentioned && timedOut) {
+        return "timeout";
+    }
+    if (proxyFailure) {
+        return "proxy";
+    }
+    if (/\b(?:401|403)\b|\b(?:unauthori[sz]ed|forbidden|authentication|api[-_\s]?key|login required|not logged in|sign in)\b/i.test(reason)) {
+        return "auth";
+    }
+    if (/\b429\b|\b(?:rate[ -]?limit|too many requests|quota (?:exceeded|exhausted)|usage limit)\b/i.test(reason)) {
+        return "rate-limit";
+    }
+    if (/\b(?:ECONNREFUSED|ECONNRESET|ENETUNREACH|EHOSTUNREACH|ENOTFOUND|EAI_AGAIN)\b|\b(?:network|websocket|https transport|fetch failed|certificate|tls|ssl)\b/i.test(reason)) {
+        return "network";
+    }
+    if (timedOut) {
+        return "timeout";
+    }
+    if (/\b(?:ENOENT|command not found|spawn error)\b/i.test(reason)) {
+        return "unavailable";
+    }
+    if (/\b(?:no json object|invalid json|invalid codex router (?:mode|response object)|failed to parse json|unexpected token)\b/i.test(reason)) {
+        return "invalid-output";
+    }
+    if (/\b(?:exited with (?:code|signal)|process exited)\b/i.test(reason)) {
+        return "exit";
+    }
+    if (/\b(?:router input failed|stdin|EPIPE)\b/i.test(reason)) {
+        return "input";
+    }
+    return null;
+}
+export function routerFallbackIsTransient(route) {
+    if (route.source !== "fallback") {
+        return false;
+    }
+    if (route.router_timeout_kind === "total") {
+        return false;
+    }
+    if (route.router_timeout_kind === "first-output" || route.router_timeout_kind === "idle") {
+        return true;
+    }
+    const kind = route.router_failure_kind ?? classifyRouterFailure(route.reason);
+    if (kind === "network" || kind === "proxy") {
+        return true;
+    }
+    if (kind === "timeout") {
+        return route.router_failure_stage !== "response";
+    }
+    if (kind === "input") {
+        return /\b(?:EPIPE|ECONNRESET|temporar(?:y|ily))\b/i.test(route.reason);
+    }
+    if (kind === "exit") {
+        return /\b(?:ECONNRESET|ETIMEDOUT|EAI_AGAIN|temporar(?:y|ily)|try again|connection reset)\b/i.test(route.reason);
+    }
+    return false;
+}
+export function diagnoseRouterFailure(evidence) {
+    const kind = evidence.failure_kind ?? classifyRouterFailure(evidence.reason) ?? "unknown";
+    if (kind === "auth") {
+        return diagnosis(kind, "Codex authentication failed", "run codex login, then retry Router");
+    }
+    if (kind === "rate-limit") {
+        return diagnosis(kind, "The provider rate limit blocked routing", "wait for quota or change the Router model/provider");
+    }
+    if (kind === "proxy") {
+        return diagnosis(kind, "Router reported a proxy-path failure", "run parallel-codex-tui --doctor --probe-router and verify the proxy upstream");
+    }
+    if (kind === "network") {
+        return diagnosis(kind, "Router reported a network-path failure", "run parallel-codex-tui --doctor --probe-router and verify DNS, TLS, and API reachability");
+    }
+    if (kind === "unavailable") {
+        return diagnosis(kind, evidence.router_failure_stage === "spawn" ? "Router process could not start" : "Router command is unavailable", "run parallel-codex-tui --doctor and fix router.codex.command");
+    }
+    if (kind === "invalid-output") {
+        return diagnosis(kind, "Router returned output that was not valid route JSON", "retry Router; if it repeats, inspect the Router model/provider output");
+    }
+    if (kind === "input") {
+        return diagnosis(kind, "Router process rejected the request input", "check that router.codex.args accepts a prompt on stdin");
+    }
+    if (kind === "timeout") {
+        return diagnoseRouterTimeout(evidence);
+    }
+    if (kind === "exit") {
+        return diagnosis(kind, "Router process exited before a valid route response", "run the configured Codex command directly and inspect its exit output");
+    }
+    return diagnosis("unknown", "Router failed before a valid route response", "run parallel-codex-tui --doctor --probe-router and inspect the recorded reason");
+}
+function diagnoseRouterTimeout(evidence) {
+    if (evidence.router_timeout_kind === "first-output") {
+        return diagnosis("timeout", "Router produced no output before the first-output deadline", evidence.proxy_configured
+            ? "run parallel-codex-tui --doctor --probe-router; verify Codex login and proxy upstream, or raise router.codex.firstOutputTimeoutMs"
+            : "run parallel-codex-tui --doctor --probe-router; verify Codex login and API network path, or raise router.codex.firstOutputTimeoutMs");
+    }
+    if (evidence.router_timeout_kind === "idle") {
+        return diagnosis("timeout", (evidence.router_stdout_bytes ?? 0) > 0
+            ? "Router response stopped before valid route JSON completed"
+            : "Router diagnostics stopped before a route response", "inspect the reason; retry Router or raise router.codex.idleTimeoutMs");
+    }
+    if ((evidence.router_stdout_bytes ?? 0) > 0) {
+        return diagnosis("timeout", "Router began a route response but did not finish", "retry Router or raise router.codex.timeoutMs");
+    }
+    if ((evidence.router_stderr_bytes ?? 0) > 0) {
+        return diagnosis("timeout", "Router emitted diagnostics but no route response", "inspect the reason, then run parallel-codex-tui --doctor --probe-router");
+    }
+    if (evidence.router_failure_stage === "waiting-output") {
+        return diagnosis("timeout", "Router produced no output before the timeout", evidence.proxy_configured
+            ? "run parallel-codex-tui --doctor --probe-router; verify Codex login and proxy upstream"
+            : "run parallel-codex-tui --doctor --probe-router; verify Codex login and API network path");
+    }
+    return diagnosis("timeout", "Router timed out before a valid route response", evidence.proxy_configured
+        ? "run parallel-codex-tui --doctor --probe-router; verify Codex login and proxy upstream"
+        : "run parallel-codex-tui --doctor --probe-router; verify Codex login and API network path");
+}
+function diagnosis(kind, summary, action) {
+    return { kind, summary, action };
+}
+export async function readRouterAudit(path, limit = 100) {
+    const boundedLimit = Number.isFinite(limit)
+        ? Math.min(500, Math.max(0, Math.trunc(limit)))
+        : 100;
+    if (boundedLimit === 0) {
+        return [];
+    }
+    return (await readRecentJsonLines(path, RouterAuditRecordSchema, boundedLimit)).map((record) => ({
+        ...record,
+        request: sanitizeRouterText(record.request),
+        reason: sanitizeRouterText(record.reason)
+    }));
+}

package/dist/core/router-redaction.js

@@ -0,0 +1,31 @@
+const ROUTER_URL_PATTERN = /\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`]+/giu;
+const ROUTER_SECRET_ASSIGNMENT_PATTERN = /\b((?:(?:[a-z][a-z0-9]*_)*(?:api_?key|access_?token|auth_?token|token|password|passwd|secret|client_?secret))\s*(?:=|:)\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;]+)/giu;
+const ROUTER_AUTHORIZATION_PATTERN = /\b((?:authorization\s*:\s*)?(?:bearer|basic)\s+)[^\s,;]+/giu;
+const ROUTER_RAW_TOKEN_PATTERN = /\b(?:sk-[a-z0-9_-]{8,}|npm_[a-z0-9]{20,}|gh[pousr]_[a-z0-9]{20,}|github_pat_[a-z0-9_]{20,})\b/giu;
+const ROUTER_URL_TRAILING_PUNCTUATION = /[),.;!?，。；！？、]+$/u;
+export function sanitizeRouterText(value) {
+    return value
+        .replace(ROUTER_URL_PATTERN, sanitizeRouterUrl)
+        .replace(ROUTER_AUTHORIZATION_PATTERN, "$1***")
+        .replace(ROUTER_SECRET_ASSIGNMENT_PATTERN, "$1***")
+        .replace(ROUTER_RAW_TOKEN_PATTERN, "***");
+}
+function sanitizeRouterUrl(value) {
+    const trailing = value.match(ROUTER_URL_TRAILING_PUNCTUATION)?.[0] ?? "";
+    const candidate = trailing ? value.slice(0, -trailing.length) : value;
+    try {
+        const parsed = new URL(candidate);
+        const credentials = parsed.username || parsed.password ? "***@" : "";
+        return `${parsed.protocol}//${credentials}${parsed.host}${trailing}`;
+    }
+    catch {
+        const authority = candidate.match(/^([a-z][a-z0-9+.-]*:\/\/)([^/?#]*)/iu);
+        if (!authority) {
+            return value.replace(/\b([a-z][a-z0-9+.-]*:\/\/)([^@\s/]+)@/iu, "$1***@");
+        }
+        const safeAuthority = authority[2]?.includes("@")
+            ? `***@${authority[2].slice(authority[2].lastIndexOf("@") + 1)}`
+            : authority[2] ?? "";
+        return `${authority[1]}${safeAuthority}${trailing}`;
+    }
+}