Fix explain artifact path resolution (#38)

Author: V3RON

src/cli/explain.ts

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import cliSpinners from "cli-spinners";
@@ -32,7 +32,7 @@ export async function explainCommandWithWriter(
   const colors = pc.createColors(Boolean(stdout.isTTY));
   const accent = (value: string): string =>
     colors.isColorSupported ? `${ACCENT_OPEN}${value}${ACCENT_CLOSE}` : value;
-  const artifactDir = path.resolve(options.artifactDir);
+  const artifactDir = await resolveExplainArtifactDirectory(path.resolve(options.artifactDir));
   const explainPath = path.join(artifactDir, "explain.json");
   const explanationsPath = path.join(artifactDir, "explanations.json");
   const reportPath = path.join(artifactDir, "report.json");
@@ -195,6 +195,72 @@ async function readJsonIfPresent<T>(filePath: string): Promise<T | undefined> {
   }
 }
 
+async function resolveExplainArtifactDirectory(artifactDir: string): Promise<string> {
+  if (await hasExplainArtifacts(artifactDir)) {
+    return artifactDir;
+  }
+
+  const nestedArtifactDirs = await collectExplainArtifactDirectories(artifactDir, 2);
+
+  if (nestedArtifactDirs.length === 1) {
+    return nestedArtifactDirs[0]!;
+  }
+
+  if (nestedArtifactDirs.length > 1) {
+    throw new Error(
+      "Multiple explain artifacts were found below the provided artifact directory. Pass the exact failed artifact directory instead.",
+    );
+  }
+
+  return artifactDir;
+}
+
+async function collectExplainArtifactDirectories(
+  artifactDir: string,
+  depth: number,
+): Promise<string[]> {
+  if (depth <= 0) {
+    return [];
+  }
+
+  let entries;
+  try {
+    entries = await readdir(artifactDir, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return [];
+    }
+
+    throw error;
+  }
+
+  const nestedDirs = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(artifactDir, entry.name))
+    .sort();
+  const matches: string[] = [];
+
+  for (const nestedDir of nestedDirs) {
+    if (await hasExplainArtifacts(nestedDir)) {
+      matches.push(nestedDir);
+      continue;
+    }
+
+    matches.push(...(await collectExplainArtifactDirectories(nestedDir, depth - 1)));
+  }
+
+  return matches;
+}
+
+async function hasExplainArtifacts(artifactDir: string): Promise<boolean> {
+  const [explainArtifact, explanationsArtifact] = await Promise.all([
+    readJsonIfPresent<ExplainArtifact>(path.join(artifactDir, "explain.json")),
+    readJsonIfPresent<ExplanationsArtifact>(path.join(artifactDir, "explanations.json")),
+  ]);
+
+  return explainArtifact !== undefined || explanationsArtifact !== undefined;
+}
+
 function isMissingFileError(error: unknown): error is NodeJS.ErrnoException {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }

src/reporters/standard.ts

@@ -290,7 +290,7 @@ export function createStandardReporter(options: StandardReporterOptions = {}): B
 }
 
 function hasExplainArtifact(failure: FailureEntry): boolean {
-  return existsSync(path.join(failure.executionArtifactDir, "explain.json"));
+  return existsSync(path.join(failure.artifactDir, "explain.json"));
 }
 
 function formatCaseRow(result: CaseResult, symbols: ReturnType<typeof getSymbols>): string {

test/cli.test.ts

@@ -246,6 +246,121 @@ test("explainCommand writes explanations.json from persisted explain questions",
   ]);
 });
 
+test("explainCommand resolves a nested failed artifact directory from the execution root", async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "skillgym-cli-"));
+  tempDirs.push(tempDir);
+  const executionArtifactDir = path.join(tempDir, "alpha", "open-main");
+  const artifactDir = path.join(executionArtifactDir, "repeat-1", "session-2");
+  await mkdir(artifactDir, { recursive: true });
+  await writeFile(
+    path.join(artifactDir, "report.json"),
+    `${JSON.stringify({
+      runner: {
+        id: "open-main",
+        pathKey: "open-main",
+        agent: { type: "opencode", model: "openai/gpt-5" },
+      },
+      prompt: "prompt",
+      usage: {
+        inputChars: 0,
+        outputChars: 0,
+        reasoningChars: 0,
+        source: { input: "chars", output: "chars", reasoning: "chars" },
+      },
+      files: { observedReads: [], observedSkillReads: [] },
+      detectedSkills: [],
+      events: [],
+      finalOutput: "",
+      rawArtifacts: {},
+    })}\n`,
+    "utf8",
+  );
+  await writeFile(
+    path.join(artifactDir, "explain.json"),
+    `${JSON.stringify({
+      suitePath: path.join(tempDir, "suite.ts"),
+      caseId: "alpha",
+      runnerId: "open-main",
+      cwd: tempDir,
+      sessionId: "ses_123",
+      questions: [
+        {
+          question: "Why did you skip SKILL.md?",
+          source: { filePath: path.join(tempDir, "suite.ts"), line: "12", column: "5" },
+        },
+      ],
+    })}\n`,
+    "utf8",
+  );
+
+  const explain = vi.fn(async () => ({
+    answers: [
+      {
+        question: {
+          question: "Why did you skip SKILL.md?",
+          source: { filePath: path.join(tempDir, "suite.ts"), line: "12", column: "5" },
+        },
+        answer: "Because the prompt looked sufficient.",
+        sessionId: "ses_123",
+        startedAt: "2026-05-07T10:00:00.000Z",
+        endedAt: "2026-05-07T10:00:01.000Z",
+        durationMs: 1_000,
+        rawArtifacts: {},
+      },
+    ],
+  }));
+
+  vi.resetModules();
+  vi.doMock("../src/config.js", () => ({
+    loadConfig: vi.fn(async () => ({
+      config: {
+        runners: {
+          "open-main": { agent: { type: "opencode", model: "openai/gpt-5" } },
+        },
+      },
+    })),
+  }));
+  vi.doMock("../src/adapters/index.js", () => ({
+    getAdapter: vi.fn(() => ({
+      run: vi.fn(),
+      collect: vi.fn(),
+      normalize: vi.fn(),
+      explain,
+    })),
+  }));
+
+  const output: string[] = [];
+  const stdout = {
+    isTTY: false,
+    write(value: string) {
+      output.push(value);
+      return true;
+    },
+  };
+  try {
+    const { explainCommandWithWriter } = await import("../src/cli/explain.js");
+    await explainCommandWithWriter({ artifactDir: executionArtifactDir }, stdout);
+  } finally {
+    vi.doUnmock("../src/config.js");
+    vi.doUnmock("../src/adapters/index.js");
+    vi.resetModules();
+  }
+
+  expect(explain).toHaveBeenCalledWith(
+    expect.objectContaining({
+      artifactDir,
+      cwd: tempDir,
+      sessionId: "ses_123",
+    }),
+  );
+  expect(output.join("")).toContain(artifactDir);
+  expect(
+    JSON.parse(await readFile(path.join(artifactDir, "explanations.json"), "utf8")) as {
+      sessionId: string;
+    },
+  ).toMatchObject({ sessionId: "ses_123" });
+});
+
 test("explainCommand reuses existing explanations.json by default", async () => {
   const tempDir = await mkdtemp(path.join(os.tmpdir(), "skillgym-cli-"));
   tempDirs.push(tempDir);

test/reporters/standard.test.ts

@@ -279,6 +279,107 @@ test("standard reporter shows explain hint when a failed execution has explain.j
   expect(output).toContain("Explain failed executions with `skillgym explain <artifactDir>`.");
 });
 
+test("standard reporter finds explain.json in the failed artifactDir for retried executions", async () => {
+  const writes: string[] = [];
+  const reporter = createStandardReporter({
+    stdout: {
+      isTTY: false,
+      columns: 120,
+      write(chunk: string) {
+        writes.push(chunk);
+        return true;
+      },
+    },
+    isInteractive: false,
+    isUnicode: true,
+  });
+
+  const executionArtifactDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), "skillgym-standard-reporter-"),
+  );
+  const artifactDir = path.join(executionArtifactDir, "session-2");
+  await fs.mkdir(artifactDir, { recursive: true });
+  await fs.writeFile(
+    path.join(artifactDir, "explain.json"),
+    JSON.stringify({ questions: ["why"] }),
+  );
+
+  const runner = createRunnerInfo("code-main", { type: "codex", model: "gpt-5.4" });
+  const context = {
+    isInteractive: false,
+    cwd: "/workspace",
+    workspaceMode: "shared" as const,
+    suitePath: "examples/basic-suite.ts",
+    suiteRunArtifactDir: ".skillgym-results/run-1",
+    selectedCaseCount: 1,
+    selectedRunnerCount: 1,
+    selectedExecutionCount: 1,
+    scheduleMode: "serial" as const,
+    maxParallel: 1,
+    declaredTags: [],
+  };
+  const suiteResult: SuiteRunResult = {
+    suitePath: context.suitePath,
+    startedAt: "2026-04-02T12:00:00.000Z",
+    endedAt: "2026-04-02T12:01:42.000Z",
+    durationMs: 102_000,
+    suiteRunArtifactDir: context.suiteRunArtifactDir,
+    declaredTags: [],
+    selectedTags: [],
+    cases: [
+      createCaseResult({
+        caseId: "case-a",
+        runnerResults: [
+          createRunnerResult({
+            runner,
+            passed: false,
+            executionArtifactDir,
+            artifactDir,
+            totalTokens: 12_000,
+            sessions: 2,
+          }),
+        ],
+      }),
+    ],
+    runners: [
+      createRunnerSummary({
+        runner,
+        passedCases: 0,
+        totalCases: 1,
+        averageDurationMs: 19_300,
+        averageTotalTokens: 13_500,
+      }),
+    ],
+  };
+
+  await reporter.onSuiteStart?.({
+    context,
+    cases: [],
+    runners: [runner],
+    startedAt: suiteResult.startedAt,
+  });
+  await reporter.onRunnerFinish?.({
+    context,
+    case: { id: "case-a", prompt: "", assert() {} },
+    runner,
+    result: suiteResult.cases[0]!.runnerResults[0]!,
+    caseIndex: 1,
+    totalCases: 1,
+  });
+  await reporter.onCaseFinish?.({
+    context,
+    case: { id: "case-a", prompt: "", assert() {} },
+    result: suiteResult.cases[0]!,
+    caseIndex: 1,
+    totalCases: 1,
+  });
+  await reporter.onSuiteFinish?.({ context, result: suiteResult });
+
+  const output = writes.join("");
+
+  expect(output).toContain("Explain failed executions with `skillgym explain <artifactDir>`.");
+});
+
 test("standard reporter interactive mode renders queued, running, and finished executions", async () => {
   vi.useFakeTimers();
   const writes: string[] = [];