@awak-app/simy-cli 0.1.3 → 0.1.5

package/src/backend-executable.js

@@ -2,14 +2,67 @@ import { spawn } from "node:child_process";
 
 const MACOS_CODEX_BINARY = "/Applications/ChatGPT.app/Contents/Resources/codex";
 
-export async function resolveBackendExecutable(
+export const BACKEND_VERSION_POLICIES = Object.freeze({
+  codex: Object.freeze({
+    label: "Codex",
+    minimumVersion: "0.144.0",
+    updateCommand: "npm install -g @openai/codex@latest",
+  }),
+  claude: Object.freeze({
+    label: "Claude Code",
+    minimumVersion: "2.1.200",
+    updateCommand: "claude update",
+  }),
+});
+
+export async function resolveBackendExecutable(backend, options = {}) {
+  const inspection = await inspectBackendExecutable(backend, options);
+  return inspection.available ? inspection.executable : null;
+}
+
+export async function inspectBackendExecutable(
   backend,
   { spawnImpl = spawn, candidates = backendCandidates(backend), timeoutMs = 1_500 } = {},
 ) {
+  const policy = versionPolicy(backend);
   for (const candidate of [...new Set(candidates.filter(Boolean))]) {
-    if (await executableAvailable(candidate, { spawnImpl, timeoutMs })) return candidate;
+    const probe = await probeExecutable(candidate, { spawnImpl, timeoutMs });
+    if (!probe.available) continue;
+    const installedVersion = parseBackendVersion(probe.output);
+    if (!installedVersion) {
+      return {
+        backend,
+        executable: candidate,
+        available: true,
+        compatible: false,
+        status: "unknown_version",
+        installed_version: null,
+        minimum_version: policy.minimumVersion,
+        update_command: policy.updateCommand,
+      };
+    }
+    const compatible = compareVersions(installedVersion, policy.minimumVersion) >= 0;
+    return {
+      backend,
+      executable: candidate,
+      available: true,
+      compatible,
+      status: compatible ? "compatible" : "outdated",
+      installed_version: installedVersion,
+      minimum_version: policy.minimumVersion,
+      update_command: policy.updateCommand,
+    };
   }
-  return null;
+  return {
+    backend,
+    executable: null,
+    available: false,
+    compatible: false,
+    status: "missing",
+    installed_version: null,
+    minimum_version: policy.minimumVersion,
+    update_command: policy.updateCommand,
+  };
 }
 
 export function backendCandidates(backend) {
@@ -23,16 +76,49 @@ export function backendCandidates(backend) {
   ];
 }
 
-function executableAvailable(command, { spawnImpl, timeoutMs }) {
+export function parseBackendVersion(output) {
+  const match = String(output || "").match(/(?:^|\s|v)(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?=\s|$|\))/);
+  return match?.[1] ?? null;
+}
+
+export function compareVersions(left, right) {
+  const leftParts = numericVersionParts(left);
+  const rightParts = numericVersionParts(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+function versionPolicy(backend) {
+  return backend === "claude" ? BACKEND_VERSION_POLICIES.claude : BACKEND_VERSION_POLICIES.codex;
+}
+
+function numericVersionParts(value) {
+  const match = String(value || "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return [0, 0, 0];
+  return match.slice(1).map(Number);
+}
+
+function probeExecutable(command, { spawnImpl, timeoutMs }) {
   return new Promise((resolve) => {
     let settled = false;
     let timeout;
-    const child = spawnImpl(command, ["--version"], { stdio: "ignore" });
+    let output = "";
+    const child = spawnImpl(command, ["--version"], { stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    child.stdout?.on?.("data", (chunk) => {
+      output += chunk;
+    });
+    child.stderr?.on?.("data", (chunk) => {
+      output += chunk;
+    });
     const finish = (available) => {
       if (settled) return;
       settled = true;
       if (timeout) clearTimeout(timeout);
-      resolve(available);
+      resolve({ available, output: output.trim() });
     };
     timeout = setTimeout(() => {
       child.kill?.("SIGTERM");

package/src/console/app.js

@@ -19,11 +19,12 @@ const TERMINAL_STATES = new Set([
 ]);
 const NEW_TASK = "__new_task__";
 
-export function CodingLoopConsole({ agent, onQuit = () => {} }) {
+export function AgenticLoopConsole({ agent, onQuit = () => {} }) {
   const { exit } = useApp();
   const { stdout } = useStdout();
   const [terminal, setTerminal] = useState(() => terminalSize(stdout));
   const [runs, setRuns] = useState(() => agent.registry.list());
+  const [cliUpdate, setCliUpdate] = useState(() => agent.updates?.snapshot?.() ?? null);
   const [selectedId, setSelectedId] = useState(() => runs[0]?.id ?? NEW_TASK);
   const [inputMode, setInputMode] = useState(() => runs.length === 0);
   const [input, setInput] = useState("");
@@ -51,6 +52,13 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
     return () => agent.registry.off("change", update);
   }, [agent.registry]);
 
+  useEffect(() => {
+    if (!agent.updates?.on) return undefined;
+    const update = (nextState) => setCliUpdate(nextState);
+    agent.updates.on("change", update);
+    return () => agent.updates.off("change", update);
+  }, [agent.updates]);
+
   useEffect(() => {
     const resize = () => setTerminal(terminalSize(stdout));
     stdout.on("resize", resize);
@@ -68,7 +76,8 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
     1 +
     (waitingForHuman ? 1 : 0) +
     (!selectedRun ? 1 : 0) +
-    (notice || busy ? 1 : 0);
+    (notice || busy ? 1 : 0) +
+    (visibleUpdateNotice(cliUpdate) ? 1 : 0);
   const mainHeight = Math.max(8, terminal.rows - 5 - actionRows);
   const detailInnerWidth = Math.max(20, terminal.columns - 4);
   const detailRows = useMemo(
@@ -138,7 +147,7 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
     }
     if (!selectedRun) {
       if (command.type !== "guidance") {
-        setNotice("That command requires a selected coding run.");
+        setNotice("That command requires a selected Agentic Loop run.");
         return;
       }
       setBusy(true);
@@ -175,12 +184,12 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
             setNotice("Guidance queued for the next executor handoff.");
           } else {
             await agent.controls.continue(selectedRun, command.message);
-            setNotice("Human guidance accepted. The coding loop is continuing.");
+            setNotice("Human guidance accepted. The agentic loop is continuing.");
           }
           break;
         case "decision":
           await agent.controls.applyDecision(selectedRun, command);
-          setNotice("Human decision recorded. The coding loop is continuing.");
+          setNotice("Human decision recorded. The agentic loop is continuing.");
           break;
         case "recheck":
           await agent.controls.recheck(selectedRun);
@@ -259,7 +268,7 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
         await agent.controls.selectRepository(selectedRun, match);
         setDetailOpen(true);
         setDetailScrollFromEnd(0);
-        setNotice(`Authorized ${match.repository}. The same coding run is continuing.`);
+        setNotice(`Authorized ${match.repository}. The same Agentic Loop run is continuing.`);
       } else if (selectedRun) {
         setNotice(
           `${selectedRun.request.repository} was not found under ${result.root}. Run /scan <path> for another authorized root.`,
@@ -290,7 +299,7 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
         setRepositoryPicker(null);
         setDetailOpen(true);
         setDetailScrollFromEnd(0);
-        setNotice(`Authorized ${selected.repository}. The same coding run is continuing.`);
+        setNotice(`Authorized ${selected.repository}. The same Agentic Loop run is continuing.`);
       } else {
         const verified = await agent.controls.selectRepository(null, selected);
         setDraft((current) => ({
@@ -461,7 +470,7 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
       if (confirmStop) void execute("/stop");
       else {
         setConfirmStop(true);
-        setNotice("Press x again to stop the selected coding run.");
+        setNotice("Press x again to stop the selected Agentic Loop run.");
       }
       return;
     }
@@ -529,11 +538,14 @@ export function CodingLoopConsole({ agent, onQuit = () => {} }) {
         draft,
         repositoryMissing: isRepositoryMissing(selectedRun),
         modalOpen: Boolean(scanPrompt || repositoryPicker),
+        cliUpdate,
       }),
     ],
   });
 }
 
+export const CodingLoopConsole = AgenticLoopConsole;
+
 function Header({ agent, runCount }) {
   return jsxs(Box, {
     borderStyle: "single",
@@ -542,6 +554,12 @@ function Header({ agent, runCount }) {
     children: [
       jsx(Text, { bold: true, color: "cyan", children: "SIMY" }),
       jsx(Text, { bold: true, children: " Coding Chat" }),
+      agent.updates?.snapshot?.().current_version
+        ? jsx(Text, {
+            dimColor: true,
+            children: `  v${agent.updates.snapshot().current_version}`,
+          })
+        : null,
       jsx(Text, { dimColor: true, children: `  localhost:${agent.port}` }),
       jsx(Spacer, {}),
       jsx(Text, { color: runCount > 0 ? "green" : "yellow", children: `${runCount} runs` }),
@@ -778,6 +796,7 @@ function ActionBar({
   draft,
   repositoryMissing,
   modalOpen,
+  cliUpdate,
 }) {
   const waiting = run && (run.controlState === "waiting_human" || run.status === "waiting_human");
   return jsxs(Box, {
@@ -823,10 +842,29 @@ function ActionBar({
         : busy
           ? jsx(Text, { color: "cyan", children: "Working..." })
           : null,
+      visibleUpdateNotice(cliUpdate)
+        ? jsx(Text, {
+            color: cliUpdate.state === "failed" ? "red" : "yellow",
+            children: visibleUpdateNotice(cliUpdate),
+          })
+        : null,
     ],
   });
 }
 
+function visibleUpdateNotice(update) {
+  if (
+    !update ||
+    !["update_available", "waiting_for_idle", "updating", "restarting", "failed"].includes(
+      update.state,
+    )
+  ) {
+    return "";
+  }
+  const command = update.action?.command ? ` Run: ${update.action.command}` : "";
+  return `${update.message || "SIMY CLI update status changed."}${command}`;
+}
+
 function initialDraft(agent) {
   const backends = agent.capabilities?.backends ?? {};
   return {

package/src/console/index.js

@@ -1,11 +1,11 @@
 import { jsx } from "react/jsx-runtime";
 import { render } from "ink";
 
-import { CodingLoopConsole } from "./app.js";
+import { AgenticLoopConsole } from "./app.js";
 
-export async function runCodingLoopConsole(agent, options = {}) {
+export async function runAgenticLoopConsole(agent, options = {}) {
   const instance = render(
-    jsx(CodingLoopConsole, {
+    jsx(AgenticLoopConsole, {
       agent,
       onQuit: options.onQuit,
     }),
@@ -21,5 +21,6 @@ export async function runCodingLoopConsole(agent, options = {}) {
   await instance.waitUntilExit();
 }
 
-export { CodingLoopConsole } from "./app.js";
+export const runCodingLoopConsole = runAgenticLoopConsole;
+export { AgenticLoopConsole, CodingLoopConsole } from "./app.js";
 export { consoleHelpLines, parseConsoleCommand } from "./commands.js";

package/src/desktop-executor.js

@@ -0,0 +1,137 @@
+import { spawn } from "node:child_process";
+
+import {
+  BACKEND_VERSION_POLICIES,
+  inspectBackendExecutable,
+} from "./backend-executable.js";
+
+export const DESKTOP_EXECUTION_TARGET = "desktop";
+export const DESKTOP_EXECUTION_LABEL = "Your Desktop";
+
+export function normalizeDesktopExecutionTarget(value) {
+  const target = String(value ?? "").trim().toLowerCase();
+  if (!target || target === DESKTOP_EXECUTION_TARGET) return DESKTOP_EXECUTION_TARGET;
+  const error = new Error(
+    `SIMY CLI runs only on ${DESKTOP_EXECUTION_LABEL}; execution_target must be desktop.`,
+  );
+  error.code = "unsupported_execution_target";
+  error.executionTarget = target;
+  throw error;
+}
+
+export async function inspectDesktopExecutor(backend, options = {}) {
+  const provider = normalizeBackend(backend);
+  const inspection = await inspectBackendExecutable(provider, options);
+  return {
+    execution_target: DESKTOP_EXECUTION_TARGET,
+    execution_label: DESKTOP_EXECUTION_LABEL,
+    provider_label: BACKEND_VERSION_POLICIES[provider].label,
+    ...inspection,
+  };
+}
+
+export function desktopExecutorCapability(inspection) {
+  return {
+    execution_target: DESKTOP_EXECUTION_TARGET,
+    execution_label: DESKTOP_EXECUTION_LABEL,
+    backend: inspection.backend,
+    provider_label: inspection.provider_label,
+    status: inspection.status,
+    available: inspection.available,
+    compatible: inspection.compatible,
+    installed_version: inspection.installed_version,
+    minimum_version: inspection.minimum_version,
+    update_command: inspection.update_command,
+  };
+}
+
+export async function resolveDesktopExecutorCommand({
+  backend,
+  instruction,
+  repositoryPath,
+  environment = process.env,
+  spawnImpl = spawn,
+  inspectionOptions = {},
+} = {}) {
+  const provider = normalizeBackend(backend);
+  const target = normalizeDesktopExecutionTarget(DESKTOP_EXECUTION_TARGET);
+  const override =
+    provider === "claude" ? environment.SIMY_CLAUDE_COMMAND : environment.SIMY_CODEX_COMMAND;
+  if (override) {
+    return {
+      ...shellCommand(override, repositoryPath, instruction, spawnImpl),
+      backend: provider,
+      execution_target: target,
+      verification: "explicit_command_override",
+    };
+  }
+
+  const inspection = await inspectDesktopExecutor(provider, {
+    ...inspectionOptions,
+    spawnImpl: inspectionOptions.spawnImpl ?? spawnImpl,
+  });
+  if (!inspection.compatible || !inspection.executable) {
+    throw desktopExecutorUnavailableError(inspection);
+  }
+  return {
+    bin: inspection.executable,
+    args:
+      provider === "claude"
+        ? claudeBackendArgs(instruction)
+        : ["exec", "--json", instruction],
+    env: {},
+    spawn: spawnImpl,
+    backend: provider,
+    execution_target: target,
+    verification: "compatible_version",
+    installed_version: inspection.installed_version,
+  };
+}
+
+export function claudeBackendArgs(instruction) {
+  return [
+    "-p",
+    instruction,
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    // The Agentic Loop is scoped to a verified checkout and explicitly approved
+    // by the user. Print mode cannot display permission prompts, so edits would
+    // otherwise be silently unavailable to the desktop executor.
+    "--dangerously-skip-permissions",
+  ];
+}
+
+function normalizeBackend(backend) {
+  if (backend === "codex" || backend === "claude") return backend;
+  throw new Error("Desktop executor backend must be codex or claude.");
+}
+
+function desktopExecutorUnavailableError(inspection) {
+  const provider = inspection.provider_label;
+  let message;
+  if (inspection.status === "outdated") {
+    message = `${provider} ${inspection.installed_version} is too old for ${DESKTOP_EXECUTION_LABEL}. Update to ${inspection.minimum_version} or newer: ${inspection.update_command}`;
+  } else if (inspection.status === "unknown_version") {
+    message = `${provider} is installed on ${DESKTOP_EXECUTION_LABEL}, but its version could not be verified. Update it and try again: ${inspection.update_command}`;
+  } else {
+    message = `${provider} is not installed on ${DESKTOP_EXECUTION_LABEL}. Install or update it before starting this run: ${inspection.update_command}`;
+  }
+  const error = new Error(message);
+  error.code = `desktop_executor_${inspection.status}`;
+  error.inspection = desktopExecutorCapability(inspection);
+  return error;
+}
+
+function shellCommand(command, cwd, instruction, spawnImpl) {
+  return {
+    bin: process.platform === "win32" ? "cmd.exe" : "sh",
+    args: process.platform === "win32" ? ["/d", "/s", "/c", command] : ["-lc", command],
+    cwd,
+    env: {
+      SIMY_AGENTIC_LOOP_REQUIREMENT: instruction,
+      SIMY_CODING_LOOP_REQUIREMENT: instruction,
+    },
+    spawn: spawnImpl,
+  };
+}

package/src/index.js

@@ -4,6 +4,13 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import { startAgent } from "./agent.js";
+import {
+  autoUpdateHelpText,
+  createCliAutoUpdater,
+  readCliPackageInfo,
+  restartDaemonProcess,
+  writeUpdateHandoffFromEnvironment,
+} from "./auto-update.js";
 import { openAuthorizationUrl } from "./browser.js";
 import { DEFAULT_WEB_ORIGIN, resolveWebOrigin } from "./web-origin.js";
 
@@ -18,10 +25,13 @@ if (args.has("--help") || args.has("-h")) {
 
 Options:
   --daemon, --deamon  Run detached in the background
-  --no-tui            Disable the interactive Coding Loop console
+  --no-tui            Disable the interactive Agentic Loop console
   --no-open           Do not open the browser when authorization is required
   --port <port>       Bind a specific localhost port
   --host <url>        Connect to a SIMY Web origin (default: ${DEFAULT_WEB_ORIGIN})
+  --no-auto-update    Disable the hourly CLI update check
+
+${autoUpdateHelpText()}
 `);
   process.exit(0);
 }
@@ -29,6 +39,7 @@ Options:
 const daemon = args.has("--daemon") || args.has("--deamon");
 const interactive = !daemon && !args.has("--no-tui") && process.stdin.isTTY && process.stdout.isTTY;
 const port = readPort(argv);
+const packageInfo = await readCliPackageInfo();
 let webOrigin;
 try {
   webOrigin = resolveWebOrigin(readOption(argv, "--host"));
@@ -48,14 +59,39 @@ if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
   process.exit(0);
 }
 
-const agent = await startAgent({ requestedPort: port, daemon, webOrigin, quiet: interactive });
+const updateManager = await createCliAutoUpdater({
+  daemon,
+  interactive,
+  requestedPort: port,
+  disabled: args.has("--no-auto-update") || process.env.SIMY_AUTO_UPDATE === "0",
+  dependencies: { packageInfo },
+});
+const agent = await startAgent({
+  requestedPort: port,
+  daemon,
+  webOrigin,
+  quiet: interactive,
+  updateManager,
+});
+await writeUpdateHandoffFromEnvironment({ version: packageInfo.version, port: agent.port });
+updateManager.start({
+  registry: agent.registry,
+  restartDaemon: async (targetVersion) => {
+    await restartDaemonProcess({
+      entryPath: fileURLToPath(import.meta.url),
+      argv: process.argv.slice(2),
+      targetVersion,
+    });
+    await closeServer(agent.server);
+  },
+});
 if (agent.loginUrl && !args.has("--no-open")) {
   await openAuthorizationUrl(agent.loginUrl);
 }
 if (interactive) {
-  const { runCodingLoopConsole } = await import("./console/index.js");
+  const { runAgenticLoopConsole } = await import("./console/index.js");
   try {
-    await runCodingLoopConsole(agent);
+    await runAgenticLoopConsole(agent);
   } finally {
     await closeServer(agent.server);
   }

package/src/local-attachments.js

@@ -7,7 +7,7 @@ export const MAX_ATTACHMENT_COUNT = 5;
 export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
 export const MAX_ATTACHMENTS_TOTAL_BYTES = 50 * 1024 * 1024;
 const RUN_RETENTION_MS = 24 * 60 * 60 * 1000;
-const SAFE_RUN_ID = /^coding_loop_[A-Za-z0-9_-]+$/;
+const SAFE_RUN_ID = /^(?:agentic_loop|coding_loop)_[A-Za-z0-9_-]+$/;
 const ALLOWED_EXACT_MIME_TYPES = new Set([
   "application/json",
   "application/octet-stream",
@@ -32,7 +32,7 @@ export function runsRoot(override) {
 }
 
 export async function stageRunAttachments({ runId, attachments, manifest, root }) {
-  if (!SAFE_RUN_ID.test(runId)) throw new Error("invalid coding loop run_id");
+  if (!SAFE_RUN_ID.test(runId)) throw new Error("invalid agentic loop run_id");
   if (!Array.isArray(attachments) || attachments.length === 0) return [];
   if (attachments.length > MAX_ATTACHMENT_COUNT) {
     throw new Error(`at most ${MAX_ATTACHMENT_COUNT} attachments are allowed`);

package/src/orchestrator/audit.js

@@ -1,4 +1,4 @@
-import { stat } from "node:fs/promises";
+import { open, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 
 import {
@@ -7,8 +7,9 @@ import {
   hasAllowedPrefix,
   stringArray,
 } from "./shared.js";
+import { evaluateRetryProblemSolving } from "./problem-solving.js";
 
-export async function auditAttempt(charter, attempt) {
+export async function auditAttempt(charter, attempt, { previousAttempt = null } = {}) {
   const checks = [];
   const addCheck = (id, label, passed, detail, severity = "blocker", repairability = "auto") => {
     checks.push({ id, label, passed, severity, detail, repairability, evidence_refs: [] });
@@ -112,6 +113,12 @@ export async function auditAttempt(charter, attempt) {
       : "No committed local evidence artifacts reported.",
   );
 
+  const retryProblemSolving = evaluateRetryProblemSolving(attempt, previousAttempt);
+  for (const check of retryProblemSolving.checks) {
+    addCheck(check.id, check.label, check.passed, check.detail);
+  }
+  attempt.retry_problem_solving = retryProblemSolving;
+
   const evidenceRequired = charter.expected_evidence.includes("ui_evidence_path");
   const evidenceArtifact = await inspectEvidence(charter, attempt.ui_evidence_path);
   if (evidenceRequired || attempt.ui_evidence_path) {
@@ -126,6 +133,16 @@ export async function auditAttempt(charter, attempt) {
       evidenceArtifact?.summary || "Local evidence path missing.",
     );
   }
+  if (charter.evidence_policy?.browser_required) {
+    addCheck(
+      "browser_visual_evidence_present",
+      "Browser screenshot or video evidence is present",
+      Boolean(evidenceArtifact?.visual_file_count > 0),
+      evidenceArtifact?.visual_file_count > 0
+        ? `${evidenceArtifact.visual_file_count} screenshot or video artifact(s) found.`
+        : "UI and browser-extension work requires a real screenshot or video; a path, text file, or empty directory is not sufficient.",
+    );
+  }
 
   const findings = checks
     .filter((check) => !check.passed)
@@ -301,17 +318,94 @@ async function inspectEvidence(charter, evidencePath) {
   const underRoot = Boolean(
     root && (resolved === root || resolved.startsWith(`${root}${path.sep}`)),
   );
+  const directoryEvidence = fileStat?.isDirectory()
+    ? await scanEvidenceDirectory(resolved)
+    : null;
+  const directKind = fileStat?.isFile() ? evidenceKind(resolved) : "unknown";
+  const visualFileCount = fileStat?.isFile()
+    ? (await isVisualEvidenceFile(resolved))
+      ? 1
+      : 0
+    : directoryEvidence?.visualFileCount ?? 0;
+  const sizeBytes = fileStat?.isDirectory()
+    ? directoryEvidence?.sizeBytes ?? 0
+    : fileStat?.size ?? 0;
   return {
     path: resolved,
-    kind: fileStat?.isDirectory() ? "directory" : evidenceKind(resolved),
+    kind: fileStat?.isDirectory() ? "directory" : directKind,
     exists: Boolean(fileStat),
     under_required_root: underRoot,
-    size_bytes: fileStat?.size ?? 0,
-    file_count: fileStat?.isFile() ? 1 : 0,
+    size_bytes: sizeBytes,
+    file_count: fileStat?.isFile() ? 1 : directoryEvidence?.fileCount ?? 0,
+    visual_file_count: visualFileCount,
     git_tracked: false,
     summary:
-      fileStat && underRoot && fileStat.size > 0
-        ? "Evidence exists under the required local root."
+      fileStat && underRoot && sizeBytes > 0
+        ? `Evidence exists under the required local root; ${visualFileCount} visual artifact(s) found.`
         : "Evidence is missing, empty, or outside the required local root.",
   };
 }
+
+async function scanEvidenceDirectory(directory) {
+  const pending = [directory];
+  let fileCount = 0;
+  let visualFileCount = 0;
+  let sizeBytes = 0;
+  while (pending.length > 0 && fileCount < 500) {
+    const current = pending.shift();
+    if (!current) break;
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const candidate = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(candidate);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      fileCount += 1;
+      if (await isVisualEvidenceFile(candidate)) visualFileCount += 1;
+      try {
+        sizeBytes += (await stat(candidate)).size;
+      } catch {
+        // A file disappearing during inspection is simply not counted toward its size.
+      }
+      if (fileCount >= 500) break;
+    }
+  }
+  return { fileCount, visualFileCount, sizeBytes };
+}
+
+async function isVisualEvidenceFile(filePath) {
+  if (!["image", "video"].includes(evidenceKind(filePath))) return false;
+  const header = Buffer.alloc(16);
+  let handle;
+  try {
+    handle = await open(filePath, "r");
+    const { bytesRead } = await handle.read(header, 0, header.length, 0);
+    if (bytesRead === 0) return false;
+  } catch {
+    return false;
+  } finally {
+    try {
+      await handle?.close();
+    } catch {
+      // The evidence file may disappear while it is being inspected.
+    }
+  }
+  const ascii = header.toString("ascii");
+  return (
+    header.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ||
+    header.subarray(0, 3).equals(Buffer.from([255, 216, 255])) ||
+    ascii.startsWith("GIF87a") ||
+    ascii.startsWith("GIF89a") ||
+    (ascii.startsWith("RIFF") && ascii.slice(8, 12) === "WEBP") ||
+    ascii.slice(4, 8) === "ftyp" ||
+    header.subarray(0, 4).equals(Buffer.from([26, 69, 223, 163]))
+  );
+}