@elench/testkit 0.1.150 → 0.1.151

package/README.md

@@ -148,19 +148,28 @@ results without any separate follow-up maintenance command.
 - `new regressions`
 - `known regressions`
 - `fixed known regressions`
-- `catalog stale`
+- `case store stale`
 
 The default CLI keeps those signals lightweight:
 
 - failed files print inline diagnosis immediately under the file line
 - the final summary box reports aggregate regression counts only
 - machine-readable artifacts gain per-file `diagnosis` plus top-level
-  `regressions.summary`, `regressions.catalog`, and prepared `regressions.drafts`
+  `regressions.summary`, `regressions.caseStore`, `regressions.workflow`, and prepared `regressions.drafts`
 
-`catalog stale` is repo hygiene, not a test failure. It means the regression
-catalog or linked issue tracker metadata needs attention, for example because a
+`case store stale` is repo hygiene, not a test failure. It means the regression
+case store or linked issue tracker metadata needs attention, for example because a
 linked issue is closed but the regression still reproduces.
 
+The canonical durable file is `testkit.regressions.json` with
+`schemaVersion: 2` and a top-level `cases` array. When a configured full run sees
+a new failure, Testkit records an untriaged case automatically. When a known case
+passes, Testkit moves it through `fixed_pending_verification`; after the
+configured stability window it can close the linked GitHub issue and mark the
+case resolved. Open GitHub bug issues with no linked regression case are recorded
+as `coverage_missing` cases so missing regression coverage is visible in normal
+run output instead of becoming a separate manual audit.
+
 ## Tooling Adapters
 
 `testkit` also ships tool-specific config helpers so consumer repos do not need
@@ -382,7 +391,9 @@ destroyed. `testkit cleanup --resources` cleans stale resources for the current
 product; add `--global` to clean labelled resources whose product directory no
 longer exists, and add `--include-legacy` only when you intentionally want to
 remove old unlabelled `testkit_pg_*` containers from pre-ownership Testkit
-versions. Use `--dry-run` first when cleaning globally.
+versions. Host-local Postgres data lives in a Testkit-labelled named Docker
+volume instead of an image-declared anonymous volume, so cleanup can account for
+and remove it safely. Use `--dry-run` first when cleaning globally.
 
 `database.template` is the database-side equivalent for reusable template DB
 state. When `database.sourceSchema` is configured, Testkit treats the configured
@@ -488,7 +499,7 @@ If `regressions.file` is configured, `testkit` enriches
 - per-file `diagnosis` metadata (new regression, known regression, fixed known regression)
 - top-level `regressions` summary and prepared draft updates
 
-Regression-catalog entry authoring uses this contract:
+Regression case authoring uses this contract:
 
 - `summary`
   - concise local statement of the regression slice
@@ -498,12 +509,12 @@ Regression-catalog entry authoring uses this contract:
   - selectors that let testkit automatically recognize the regression in future runs
 
 If `regressions.sync` is also configured, `testkit` syncs linked GitHub issues and
-adds top-level regression catalog health to the run/status artifacts. The most
-important catalog-staleness signal is:
+adds top-level regression case health to the run/status artifacts. The most
+important stale-case signal is:
 
 - a known regression still fails, but the linked GitHub issue is closed
 
-In `mode: "error"`, catalog health can also fail the run for problems such as:
+In `mode: "error"`, case-store health can also fail the run for problems such as:
 
 - closed issues that still reproduce
 - missing issue refs
@@ -811,6 +822,7 @@ npm run test:unit
 npm run test:integration
 npm run test:system
 npm run test:live:github
+npm run test:live:regression-workflow
 npm run test:live:neon
 npm run test:database-version:compat
 ```

package/lib/cli/assistant/view-model.mjs

@@ -118,7 +118,7 @@ export function buildWelcomeModel(snapshot, { cwd = process.cwd(), providerLabel
   const issues = [
     rowValue("New regressions") ? `${rowValue("New regressions")} new regression${rowValue("New regressions") === "1" ? "" : "s"}` : null,
     rowValue("Known regressions") ? `${rowValue("Known regressions")} known` : null,
-    rowValue("Catalog stale") ? `${rowValue("Catalog stale")} stale` : null,
+    rowValue("Case store stale") ? `${rowValue("Case store stale")} stale` : null,
   ].filter(Boolean);
 
   return {

package/lib/cli/components/blocks/run-tree.mjs

@@ -120,7 +120,7 @@ function renderTreeLine(snapshot, spinnerFrame, terminalWidth, entry) {
 
   if (entry.kind === "file" && !entry.collapsed && snapshot.finished) {
     const detailLines = entry.status === "failed"
-      ? renderFailureDetail(entry, { width: terminalWidth, regressionCatalog: snapshot.regressionCatalog })
+      ? renderFailureDetail(entry, { width: terminalWidth, regressionCaseStore: snapshot.regressionCaseStore })
       : entry.status === "passed"
         ? renderPassedDetail(entry, { width: terminalWidth })
         : [];

package/lib/cli/renderers/run/events.mjs

@@ -6,9 +6,10 @@ export function createRunEventsReporter({ stdout = process.stdout, stderr = proc
   return {
     outputMode: "events",
 
-    setRegressionCatalog(document) {
-      writeEvent("run.regression_catalog", {
-        configured: Boolean(document?.configured),
+    setRegressionCaseStore(document) {
+      writeEvent("run.regression_case_store", {
+        configured: Boolean(document),
+        caseCount: document?.cases?.length || 0,
       });
     },
 

package/lib/cli/renderers/run/failure.mjs

@@ -1,7 +1,7 @@
 import { buildFailurePresentation } from "../../../runner/formatting.mjs";
 import { renderIndentedBlock } from "../../terminal/layout.mjs";
 
-export function renderFailureBlock(task, outcome, { width, regressionCatalog } = {}) {
+export function renderFailureBlock(task, outcome, { width, regressionCaseStore } = {}) {
   const failureView = buildFailurePresentation(
     {
       service: task.serviceName,
@@ -11,7 +11,7 @@ export function renderFailureBlock(task, outcome, { width, regressionCatalog } =
       failureDetails: Array.isArray(outcome.failureDetails) ? outcome.failureDetails : [],
       suiteError: null,
     },
-    regressionCatalog
+    regressionCaseStore
   );
 
   const lines = [];

package/lib/cli/renderers/run/inline-detail.mjs

@@ -3,7 +3,7 @@ import { renderIndentedBlock } from "../../terminal/layout.mjs";
 import { dim, green, red } from "../../terminal/colors.mjs";
 import figures from "figures";
 
-export function renderFailureDetail(entry, { width, regressionCatalog } = {}) {
+export function renderFailureDetail(entry, { width, regressionCaseStore } = {}) {
   const fileSummary = {
     service: entry.serviceName,
     type: normalizeType(entry),
@@ -13,7 +13,7 @@ export function renderFailureDetail(entry, { width, regressionCatalog } = {}) {
     suiteError: null,
   };
 
-  const failureView = buildFailurePresentation(fileSummary, regressionCatalog);
+  const failureView = buildFailurePresentation(fileSummary, regressionCaseStore);
   const lines = [];
   const indent = " ".repeat(2 + (entry.depth || 0) * 2 + 2);
 

package/lib/cli/renderers/run/interactive.mjs

@@ -32,8 +32,8 @@ export function createRunSession({
       runState.setTotalFileCount(count);
     },
 
-    setRegressionCatalog(document) {
-      runState.setRegressionCatalog(document);
+    setRegressionCaseStore(document) {
+      runState.setRegressionCaseStore(document);
     },
 
     serviceSkipped(config, reason) {

package/lib/cli/renderers/run/text-reporter.mjs

@@ -13,15 +13,15 @@ export function createRunReporter({ outputMode = "compact", stdout = process.std
   const mode = outputMode || "compact";
   let completedCount = 0;
   let totalFileCount = 0;
-  let regressionCatalog = null;
+  let regressionCaseStore = null;
 
   return {
     outputMode: mode,
     setTotalFileCount(count) {
       totalFileCount = count;
     },
-    setRegressionCatalog(document) {
-      regressionCatalog = document;
+    setRegressionCaseStore(document) {
+      regressionCaseStore = document;
     },
     writeLine(line = "") {
       stdout.write(`${line}\n`);
@@ -92,7 +92,7 @@ export function createRunReporter({ outputMode = "compact", stdout = process.std
       if (status === "FAIL") {
         const detailLines = renderFailureBlock(task, outcome, {
           width: getTerminalWidth(stdout, 100),
-          regressionCatalog,
+          regressionCaseStore,
         });
         for (const line of detailLines) {
           stdout.write(`${line}\n`);
@@ -138,13 +138,13 @@ export function createRunReporter({ outputMode = "compact", stdout = process.std
       if (summary.fixedKnownRegressions > 0) {
         rows.push(["Fixed known", String(summary.fixedKnownRegressions)]);
       }
-      if (summary.catalogStale > 0) {
-        rows.push(["Catalog stale", String(summary.catalogStale)]);
+      if (summary.staleCases > 0) {
+        rows.push(["Case store stale", String(summary.staleCases)]);
       }
-      if (summary.catalogSyncUnavailable) {
-        rows.push(["Catalog sync", "Unavailable"]);
+      if (summary.syncUnavailable) {
+        rows.push(["Case store sync", "Unavailable"]);
       } else if (summary.usedStaleCache) {
-        rows.push(["Catalog sync", "Used stale cache"]);
+        rows.push(["Case store sync", "Used stale cache"]);
       }
       const boxed = renderSummaryBox(rows, { stdout });
       stdout.write("\n");

package/lib/cli/state/run/model.mjs

@@ -32,8 +32,8 @@ export function buildSummaryRows({
   if ((regressionSummary?.fixedKnownRegressions || 0) > 0) {
     rows.push(["Fixed known", String(regressionSummary.fixedKnownRegressions)]);
   }
-  if ((regressionSummary?.catalogStale || 0) > 0) {
-    rows.push(["Catalog stale", String(regressionSummary.catalogStale)]);
+  if ((regressionSummary?.staleCases || 0) > 0) {
+    rows.push(["Case store stale", String(regressionSummary.staleCases)]);
   }
   return rows;
 }
@@ -44,7 +44,7 @@ export function createEmptyRunModel(dataSource = "live", options = {}) {
     autoCollapsePassedTreeBranches: options.autoCollapsePassedTreeBranches !== false,
     services: new Map(),
     summaryData: null,
-    regressionCatalog: null,
+    regressionCaseStore: null,
     runArtifact: null,
     finished: dataSource === "artifact",
     totalCount: 0,
@@ -59,7 +59,7 @@ export function resetRunModel(model, dataSource = model.dataSource) {
   model.dataSource = dataSource;
   model.services = new Map();
   model.summaryData = null;
-  model.regressionCatalog = null;
+  model.regressionCaseStore = null;
   model.runArtifact = null;
   model.finished = dataSource === "artifact";
   model.totalCount = 0;
@@ -250,8 +250,8 @@ export function setPhase(model, label) {
   model.phase = label;
 }
 
-export function setRegressionCatalog(model, document) {
-  model.regressionCatalog = document;
+export function setRegressionCaseStore(model, document) {
+  model.regressionCaseStore = document;
 }
 
 export function finishModel(model, results, durationMs, regressionReport) {
@@ -316,7 +316,7 @@ export function buildSnapshot(model) {
     phase: model.phase,
     finished: model.finished,
     summaryData: model.summaryData,
-    regressionCatalog: model.regressionCatalog,
+    regressionCaseStore: model.regressionCaseStore,
     runArtifact: model.runArtifact,
   };
 }

package/lib/cli/state/run/state.mjs

@@ -14,7 +14,7 @@ import {
   resetRunModel,
   revealEntry,
   setPhase,
-  setRegressionCatalog,
+  setRegressionCaseStore,
   setTotalFileCount,
   toggleCollapsed,
 } from "./model.mjs";
@@ -66,8 +66,8 @@ export function createRunState({ dataSource = "live", autoCollapsePassedTreeBran
       notify();
     },
 
-    setRegressionCatalog(document) {
-      setRegressionCatalog(model, document);
+    setRegressionCaseStore(document) {
+      setRegressionCaseStore(model, document);
       notify();
     },
 

package/lib/cli/terminal/colors.mjs

@@ -82,7 +82,7 @@ export function colorResultLine(line) {
 }
 
 export function colorSectionLine(line) {
-  if (line === "Catalog issues:" || line === "Diagnosis:") {
+  if (line === "Case store issues:" || line === "Diagnosis:") {
     return pc.bold(line);
   }
   if (/^Summary: /.test(line)) return line.replace("Summary:", `${pc.bold("Summary:")}`);

package/lib/config/runtime.mjs

@@ -32,9 +32,139 @@ export function normalizeRegressionsConfig(value) {
   return {
     file,
     sync,
+    workflow: normalizeRegressionWorkflowConfig(value.workflow),
   };
 }
 
+function normalizeRegressionWorkflowConfig(value) {
+  const defaults = {
+    mode: "autopilot",
+    github: {
+      read: true,
+      write: false,
+      bugLabels: ["bug"],
+      issueLabels: ["bug"],
+      createIssues: "confirmed",
+      reopenIssues: "closed_reproduced",
+      closeIssues: "after_stability_window",
+      comment: "state_changes",
+    },
+    evidence: {
+      autoRerunThinFailures: true,
+      maxAutoReruns: 2,
+      requireForIssueCreation: true,
+    },
+    stability: {
+      cleanRunsBeforeClose: 3,
+    },
+  };
+  if (value == null) return defaults;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("testkit.config.ts regressions.workflow must be an object");
+  }
+  const mode = normalizeOptionalString(value.mode) || defaults.mode;
+  if (!["off", "observe", "autopilot"].includes(mode)) {
+    throw new Error('testkit.config.ts regressions.workflow.mode must be one of: off, observe, autopilot');
+  }
+  const github = normalizeObject(value.github, "testkit.config.ts regressions.workflow.github");
+  const evidence = normalizeObject(value.evidence, "testkit.config.ts regressions.workflow.evidence");
+  const stability = normalizeObject(value.stability, "testkit.config.ts regressions.workflow.stability");
+  return {
+    mode,
+    github: {
+      ...defaults.github,
+      ...normalizeRegressionWorkflowGithub(github),
+    },
+    evidence: {
+      ...defaults.evidence,
+      ...normalizeRegressionWorkflowEvidence(evidence),
+    },
+    stability: {
+      ...defaults.stability,
+      ...normalizeRegressionWorkflowStability(stability),
+    },
+  };
+}
+
+function normalizeRegressionWorkflowGithub(value) {
+  if (!value) return {};
+  return {
+    ...(value.read == null ? {} : { read: normalizeBoolean(value.read, "testkit.config.ts regressions.workflow.github.read") }),
+    ...(value.write == null ? {} : { write: normalizeBoolean(value.write, "testkit.config.ts regressions.workflow.github.write") }),
+    ...(value.apiBaseUrl == null ? {} : { apiBaseUrl: requireNonEmptyString(value.apiBaseUrl, "testkit.config.ts regressions.workflow.github.apiBaseUrl") }),
+    ...(value.bugLabels == null ? {} : { bugLabels: normalizeStringArray(value.bugLabels, "testkit.config.ts regressions.workflow.github.bugLabels") }),
+    ...(value.issueLabels == null ? {} : { issueLabels: normalizeStringArray(value.issueLabels, "testkit.config.ts regressions.workflow.github.issueLabels") }),
+    ...(value.createIssues == null ? {} : { createIssues: normalizeEnum(value.createIssues, ["never", "confirmed"], "testkit.config.ts regressions.workflow.github.createIssues") }),
+    ...(value.reopenIssues == null ? {} : { reopenIssues: normalizeEnum(value.reopenIssues, ["never", "closed_reproduced"], "testkit.config.ts regressions.workflow.github.reopenIssues") }),
+    ...(value.closeIssues == null ? {} : { closeIssues: normalizeEnum(value.closeIssues, ["never", "after_stability_window"], "testkit.config.ts regressions.workflow.github.closeIssues") }),
+    ...(value.comment == null ? {} : { comment: normalizeEnum(value.comment, ["never", "state_changes"], "testkit.config.ts regressions.workflow.github.comment") }),
+  };
+}
+
+function normalizeRegressionWorkflowEvidence(value) {
+  if (!value) return {};
+  return {
+    ...(value.autoRerunThinFailures == null ? {} : { autoRerunThinFailures: normalizeBoolean(value.autoRerunThinFailures, "testkit.config.ts regressions.workflow.evidence.autoRerunThinFailures") }),
+    ...(value.maxAutoReruns == null ? {} : { maxAutoReruns: normalizeNonNegativeInteger(value.maxAutoReruns, "testkit.config.ts regressions.workflow.evidence.maxAutoReruns") }),
+    ...(value.requireForIssueCreation == null ? {} : { requireForIssueCreation: normalizeBoolean(value.requireForIssueCreation, "testkit.config.ts regressions.workflow.evidence.requireForIssueCreation") }),
+  };
+}
+
+function normalizeRegressionWorkflowStability(value) {
+  if (!value) return {};
+  return {
+    ...(value.cleanRunsBeforeClose == null ? {} : { cleanRunsBeforeClose: normalizePositiveInteger(value.cleanRunsBeforeClose, "testkit.config.ts regressions.workflow.stability.cleanRunsBeforeClose") }),
+  };
+}
+
+function normalizeObject(value, label) {
+  if (value == null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+function normalizeBoolean(value, label) {
+  if (typeof value !== "boolean") throw new Error(`${label} must be a boolean`);
+  return value;
+}
+
+function normalizeEnum(value, allowed, label) {
+  const normalized = requireNonEmptyString(value, label);
+  if (!allowed.includes(normalized)) {
+    throw new Error(`${label} must be one of: ${allowed.join(", ")}`);
+  }
+  return normalized;
+}
+
+function normalizeStringArray(value, label) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${label} must be a non-empty array`);
+  }
+  return value.map((entry, index) => requireNonEmptyString(entry, `${label}[${index}]`));
+}
+
+function normalizeNonNegativeInteger(value, label) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function normalizePositiveInteger(value, label) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return value;
+}
+
+function requireNonEmptyString(value, label) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) throw new Error(`${label} must be a non-empty string`);
+  return normalized;
+}
+
 export function inferLocalRuntime(productDir, cwd) {
   const absoluteCwd = resolveServiceCwd(productDir, cwd);
   if (!fs.existsSync(absoluteCwd)) return undefined;

package/lib/config-api/index.d.ts

@@ -586,6 +586,28 @@ export interface TestkitConfig {
   regressions?: {
     file?: string;
     sync?: RegressionSyncConfig;
+    workflow?: {
+      mode?: "off" | "observe" | "autopilot";
+      github?: {
+        read?: boolean;
+        write?: boolean;
+        apiBaseUrl?: string;
+        bugLabels?: string[];
+        issueLabels?: string[];
+        createIssues?: "never" | "confirmed";
+        reopenIssues?: "never" | "closed_reproduced";
+        closeIssues?: "never" | "after_stability_window";
+        comment?: "never" | "state_changes";
+      };
+      evidence?: {
+        autoRerunThinFailures?: boolean;
+        maxAutoReruns?: number;
+        requireForIssueCreation?: boolean;
+      };
+      stability?: {
+        cleanRunsBeforeClose?: number;
+      };
+    };
   };
   services?: Record<string, ServiceConfig>;
   toolchains?: Record<string, ToolchainConfig>;

package/lib/database/cleanup.mjs

@@ -7,9 +7,12 @@ import {
   TESTKIT_SCOPE_LABEL,
   buildProductIdentity,
   dockerContainerSummary,
+  dockerVolumeSummary,
   listLegacyTestkitPostgresContainers,
   listManagedDockerContainers,
+  listManagedDockerVolumes,
   removeDockerContainer,
+  removeDockerVolume,
   stopDockerContainer,
 } from "../ownership/docker.mjs";
 import { buildContainerName } from "./naming.mjs";
@@ -22,6 +25,7 @@ import {
 export async function cleanupLocalPostgresDockerResources(options = {}) {
   const product = buildProductIdentity(options.productDir || process.cwd());
   const managed = await listManagedDockerContainers();
+  const managedVolumes = await listManagedDockerVolumes();
   const targets = [];
   const kept = [];
   const stopped = [];
@@ -38,6 +42,16 @@ export async function cleanupLocalPostgresDockerResources(options = {}) {
     }
   }
 
+  for (const volume of managedVolumes) {
+    if (!isManagedLocalPostgresVolume(volume)) continue;
+    const classification = classifyManagedLocalPostgresVolume(volume, product, options);
+    if (classification.action === "remove") {
+      targets.push({ ...volume, action: "remove", reason: classification.reason, legacy: false, resourceType: "volume" });
+    } else if (classification.reason) {
+      kept.push({ ...volume, reason: classification.reason, legacy: false, resourceType: "volume" });
+    }
+  }
+
   if (options.includeLegacy) {
     const currentLegacyName = buildContainerName(product.dir);
     for (const container of await listLegacyTestkitPostgresContainers()) {
@@ -51,6 +65,8 @@ export async function cleanupLocalPostgresDockerResources(options = {}) {
       if (container.action === "stop") {
         await stopDockerContainer(container.name || container.id);
         stopped.push(container);
+      } else if (container.resourceType === "volume") {
+        await removeDockerVolume(container.name);
       } else {
         await removeDockerContainer(container.name || container.id);
       }
@@ -71,7 +87,10 @@ export function formatDatabaseResourceCleanupLine(entry, dryRun = false) {
     ? isStop ? "Would stop" : "Would remove"
     : isStop ? "Stopped" : "Removed";
   const legacy = entry.legacy ? " legacy" : "";
-  return `${action}${legacy} database resource ${dockerContainerSummary(entry)} reason=${entry.reason}`;
+  const summary = entry.resourceType === "volume"
+    ? `volume ${dockerVolumeSummary(entry)}`
+    : dockerContainerSummary(entry);
+  return `${action}${legacy} database resource ${summary} reason=${entry.reason}`;
 }
 
 function classifyManagedLocalPostgresContainer(container, product, options) {
@@ -112,6 +131,41 @@ function classifyManagedLocalPostgresContainer(container, product, options) {
   return { action: "keep", reason: options.global ? "other-product-retained" : "different-product" };
 }
 
+function classifyManagedLocalPostgresVolume(volume, product, options) {
+  const labels = volume.labels || {};
+  const volumeProductId = labels[TESTKIT_PRODUCT_ID_LABEL] || "";
+  const volumeProductDir = labels[TESTKIT_PRODUCT_DIR_LABEL] || "";
+  const currentProduct = volumeProductId === product.id;
+
+  if (options.force && currentProduct) {
+    return { action: "remove", reason: "destroy-current-product" };
+  }
+
+  if (!options.global && !currentProduct) {
+    return { action: "keep", reason: "different-product" };
+  }
+
+  if (currentProduct) {
+    if (!hasRemainingLocalArtifacts(product.dir, readStateValue)) {
+      return { action: "remove", reason: "current-product-no-local-artifacts" };
+    }
+    if (!localArtifactsReferenceVolume(product.dir, volume.name)) {
+      return { action: "remove", reason: "current-product-unreferenced" };
+    }
+    return { action: "keep", reason: "current-product-referenced" };
+  }
+
+  if (options.global && volumeProductDir && !fs.existsSync(volumeProductDir)) {
+    return { action: "remove", reason: "product-dir-missing" };
+  }
+
+  if (options.global && volumeProductDir && !hasRemainingLocalArtifacts(volumeProductDir, readStateValue)) {
+    return { action: "remove", reason: "product-has-no-local-artifacts" };
+  }
+
+  return { action: "keep", reason: options.global ? "other-product-retained" : "different-product" };
+}
+
 function shouldStopIdleLocalPostgresContainer(container, productDir, options) {
   return Boolean(
     options.stopIdle &&
@@ -130,6 +184,14 @@ function isManagedLocalPostgresContainer(container) {
   );
 }
 
+function isManagedLocalPostgresVolume(volume) {
+  const labels = volume.labels || {};
+  return (
+    labels[TESTKIT_RESOURCE_KIND_LABEL] === "postgres-volume" &&
+    labels[TESTKIT_SCOPE_LABEL] === "local-postgres"
+  );
+}
+
 function localArtifactsReferenceContainer(productDir, containerName) {
   if (!containerName) return false;
   const root = path.join(productDir, ".testkit");
@@ -146,6 +208,19 @@ function localArtifactsReferenceContainer(productDir, containerName) {
   return referenced;
 }
 
+function localArtifactsReferenceVolume(productDir, volumeName) {
+  if (!volumeName) return false;
+  const root = path.join(productDir, ".testkit");
+  let referenced = false;
+  visitDirs(root, (dir) => {
+    if (referenced) return;
+    if (readStateValue(path.join(dir, "volume_name")) === volumeName) {
+      referenced = true;
+    }
+  });
+  return referenced;
+}
+
 function hasActiveProductRuntime(productDir) {
   return hasActiveRunManifest(productDir) || hasActiveLocalEnvironmentManifest(productDir);
 }

package/lib/database/index.mjs

@@ -457,6 +457,12 @@ async function ensureRuntimeClone(config, infra, cacheDir, templateFingerprint,
   fs.writeFileSync(path.join(config.stateDir, `${backend}_template_database_name`), templateDbName);
   if (backend === "local") {
     fs.writeFileSync(path.join(config.stateDir, "local_container_name"), infra.containerName);
+    if (infra.volumeName) {
+      fs.writeFileSync(path.join(config.stateDir, "volume_name"), infra.volumeName);
+    }
+    if (infra.volumeMountPath) {
+      fs.writeFileSync(path.join(config.stateDir, "volume_mount_path"), infra.volumeMountPath);
+    }
   } else {
     fs.writeFileSync(path.join(config.stateDir, "resource_name"), infra.resourceName);
     writeResourceConnectionState(config.stateDir, infra);