imprint-mcp 0.3.0 → 0.4.0

package/src/imprint/export-archive.ts

@@ -0,0 +1,355 @@
+/**
+ * `imprint export` / `imprint import` — portable .tar.gz archives of
+ * generated MCP tools, optionally including encrypted credential bundles.
+ *
+ * Archive layout:
+ *   manifest.json
+ *   <site>/<tool>/{ workflow.json, playbook.yaml, index.ts, ... }
+ *   <site>/_shared/{ *.ts, package.json }
+ *   <site>/credentials.imprintbundle   (when --include-credentials)
+ */
+
+import { execSync } from 'node:child_process';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join as pathJoin, resolve as pathResolve } from 'node:path';
+import * as p from '@clack/prompts';
+import { type BundleEnvelope, exportBundle, importBundle } from './credential-bundle.ts';
+import { getCredentialBackend } from './credential-store.ts';
+import { imprintHomeDir, localSharedDir, localSiteDir } from './paths.ts';
+import { ensureImprintRuntimeLink } from './runtime-link.ts';
+import { availableSitesHint } from './sites.ts';
+import { VERSION } from './version.ts';
+
+const TOOL_FILES = [
+  'workflow.json',
+  'playbook.yaml',
+  'index.ts',
+  'parser.ts',
+  'request-transform.ts',
+  'package.json',
+  'backends.json',
+  'cron.json',
+];
+
+const SHARED_SKIP = new Set(['node_modules', 'bun.lock']);
+
+interface ExportManifest {
+  version: 1;
+  imprintVersion: string;
+  createdAt: string;
+  sites: Array<{
+    name: string;
+    tools: string[];
+    hasCredentials: boolean;
+    hasShared: boolean;
+  }>;
+}
+
+interface ExportResult {
+  archivePath: string;
+  sites: Array<{ name: string; tools: string[] }>;
+  byteSize: number;
+}
+
+interface ImportResult {
+  sites: Array<{
+    name: string;
+    tools: string[];
+    credentialsImported: boolean;
+    skipped: boolean;
+  }>;
+}
+
+function isToolDir(dir: string): boolean {
+  return existsSync(pathJoin(dir, 'index.ts'));
+}
+
+function discoverToolNames(siteDir: string): string[] {
+  if (!existsSync(siteDir)) return [];
+  return readdirSync(siteDir)
+    .filter((entry) => {
+      if (
+        entry.startsWith('.') ||
+        entry.startsWith('_') ||
+        entry === 'sessions' ||
+        entry === 'node_modules'
+      )
+        return false;
+      const full = pathJoin(siteDir, entry);
+      try {
+        return statSync(full).isDirectory() && isToolDir(full);
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+}
+
+function collectToolFiles(toolDir: string): string[] {
+  return TOOL_FILES.filter((f) => existsSync(pathJoin(toolDir, f)));
+}
+
+function collectSharedFiles(sharedDir: string): string[] {
+  if (!existsSync(sharedDir)) return [];
+  return readdirSync(sharedDir).filter((f) => {
+    if (SHARED_SKIP.has(f)) return false;
+    if (f.endsWith('.test.ts') || f.endsWith('.plan.md')) return false;
+    const full = pathJoin(sharedDir, f);
+    try {
+      return statSync(full).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+export async function exportArchive(opts: {
+  sites: string[];
+  out: string;
+  includeCredentials?: boolean;
+}): Promise<ExportResult> {
+  for (const site of opts.sites) {
+    const dir = localSiteDir(site);
+    if (!existsSync(dir)) {
+      throw new Error(
+        `Site "${site}" not found at ${dir}.\n${availableSitesHint(imprintHomeDir(), site)}`,
+      );
+    }
+  }
+
+  const staging = mkdtempSync(pathJoin(tmpdir(), 'imprint-export-'));
+
+  try {
+    const manifest: ExportManifest = {
+      version: 1,
+      imprintVersion: VERSION,
+      createdAt: new Date().toISOString(),
+      sites: [],
+    };
+
+    for (const site of opts.sites) {
+      const siteDir = localSiteDir(site);
+      const tools = discoverToolNames(siteDir);
+      if (tools.length === 0) {
+        throw new Error(
+          `Site "${site}" has no tools (no subdirectories with index.ts). Nothing to export.`,
+        );
+      }
+
+      const stagingSite = pathJoin(staging, site);
+      mkdirSync(stagingSite, { recursive: true });
+
+      for (const tool of tools) {
+        const toolDir = pathJoin(siteDir, tool);
+        const stagingTool = pathJoin(stagingSite, tool);
+        mkdirSync(stagingTool, { recursive: true });
+
+        for (const file of collectToolFiles(toolDir)) {
+          copyFileSync(pathJoin(toolDir, file), pathJoin(stagingTool, file));
+        }
+      }
+
+      const sharedDir = localSharedDir(site);
+      const sharedFiles = collectSharedFiles(sharedDir);
+      let hasShared = false;
+      if (sharedFiles.length > 0) {
+        const stagingShared = pathJoin(stagingSite, '_shared');
+        mkdirSync(stagingShared, { recursive: true });
+        for (const file of sharedFiles) {
+          copyFileSync(pathJoin(sharedDir, file), pathJoin(stagingShared, file));
+        }
+        hasShared = true;
+      }
+
+      let hasCredentials = false;
+      if (opts.includeCredentials) {
+        const backend = await getCredentialBackend();
+        const secrets = await backend.listSecrets(site);
+        const cookies = await backend.getCookies(site);
+        if (secrets.length > 0 || cookies.length > 0) {
+          const passphrase = await p.password({
+            message: `Passphrase to encrypt credentials for "${site}" (min 8 chars):`,
+            validate: (v) =>
+              (v ?? '').length < 8 ? 'Passphrase must be at least 8 characters.' : undefined,
+          });
+          if (p.isCancel(passphrase)) {
+            throw new Error('Export cancelled.');
+          }
+          const envelope = await exportBundle({
+            backend,
+            site,
+            passphrase,
+          });
+          writeFileSync(
+            pathJoin(stagingSite, 'credentials.imprintbundle'),
+            JSON.stringify(envelope, null, 2),
+            'utf8',
+          );
+          hasCredentials = true;
+        }
+      }
+
+      manifest.sites.push({ name: site, tools, hasCredentials, hasShared });
+    }
+
+    writeFileSync(pathJoin(staging, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+
+    const archivePath = pathResolve(opts.out);
+    execSync(`tar czf ${shellEscape(archivePath)} -C ${shellEscape(staging)} .`, {
+      stdio: 'pipe',
+    });
+
+    const byteSize = statSync(archivePath).size;
+    return {
+      archivePath,
+      sites: manifest.sites.map((s) => ({ name: s.name, tools: s.tools })),
+      byteSize,
+    };
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+export async function importArchive(opts: {
+  archivePath: string;
+  force?: boolean;
+}): Promise<ImportResult> {
+  const archivePath = pathResolve(opts.archivePath);
+  if (!existsSync(archivePath)) {
+    throw new Error(`Archive not found: ${archivePath}`);
+  }
+
+  const staging = mkdtempSync(pathJoin(tmpdir(), 'imprint-import-'));
+
+  try {
+    execSync(`tar xzf ${shellEscape(archivePath)} -C ${shellEscape(staging)}`, {
+      stdio: 'pipe',
+    });
+
+    const manifestPath = pathJoin(staging, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      throw new Error(
+        'Invalid archive: missing manifest.json. This does not appear to be an imprint export.',
+      );
+    }
+
+    const manifest: ExportManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (manifest.version !== 1) {
+      throw new Error(
+        `Unsupported archive version ${manifest.version}. Update imprint and try again.`,
+      );
+    }
+
+    const home = imprintHomeDir();
+    const result: ImportResult = { sites: [] };
+
+    for (const entry of manifest.sites) {
+      const targetDir = localSiteDir(entry.name);
+      const skipped = false;
+
+      if (existsSync(targetDir) && !opts.force) {
+        console.error(
+          `warning: site "${entry.name}" already exists at ${targetDir} — skipping (use --force to overwrite).`,
+        );
+        result.sites.push({
+          name: entry.name,
+          tools: entry.tools,
+          credentialsImported: false,
+          skipped: true,
+        });
+        continue;
+      }
+
+      const stagedSite = pathJoin(staging, entry.name);
+
+      if (existsSync(targetDir)) {
+        rmSync(targetDir, { recursive: true, force: true });
+      }
+
+      for (const tool of entry.tools) {
+        assertSafeSegment('tool name', tool);
+        const src = pathJoin(stagedSite, tool);
+        const dest = pathJoin(targetDir, tool);
+        mkdirSync(dest, { recursive: true });
+        for (const file of readdirSync(src)) {
+          const srcFile = pathJoin(src, file);
+          if (statSync(srcFile).isFile()) {
+            copyFileSync(srcFile, pathJoin(dest, file));
+          }
+        }
+      }
+
+      if (entry.hasShared) {
+        const sharedSrc = pathJoin(stagedSite, '_shared');
+        const sharedDest = pathJoin(targetDir, '_shared');
+        if (existsSync(sharedSrc)) {
+          mkdirSync(sharedDest, { recursive: true });
+          for (const file of readdirSync(sharedSrc)) {
+            const srcFile = pathJoin(sharedSrc, file);
+            if (statSync(srcFile).isFile()) {
+              copyFileSync(srcFile, pathJoin(sharedDest, file));
+            }
+          }
+        }
+      }
+
+      let credentialsImported = false;
+      const bundlePath = pathJoin(stagedSite, 'credentials.imprintbundle');
+      if (entry.hasCredentials && existsSync(bundlePath)) {
+        const envelope: BundleEnvelope = JSON.parse(readFileSync(bundlePath, 'utf8'));
+        const passphrase = await p.password({
+          message: `Passphrase to decrypt credentials for "${entry.name}":`,
+        });
+        if (p.isCancel(passphrase)) {
+          console.error(`Skipping credential import for "${entry.name}".`);
+        } else {
+          try {
+            const backend = await getCredentialBackend();
+            await importBundle({ backend, envelope, passphrase });
+            credentialsImported = true;
+          } catch (err) {
+            console.error(
+              `warning: credential import failed for "${entry.name}": ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+        }
+      }
+
+      ensureImprintRuntimeLink(home);
+
+      result.sites.push({
+        name: entry.name,
+        tools: entry.tools,
+        credentialsImported,
+        skipped,
+      });
+    }
+
+    return result;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function assertSafeSegment(label: string, value: string): void {
+  if (value.includes('..') || value.includes('/') || value.includes('\\')) {
+    throw new Error(
+      `Invalid ${label} in archive: "${value}". Must not contain path separators or ".." sequences.`,
+    );
+  }
+}
+
+function shellEscape(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/src/imprint/install.ts

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { dirname as pathDirname, join as pathJoin, resolve as pathResolve } from 'node:path';
 import * as p from '@clack/prompts';
 import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
+import { defaultPlaywrightBrowsersPath, ensurePlaywrightChromiumInstalled } from './chromium.ts';
 import {
   type McpServerConfig,
   PLATFORMS,
@@ -16,7 +17,7 @@ import {
   shellQuote,
 } from './integrations.ts';
 import { imprintHomeDir } from './paths.ts';
-import { discoverTools } from './tool-loader.ts';
+import { type ResolvedTool, discoverTools } from './tool-loader.ts';
 import type { Workflow } from './types.ts';
 
 type InstallSource = 'local' | 'examples';
@@ -28,6 +29,7 @@ interface InstallOptions {
   source?: InstallSource;
   print?: boolean;
   noInteractive?: boolean;
+  skipBrowserInstall?: boolean;
 }
 
 interface UninstallOptions {
@@ -70,6 +72,7 @@ interface InstallTarget {
   source: InstallSource;
   assetRoot: string;
   site: string;
+  tools: ResolvedTool[];
   workflows: Workflow[];
 }
 
@@ -114,7 +117,11 @@ function defaultOpenClawConfigPath(): string {
   return pathJoin(homedir(), '.openclaw', 'openclaw.json');
 }
 
-function defaultHermesConfigPath(): string {
+export function defaultHermesConfigPath(): string {
+  const explicit = process.env.HERMES_CONFIG?.trim();
+  if (explicit) return explicit;
+  const hermesHome = process.env.HERMES_HOME?.trim();
+  if (hermesHome) return pathJoin(hermesHome, 'config.yaml');
   return pathJoin(homedir(), '.hermes', 'config.yaml');
 }
 
@@ -255,7 +262,7 @@ export async function install(opts: InstallOptions = {}): Promise<InstallResult>
   const imprintCommand = configFilePlatform(platform)
     ? detectDirectBunImprintCommand()
     : detectImprintCommand();
-  const env = { IMPRINT_HOME: target.assetRoot };
+  const env = buildInstallEnvironment(target);
   const workflow = target.workflows[0];
   if (!workflow) {
     throw new Error(`No emitted workflows found for ${target.site}. Run \`imprint emit\` first.`);
@@ -287,6 +294,10 @@ export async function install(opts: InstallOptions = {}): Promise<InstallResult>
     };
   }
 
+  if (!opts.skipBrowserInstall) {
+    ensureBrowserRuntimeForInstall(target);
+  }
+
   const regCommand = buildRegistrationCommand({
     site: target.site,
     platform,
@@ -422,10 +433,68 @@ async function resolveInstallTarget(opts: InstallOptions): Promise<InstallTarget
     source: selected.source,
     assetRoot: selected.assetRoot,
     site: selected.site,
+    tools,
     workflows,
   };
 }
 
+function buildInstallEnvironment(target: InstallTarget): Record<string, string> {
+  const env: Record<string, string> = { IMPRINT_HOME: target.assetRoot };
+  const browsersPath = defaultPlaywrightBrowsersPath();
+  if (browsersPath && installTargetNeedsBrowserRuntime(target)) {
+    env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  }
+  return env;
+}
+
+function ensureBrowserRuntimeForInstall(target: InstallTarget): void {
+  if (!installTargetNeedsBrowserRuntime(target)) return;
+  const result = ensurePlaywrightChromiumInstalled({
+    log: (message) => process.stderr.write(`[imprint install] ${message}\n`),
+  });
+  if (result.installed) {
+    process.stderr.write(`[imprint install] installed Playwright Chromium at ${result.path}\n`);
+  }
+}
+
+function installTargetNeedsBrowserRuntime(target: InstallTarget): boolean {
+  return target.tools.some(
+    (tool) => workflowNeedsBrowserRuntime(tool.workflow) || toolDirNeedsBrowserRuntime(tool.dir),
+  );
+}
+
+function workflowNeedsBrowserRuntime(workflow: Workflow): boolean {
+  if (workflow.bootstrap) return true;
+  if (workflow.liveVerified === false && workflow.liveVerifiedWaiver?.kind === 'waived-bot') {
+    return true;
+  }
+  if (workflow.requests.some((request) => request.url.includes('${state.'))) return true;
+  return workflow.requests.some((request) =>
+    (request.captures ?? []).some((capture) => captureNeedsBrowserRuntime(capture.capability)),
+  );
+}
+
+function toolDirNeedsBrowserRuntime(toolDir: string): boolean {
+  if (existsSync(pathJoin(toolDir, 'playbook.yaml'))) return true;
+  const backendsPath = pathJoin(toolDir, 'backends.json');
+  if (!existsSync(backendsPath)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(backendsPath, 'utf8')) as { preferredOrder?: unknown };
+    if (!Array.isArray(parsed.preferredOrder)) return false;
+    return parsed.preferredOrder.some(
+      (backend) =>
+        typeof backend === 'string' &&
+        ['fetch-bootstrap', 'cdp-replay', 'stealth-fetch', 'playbook'].includes(backend),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function captureNeedsBrowserRuntime(capability: string | undefined): boolean {
+  return capability === 'browser_bootstrap' || capability === 'stealth_bootstrap';
+}
+
 async function resolveInstallPlatform(
   opts: Pick<InstallOptions, 'platform' | 'noInteractive'>,
   message = 'Install this MCP server where?',
@@ -658,7 +727,13 @@ function isPlatformDetected(platform: Platform): boolean {
     case 'openclaw':
       return commandExists('openclaw') || existsSync(pathJoin(homedir(), '.openclaw'));
     case 'hermes':
-      return commandExists('hermes') || existsSync(pathJoin(homedir(), '.hermes'));
+      return (
+        commandExists('hermes') ||
+        Boolean(process.env.HERMES_CONFIG?.trim()) ||
+        Boolean(process.env.HERMES_HOME?.trim()) ||
+        existsSync(defaultHermesConfigPath()) ||
+        existsSync(pathJoin(homedir(), '.hermes'))
+      );
   }
 }
 

package/src/imprint/integrations.ts

@@ -105,7 +105,7 @@ export function generatePasteSnippet(opts: {
 This gives your agent a tool that ${descLower}. Parameters: ${paramList}.`;
 
     case 'hermes':
-      return `Add the ${toolName} tool: add to ~/.hermes/config.yaml under mcp_servers:
+      return `Add the ${toolName} tool: add to $HERMES_HOME/config.yaml (or ~/.hermes/config.yaml outside Hermes) under mcp_servers:
 
   ${toolName}:
     command: "${ic.command}"

package/src/imprint/mcp-maintenance.ts

@@ -30,6 +30,7 @@ import { imprintHomeDir, localSiteDir } from './paths.ts';
 import {
   type WorkflowState,
   loadTeachState,
+  pruneStalePendingTeachWorkflows,
   resolveTeachStatePath,
   saveTeachState,
   teachStatePath,
@@ -37,7 +38,7 @@ import {
 
 type McpClient = 'claude-code' | 'codex' | 'claude-desktop' | 'openclaw' | 'hermes';
 type LocalDeleteMode = 'none' | 'tool' | 'site';
-type IssueKind = 'incomplete' | 'missing-session' | 'stale-registration';
+type IssueKind = 'missing-session' | 'stale-registration';
 
 const CLIENTS: McpClient[] = ['claude-code', 'codex', 'claude-desktop', 'openclaw', 'hermes'];
 const DISABLED_STORE_VERSION = 1;
@@ -144,6 +145,14 @@ function defaultContext(opts: Partial<MaintenanceContext> = {}): MaintenanceCont
   };
 }
 
+function hermesConfigPath(ctx: MaintenanceContext): string {
+  const explicit = process.env.HERMES_CONFIG?.trim();
+  if (explicit) return explicit;
+  const hermesHome = process.env.HERMES_HOME?.trim();
+  if (hermesHome) return pathJoin(hermesHome, 'config.yaml');
+  return pathJoin(ctx.homeDir, '.hermes', 'config.yaml');
+}
+
 function parseSubArgs(argv: string[]): ParsedArgs {
   const positionals: string[] = [];
   const flags: Record<string, string | boolean> = {};
@@ -419,7 +428,7 @@ function fixIssue(issue: McpIssue, status: McpStatus, ctx: MaintenanceContext):
         };
   }
 
-  if ((issue.kind === 'incomplete' || issue.kind === 'missing-session') && issue.workflow) {
+  if (issue.kind === 'missing-session' && issue.workflow) {
     return pruneSingleTeachWorkflow(issue.site, issue.workflow);
   }
 
@@ -680,8 +689,6 @@ function issueFixHint(issue: McpIssue): string | null {
   switch (issue.kind) {
     case 'stale-registration':
       return `choose "Fix an issue" or run: imprint mcp delete ${issue.name ?? `imprint-${issue.site}`} --client ${issue.client ?? 'all'} --yes`;
-    case 'incomplete':
-      return `choose "Fix an issue" or run: imprint mcp prune-state --site ${issue.site} --incomplete --yes`;
     case 'missing-session':
       return `choose "Fix an issue" or run: imprint mcp prune-state --site ${issue.site} --missing-session --yes`;
   }
@@ -729,6 +736,9 @@ function scanLocalSite(site: string, dir: string): LocalSiteStatus {
   }
 
   const state = loadTeachState(site);
+  if (pruneStalePendingTeachWorkflows(site, state)) {
+    saveTeachState(site, state);
+  }
   const workflows = Object.entries(state.workflows)
     .map(([name, ws]) => workflowStatus(site, name, ws, tools))
     .sort((a, b) => a.name.localeCompare(b.name));
@@ -795,14 +805,6 @@ function collectIssues(opts: {
           path: wf.sessionPath ?? undefined,
         });
       }
-      if (wf.incomplete) {
-        issues.push({
-          kind: 'incomplete',
-          site: site.site,
-          workflow: wf.name,
-          message: `${site.site}/${wf.name} is incomplete (${wf.completedSteps.join(', ') || 'no completed steps'})`,
-        });
-      }
     }
   }
 
@@ -1419,7 +1421,7 @@ function scanJsonMap(
 }
 
 function scanHermes(ctx: MaintenanceContext): McpRegistration[] {
-  const configPath = pathJoin(ctx.homeDir, '.hermes', 'config.yaml');
+  const configPath = hermesConfigPath(ctx);
   if (!existsSync(configPath)) return [];
   const doc = YAML.parseDocument(readFileSync(configPath, 'utf8'));
   const servers = doc.get('mcp_servers', true);

package/src/imprint/mcp-server.ts

@@ -179,7 +179,7 @@ function buildServer(
         args,
         assetRoot,
         stealthCache,
-        { cdpPool, winnerCache },
+        { cdpPool, winnerCache, skipBootstrapSplice: Boolean(tool.preferredOrder?.length) },
       );
       // Reset the idle timer for this site's pooled Chrome.
       if (result.ok && usedBackend === 'cdp-replay' && cdpPool.has(tool.site)) {

package/src/imprint/stealth-chromium.ts

@@ -1,4 +1,4 @@
-import { findChromium } from './chromium.ts';
+import { ensurePlaywrightChromiumInstalled } from './chromium.ts';
 
 /**
  * Shared loader for Playwright's chromium with the stealth plugin applied.
@@ -69,13 +69,11 @@ export async function isStealthPluginAvailable(): Promise<boolean> {
  * replay browser using chrome-headless-shell looks like a bot. Using the
  * SAME binary for both eliminates the binary asymmetry.
  *
- * Returns `undefined` if no Chromium can be located — callers should let
- * Playwright fall back to whatever default it finds.
+ * Throws if Chromium cannot be installed or started; callers translate the
+ * error into their own result shape.
  */
 export function getStealthExecutablePath(): string | undefined {
-  try {
-    return findChromium();
-  } catch {
-    return undefined;
-  }
+  return ensurePlaywrightChromiumInstalled({
+    log: (message) => process.stderr.write(`[imprint] ${message}\n`),
+  }).path;
 }

package/src/imprint/teach-state.ts

@@ -148,6 +148,24 @@ export function resolveTeachStatePath(
   return resolveLocalSitePath(site, value);
 }
 
+export function resolveWorkflowTriagedPath(
+  site: string,
+  ws: WorkflowState | undefined,
+): string | null {
+  if (!ws) return null;
+
+  const explicitPath = resolveTeachStatePath(site, ws.triagedPath);
+  if (explicitPath) return explicitPath;
+
+  if (!ws.completedSteps.includes('triage')) return null;
+
+  const redactedPath = resolveTeachStatePath(site, ws.redactedPath);
+  if (!redactedPath?.endsWith('.redacted.json')) return null;
+
+  const derivedPath = redactedPath.replace(/\.redacted\.json$/, '.triaged.json');
+  return existsSync(derivedPath) ? derivedPath : null;
+}
+
 export function toRelativeTeachStatePath(site: string, absPath: string): string {
   const localRelative = relativeToLocalSite(site, absPath);
   if (localRelative) return localRelative;
@@ -245,6 +263,25 @@ export function isExistingTeachFile(path: string | null | undefined): path is st
   }
 }
 
+function hasRecoverableRawOrRedactedSession(site: string, ws: WorkflowState): boolean {
+  return (
+    isExistingTeachFile(resolveTeachStatePath(site, ws.sessionPath)) ||
+    isExistingTeachFile(resolveTeachStatePath(site, ws.redactedPath))
+  );
+}
+
+export function pruneStalePendingTeachWorkflows(site: string, state: TeachState): boolean {
+  let changed = false;
+  for (const [key, ws] of Object.entries(state.workflows)) {
+    if (!key.startsWith('_pending_')) continue;
+    if (hasRecoverableRawOrRedactedSession(site, ws)) continue;
+    delete state.workflows[key];
+    changed = true;
+  }
+
+  return changed;
+}
+
 export function friendlySessionTimestamp(sessionPath: string): string {
   const m = sessionPath.match(/(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})/);
   if (!m) return pathBasename(sessionPath);