auditor-lambda 0.2.8 → 0.2.9

package/dist/types/externalAnalyzer.d.ts

@@ -1,3 +1,4 @@
+/** One normalized result imported from an external analyzer such as eslint or tsc. */
 export interface ExternalAnalyzerResultItem {
     id: string;
     category: string;
@@ -7,8 +8,10 @@ export interface ExternalAnalyzerResultItem {
     line_end?: number;
     summary: string;
     rule?: string;
+    /** Preserves the analyzer-native payload when consumers need original detail. */
     raw?: unknown;
 }
+/** Imported analyzer output captured at a single generation time. */
 export interface ExternalAnalyzerResults {
     tool: string;
     generated_at?: string;

package/dist/types/flowCoverage.d.ts

@@ -1,11 +1,15 @@
+export declare const FLOW_COVERAGE_STATUSES: readonly ["pending", "partial", "complete"];
+export type FlowCoverageStatus = (typeof FLOW_COVERAGE_STATUSES)[number];
+/** Coverage for one critical flow across the lenses the audit expects to see. */
 export interface FlowCoverageRecord {
     flow_id: string;
     paths: string[];
     required_lenses: string[];
     completed_lenses: string[];
-    status: "pending" | "partial" | "complete";
+    status: FlowCoverageStatus;
     notes?: string[];
 }
+/** Aggregated flow coverage written beside the critical flow manifest. */
 export interface FlowCoverageManifest {
     flows: FlowCoverageRecord[];
 }

package/dist/types/flowCoverage.js

@@ -1 +1,5 @@
-export {};
+export const FLOW_COVERAGE_STATUSES = [
+    "pending",
+    "partial",
+    "complete",
+];

package/dist/types/flows.d.ts

@@ -1,12 +1,16 @@
+export declare const FLOW_CONFIDENCE_LEVELS: readonly ["high", "low"];
+export type FlowConfidenceLevel = (typeof FLOW_CONFIDENCE_LEVELS)[number];
+/** A critical user or system flow that must be covered by the audit. */
 export interface CriticalFlow {
     id: string;
     name: string;
     entrypoints: string[];
     paths: string[];
     concerns: string[];
-    confidence?: "high" | "low";
+    confidence?: FlowConfidenceLevel;
     notes?: string[];
 }
+/** The set of critical flows inferred from intake artifacts. */
 export interface CriticalFlowManifest {
     flows: CriticalFlow[];
     fallback_required?: boolean;

package/dist/types/flows.js

@@ -1 +1 @@
-export {};
+export const FLOW_CONFIDENCE_LEVELS = ["high", "low"];

package/dist/types/runLedger.d.ts

@@ -1,13 +1,17 @@
+export declare const RUN_LEDGER_STATUSES: readonly ["completed", "blocked", "failed", "no_progress"];
+export type RunLedgerStatus = (typeof RUN_LEDGER_STATUSES)[number];
+/** One persisted supervisor run entry, including the terminal worker outcome. */
 export interface RunLedgerEntry {
     run_id: string;
     provider: string;
     obligation_id: string | null;
     selected_executor: string | null;
-    status: "completed" | "blocked" | "failed" | "no_progress";
+    status: RunLedgerStatus;
     started_at: string;
     ended_at: string;
     result_path: string;
 }
+/** Append-only ledger used to explain how the audit advanced over time. */
 export interface RunLedger {
     runs: RunLedgerEntry[];
 }

package/dist/types/runLedger.js

@@ -1 +1,6 @@
-export {};
+export const RUN_LEDGER_STATUSES = [
+    "completed",
+    "blocked",
+    "failed",
+    "no_progress",
+];

package/dist/types/runtimeValidation.d.ts

@@ -1,24 +1,33 @@
-export type RuntimeValidationKind = "unit-risk-check" | "critical-flow-check";
+export declare const RUNTIME_VALIDATION_KINDS: readonly ["unit-risk-check", "critical-flow-check"];
+export type RuntimeValidationKind = (typeof RUNTIME_VALIDATION_KINDS)[number];
+export declare const RUNTIME_VALIDATION_PRIORITIES: readonly ["high", "medium", "low"];
+export type RuntimeValidationPriority = (typeof RUNTIME_VALIDATION_PRIORITIES)[number];
+export declare const RUNTIME_VALIDATION_STATUSES: readonly ["pending", "confirmed", "not_confirmed", "inconclusive", "not_required"];
+export type RuntimeValidationStatus = (typeof RUNTIME_VALIDATION_STATUSES)[number];
+/** A deterministic runtime check queued after static review highlights risk. */
 export interface RuntimeValidationTask {
     id: string;
     kind: RuntimeValidationKind;
     target_paths: string[];
     reason: string;
-    priority: "high" | "medium" | "low";
+    priority: RuntimeValidationPriority;
     command?: string[];
     suggested_checks?: string[];
     source_artifacts?: string[];
 }
+/** Planner output for the runtime validation stage. */
 export interface RuntimeValidationTaskManifest {
     tasks: RuntimeValidationTask[];
 }
+/** Result recorded after a runtime validation task runs or is intentionally skipped. */
 export interface RuntimeValidationResult {
     task_id: string;
-    status: "pending" | "confirmed" | "not_confirmed" | "inconclusive" | "not_required";
+    status: RuntimeValidationStatus;
     summary: string;
     evidence?: string[];
     notes?: string[];
 }
+/** Persisted runtime validation outcomes keyed by generated task id. */
 export interface RuntimeValidationReport {
     results: RuntimeValidationResult[];
 }

package/dist/types/runtimeValidation.js

@@ -1 +1,16 @@
-export {};
+export const RUNTIME_VALIDATION_KINDS = [
+    "unit-risk-check",
+    "critical-flow-check",
+];
+export const RUNTIME_VALIDATION_PRIORITIES = [
+    "high",
+    "medium",
+    "low",
+];
+export const RUNTIME_VALIDATION_STATUSES = [
+    "pending",
+    "confirmed",
+    "not_confirmed",
+    "inconclusive",
+    "not_required",
+];

package/dist/types/sessionConfig.d.ts

@@ -1,5 +1,8 @@
-export type ProviderName = "auto" | "local-subprocess" | "subprocess-template" | "claude-code" | "opencode" | "vscode-task";
+export declare const PROVIDER_NAMES: readonly ["auto", "local-subprocess", "subprocess-template", "claude-code", "opencode", "vscode-task"];
+export type ProviderName = (typeof PROVIDER_NAMES)[number];
 export type ResolvedProviderName = Exclude<ProviderName, "auto">;
+export declare const SESSION_UI_MODES: readonly ["visible", "headless"];
+export type SessionUiMode = (typeof SESSION_UI_MODES)[number];
 export interface SubprocessTemplateConfig {
     command_template: string[];
     env?: Record<string, string>;
@@ -16,10 +19,20 @@ export interface VSCodeTaskConfig {
     command_template: string[];
     env?: Record<string, string>;
 }
+export declare const PROVIDER_SECTION_KEYS: {
+    readonly "subprocess-template": "subprocess_template";
+    readonly "claude-code": "claude_code";
+    readonly opencode: "opencode";
+    readonly "vscode-task": "vscode_task";
+};
+/**
+ * Provider names use CLI-friendly hyphenation, while nested provider config
+ * sections stay snake_case because they serialize directly into JSON files.
+ */
 export interface SessionConfig {
     provider?: ProviderName;
     timeout_ms?: number;
-    ui_mode?: "visible" | "headless";
+    ui_mode?: SessionUiMode;
     subprocess_template?: SubprocessTemplateConfig;
     claude_code?: ClaudeCodeConfig;
     opencode?: OpenCodeConfig;

package/dist/types/sessionConfig.js

@@ -1 +1,15 @@
-export {};
+export const PROVIDER_NAMES = [
+    "auto",
+    "local-subprocess",
+    "subprocess-template",
+    "claude-code",
+    "opencode",
+    "vscode-task",
+];
+export const SESSION_UI_MODES = ["visible", "headless"];
+export const PROVIDER_SECTION_KEYS = {
+    "subprocess-template": "subprocess_template",
+    "claude-code": "claude_code",
+    opencode: "opencode",
+    "vscode-task": "vscode_task",
+};

package/dist/types/surfaces.d.ts

@@ -1,4 +1,6 @@
-export type SurfaceKind = "interface" | "background";
+export declare const SURFACE_KINDS: readonly ["interface", "background"];
+export type SurfaceKind = (typeof SURFACE_KINDS)[number];
+/** Discovered execution surfaces that define where the product can be reached. */
 export interface SurfaceRecord {
     id: string;
     kind: SurfaceKind;
@@ -7,6 +9,7 @@ export interface SurfaceRecord {
     methods?: string[];
     notes?: string[];
 }
+/** Intake output that summarizes externally reachable product surfaces. */
 export interface SurfaceManifest {
     surfaces: SurfaceRecord[];
 }

package/dist/types/surfaces.js

@@ -1 +1 @@
-export {};
+export const SURFACE_KINDS = ["interface", "background"];

package/dist/types/workerSession.d.ts

@@ -1,3 +1,9 @@
+export declare const WORKER_COMMAND_MODES: readonly ["run", "deferred"];
+export type WorkerCommandMode = (typeof WORKER_COMMAND_MODES)[number];
+/**
+ * Worker tasks serialize directly to task.json, so their persisted field names
+ * intentionally stay snake_case for consistency across providers and bridges.
+ */
 export interface WorkerTask {
     contract_version: "audit-code-worker/v1alpha1";
     run_id: string;
@@ -11,7 +17,10 @@ export interface WorkerTask {
     pending_audit_tasks_path?: string;
     runtime_updates_path?: string;
     external_analyzer_results_path?: string;
+    worker_command_mode?: WorkerCommandMode;
+    /** @deprecated Prefer worker_command_mode: "deferred" for new task files. */
     skip_worker_command?: boolean;
     timeout_ms?: number;
     max_retries?: number;
 }
+export declare function usesDeferredWorkerCommand(task: Pick<WorkerTask, "worker_command_mode" | "skip_worker_command">): boolean;

package/dist/types/workerSession.js

@@ -1 +1,5 @@
-export {};
+export const WORKER_COMMAND_MODES = ["run", "deferred"];
+export function usesDeferredWorkerCommand(task) {
+    return (task.worker_command_mode === "deferred" ||
+        task.skip_worker_command === true);
+}

package/dist/validation/artifacts.d.ts

@@ -1,3 +1,3 @@
 import type { ArtifactBundle } from "../io/artifacts.js";
-import type { ValidationIssue } from "./basic.js";
+import { type ValidationIssue } from "./basic.js";
 export declare function validateArtifactBundle(bundle: ArtifactBundle): ValidationIssue[];

package/dist/validation/artifacts.js

@@ -1,6 +1,9 @@
-import { requireKeys } from "./basic.js";
+import { pushValidationIssue, requireKeys, } from "./basic.js";
 function pushIssue(issues, path, message) {
-    issues.push({ path, message });
+    pushValidationIssue(issues, path, message);
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
 }
 export function validateArtifactBundle(bundle) {
     const issues = [];
@@ -37,14 +40,24 @@ export function validateArtifactBundle(bundle) {
     if (bundle.external_analyzer_results) {
         issues.push(...requireKeys(bundle.external_analyzer_results, "external_analyzer_results", ["tool", "results"]));
     }
-    const repoPaths = new Set(bundle.repo_manifest?.files.map((file) => file.path) ?? []);
-    const dispositionMap = new Map(bundle.file_disposition?.files.map((item) => [item.path, item.status]) ??
-        []);
-    const unitIds = new Set(bundle.unit_manifest?.units.map((unit) => unit.unit_id) ?? []);
-    const flowIds = new Set(bundle.critical_flows?.flows.map((flow) => flow.id) ?? []);
-    const runtimeTaskIds = new Set(bundle.runtime_validation_tasks?.tasks.map((task) => task.id) ?? []);
+    const repoManifestFiles = asArray(bundle.repo_manifest?.files);
+    const fileDispositionEntries = asArray(bundle.file_disposition?.files);
+    const unitManifestUnits = asArray(bundle.unit_manifest?.units);
+    const criticalFlows = asArray(bundle.critical_flows?.flows);
+    const flowCoverageEntries = asArray(bundle.flow_coverage?.flows);
+    const riskRegisterItems = asArray(bundle.risk_register?.items);
+    const surfaceEntries = asArray(bundle.surface_manifest?.surfaces);
+    const runtimeValidationTasks = asArray(bundle.runtime_validation_tasks?.tasks);
+    const runtimeValidationResults = asArray(bundle.runtime_validation_report?.results);
+    const externalAnalyzerResults = asArray(bundle.external_analyzer_results?.results);
+    const coverageFiles = asArray(bundle.coverage_matrix?.files);
+    const repoPaths = new Set(repoManifestFiles.map((file) => file.path));
+    const dispositionMap = new Map(fileDispositionEntries.map((item) => [item.path, item.status]));
+    const unitIds = new Set(unitManifestUnits.map((unit) => unit.unit_id));
+    const flowIds = new Set(criticalFlows.map((flow) => flow.id));
+    const runtimeTaskIds = new Set(runtimeValidationTasks.map((task) => task.id));
     if (bundle.repo_manifest && bundle.coverage_matrix) {
-        const coveragePaths = new Set(bundle.coverage_matrix.files.map((file) => file.path));
+        const coveragePaths = new Set(coverageFiles.map((file) => file.path));
         for (const path of repoPaths) {
             if (!coveragePaths.has(path)) {
                 pushIssue(issues, "coverage_matrix", `Missing coverage entry for ${path}`);
@@ -52,7 +65,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.repo_manifest && bundle.file_disposition) {
-        const dispositionPaths = new Set(bundle.file_disposition.files.map((file) => file.path));
+        const dispositionPaths = new Set(fileDispositionEntries.map((file) => file.path));
         for (const path of repoPaths) {
             if (!dispositionPaths.has(path)) {
                 pushIssue(issues, "file_disposition", `Missing disposition entry for ${path}`);
@@ -60,7 +73,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.unit_manifest) {
-        for (const unit of bundle.unit_manifest.units) {
+        for (const unit of unitManifestUnits) {
             if (unit.files.length === 0) {
                 pushIssue(issues, `unit_manifest:${unit.unit_id}`, "Unit has no files");
             }
@@ -79,7 +92,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.coverage_matrix && bundle.unit_manifest) {
-        for (const file of bundle.coverage_matrix.files) {
+        for (const file of coverageFiles) {
             if (!repoPaths.has(file.path)) {
                 pushIssue(issues, "coverage_matrix", `Coverage contains unknown file ${file.path}`);
             }
@@ -103,7 +116,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.critical_flows) {
-        for (const flow of bundle.critical_flows.flows) {
+        for (const flow of criticalFlows) {
             if (flow.paths.length === 0) {
                 pushIssue(issues, `critical_flows:${flow.id}`, "Flow has no paths");
             }
@@ -122,7 +135,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.flow_coverage && bundle.critical_flows) {
-        for (const flow of bundle.flow_coverage.flows) {
+        for (const flow of flowCoverageEntries) {
             if (!flowIds.has(flow.flow_id)) {
                 pushIssue(issues, `flow_coverage:${flow.flow_id}`, `Flow coverage references unknown flow ${flow.flow_id}`);
             }
@@ -143,15 +156,15 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.risk_register && bundle.unit_manifest) {
-        const riskUnitIds = new Set(bundle.risk_register.items.map((item) => item.unit_id));
-        for (const unit of bundle.unit_manifest.units) {
+        const riskUnitIds = new Set(riskRegisterItems.map((item) => item.unit_id));
+        for (const unit of unitManifestUnits) {
             if (!riskUnitIds.has(unit.unit_id)) {
                 pushIssue(issues, "risk_register", `Missing risk entry for unit ${unit.unit_id}`);
             }
         }
     }
     if (bundle.surface_manifest) {
-        for (const surface of bundle.surface_manifest.surfaces) {
+        for (const surface of surfaceEntries) {
             if (!repoPaths.has(surface.entrypoint)) {
                 pushIssue(issues, `surface_manifest:${surface.id}`, `Surface references unknown entrypoint ${surface.entrypoint}`);
             }
@@ -162,7 +175,7 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.runtime_validation_tasks) {
-        for (const task of bundle.runtime_validation_tasks.tasks) {
+        for (const task of runtimeValidationTasks) {
             if (task.target_paths.length === 0) {
                 pushIssue(issues, `runtime_validation_tasks:${task.id}`, "Runtime validation task has no target paths");
             }
@@ -174,14 +187,14 @@ export function validateArtifactBundle(bundle) {
         }
     }
     if (bundle.runtime_validation_report) {
-        for (const result of bundle.runtime_validation_report.results) {
+        for (const result of runtimeValidationResults) {
             if (!runtimeTaskIds.has(result.task_id)) {
                 pushIssue(issues, `runtime_validation_report:${result.task_id}`, `Runtime validation result references unknown task ${result.task_id}`);
             }
         }
     }
     if (bundle.external_analyzer_results) {
-        for (const item of bundle.external_analyzer_results.results) {
+        for (const item of externalAnalyzerResults) {
             if (!repoPaths.has(item.path) && bundle.repo_manifest) {
                 pushIssue(issues, `external_analyzer_results:${item.id}`, `External analyzer result references unknown path ${item.path}`);
             }

package/dist/validation/auditResults.d.ts

@@ -1,11 +1,11 @@
 import type { AuditTask } from "../types.js";
+import { type ValidationIssue } from "./basic.js";
 export type IssueSeverity = "error" | "warning";
-export interface AuditResultIssue {
+export interface AuditResultIssue extends ValidationIssue {
     result_index: number;
     task_id: string;
     severity: IssueSeverity;
     field: string;
-    message: string;
 }
 export interface ValidateAuditResultOptions {
     lineIndex?: Record<string, number>;

package/dist/validation/auditResults.js

@@ -1,3 +1,4 @@
+import { describeValue, formatValidationIssues, isRecord, } from "./basic.js";
 const REQUIRED_FINDING_FIELDS = [
     "id",
     "title",
@@ -24,21 +25,10 @@ const VALID_LENSES = new Set([
 function pushIssue(issues, params) {
     issues.push({
         ...params,
+        path: params.path ?? params.field,
         severity: params.severity ?? "error",
     });
 }
-function describeValue(value) {
-    if (Array.isArray(value)) {
-        return "array";
-    }
-    if (value === null) {
-        return "null";
-    }
-    return typeof value;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -404,7 +394,9 @@ export function validateAuditResults(results, tasks, options = {}) {
     return issues;
 }
 export function formatAuditResultIssues(issues) {
-    return issues
-        .map((issue) => `  [${issue.severity}] ${issue.task_id} / ${issue.field}: ${issue.message}`)
-        .join("\n");
+    return formatValidationIssues(issues.map((issue) => ({
+        path: `${issue.task_id} / ${issue.field}`,
+        message: issue.message,
+        severity: issue.severity,
+    })));
 }

package/dist/validation/basic.d.ts

@@ -1,5 +1,13 @@
+export type ValidationSeverity = "error" | "warning";
 export interface ValidationIssue {
     path: string;
     message: string;
+    severity: ValidationSeverity;
 }
-export declare function requireKeys(record: Record<string, unknown>, path: string, keys: string[]): ValidationIssue[];
+export declare function describeValue(value: unknown): string;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function createValidationIssue(path: string, message: string, severity?: ValidationSeverity): ValidationIssue;
+export declare function pushValidationIssue(issues: ValidationIssue[], path: string, message: string, severity?: ValidationSeverity): void;
+export declare function prefixValidationIssues(prefix: string, issues: ValidationIssue[]): ValidationIssue[];
+export declare function formatValidationIssues(issues: ValidationIssue[]): string;
+export declare function requireKeys(value: unknown, path: string, keys: readonly string[]): ValidationIssue[];

package/dist/validation/basic.js

@@ -1,8 +1,45 @@
-export function requireKeys(record, path, keys) {
+export function describeValue(value) {
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (value === null) {
+        return "null";
+    }
+    return typeof value;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function createValidationIssue(path, message, severity = "error") {
+    return { path, message, severity };
+}
+export function pushValidationIssue(issues, path, message, severity = "error") {
+    issues.push(createValidationIssue(path, message, severity));
+}
+export function prefixValidationIssues(prefix, issues) {
+    return issues.map((issue) => ({
+        ...issue,
+        path: issue.path.length === 0
+            ? prefix
+            : issue.path === prefix || issue.path.startsWith(`${prefix}.`)
+                ? issue.path
+                : `${prefix}.${issue.path}`,
+    }));
+}
+export function formatValidationIssues(issues) {
+    return issues
+        .map((issue) => `  [${issue.severity}] ${issue.path}: ${issue.message}`)
+        .join("\n");
+}
+export function requireKeys(value, path, keys) {
     const issues = [];
+    if (!isRecord(value)) {
+        pushValidationIssue(issues, path, `Expected an object, got ${describeValue(value)}.`);
+        return issues;
+    }
     for (const key of keys) {
-        if (!(key in record)) {
-            issues.push({ path, message: `Missing required key: ${key}` });
+        if (!(key in value)) {
+            pushValidationIssue(issues, path, `Missing required key: ${key}`);
         }
     }
     return issues;

package/dist/validation/sessionConfig.d.ts

@@ -1,6 +1,8 @@
-import type { SessionConfig } from "../types/sessionConfig.js";
-import type { ValidationIssue } from "./basic.js";
+import { type SessionConfig } from "../types/sessionConfig.js";
+import { type ValidationIssue } from "./basic.js";
 export declare function validateSessionConfig(value: unknown): ValidationIssue[];
 export declare function validateConfiguredProviderEnvironment(sessionConfig: SessionConfig, options?: {
     commandExists?: (command: string) => boolean;
+    pathExists?: (commandPath: string) => boolean;
 }): ValidationIssue[];
+export { formatValidationIssues } from "./basic.js";

package/dist/validation/sessionConfig.js

@@ -1,18 +1,11 @@
 import { spawnSync } from "node:child_process";
-const VALID_PROVIDERS = new Set([
-    "auto",
-    "local-subprocess",
-    "subprocess-template",
-    "claude-code",
-    "opencode",
-    "vscode-task",
-]);
-const VALID_UI_MODES = new Set(["headless", "visible"]);
+import { accessSync, constants } from "node:fs";
+import { PROVIDER_NAMES, SESSION_UI_MODES, } from "../types/sessionConfig.js";
+import { isRecord, pushValidationIssue, } from "./basic.js";
+const VALID_PROVIDERS = new Set(PROVIDER_NAMES);
+const VALID_UI_MODES = new Set(SESSION_UI_MODES);
 function pushIssue(issues, path, message) {
-    issues.push({ path, message });
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    pushValidationIssue(issues, path, message);
 }
 function validateStringArray(value, path, label, issues, options = {}) {
     if (!Array.isArray(value)) {
@@ -74,6 +67,9 @@ function validateAgentProviderSection(value, path, issues) {
         if (typeof value.command !== "string" || value.command.trim().length === 0) {
             pushIssue(issues, `${path}.command`, "command must be a non-empty string when provided.");
         }
+        else if (!isSupportedConfiguredCommand(value.command)) {
+            pushIssue(issues, `${path}.command`, "command must be a bare executable name or direct executable path. Put CLI flags in extra_args.");
+        }
     }
     if (value.extra_args !== undefined) {
         validateStringArray(value.extra_args, `${path}.extra_args`, "extra_args", issues, { allowEmptyArray: true });
@@ -84,6 +80,43 @@ function commandExists(command) {
     const result = spawnSync(lookupCommand, [command], { stdio: "ignore" });
     return result.status === 0;
 }
+function configuredPathExists(commandPath) {
+    try {
+        accessSync(commandPath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function startsWithPathPrefix(command) {
+    return (command.startsWith(".") ||
+        command.startsWith("/") ||
+        command.startsWith("\\\\") ||
+        /^[A-Za-z]:[\\/]/.test(command));
+}
+function containsForbiddenCommandSyntax(command) {
+    return /[\r\n"'`|&;<>]/.test(command);
+}
+function isBareExecutableName(command) {
+    return (command.length > 0 &&
+        !/\s/.test(command) &&
+        !containsForbiddenCommandSyntax(command) &&
+        !/[\\/]/.test(command) &&
+        !/^[A-Za-z]:/.test(command));
+}
+function isDirectExecutablePath(command) {
+    return (command.length > 0 &&
+        !containsForbiddenCommandSyntax(command) &&
+        startsWithPathPrefix(command));
+}
+function isSupportedConfiguredCommand(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0 || trimmed !== command) {
+        return false;
+    }
+    return isBareExecutableName(trimmed) || isDirectExecutablePath(trimmed);
+}
 export function validateSessionConfig(value) {
     const issues = [];
     if (value === undefined) {
@@ -122,18 +155,32 @@ export function validateSessionConfig(value) {
 export function validateConfiguredProviderEnvironment(sessionConfig, options = {}) {
     const issues = [];
     const lookupCommand = options.commandExists ?? commandExists;
+    const lookupPath = options.pathExists ?? configuredPathExists;
     const provider = sessionConfig.provider ?? "local-subprocess";
     if (provider === "claude-code") {
         const command = sessionConfig.claude_code?.command ?? "claude";
-        if (!lookupCommand(command)) {
+        if (isBareExecutableName(command) && !lookupCommand(command)) {
             pushIssue(issues, "claude_code.command", `Configured claude-code executable was not found on PATH: ${command}.`);
         }
+        else if (isDirectExecutablePath(command) && !lookupPath(command)) {
+            pushIssue(issues, "claude_code.command", `Configured claude-code executable path does not exist: ${command}.`);
+        }
+        else if (!isSupportedConfiguredCommand(command)) {
+            pushIssue(issues, "claude_code.command", "Configured claude-code command must be a bare executable name or direct path. Put CLI flags in extra_args.");
+        }
     }
     if (provider === "opencode") {
         const command = sessionConfig.opencode?.command ?? "opencode";
-        if (!lookupCommand(command)) {
+        if (isBareExecutableName(command) && !lookupCommand(command)) {
             pushIssue(issues, "opencode.command", `Configured opencode executable was not found on PATH: ${command}.`);
         }
+        else if (isDirectExecutablePath(command) && !lookupPath(command)) {
+            pushIssue(issues, "opencode.command", `Configured opencode executable path does not exist: ${command}.`);
+        }
+        else if (!isSupportedConfiguredCommand(command)) {
+            pushIssue(issues, "opencode.command", "Configured opencode command must be a bare executable name or direct path. Put CLI flags in extra_args.");
+        }
     }
     return issues;
 }
+export { formatValidationIssues } from "./basic.js";