@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/infra/session-cost-usage.js

@@ -2,7 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
 import { normalizeUsage } from "../agents/usage.js";
+import { stripInboundMetadata } from "../auto-reply/reply/strip-inbound-meta.js";
 import { resolveSessionFilePath, resolveSessionTranscriptsDirForAgent, } from "../config/sessions/paths.js";
+import { stripEnvelope, stripMessageIdHints } from "../shared/chat-envelope.js";
 import { countToolResults, extractToolCallNames } from "../utils/transcript-tools.js";
 import { estimateUsageCost, resolveModelCostConfig } from "../utils/usage-format.js";
 const emptyTotals = () => ({
@@ -105,7 +107,7 @@ const computeLatencyStats = (values) => {
     if (!values.length) {
         return undefined;
     }
-    const sorted = [...values].sort((a, b) => a - b);
+    const sorted = values.toSorted((a, b) => a - b);
     const total = sorted.reduce((sum, v) => sum + v, 0);
     const count = sorted.length;
     const p95Index = Math.max(0, Math.ceil(count * 0.95) - 1);
@@ -144,33 +146,47 @@ const applyCostTotal = (totals, costTotal) => {
     }
     totals.totalCost += costTotal;
 };
-async function scanTranscriptFile(params) {
-    const fileStream = fs.createReadStream(params.filePath, { encoding: "utf-8" });
+async function* readJsonlRecords(filePath) {
+    const fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
     const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
-    for await (const line of rl) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-            continue;
-        }
-        try {
-            const parsed = JSON.parse(trimmed);
-            const entry = parseTranscriptEntry(parsed);
-            if (!entry) {
+    try {
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed) {
                 continue;
             }
-            if (entry.usage && entry.costTotal === undefined) {
-                const cost = resolveModelCostConfig({
-                    provider: entry.provider,
-                    model: entry.model,
-                    config: params.config,
-                });
-                entry.costTotal = estimateUsageCost({ usage: entry.usage, cost });
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (!parsed || typeof parsed !== "object") {
+                    continue;
+                }
+                yield parsed;
+            }
+            catch {
+                // Ignore malformed lines
             }
-            params.onEntry(entry);
         }
-        catch {
-            // Ignore malformed lines
+    }
+    finally {
+        rl.close();
+        fileStream.destroy();
+    }
+}
+async function scanTranscriptFile(params) {
+    for await (const parsed of readJsonlRecords(params.filePath)) {
+        const entry = parseTranscriptEntry(parsed);
+        if (!entry) {
+            continue;
         }
+        if (entry.usage && entry.costTotal === undefined) {
+            const cost = resolveModelCostConfig({
+                provider: entry.provider,
+                model: entry.model,
+                config: params.config,
+            });
+            entry.costTotal = estimateUsageCost({ usage: entry.usage, cost });
+        }
+        params.onEntry(entry);
     }
 }
 async function scanUsageFile(params) {
@@ -257,7 +273,7 @@ export async function loadCostUsageSummary(params) {
     }
     const daily = Array.from(dailyMap.entries())
         .map(([date, bucket]) => Object.assign({ date }, bucket))
-        .sort((a, b) => a.date.localeCompare(b.date));
+        .toSorted((a, b) => a.date.localeCompare(b.date));
     // Calculate days for backwards compatibility in response
     const days = Math.ceil((untilTime - sinceTime) / (24 * 60 * 60 * 1000)) + 1;
     return {
@@ -294,15 +310,8 @@ export async function discoverAllSessions(params) {
         // Try to read first user message for label extraction
         let firstUserMessage;
         try {
-            const fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
-            const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
-            for await (const line of rl) {
-                const trimmed = line.trim();
-                if (!trimmed) {
-                    continue;
-                }
+            for await (const parsed of readJsonlRecords(filePath)) {
                 try {
-                    const parsed = JSON.parse(trimmed);
                     const message = parsed.message;
                     if (message?.role === "user") {
                         const content = message.content;
@@ -329,8 +338,6 @@ export async function discoverAllSessions(params) {
                     // Skip malformed lines
                 }
             }
-            rl.close();
-            fileStream.destroy();
         }
         catch {
             // Ignore read errors
@@ -343,11 +350,15 @@ export async function discoverAllSessions(params) {
         });
     }
     // Sort by mtime descending (most recent first)
-    return discovered.sort((a, b) => b.mtime - a.mtime);
+    return discovered.toSorted((a, b) => b.mtime - a.mtime);
 }
 export async function loadSessionCostSummary(params) {
     const sessionFile = params.sessionFile ??
-        (params.sessionId ? resolveSessionFilePath(params.sessionId, params.sessionEntry) : undefined);
+        (params.sessionId
+            ? resolveSessionFilePath(params.sessionId, params.sessionEntry, {
+                agentId: params.agentId,
+            })
+            : undefined);
     if (!sessionFile || !fs.existsSync(sessionFile)) {
         return null;
     }
@@ -527,8 +538,8 @@ export async function loadSessionCostSummary(params) {
     // Convert daily map to sorted array
     const dailyBreakdown = Array.from(dailyMap.entries())
         .map(([date, data]) => ({ date, tokens: data.tokens, cost: data.cost }))
-        .sort((a, b) => a.date.localeCompare(b.date));
-    const dailyMessageCounts = Array.from(dailyMessageMap.values()).sort((a, b) => a.date.localeCompare(b.date));
+        .toSorted((a, b) => a.date.localeCompare(b.date));
+    const dailyMessageCounts = Array.from(dailyMessageMap.values()).toSorted((a, b) => a.date.localeCompare(b.date));
     const dailyLatency = Array.from(dailyLatencyMap.entries())
         .map(([date, values]) => {
         const stats = computeLatencyStats(values);
@@ -538,19 +549,19 @@ export async function loadSessionCostSummary(params) {
         return { date, ...stats };
     })
         .filter((entry) => Boolean(entry))
-        .sort((a, b) => a.date.localeCompare(b.date));
-    const dailyModelUsage = Array.from(dailyModelUsageMap.values()).sort((a, b) => a.date.localeCompare(b.date) || b.cost - a.cost);
+        .toSorted((a, b) => a.date.localeCompare(b.date));
+    const dailyModelUsage = Array.from(dailyModelUsageMap.values()).toSorted((a, b) => a.date.localeCompare(b.date) || b.cost - a.cost);
     const toolUsage = toolUsageMap.size
         ? {
             totalCalls: Array.from(toolUsageMap.values()).reduce((sum, count) => sum + count, 0),
             uniqueTools: toolUsageMap.size,
             tools: Array.from(toolUsageMap.entries())
                 .map(([name, count]) => ({ name, count }))
-                .sort((a, b) => b.count - a.count),
+                .toSorted((a, b) => b.count - a.count),
         }
         : undefined;
     const modelUsage = modelUsageMap.size
-        ? Array.from(modelUsageMap.values()).sort((a, b) => {
+        ? Array.from(modelUsageMap.values()).toSorted((a, b) => {
             const costDiff = b.totals.totalCost - a.totals.totalCost;
             if (costDiff !== 0) {
                 return costDiff;
@@ -566,7 +577,7 @@ export async function loadSessionCostSummary(params) {
         durationMs: firstActivity !== undefined && lastActivity !== undefined
             ? Math.max(0, lastActivity - firstActivity)
             : undefined,
-        activityDates: Array.from(activityDatesSet).sort(),
+        activityDates: Array.from(activityDatesSet).toSorted(),
         dailyBreakdown,
         dailyMessageCounts,
         dailyLatency: dailyLatency.length ? dailyLatency : undefined,
@@ -580,7 +591,11 @@ export async function loadSessionCostSummary(params) {
 }
 export async function loadSessionUsageTimeSeries(params) {
     const sessionFile = params.sessionFile ??
-        (params.sessionId ? resolveSessionFilePath(params.sessionId, params.sessionEntry) : undefined);
+        (params.sessionId
+            ? resolveSessionFilePath(params.sessionId, params.sessionEntry, {
+                agentId: params.agentId,
+            })
+            : undefined);
     if (!sessionFile || !fs.existsSync(sessionFile)) {
         return null;
     }
@@ -617,18 +632,47 @@ export async function loadSessionUsageTimeSeries(params) {
         },
     });
     // Sort by timestamp
-    const sortedPoints = points.sort((a, b) => a.timestamp - b.timestamp);
+    const sortedPoints = points.toSorted((a, b) => a.timestamp - b.timestamp);
     // Optionally downsample if too many points
     const maxPoints = params.maxPoints ?? 100;
     if (sortedPoints.length > maxPoints) {
         const step = Math.ceil(sortedPoints.length / maxPoints);
         const downsampled = [];
+        let downsampledCumulativeTokens = 0;
+        let downsampledCumulativeCost = 0;
         for (let i = 0; i < sortedPoints.length; i += step) {
-            downsampled.push(sortedPoints[i]);
-        }
-        // Always include the last point
-        if (downsampled[downsampled.length - 1] !== sortedPoints[sortedPoints.length - 1]) {
-            downsampled.push(sortedPoints[sortedPoints.length - 1]);
+            const bucket = sortedPoints.slice(i, i + step);
+            const bucketLast = bucket[bucket.length - 1];
+            if (!bucketLast) {
+                continue;
+            }
+            let bucketInput = 0;
+            let bucketOutput = 0;
+            let bucketCacheRead = 0;
+            let bucketCacheWrite = 0;
+            let bucketTotalTokens = 0;
+            let bucketCost = 0;
+            for (const point of bucket) {
+                bucketInput += point.input;
+                bucketOutput += point.output;
+                bucketCacheRead += point.cacheRead;
+                bucketCacheWrite += point.cacheWrite;
+                bucketTotalTokens += point.totalTokens;
+                bucketCost += point.cost;
+            }
+            downsampledCumulativeTokens += bucketTotalTokens;
+            downsampledCumulativeCost += bucketCost;
+            downsampled.push({
+                timestamp: bucketLast.timestamp,
+                input: bucketInput,
+                output: bucketOutput,
+                cacheRead: bucketCacheRead,
+                cacheWrite: bucketCacheWrite,
+                totalTokens: bucketTotalTokens,
+                cost: bucketCost,
+                cumulativeTokens: downsampledCumulativeTokens,
+                cumulativeCost: downsampledCumulativeCost,
+            });
         }
         return { sessionId: params.sessionId, points: downsampled };
     }
@@ -636,21 +680,18 @@ export async function loadSessionUsageTimeSeries(params) {
 }
 export async function loadSessionLogs(params) {
     const sessionFile = params.sessionFile ??
-        (params.sessionId ? resolveSessionFilePath(params.sessionId, params.sessionEntry) : undefined);
+        (params.sessionId
+            ? resolveSessionFilePath(params.sessionId, params.sessionEntry, {
+                agentId: params.agentId,
+            })
+            : undefined);
     if (!sessionFile || !fs.existsSync(sessionFile)) {
         return null;
     }
     const logs = [];
     const limit = params.limit ?? 50;
-    const fileStream = fs.createReadStream(sessionFile, { encoding: "utf-8" });
-    const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
-    for await (const line of rl) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-            continue;
-        }
+    for await (const parsed of readJsonlRecords(sessionFile)) {
         try {
-            const parsed = JSON.parse(trimmed);
             const message = parsed.message;
             if (!message) {
                 continue;
@@ -718,6 +759,13 @@ export async function loadSessionLogs(params) {
             if (!content) {
                 continue;
             }
+            content = stripInboundMetadata(content);
+            if (role === "user") {
+                content = stripMessageIdHints(stripEnvelope(content)).trim();
+            }
+            if (!content) {
+                continue;
+            }
             // Truncate very long content
             const maxLen = 2000;
             if (content.length > maxLen) {
@@ -771,7 +819,7 @@ export async function loadSessionLogs(params) {
         }
     }
     // Sort by timestamp and limit
-    const sortedLogs = logs.sort((a, b) => a.timestamp - b.timestamp);
+    const sortedLogs = logs.toSorted((a, b) => a.timestamp - b.timestamp);
     // Return most recent logs
     if (sortedLogs.length > limit) {
         return sortedLogs.slice(-limit);

package/dist/infra/session-maintenance-warning.js

@@ -1,7 +1,9 @@
 import { resolveSessionAgentId } from "../agents/agent-scope.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import { isDeliverableMessageChannel, normalizeMessageChannel } from "../utils/message-channel.js";
 import { resolveSessionDeliveryTarget } from "./outbound/targets.js";
 import { enqueueSystemEvent } from "./system-events.js";
+const log = createSubsystemLogger("session-maintenance");
 const warnedContexts = new Map();
 function shouldSendWarning() {
     return !process.env.VITEST && process.env.NODE_ENV !== "test";
@@ -83,7 +85,7 @@ export async function deliverSessionMaintenanceWarning(params) {
         });
     }
     catch (err) {
-        console.warn(`Failed to deliver session maintenance warning: ${String(err)}`);
+        log.warn(`Failed to deliver session maintenance warning: ${String(err)}`);
         enqueueSystemEvent(text, { sessionKey: params.sessionKey });
     }
 }

package/dist/infra/shell-env.js

@@ -1,26 +1,100 @@
 import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
 import { isTruthyEnvValue } from "./env.js";
 const DEFAULT_TIMEOUT_MS = 15_000;
 const DEFAULT_MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+const DEFAULT_SHELL = "/bin/sh";
+const TRUSTED_SHELL_PREFIXES = [
+    "/bin/",
+    "/usr/bin/",
+    "/usr/local/bin/",
+    "/opt/homebrew/bin/",
+    "/run/current-system/sw/bin/",
+];
 let lastAppliedKeys = [];
 let cachedShellPath;
+let cachedEtcShells;
+function resolveTimeoutMs(timeoutMs) {
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    return Math.max(0, timeoutMs);
+}
+function readEtcShells() {
+    if (cachedEtcShells !== undefined) {
+        return cachedEtcShells;
+    }
+    try {
+        const raw = fs.readFileSync("/etc/shells", "utf8");
+        const entries = raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith("#") && path.isAbsolute(line));
+        cachedEtcShells = new Set(entries);
+    }
+    catch {
+        cachedEtcShells = null;
+    }
+    return cachedEtcShells;
+}
+function isTrustedShellPath(shell) {
+    if (!path.isAbsolute(shell)) {
+        return false;
+    }
+    const normalized = path.normalize(shell);
+    if (normalized !== shell) {
+        return false;
+    }
+    // Primary trust anchor: shell registered in /etc/shells.
+    const registeredShells = readEtcShells();
+    if (registeredShells?.has(shell)) {
+        return true;
+    }
+    // Fallback for environments where /etc/shells is incomplete/unavailable.
+    if (!TRUSTED_SHELL_PREFIXES.some((prefix) => shell.startsWith(prefix))) {
+        return false;
+    }
+    try {
+        fs.accessSync(shell, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function resolveShell(env) {
     const shell = env.SHELL?.trim();
-    return shell && shell.length > 0 ? shell : "/bin/sh";
+    if (shell && isTrustedShellPath(shell)) {
+        return shell;
+    }
+    return DEFAULT_SHELL;
+}
+function execLoginShellEnvZero(params) {
+    return params.exec(params.shell, ["-l", "-c", "env -0"], {
+        encoding: "buffer",
+        timeout: params.timeoutMs,
+        maxBuffer: DEFAULT_MAX_BUFFER_BYTES,
+        env: params.env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
 }
 function parseShellEnv(stdout) {
     const shellEnv = new Map();
     const parts = stdout.toString("utf8").split("\0");
     for (const part of parts) {
-        if (!part)
+        if (!part) {
             continue;
+        }
         const eq = part.indexOf("=");
-        if (eq <= 0)
+        if (eq <= 0) {
             continue;
+        }
         const key = part.slice(0, eq);
         const value = part.slice(eq + 1);
-        if (!key)
+        if (!key) {
             continue;
+        }
         shellEnv.set(key, value);
     }
     return shellEnv;
@@ -37,19 +111,11 @@ export function loadShellEnvFallback(opts) {
         lastAppliedKeys = [];
         return { ok: true, applied: [], skippedReason: "already-has-keys" };
     }
-    const timeoutMs = typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs)
-        ? Math.max(0, opts.timeoutMs)
-        : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = resolveTimeoutMs(opts.timeoutMs);
     const shell = resolveShell(opts.env);
     let stdout;
     try {
-        stdout = exec(shell, ["-l", "-c", "env -0"], {
-            encoding: "buffer",
-            timeout: timeoutMs,
-            maxBuffer: DEFAULT_MAX_BUFFER_BYTES,
-            env: opts.env,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
+        stdout = execLoginShellEnvZero({ shell, env: opts.env, exec, timeoutMs });
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -60,11 +126,13 @@ export function loadShellEnvFallback(opts) {
     const shellEnv = parseShellEnv(stdout);
     const applied = [];
     for (const key of opts.expectedKeys) {
-        if (opts.env[key]?.trim())
+        if (opts.env[key]?.trim()) {
             continue;
+        }
         const value = shellEnv.get(key);
-        if (!value?.trim())
+        if (!value?.trim()) {
             continue;
+        }
         opts.env[key] = value;
         applied.push(key);
     }
@@ -72,42 +140,37 @@ export function loadShellEnvFallback(opts) {
     return { ok: true, applied };
 }
 export function shouldEnableShellEnvFallback(env) {
-    return (isTruthyEnvValue(env.POOLBOT_LOAD_SHELL_ENV) || isTruthyEnvValue(env.CLAWDBOT_LOAD_SHELL_ENV));
+    return isTruthyEnvValue(env.POOLBOT_LOAD_SHELL_ENV);
 }
 export function shouldDeferShellEnvFallback(env) {
-    return (isTruthyEnvValue(env.POOLBOT_DEFER_SHELL_ENV_FALLBACK) ||
-        isTruthyEnvValue(env.CLAWDBOT_DEFER_SHELL_ENV_FALLBACK));
+    return isTruthyEnvValue(env.POOLBOT_DEFER_SHELL_ENV_FALLBACK);
 }
 export function resolveShellEnvFallbackTimeoutMs(env) {
-    const raw = env.POOLBOT_SHELL_ENV_TIMEOUT_MS?.trim() || env.CLAWDBOT_SHELL_ENV_TIMEOUT_MS?.trim();
-    if (!raw)
+    const raw = env.POOLBOT_SHELL_ENV_TIMEOUT_MS?.trim();
+    if (!raw) {
         return DEFAULT_TIMEOUT_MS;
+    }
     const parsed = Number.parseInt(raw, 10);
-    if (!Number.isFinite(parsed))
+    if (!Number.isFinite(parsed)) {
         return DEFAULT_TIMEOUT_MS;
+    }
     return Math.max(0, parsed);
 }
 export function getShellPathFromLoginShell(opts) {
-    if (cachedShellPath !== undefined)
+    if (cachedShellPath !== undefined) {
         return cachedShellPath;
-    if (process.platform === "win32") {
+    }
+    const platform = opts.platform ?? process.platform;
+    if (platform === "win32") {
         cachedShellPath = null;
         return cachedShellPath;
     }
     const exec = opts.exec ?? execFileSync;
-    const timeoutMs = typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs)
-        ? Math.max(0, opts.timeoutMs)
-        : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = resolveTimeoutMs(opts.timeoutMs);
     const shell = resolveShell(opts.env);
     let stdout;
     try {
-        stdout = exec(shell, ["-l", "-c", "env -0"], {
-            encoding: "buffer",
-            timeout: timeoutMs,
-            maxBuffer: DEFAULT_MAX_BUFFER_BYTES,
-            env: opts.env,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
+        stdout = execLoginShellEnvZero({ shell, env: opts.env, exec, timeoutMs });
     }
     catch {
         cachedShellPath = null;
@@ -120,6 +183,7 @@ export function getShellPathFromLoginShell(opts) {
 }
 export function resetShellPathCacheForTests() {
     cachedShellPath = undefined;
+    cachedEtcShells = undefined;
 }
 export function getShellEnvAppliedKeys() {
     return [...lastAppliedKeys];

package/dist/infra/ssh-config.js

@@ -1,10 +1,12 @@
 import { spawn } from "node:child_process";
 function parsePort(value) {
-    if (!value)
+    if (!value) {
         return undefined;
+    }
     const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0)
+    if (!Number.isFinite(parsed) || parsed <= 0) {
         return undefined;
+    }
     return parsed;
 }
 export function parseSshConfigOutput(output) {
@@ -12,12 +14,14 @@ export function parseSshConfigOutput(output) {
     const lines = output.split("\n");
     for (const raw of lines) {
         const line = raw.trim();
-        if (!line)
+        if (!line) {
             continue;
+        }
         const [key, ...rest] = line.split(/\s+/);
         const value = rest.join(" ").trim();
-        if (!key || !value)
+        if (!key || !value) {
             continue;
+        }
         switch (key) {
             case "user":
                 result.user = value;
@@ -29,8 +33,9 @@ export function parseSshConfigOutput(output) {
                 result.port = parsePort(value);
                 break;
             case "identityfile":
-                if (value !== "none")
+                if (value !== "none") {
                     result.identityFiles.push(value);
+                }
                 break;
             default:
                 break;
@@ -48,7 +53,8 @@ export async function resolveSshConfig(target, opts = {}) {
         args.push("-i", opts.identity.trim());
     }
     const userHost = target.user ? `${target.user}@${target.host}` : target.host;
-    args.push(userHost);
+    // Use "--" so userHost can't be parsed as an ssh option.
+    args.push("--", userHost);
     return await new Promise((resolve) => {
         const child = spawn(sshPath, args, {
             stdio: ["ignore", "pipe", "ignore"],

package/dist/infra/system-run-command.js

@@ -45,8 +45,12 @@ export function extractShellCommandFromArgv(argv) {
         if (idx === -1) {
             return null;
         }
-        const cmd = argv[idx + 1];
-        return typeof cmd === "string" ? cmd : null;
+        const tail = argv.slice(idx + 1).map((item) => String(item));
+        if (tail.length === 0) {
+            return null;
+        }
+        const cmd = tail.join(" ").trim();
+        return cmd.length > 0 ? cmd : null;
     }
     return null;
 }
@@ -55,7 +59,7 @@ export function validateSystemRunCommandConsistency(params) {
         ? params.rawCommand.trim()
         : null;
     const shellCommand = extractShellCommandFromArgv(params.argv);
-    const inferred = shellCommand ? shellCommand.trim() : formatExecCommand(params.argv);
+    const inferred = shellCommand !== null ? shellCommand.trim() : formatExecCommand(params.argv);
     if (raw && raw !== inferred) {
         return {
             ok: false,
@@ -72,7 +76,48 @@ export function validateSystemRunCommandConsistency(params) {
         // Only treat this as a shell command when argv is a recognized shell wrapper.
         // For direct argv execution, rawCommand is purely display/approval text and
         // must match the formatted argv.
-        shellCommand: shellCommand ? (raw ?? shellCommand) : null,
+        shellCommand: shellCommand !== null ? (raw ?? shellCommand) : null,
         cmdText: raw ?? shellCommand ?? inferred,
     };
 }
+export function resolveSystemRunCommand(params) {
+    const raw = typeof params.rawCommand === "string" && params.rawCommand.trim().length > 0
+        ? params.rawCommand.trim()
+        : null;
+    const command = Array.isArray(params.command) ? params.command : [];
+    if (command.length === 0) {
+        if (raw) {
+            return {
+                ok: false,
+                message: "rawCommand requires params.command",
+                details: { code: "MISSING_COMMAND" },
+            };
+        }
+        return {
+            ok: true,
+            argv: [],
+            rawCommand: null,
+            shellCommand: null,
+            cmdText: "",
+        };
+    }
+    const argv = command.map((v) => String(v));
+    const validation = validateSystemRunCommandConsistency({
+        argv,
+        rawCommand: raw,
+    });
+    if (!validation.ok) {
+        return {
+            ok: false,
+            message: validation.message,
+            details: validation.details ?? { code: "RAW_COMMAND_MISMATCH" },
+        };
+    }
+    return {
+        ok: true,
+        argv,
+        rawCommand: raw,
+        shellCommand: validation.shellCommand,
+        cmdText: validation.cmdText,
+    };
+}